Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(loops): an unreadable sources table is unknown coverage, not an empty inbox

garrytan5daad41ae040
diff --git a/docs/guides/open-loops.md b/docs/guides/open-loops.md
index 01a9de49da..524c381b3e 100644
--- a/docs/guides/open-loops.md
+++ b/docs/guides/open-loops.md
@@ -378,7 +378,10 @@ instead: the answer covered only the sources the call read (named, all inside
the grant), pass `source_id` for a granted google source, and the fix lists
them.
The notice never names a source outside the grant, so it reads the same
-whether or not one exists.
+whether or not one exists. When the sources table cannot be read at all, the
+answer carries `no_google_sources: null` and `completeness: "partial"` with
+a `loops_source_read_failed` notice (no database error text): presence, sync
+ages and held mail are unknown, so an empty answer is not "inbox clean".
Memory verbs: entity cards' `open_threads[]` entries backed by loop rows
carry additive optional fields (`direction`, `due`, `counterparty`,
diff --git a/plugin/skills/google-loops/SKILL.md b/plugin/skills/google-loops/SKILL.md
index 6bc949bc2b..cc30ec2bf8 100644
--- a/plugin/skills/google-loops/SKILL.md
+++ b/plugin/skills/google-loops/SKILL.md
@@ -117,7 +117,8 @@ gbrain loops drop sender <email> --dry-run # preview closing one sender's repl
exact fix (`gbrain sync --source <id>`). Run the sync, then retry. Only
use `--stale-ok` when the user explicitly accepts stale results.
- `completeness: "partial"` means some mail in the last 14 days is held after
- repeated import failures (listed in `held`). Present the answer as partial:
+ repeated import failures (listed in `held`), or, with `no_google_sources:
+ null`, the sources could not be read (retry). Present the answer as partial:
name each held item (sender, and subject when shown) and its retry command
(`gbrain sources retry-held <id>`). Never say "you are clean" on a partial
answer.
diff --git a/skills/google-loops/SKILL.md b/skills/google-loops/SKILL.md
index 162b5d3031..d5f927b909 100644
--- a/skills/google-loops/SKILL.md
+++ b/skills/google-loops/SKILL.md
@@ -116,7 +116,8 @@ gbrain loops drop sender <email> --dry-run # preview closing one sender's repl
exact fix (`gbrain sync --source <id>`). Run the sync, then retry. Only
use `--stale-ok` when the user explicitly accepts stale results.
- `completeness: "partial"` means some mail in the last 14 days is held after
- repeated import failures (listed in `held`). Present the answer as partial:
+ repeated import failures (listed in `held`), or, with `no_google_sources:
+ null`, the sources could not be read (retry). Present the answer as partial:
name each held item (sender, and subject when shown) and its retry command
(`gbrain sources retry-held <id>`). Never say "you are clean" on a partial
answer.
diff --git a/skills/skills.lock.json b/skills/skills.lock.json
index 76abef9092..b124c19aca 100644
--- a/skills/skills.lock.json
+++ b/skills/skills.lock.json
@@ -89,7 +89,7 @@
"functional-area-resolver/routing-eval.jsonl": "f80674d915acdfe229046737a5b171da834be15ac6524b5a3fd18048e9b37028",
"gbrain-advisor/SKILL.md": "976b3c5c3798f9fec764fa5bacd1567f751875bd837fe188a0c6df041805ed51",
"gbrain-upgrade/SKILL.md": "8f3082539194ffd6d7f4ad1fa85e4b993ed6d8731f8ea83a28558d852a009f93",
- "google-loops/SKILL.md": "20955fac0a94bbe9298a8aa7416e851cac86eb145bc551ed0fc556d2f583fa5e",
+ "google-loops/SKILL.md": "47c0046e9e5ec9806540aa271113933433c9bfd5df9320a880b8933602d1d5e3",
"idea-ingest/SKILL.md": "863be3660ead12a45d3b86309d73df0ffda6c5db6ca69873cce1810680df79b4",
"idea-lineage/SKILL.md": "8cb36179dbf94abc17065613b8e773b1bb2b22670742aa77347b91ac885a05c5",
"idea-lineage/routing-eval.jsonl": "ee2e00704b9accb7dd58bb8f126a3bc04a2c40be499180fa505dbf6d5061cd41",
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index af6d21fed8..8a402ee697 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -974,6 +974,7 @@ export const NOTICE_CODES = {
alias_fanout: { kind: 'info', summary: 'search fanned out over an entity\'s other names and stopped at the per-call cap; the skipped names are listed and can be searched directly.' },
search_filter_hint: { kind: 'info', summary: 'A search or query looked like it wanted a filter it did not pass (the query names a page type or a time, or one type fills the top results); the notice names types, since/until or where and the call to repeat. Results are unchanged.' },
graph_walk_truncated: { kind: 'degraded', summary: 'traverse_graph stopped at its walk cap (pages visited or edge rows), so the deepest edges were dropped and the result is not the whole neighborhood; above depth 1 the fix repeats the walk one level shallower with the same link_type and direction; at depth 1 it carries no fix, so narrow with link_type or direction.' },
+ loops_source_read_failed: { kind: 'degraded', summary: 'open_loops could not read the sources table, so google-source presence, sync ages and held mail are unknown: the answer carries no_google_sources: null and completeness: "partial", and an empty answer is not "inbox clean". The notice carries no database error text; repeat the call.' },
loops_no_google_in_scope: { kind: 'info', summary: 'A remote open_loops call read no google source, so the empty answer is not "inbox clean"; the notice names only the sources the call read, all inside the caller\'s grant (never one outside it) and the fix lists them for source_id.' },
mention_index: { kind: 'degraded', summary: 'The entity mention index is pending, off, failed or does not cover this page type, so references listed for an entity may be incomplete.' },
degraded_recall: { kind: 'degraded', summary: 'A retrieval stage that affects recall did not run; an empty or thin result is not proof of absence. A failed rerank names its reason (timeout, budget, rate_limited, unreachable, auth, provider_error), the fused-order fallback and the session\'s count of reranker-degraded calls; timeout and rate_limited say to repeat the call after a delay, the rest point at doctor\'s reranker_health.' },
diff --git a/src/core/notice-ledger.ts b/src/core/notice-ledger.ts
index 5c7ff10fe9..f04149b311 100644
--- a/src/core/notice-ledger.ts
+++ b/src/core/notice-ledger.ts
@@ -34,7 +34,7 @@ export const COACHING_BUDGET_PER_SESSION = 2;
/** The one muteable `ask`: an unanswered first-run bundle must stay dismissible. Every other ask always shows. */
export const MUTEABLE_ASK_CODES: ReadonlySet<string> = new Set(['first_run_decisions']);
/** Notices that describe THIS call's result (never deduped unless the notice carries a `dedupe_key`): the diagnosis must ride every affected call. */
-export const PER_CALL_NOTICE_CODES: ReadonlySet<string> = new Set(['degraded_recall', 'hidden_tool_content', 'empty_retrieval', 'unknown_param', 'listing_truncated', 'former_relationships_hidden', 'source_binding_narrowed', 'local_transcripts', 'held_files', 'relational_chain', 'graph_walk_truncated', 'mention_index', 'delta_incomplete', 'identity_siblings_capped', 'references_unavailable', 'record_types_undeclared', 'alias_fanout', 'facts_unembedded', 'loops_no_google_in_scope']);
+export const PER_CALL_NOTICE_CODES: ReadonlySet<string> = new Set(['degraded_recall', 'hidden_tool_content', 'empty_retrieval', 'unknown_param', 'listing_truncated', 'former_relationships_hidden', 'source_binding_narrowed', 'local_transcripts', 'held_files', 'relational_chain', 'graph_walk_truncated', 'mention_index', 'delta_incomplete', 'identity_siblings_capped', 'references_unavailable', 'record_types_undeclared', 'alias_fanout', 'facts_unembedded', 'loops_no_google_in_scope', 'loops_source_read_failed']);
/** How long a shown coverage state (a notice's `escalation`) stays shown. */
export const COVERAGE_NOTICE_WINDOW_MS = 30 * 60 * 1000;
diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.ts
index 4f3cba05e1..54fe1e5f54 100644
--- a/src/core/operation-manifest.generated.ts
+++ b/src/core/operation-manifest.generated.ts
@@ -7246,7 +7246,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"mutating": false,
"idempotent": true,
"outputRedaction": "retrieval",
- "description": "The open-loop engine's killer output: who is waiting on you, what you promised, and the context needed to respond. Grouped by counterparty (default, ranked; each group shows at most 5 loops, the rest counted in loops_omitted) or flat. Loops that name no counterparty are never ranked as a person: they come back in no_counterparty (null when none). Loops come from the deterministic Gmail thread-state detector and the LLM commitment extractor. Remote callers get redacted evidence (no verbatim quotes); trusted local callers also get quotes, Gmail deep links, entity-card context, and a pre-rendered text digest. Carries google-source freshness (stale flag) and completeness: when it is \"partial\", some mail in the window is held after repeated import failures; present the answer as partial and name the held items and their retry command. The grouped view also returns withheld_noise (null when none): open reply-owed loops from senders whose mail the detector now treats as automated, with a per-sender preview_command for closing them.",
+ "description": "The open-loop engine's killer output: who is waiting on you, what you promised, and the context needed to respond. Grouped by counterparty (default, ranked; each group shows at most 5 loops, the rest counted in loops_omitted) or flat. Loops that name no counterparty are never ranked as a person: they come back in no_counterparty (null when none). Loops come from the deterministic Gmail thread-state detector and the LLM commitment extractor. Remote callers get redacted evidence (no verbatim quotes); trusted local callers also get quotes, Gmail deep links, entity-card context, and a pre-rendered text digest. Carries google-source freshness (stale flag) and completeness: when it is \"partial\", some mail in the window is held after repeated import failures (or, with no_google_sources: null, the sources could not be read); present the answer as partial and name the held items and their retry command. The grouped view also returns withheld_noise (null when none): open reply-owed loops from senders whose mail the detector now treats as automated, with a per-sender preview_command for closing them.",
"params": {
"group_by": {
"type": "string",
diff --git a/src/core/ops/loops.ts b/src/core/ops/loops.ts
index 3d74e6c328..554d8ca7c2 100644
--- a/src/core/ops/loops.ts
+++ b/src/core/ops/loops.ts
@@ -342,19 +342,21 @@ function renderNoCounterparty(lines: string[], none: NoCounterpartyLoops | null,
if (none.loops_omitted > 0) lines.push(`+${none.loops_omitted} more`);
}
-function renderText(groups: CounterpartyGroup[], none: NoCounterpartyLoops | null, stale: boolean, noGoogleSources: boolean,
+function renderText(groups: CounterpartyGroup[], none: NoCounterpartyLoops | null, stale: boolean, noGoogleSources: boolean | null,
coverage: { completeness: 'complete' | 'partial'; held: HeldItemView[] }, nowMs: number,
partialStaleSources: string[]): string {
const lines: string[] = [];
const { held } = coverage;
- if (stale) lines.push('⚠ google sources have not synced recently — this may be out of date.');
+ if (noGoogleSources === null) lines.push('⚠ the sources could not be read — whether a google source exists and when it last synced are unknown.');
+ else if (stale) lines.push('⚠ google sources have not synced recently — this may be out of date.');
else if (partialStaleSources.length > 0) {
lines.push(
`⚠ some google sources have not synced recently — this may be out of date: ${partialStaleSources.join(', ')}.`,
);
}
const partial = coverage.completeness === 'partial';
- const what = held.length ? `${held.length} held item(s) could not be imported:` : 'the held-item state could not be read.';
+ const what = noGoogleSources === null ? 'the sources could not be read, so held mail is unknown.'
+ : held.length ? `${held.length} held item(s) could not be imported:` : 'the held-item state could not be read.';
if (partial && groups.length === 0 && !none) {
lines.push(`No open loops found, but coverage is partial: ${what}`, ...partialLines(held));
return lines.join('\n');
@@ -403,7 +405,8 @@ const open_loops: Operation = {
'deterministic Gmail thread-state detector and the LLM commitment extractor. Remote callers get ' +
'redacted evidence (no verbatim quotes); trusted local callers also get quotes, Gmail deep links, ' +
'entity-card context, and a pre-rendered text digest. Carries google-source freshness (stale flag) and ' +
- 'completeness: when it is "partial", some mail in the window is held after repeated import failures; present the ' +
+ 'completeness: when it is "partial", some mail in the window is held after repeated import failures (or, with ' +
+ 'no_google_sources: null, the sources could not be read); present the ' +
'answer as partial and name the held items and their retry command. The grouped view also returns withheld_noise ' +
'(null when none): open reply-owed loops from senders whose mail the detector now treats as automated, with a ' +
'per-sender preview_command for closing them.',
@@ -484,10 +487,12 @@ const open_loops: Operation = {
limit: 500,
});
const freshness = await googleSourceFreshness(ctx, scope);
- const noGoogleSources = freshness.sources.length === 0;
- if (!trusted && noGoogleSources && !freshness.failed && loops.length === 0) ctx.emitNotice?.(noGoogleInScopeNotice(scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : [])));
+ // #8452: a failed sources read proves neither that no google source exists nor that coverage is complete.
+ const noGoogleSources = freshness.failed ? null : freshness.sources.length === 0;
+ if (freshness.failed) ctx.emitNotice?.(SOURCES_UNREADABLE_NOTICE);
+ else if (!trusted && noGoogleSources && loops.length === 0) ctx.emitNotice?.(noGoogleInScopeNotice(scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : [])));
const partialStaleSources = freshness.stale ? [] : freshness.staleSources;
- const coverage = await heldCoverage(ctx, freshness.sources, trusted);
+ const coverage = freshness.failed ? { completeness: 'partial' as const, held: [] } : await heldCoverage(ctx, freshness.sources, trusted);
const deepLinks = trusted ? await deepLinksFor(ctx, loops) : new Map<string, string>();
const truncated = loops.length >= 500;
@@ -638,6 +643,14 @@ function sourcesFix(why: string): Action {
return readFix(why, { argv: ['gbrain', 'sources', 'list', '--json'], mcp: { tool: 'sources_list', arguments: {} } });
}
+/** #8452: carries no database error text; the answer is partial until a read succeeds. */
+const SOURCES_UNREADABLE_NOTICE: Notice = {
+ code: 'loops_source_read_failed',
+ kind: 'degraded',
+ why: 'open_loops could not read the sources table, so whether a google source is in scope, when it last synced and which mail is held ' +
+ 'are unknown (no_google_sources: null, completeness: "partial"). An empty answer is not "inbox clean"; repeat the call.',
+};
+
/** #7286: names only the sources this read covered, all inside the grant, so the text is the same whether or not a google source exists outside it. */
function noGoogleInScopeNotice(readSources: string[]): Notice {
return {
diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.json
index c742bbcd5b..5e4f4f47df 100644
--- a/test/fixtures/goldens/cli/tools-json.json
+++ b/test/fixtures/goldens/cli/tools-json.json
@@ -2,8 +2,8 @@
"golden": {
"exitCode": 0,
"stderr": "",
- "stdoutBytes": 282967,
- "stdoutSha256": "73f135de04ba7cceced4d9fd952b23aaefd7fb4cad5ebdf3dce1aca953c70f84",
+ "stdoutBytes": 283033,
+ "stdoutSha256": "f698a68968d8942088681385a6f62f73ce04d30ea4b3641761d61234a79af1f4",
"toolNames": [
"remember",
"entity",
@@ -8399,7 +8399,7 @@
"scope": "admin"
},
{
- "description": "The open-loop engine's killer output: who is waiting on you, what you promised, and the context needed to respond. Grouped by counterparty (default, ranked; each group shows at most 5 loops, the rest counted in loops_omitted) or flat. Loops that name no counterparty are never ranked as a person: they come back in no_counterparty (null when none). Loops come from the deterministic Gmail thread-state detector and the LLM commitment extractor. Remote callers get redacted evidence (no verbatim quotes); trusted local callers also get quotes, Gmail deep links, entity-card context, and a pre-rendered text digest. Carries google-source freshness (stale flag) and completeness: when it is \"partial\", some mail in the window is held after repeated import failures; present the answer as partial and name the held items and their retry command. The grouped view also returns withheld_noise (null when none): open reply-owed loops from senders whose mail the detector now treats as automated, with a per-sender preview_command for closing them.",
+ "description": "The open-loop engine's killer output: who is waiting on you, what you promised, and the context needed to respond. Grouped by counterparty (default, ranked; each group shows at most 5 loops, the rest counted in loops_omitted) or flat. Loops that name no counterparty are never ranked as a person: they come back in no_counterparty (null when none). Loops come from the deterministic Gmail thread-state detector and the LLM commitment extractor. Remote callers get redacted evidence (no verbatim quotes); trusted local callers also get quotes, Gmail deep links, entity-card context, and a pre-rendered text digest. Carries google-source freshness (stale flag) and completeness: when it is \"partial\", some mail in the window is held after repeated import failures (or, with no_google_sources: null, the sources could not be read); present the answer as partial and name the held items and their retry command. The grouped view also returns withheld_noise (null when none): open reply-owed loops from senders whose mail the detector now treats as automated, with a per-sender preview_command for closing them.",
"idempotent": true,
"local_only": false,
"mutating": false,
diff --git a/test/loops-source-read-failure-8452.test.ts b/test/loops-source-read-failure-8452.test.ts
new file mode 100644
index 0000000000..bb5e44aae5
--- /dev/null
+++ b/test/loops-source-read-failure-8452.test.ts
@@ -0,0 +1,67 @@
+/**
+ * #8452: when open_loops cannot read the sources table it does not know
+ * whether a google source exists, so it must not answer
+ * `no_google_sources: true` with `completeness: "complete"` (an empty,
+ * complete inbox). PGLite with the sources read failing, remote and local.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { loopsOperations } from '../src/core/ops/loops.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import type { Notice } from '../src/core/agent-output.ts';
+
+let engine: PGLiteEngine;
+const openLoops = loopsOperations.find(o => o.name === 'open_loops')!;
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+ await engine.executeRaw(`INSERT INTO sources (id, name, config, last_sync_at) VALUES ('source-a', 'source-a', '{"kind":"google"}'::jsonb, now()) ON CONFLICT (id) DO NOTHING`);
+});
+afterAll(async () => { await engine.disconnect(); });
+
+function failingSources(base: BrainEngine): BrainEngine {
+ return new Proxy(base, { get(t, k, r) {
+ if (k === 'executeRaw') return (sql: string, params?: unknown[]) => /FROM sources WHERE archived/.test(sql)
+ ? Promise.reject(new Error('connection reset by peer at db-host-example')) : t.executeRaw(sql, params as never);
+ const v = Reflect.get(t, k, r); return typeof v === 'function' ? v.bind(t) : v;
+ } });
+}
+
+async function call(e: BrainEngine, remote: boolean, params: Record<string, unknown> = {}) {
+ const notices: Notice[] = [];
+ const ctx = { engine: e, config: {}, logger: { info() {}, warn() {}, error() {} }, dryRun: false, remote, sourceId: 'source-a',
+ emitNotice: (n: Notice) => notices.push(n) } as unknown as OperationContext;
+ const result = await openLoops.handler(ctx, { include_context: false, ...params }) as Record<string, unknown>;
+ return { result, notices };
+}
+
+describe('#8452 open_loops with an unreadable sources table', () => {
+ for (const view of [{}, { group_by: 'none' }]) {
+ test(`reports source presence unknown and coverage partial (${JSON.stringify(view)})`, async () => {
+ const { result, notices } = await call(failingSources(engine), true, view);
+ expect(result.no_google_sources).toBeNull();
+ expect(result.completeness).toBe('partial');
+ expect(result.stale).toBe(true);
+ expect(notices.map(n => n.code)).toContain('loops_source_read_failed');
+ expect(notices.map(n => n.code)).not.toContain('loops_no_google_in_scope');
+ expect(JSON.stringify({ result, notices })).not.toContain('db-host-example');
+ });
+ }
+
+ test('the trusted digest says the sources could not be read, not "no google source" or "clean"', async () => {
+ const { result } = await call(failingSources(engine), false);
+ expect(result.text).toContain('could not be read');
+ expect(result.text).not.toContain('No google source is connected');
+ expect(result.text).not.toContain('You are clean');
+ });
+
+ test('a readable sources table answers as before', async () => {
+ const { result, notices } = await call(engine, true);
+ expect(result.no_google_sources).toBe(false);
+ expect(result.completeness).toBe('complete');
+ expect(notices.map(n => n.code)).not.toContain('loops_source_read_failed');
+ });
+});