Skip to content

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.md
index 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 by
A 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.json
index 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.md
index 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 `remembe
first, then the facts they may read ranked by `query`. Never page bodies. The text
holds 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 is
one line: line breaks and control characters in it become spaces. Ranking is
keyword-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.ts
index 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<string
const 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+});