Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
recall: question_too_long names the 2,000-char limit and the received length; document it in the QM contract (GST-1304)
garrytanadc162701142
diff --git a/docs/contracts/qm-memory-provider/README.md b/docs/contracts/qm-memory-provider/README.mdindex 0133176ec8..dd55fab3cf 100644--- a/docs/contracts/qm-memory-provider/README.md+++ b/docs/contracts/qm-memory-provider/README.md@@ -12,5 +12,7 @@ It is generated from the live operation registry byA change to the shape is a new file, `v2.json`; `v1.json` stays until QM moves.`v2.json` adds `source_id` / `source_ids` on `memory_recall` (scope reads, `scope_read`) and `source_id` on-`memory_write` (scope writes, `scope_write`).+`memory_write` (scope writes, `scope_write`). Its `invalid_params` note names `recall`'s 2,000-character question+limit: a longer question is refused with reason `question_too_long` and detail `max_chars=2000 received_chars=<n>`,+never cut.Operator setup is in [docs/guides/qm.md](../../guides/qm.md).diff --git a/docs/contracts/qm-memory-provider/v2.json b/docs/contracts/qm-memory-provider/v2.jsonindex 8a176ba97e..0f1db89202 100644--- a/docs/contracts/qm-memory-provider/v2.json+++ b/docs/contracts/qm-memory-provider/v2.json@@ -355,7 +355,7 @@"class": "caller","summary": "A parameter is missing, has the wrong type, or has an invalid value.","docs": "docs/guides/error-codes.md#invalid_params",- "note": "Bad arguments, refused before anything is saved. A reused idempotency_key with different facts carries write_error idempotency_conflict; a claim the person forgot carries the fact_withdrawn message. A memory_write whose source_id is the credential's own source carries reason source_is_member_source (omit source_id instead)."+ "note": "Bad arguments, refused before anything is saved. A reused idempotency_key with different facts carries write_error idempotency_conflict; a claim the person forgot carries the fact_withdrawn message. A memory_write whose source_id is the credential's own source carries reason source_is_member_source (omit source_id instead). recall refuses a question over 2000 UTF-16 code units with reason question_too_long and detail max_chars=2000 received_chars=<n>; nothing is read and the question is never cut, so shorten it and retry."},{"code": "scope_denied",diff --git a/docs/guides/qm.md b/docs/guides/qm.mdindex 744b3f408a..cb859d3647 100644--- a/docs/guides/qm.md+++ b/docs/guides/qm.md@@ -30,7 +30,10 @@ a repo exists, saved facts go through the same git-first writer door as `remembefirst, then the facts they may read ranked by `query`. Never page bodies. The textholds as many whole lines as fit, with no marker line (every line is one fact;`structuredContent.truncated` says some were left out), and never exceeds `max_chars`- (a whole number of UTF-16 code units, 200-12000, default 6000). Each fact is+ (a whole number of UTF-16 code units, 200-12000, default 6000). `query` is ranked+ on its first 2,000 characters. `recall`'s `question` is capped at 2,000: a longer one is+ refused `invalid_params` with reason `question_too_long` and detail+ `max_chars=2000 received_chars=<n>`, nothing is read, so trim it before calling. Each fact isone line: line breaks and control characters in it become spaces. Ranking iskeyword-only on a keyless brain. A call that names sources (`source_id`,`source_ids`, narrowed inside the credential's grant) reads as that scope,diff --git a/scripts/build-qm-memory-contract.ts b/scripts/build-qm-memory-contract.tsindex 8c7875e99b..0713deff1b 100644--- a/scripts/build-qm-memory-contract.ts+++ b/scripts/build-qm-memory-contract.ts@@ -14,6 +14,7 @@ import { paramDefToSchema } from '../src/mcp/tool-defs.ts';import { CODES } from '../src/core/error-registry.ts';import { ACTOR_ARGUMENT, ACTOR_DEFERRED_OPS, ACTOR_HEADER, DEFAULT_ATTEST_OPS, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER } from '../src/core/access/actor-model.ts';import { SCOPE_PAGE_SLUG } from '../src/core/access/principals.ts';+import { QUESTION_MAX_CHARS } from '../src/core/facts/question-recall.ts';import { IDEMPOTENCY_KEY_RE, MEMORY_RECALL_MAX_CHARS, MEMORY_RECALL_QUERY_CHARS, MEMORY_WRITE_KINDS, MEMORY_WRITE_MAX_FACTS, MEMORY_WRITE_PROVENANCE_MAX, OWN_RECENT_WINDOW_HOURS, QM_MEMORY_OPS, unlinkedRecallResult } from '../src/core/ops/qm-memory.ts';export type QmContractVersion = 1 | 2;@@ -77,7 +78,7 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<stringconst codes = v2 ? [...ERROR_CODES, 'permission_denied' as const] : ERROR_CODES;const notes: Record<string, string | undefined> = v2 ? { ...ERROR_NOTES,actor_not_attested: 'With no x-qm-actor header, acting_user is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it); the call then runs exactly as the credential.',- invalid_params: `${ERROR_NOTES.invalid_params} A memory_write whose source_id is the credential's own source carries reason source_is_member_source (omit source_id instead).`,+ invalid_params: `${ERROR_NOTES.invalid_params} A memory_write whose source_id is the credential's own source carries reason source_is_member_source (omit source_id instead). recall refuses a question over ${QUESTION_MAX_CHARS} UTF-16 code units with reason question_too_long and detail max_chars=${QUESTION_MAX_CHARS} received_chars=<n>; nothing is read and the question is never cut, so shorten it and retry.`,permission_denied: 'memory_recall named a source (source_id or source_ids) outside the credential\'s read grant; nothing was read. memory_write named a source_id that is not one of the credential\'s scope sources (reason source_not_attested, also at publication after the operator drops it), or the scope page names readers (reason scope_page_not_shared); nothing was saved.' } : ERROR_NOTES;return {contract: 'gbrain.qm-memory-provider', version,diff --git a/src/core/facts/question-recall.ts b/src/core/facts/question-recall.tsindex c0aba1a4fc..c7f9ed30e1 100644--- a/src/core/facts/question-recall.ts+++ b/src/core/facts/question-recall.ts@@ -91,8 +91,8 @@ export function recallArgv(args: Record<string, unknown>): string[] {}/** An `invalid_params` refusal whose fix is the same recall with `retry` arguments. */-function invalidQuestionCall(message: string, suggestion: string, retry: Record<string, unknown>, why: string) {- const e = opError('invalid_params', message, suggestion, {+function invalidQuestionCall(message: string, suggestion: string, retry: Record<string, unknown>, why: string, cause: { reason?: string; detail?: string } = {}) {+ const e = opError('invalid_params', message, suggestion, { ...cause,fix: { argv: recallArgv(retry), mcp: { tool: 'recall', arguments: retry }, consent: [], actor: 'agent', requires_exclusive: false, why },});e.protocolVersion = MEMORY_VERBS_VERSION;@@ -120,7 +120,8 @@ export function parseQuestionParam(p: Record<string, unknown>): string | null {}if (question.length > QUESTION_MAX_CHARS) {throw invalidQuestionCall(`question is ${question.length} characters; the limit is ${QUESTION_MAX_CHARS}.`,- `Shorten question to at most ${QUESTION_MAX_CHARS} characters.`, { ...args, question: question.slice(0, QUESTION_MAX_CHARS) }, `The same recall with question cut to ${QUESTION_MAX_CHARS} characters.`);+ `Shorten question to at most ${QUESTION_MAX_CHARS} characters.`, { ...args, question: question.slice(0, QUESTION_MAX_CHARS) }, `The same recall with question cut to ${QUESTION_MAX_CHARS} characters.`,+ { reason: 'question_too_long', detail: `max_chars=${QUESTION_MAX_CHARS} received_chars=${question.length}` });}return question;}diff --git a/test/recall-question-limit.test.ts b/test/recall-question-limit.test.tsnew file mode 100644index 0000000000..76db1618ea--- /dev/null+++ b/test/recall-question-limit.test.ts@@ -0,0 +1,51 @@+/**+ * GST-1304 (HARN-31): recall refuses a question over QUESTION_MAX_CHARS. A provider that fails open on any refusal+ * turned that into "no facts" silently, because nothing in the structured error told the over-long question apart+ * from other bad input. The refusal now carries reason question_too_long with the limit and the received length, and+ * the server never truncates (the call is refused, nothing is read).+ *+ * 1. Protects: an over-long recall question over MCP dispatch is refused invalid_params with reason+ * question_too_long and detail `max_chars=<limit> received_chars=<n>`; a question at the limit is read.+ * 2. Fails when: the refusal loses its reason or numbers, or the server starts cutting the question.+ * 3. Existing coverage: test/recall-question.test.ts pins the message and the fix's shortened retry.+ * 4. Real seams: PGLite, MCP dispatch as a remote caller; no providers.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import type { BrainEngine } from '../src/core/engine.ts';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { dispatchToolCall } from '../src/mcp/dispatch.ts';+import { QUESTION_MAX_CHARS } from '../src/core/facts/question-recall.ts';+import type { AuthInfo } from '../src/core/ops/contract.ts';++describe('recall question limit (pglite)', () => {+ let engine: BrainEngine;+ beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({ engine: 'pglite' } as never);+ await engine.initSchema();+ }, 120_000);+ afterAll(async () => { await engine.disconnect(); });++ const recall = async (question: string) => {+ const auth = { token: 't', clientId: 'c', scopes: ['read'], sourceId: 'default' } as unknown as AuthInfo;+ const out = await dispatchToolCall(engine, 'recall', { question, caller: 'provider' }, { remote: true, transport: 'http', auth, sourceId: 'default', takesHoldersAllowList: ['world'] });+ const text = out.content.map(c => c.text).join('\n');+ let json: Record<string, any> = {};+ try { json = JSON.parse(text); } catch { /* not JSON */ }+ return { isError: out.isError === true, json, structured: out.structuredContent as Record<string, any> | undefined };+ };++ test('a question over the limit is refused with reason question_too_long, the limit and the received length', async () => {+ const question = 'what did we decide about the launch '.repeat(84).trim();+ expect(question.length).toBeGreaterThan(QUESTION_MAX_CHARS);+ const out = await recall(question);+ expect(out.isError).toBe(true);+ expect(out.json).toMatchObject({ code: 'invalid_params', reason: 'question_too_long', detail: `max_chars=${QUESTION_MAX_CHARS} received_chars=${question.length}` });+ expect(out.json.message).toContain(String(QUESTION_MAX_CHARS));+ });++ test('a question at the limit is read, not refused', async () => {+ const out = await recall('x'.repeat(QUESTION_MAX_CHARS));+ expect(out.isError).toBe(false);+ });+});