Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { submitPageMutation } from '../persistence/page-mutations.ts';
import { recordFunnelEvent } from '../funnel.ts';
import { MERGE_PRECONDITION_PARAMS, WRITE_REQUEST_PARAM } from '../persistence/params.ts';
/**
* Takes + think operation cluster — pure move from operations.ts (v0.46.x
* tranche 1). Op consts stay module-private; `takesOperations` below lists
* them in EXACTLY the order they appear in the canonical `operations` array
* in ../operations.ts. Never import from '../operations.ts' here (cycle).
*/
import { opError, type Operation, type OperationContext } from './contract.ts';
import { MIN_TRUST_PARAM, resolveReadEligibility } from '../eligibility/policy.ts';
import { stampRowTrust } from '../eligibility/stamp.ts';
import { fenceTranscriptText, quotesTier, unquoteTranscriptText } from '../search/transcript-quote.ts';
import { opTransport, paramUse } from './op-fix.ts';
import {
readPolicyOpts,
readHolders,
sourceScopeOpts,
thinkSourceScopeOpts,
enforceClientSlugFence,
validatePageSlug,
} from './context.ts';
import { embedQueryWithPrefix } from '../search/query-prefix.ts';
import { ALL_SOURCES } from '../source-id.ts';
import { privatePagesFilterForCaller } from '../search/private-visibility.ts';
import { keepRoomEvidence } from '../access/room.ts';
/** Result pages whose takes D2 checks: the page a get_page read returned, or the first distinct pages of a search/query. */
const HIDDEN_TAKES_PAGE_CAP = 3;
/**
* D2: page reads, search and query never show the takes table to an
* agent-facing reader. For the pages this result returned, the takes
* `takes_list` would list on this connection (same source scope, holder
* allow-list and read eligibility), counted, capped at 100 per page. Null
* when the result has no page with such takes. Slugs come from the result.
*/
export async function takesHiddenFromResult(ctx: OperationContext, op: string, result: unknown): Promise<{ pages: string[]; count: number } | null> {
if (ctx.remote === false) return null;
const rows = op === 'get_page' ? [result] : (op === 'search' || op === 'query') && Array.isArray(result) ? result : [];
const pages = new Map<string, string | undefined>();
for (const row of rows) {
if (pages.size >= HIDDEN_TAKES_PAGE_CAP) break;
const r = row as { slug?: unknown; source_id?: unknown; result_type?: unknown } | null;
if (!r || typeof r.slug !== 'string' || (r.result_type !== undefined && r.result_type !== 'page')) continue;
const source = typeof r.source_id === 'string' ? r.source_id : undefined;
const key = `${source ?? ''}\u0000${r.slug}`;
if (!pages.has(key)) pages.set(key, source);
}
if (pages.size === 0) return null;
const eligibility = await resolveReadEligibility(ctx, {});
const counted = await Promise.all([...pages].map(async ([key, source]) => {
const slug = key.slice(key.indexOf('\u0000') + 1);
const policy = await readPolicyOpts(ctx, ...(source ? [{ sourceId: source }] : []));
const takes = await ctx.engine.listTakes({ ...policy, page_slug: slug, takesHoldersAllowList: readHolders(ctx), eligibility, limit: 100 });
return { slug, count: takes.length };
}));
const withTakes = counted.filter(c => c.count > 0);
if (!withTakes.length) return null;
return { pages: [...new Set(withTakes.map(c => c.slug))], count: withTakes.reduce((n, c) => n + c.count, 0) };
}
/** GST-687: a remote reader gets a claim below the owner's tier (an agent's take, an ingested one) quoted as its page's, with its free-text sources. */
function quoteTakes<T extends { claim: string; page_slug: string; trust_tier: string; source?: string | null; resolved_source?: string | null }>(ctx: OperationContext, rows: T[]): Array<T | (T & { quoted: 'transcript' })> {
if (ctx.remote === false) return rows;
return rows.map(r => {
if (!quotesTier(r.trust_tier)) return r;
const fence = (text: string) => fenceTranscriptText(text, r.page_slug);
return { ...r, claim: fence(r.claim), ...(r.source ? { source: fence(r.source) } : {}), ...(r.resolved_source ? { resolved_source: fence(r.resolved_source) } : {}), quoted: 'transcript' as const };
});
}
/** #8377: a claim or source an agent copied out of a quoted takes read is written without the fence. */
function unquotedTakeParams(ctx: OperationContext, p: Record<string, unknown>): Record<string, unknown> {
if (ctx.remote === false) return p;
const slug = String(p.slug).toLowerCase();
const unquote = (key: string) => typeof p[key] === 'string' ? { [key]: unquoteTranscriptText(p[key] as string, slug) } : {};
return { ...p, ...unquote('claim'), ...unquote('source') };
}
// --- v0.28: Takes ---
const takes_list: Operation = {
name: 'takes_list',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: 'List takes (typed/weighted/attributed claims) filtered by holder/kind/active/etc.',
scope: 'read',
params: {
page_slug: { type: 'string', description: 'Filter to this page' },
holder: { type: 'string', description: 'Filter to this holder (world|garry|brain|<slug>)' },
kind: { type: 'string', description: 'Filter to this kind (fact|take|bet|hunch)' },
active: { type: 'boolean', description: 'Active rows only (default true)' },
resolved: { type: 'boolean', description: 'true → only resolved bets; false → only unresolved' },
sort_by: { type: 'string', description: 'weight | since_date | created_at (default created_at)' },
limit: { type: 'number', description: 'Max rows (default 100, cap 500)' },
offset: { type: 'number', description: 'Skip first N rows' },
min_trust: MIN_TRUST_PARAM,
},
handler: async (ctx, p) => {
const eligibility = await resolveReadEligibility(ctx, { minTrust: p.min_trust });
const rows = await ctx.engine.listTakes({
// #2200-class: honor federated/source scope (via the take's page.source_id).
...await readPolicyOpts(ctx),
page_slug: p.page_slug as string | undefined,
holder: p.holder as string | undefined,
kind: p.kind as never,
active: p.active as boolean | undefined,
resolved: p.resolved as boolean | undefined,
sortBy: p.sort_by as never,
limit: p.limit as number | undefined,
offset: p.offset as number | undefined,
// Per-token allow-list — server-side filter for MCP-bound calls.
// Local CLI callers leave takesHoldersAllowList unset and see all holders.
takesHoldersAllowList: readHolders(ctx),
eligibility,
});
return quoteTakes(ctx, await stampRowTrust(ctx.engine, 'takes', rows, r => r.id));
},
cliHints: { name: 'takes-list' },
};
const takes_search: Operation = {
name: 'takes_search',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: 'Keyword search across takes (pg_trgm similarity over claim text)',
scope: 'read',
params: {
query: { type: 'string', required: true, description: "Search text matched against take claim text via trigram similarity, e.g. 'valuation cap'. This is the search text param — there is no `text` param." },
limit: { type: 'number', description: 'Max results (default 30, cap 100)' },
min_trust: MIN_TRUST_PARAM,
},
handler: async (ctx, p) => {
const eligibility = await resolveReadEligibility(ctx, { minTrust: p.min_trust });
const hits = await ctx.engine.searchTakes(p.query as string, {
...await readPolicyOpts(ctx),
limit: p.limit as number | undefined,
takesHoldersAllowList: readHolders(ctx),
eligibility,
});
return quoteTakes(ctx, await stampRowTrust(ctx.engine, 'takes', hits, h => h.take_id));
},
cliHints: { name: 'takes-search', positional: ['query'] },
};
/**
* v0.30.0 (Slice A1): aggregate calibration scorecard. Pure SQL aggregation.
*
* Privacy (D4 fail-closed): the engine method REQUIRES the takesHoldersAllowList
* param. The handler threads it from the OperationContext so MCP-bound callers
* see only their permitted holders' aggregate counts. Local CLI callers
* (ctx.takesHoldersAllowList=undefined) get the full scorecard.
*/
const takes_scorecard: Operation = {
name: 'takes_scorecard',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Calibration scorecard for resolved bets: counts, accuracy, Brier (correct ∨ incorrect only), partial_rate.',
scope: 'read',
params: {
holder: { type: 'string', description: 'Filter to this holder (world|garry|brain|<slug>)' },
domain_prefix: { type: 'string', description: 'Slug prefix (e.g. companies/) to scope the scorecard' },
since: { type: 'string', description: 'Window start (YYYY-MM-DD)' },
until: { type: 'string', description: 'Window end (YYYY-MM-DD)' },
group_by: { type: 'string', enum: ['holder', 'source'], description: 'Trusted local CLI only: per-group journal statistics' },
min_n: { type: 'number', minimum: 1, description: 'Trusted local CLI only: groups with fewer resolved predictions are flagged low_n (default 10)' },
},
handler: async (ctx, p) => {
// W7: the grouped journal statistics are private. A remote caller that
// asks for them is refused, never silently given today's output.
const grouped = p.group_by !== undefined || p.min_n !== undefined;
if (grouped && ctx.remote !== false) {
throw opError('scorecard_group_by_local_only', 'takes_scorecard: group_by and min_n read the private forecast journal and run only from the trusted local CLI.',
'Omit group_by and min_n, or ask the brain owner to run gbrain takes scorecard --group-by on the brain host.');
}
if (grouped && p.group_by !== 'holder' && p.group_by !== 'source') {
throw opError('invalid_params', 'takes_scorecard: group_by must be holder or source.', 'Pass group_by: "holder" or "source".');
}
if (p.min_n !== undefined && !(Number.isSafeInteger(p.min_n) && (p.min_n as number) >= 1)) {
throw opError('invalid_params', 'takes_scorecard: min_n must be a positive integer.', 'Pass min_n as a whole number, e.g. 10.');
}
const card = await ctx.engine.getScorecard(
{
...await readPolicyOpts(ctx),
holder: p.holder as string | undefined,
domainPrefix: p.domain_prefix as string | undefined,
since: p.since as string | undefined,
until: p.until as string | undefined,
},
readHolders(ctx),
);
// [OV8/EV5] Resolver-provenance visibility: remote resolutions are
// server-stamped resolved_by='mcp:<client>' (takes_resolve below), and
// this coarse count keeps agent-resolved rows segregable from owner
// ground truth. Op-layer SQL (plain executeRaw both engines share) —
// no engine method added, parity untouched. Unfiltered by the window/
// domain params (coarse by design; documented).
const base = { ...card, mcp_resolved: await countMcpResolved(ctx) };
if (!grouped) return base;
const { readForecastJournal, scorecardGroups } = await import('../forecast-journal.ts');
const scope = sourceScopeOpts(ctx);
const query = {
...(scope.sourceIds?.length ? { sourceIds: scope.sourceIds } : scope.sourceId ? { sourceId: scope.sourceId } : {}),
...(p.holder ? { holder: p.holder as string } : {}), ...(p.domain_prefix ? { about: p.domain_prefix as string } : {}),
...(p.since ? { since: p.since as string } : {}), ...(p.until ? { until: p.until as string } : {}),
};
return {
...base,
groups: await scorecardGroups(ctx.engine, { ...query, groupBy: p.group_by as 'holder' | 'source', ...(p.min_n !== undefined ? { minN: p.min_n as number } : {}) }),
journal: (await readForecastJournal(ctx.engine, { ...query, limit: 0 })).totals,
};
},
cliHints: { name: 'takes-scorecard' },
};
/**
* v0.30.0 (Slice A1): calibration curve binned by stated weight. Pure SQL.
* Same allow-list contract as takes_scorecard.
*/
const takes_calibration: Operation = {
name: 'takes_calibration',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Calibration curve: resolved correct/incorrect bets binned by stated weight; observed vs predicted per bucket.',
scope: 'read',
params: {
holder: { type: 'string', description: 'Filter to this holder' },
bucket_size: { type: 'number', description: 'Bucket width in (0,1]; default 0.1' },
},
handler: async (ctx, p) => {
// (The [OV8/EV5] mcp_resolved provenance count lives on takes_scorecard —
// this op's wire shape is a bare bucket ARRAY, so decorating it would be
// a breaking change; the scorecard is the segregation surface.)
return ctx.engine.getCalibrationCurve(
{
...await readPolicyOpts(ctx),
holder: p.holder as string | undefined,
bucketSize: p.bucket_size as number | undefined,
},
readHolders(ctx),
);
},
cliHints: { name: 'takes-calibration' },
};
/**
* [OV8/EV5] Count of resolved take rows whose resolved_by carries the MCP
* server-stamp prefix. Source-scoped + holder-allow-list-scoped like the
* aggregates it decorates; unfiltered by window/domain (coarse segregation
* signal, not a scorecard dimension).
*/
async function countMcpResolved(ctx: OperationContext): Promise<number> {
const scope = await readPolicyOpts(ctx);
const where: string[] = [`t.resolved_at IS NOT NULL`, `t.resolved_by LIKE 'mcp:%'`];
if (scope.excludePrivate) where.push(privatePagesFilterForCaller('p'));
const params: unknown[] = [];
if (scope.sourceIds && scope.sourceIds.length > 0) {
params.push(scope.sourceIds);
where.push(`p.source_id = ANY($${params.length}::text[])`);
} else if (scope.sourceId) {
params.push(scope.sourceId);
where.push(`p.source_id = $${params.length}`);
}
const holders = readHolders(ctx);
if (holders !== undefined) {
params.push(holders);
where.push(`t.holder = ANY($${params.length}::text[])`);
}
try {
const rows = await ctx.engine.executeRaw<{ n: string }>(
`SELECT count(*)::text AS n FROM takes t JOIN pages p ON p.id = t.page_id WHERE ${where.join(' AND ')}`,
params,
);
return parseInt(rows[0]?.n ?? '0', 10);
} catch {
// Decoration only — never fail the aggregate over the provenance count.
return 0;
}
}
/** runThink names the CLI flag; op callers get the param on their own surface and a caller-class code. */
function thinkModelError(ctx: OperationContext, e: unknown): unknown {
if (e instanceof Error && e.name === 'ReferenceDateError') {
return opError('invalid_params', `think: ${e.message}`,
`Nothing was synthesized. Pass ${opTransport(ctx) === 'cli' ? paramUse(ctx, 'reference_date') : '`reference_date`'} as a past or current YYYY-MM-DD, or omit it to use today in brain.timezone.`);
}
if (!(e instanceof Error) || !e.message.startsWith('think: --model ')) return e;
const name = opTransport(ctx) === 'cli' ? paramUse(ctx, 'model') : '`model`';
return opError('invalid_params',
e.message.replace('think: --model ', 'think: model ').replace(' or omit --model.', ' or omit it.'),
`Nothing was synthesized. Omit ${name} to use the configured think model (models.think, then models.default), or pass a model id this brain can reach.`);
}
export const THINK_REMOTE_MODELS_KEY = 'think.remote_models';
/**
* GBRA-437: a remote caller's think model. The host's own think model and any model the host
* lists in think.remote_models run; anything else runs the host model and reports why.
*/
async function remoteThinkModel(engine: OperationContext['engine'], requested: string | undefined): Promise<{ model?: string; ignored?: 'not_allowed' | 'unusable' }> {
if (!requested) return {};
const [{ resolveModel }, { normalizeModelId }, { probeChatModel, isAvailable }] = await Promise.all([
import('../model-config.ts'), import('../model-id.ts'), import('../ai/gateway.ts'),
]);
const resolve = async (cliFlag?: string) => normalizeModelId(await resolveModel(engine, { cliFlag, configKey: 'models.think', tier: 'deep', fallback: 'opus' }));
const [wanted, host, listed] = await Promise.all([resolve(requested), resolve(), engine.getConfig(THINK_REMOTE_MODELS_KEY)]);
if (wanted === host) return {};
const allowed = await Promise.all((listed ?? '').split(',').map(m => m.trim()).filter(Boolean).map(m => resolve(m)));
if (!allowed.includes(wanted)) return { ignored: 'not_allowed' };
return probeChatModel(wanted).ok && isAvailable('chat', wanted) ? { model: wanted } : { ignored: 'unusable' };
}
const think: Operation = {
name: 'think',
idempotent: false,
outputRedaction: 'retrieval',
description: 'Multi-hop synthesis across pages + takes + graph. Pulls relevant evidence and produces a cited answer with conflict + gap analysis. Needs a chat-model API key (Anthropic or OpenAI) for the synthesized answer, a paid call; a keyless brain returns the gathered evidence only (a synthesis_keyless notice explains). save/take persist for the local CLI only.',
scope: 'read',
params: {
question: { type: 'string', required: true, description: 'The question to think about' },
anchor: { type: 'string', description: 'Pull the entity subgraph around this slug' },
rounds: { type: 'number', description: 'Multi-pass: 1 (default). Round-loop scaffolding is in place; gap-driven retrieval ships in v0.29.' },
save: { type: 'boolean', description: 'Persist a synthesis page (local-CLI only; ignored for MCP)' },
take: { type: 'boolean', description: 'Append a take row to the anchor page (requires anchor)' },
model: { type: 'string', description: 'Model override (alias or full id). Falls through models.think → models.default → GBRAIN_MODEL → opus. Remote callers get the host think model unless the host lists this one in think.remote_models.' },
since: { type: 'string', description: 'Start of temporal window (YYYY-MM-DD or YYYY-MM). Omit both bounds and a question naming one explicit date (2026-09-15, 2026-09, September 2026) is bounded to it; the result says window_source.' },
until: { type: 'string', description: 'End of temporal window' },
reference_date: { type: 'string', description: 'YYYY-MM-DD the question\'s relative time words resolve against (default: today in brain.timezone).' },
},
// Local CLI can persist with save/take; remote/MCP callers are forced
// read-only below before runThink/persistSynthesis sees those flags.
mutating: true,
handler: async (ctx, p) => {
const remote = ctx.remote ?? true;
// Codex P1 #7 + privacy: remote callers cannot persist via MCP.
const safeSave = remote ? false : Boolean(p.save);
const safeTake = remote ? false : Boolean(p.take);
// v0.40.2.0: thread source-scope scalars + remote flag for trajectory
// injection. `sourceScopeOpts(ctx)` returns the federated array (when
// present) OR the scalar; we pass both through to runThink which
// forwards to findTrajectory. CLI callers don't go through this op
// and get default scope + remote=false from runThink's CLI path.
const thinkScope = thinkSourceScopeOpts(ctx);
const requestedModel = p.model ? String(p.model) : undefined;
const thinkModel = remote ? await remoteThinkModel(ctx.engine, requestedModel) : { model: requestedModel };
const { runThink, persistSynthesis } = await import('../think/index.ts');
const result = await runThink(ctx.engine, {
question: String(p.question),
// #3734: MCP think must populate the question vector for takes retrieval.
embedQuestion: (q) => embedQueryWithPrefix(ctx.engine, q),
anchor: p.anchor ? String(p.anchor) : undefined,
rounds: remote ? 1 : typeof p.rounds === 'number' ? (p.rounds as number) : undefined,
save: safeSave,
take: safeTake,
model: thinkModel.model,
// #1698: the local CLI hard-errors on an unusable explicit model. A remote
// model is already resolved against the host's allow-list above, so it never errors.
modelExplicit: !remote && !!requestedModel,
since: p.since ? String(p.since) : undefined,
until: p.until ? String(p.until) : undefined,
...(typeof p.reference_date === 'string' ? { referenceDate: p.reference_date } : {}),
takesHoldersAllowList: readHolders(ctx),
...thinkScope,
excludePrivate: (await readPolicyOpts(ctx)).excludePrivate,
remote: ctx.remote !== false, // fail-closed: anything not strictly false is untrusted (CLAUDE.md invariant)
}).catch((e: unknown) => { throw thinkModelError(ctx, e); });
result.answer = result.answer.replace(' or pass `client`', ' on the brain host');
// A6: the fallback cause is a provider error line, host posture an HTTP caller is never told.
if (ctx.transport === 'http') delete result.fallback_reason;
if (ctx.transport === 'http' && (result.synthesis_status === 'no_llm' || result.synthesis_status === 'model_unusable')) {
// A6 HTTP view: a remote caller is never told the host's key names or provider posture. The stub
// answer and gaps are prose for the operator; synthesis_status and the warning codes stay as data.
const { redactForTransport } = await import('../agent-output.ts');
result.answer = result.synthesis_status === 'no_llm'
? '(no LLM available on the brain host — the gathered evidence is returned without a synthesized answer)'
: redactForTransport(result.answer, 'http');
result.gaps = redactForTransport(result.gaps, 'http');
}
// Persist if --save was passed locally
let savedSlug: string | undefined;
let evidenceInserted = 0;
if (safeSave) {
const persisted = await persistSynthesis(ctx.engine, result, {
// '__all__' is a read scope, not a write destination: an unscoped save keeps the default source.
sourceId: ctx.sourceId === ALL_SOURCES ? undefined : ctx.sourceId,
...(thinkScope.allowedSources ? { allowedSources: thinkScope.allowedSources } : {}),
});
savedSlug = persisted.slug;
evidenceInserted = persisted.evidenceInserted;
for (const w of persisted.warnings) result.warnings.push(w);
}
// #2556: `take` was gated (safeTake) but never EXECUTED — runThink ignores
// opts.take, so a local `take: true` silently persisted nothing. Persist
// md-first through the canonical takes write-through; refusals surface as
// loud machine-stable warnings + take_row:null. Remote stays blocked above.
let takeRow: number | null = null;
if (safeTake) {
if (!p.anchor) {
result.warnings.push('TAKE_REQUIRES_ANCHOR');
} else {
const { persistTakeFromSynthesis } = await import('../think/persist-take.ts');
const persisted = await persistTakeFromSynthesis(ctx.engine, result, {
anchor: String(p.anchor),
sourceId: ctx.sourceId,
lockTimeoutMs: 2000,
});
takeRow = persisted.take_row;
for (const w of persisted.warnings) result.warnings.push(w);
}
}
// F8: the explanations the CLI formatter prints, as model-visible notices.
const { keylessThinkNotice, thinkNotSavedNotice, modelOverrideIgnoredNotice } = await import('../interop-notices.ts');
if (result.synthesis_status === 'no_llm') ctx.emitNotice?.(keylessThinkNotice());
if (thinkModel.ignored && result.synthesis_status !== 'no_llm') {
result.warnings.push(`MODEL_OVERRIDE_IGNORED:${thinkModel.ignored}`);
ctx.emitNotice?.(modelOverrideIgnoredNotice(thinkModel.ignored));
}
if (remote && (Boolean(p.save) || Boolean(p.take))) ctx.emitNotice?.(thinkNotSavedNotice());
const { recordThinkAnswer, feedbackMetaFields } = await import('../feedback/record.ts');
const feedbackMeta = feedbackMetaFields(await recordThinkAnswer(ctx, 'think', result));
const evidence = result.taint_refs && [...result.taint_refs, ...(result.room_extra ?? [])];
delete result.feedback_evidence; delete result.taint_refs; delete result.room_extra;
const { persist: _persist, persist_base: _persistBase, ...visible } = result;
// GBRA-498: a think answer going into a room is marked at the strictest class of everything it was built from.
return keepRoomEvidence({
...visible,
...feedbackMeta,
// #1698 (#10): the persist-skip signal returns slug '' — map it (and any
// falsy) to null so callers never see an empty-string "slug".
saved_slug: savedSlug || null,
evidence_inserted: evidenceInserted,
take_row: takeRow,
remote_persisted_blocked: remote && (Boolean(p.save) || Boolean(p.take)),
}, evidence);
},
// hidden: 'think' is in CLI_ONLY (src/cli.ts) — the richer runThinkCli
// handler owns the CLI surface; a non-hidden hint here is dead (CLI_ONLY
// wins at dispatch) and lies to the catalog.
cliHints: { name: 'think', positional: ['question'], hidden: true },
};
// ---------------------------------------------------------------------------
// CLI→MCP gap-closure wave — takes WRITE verbs. Before these, agents could
// read the predictions ledger (takes_list/search/scorecard) but never record,
// refine, resolve, or supersede a take. Backed by the same md-canonical
// write-through core as the CLI (src/core/takes-write.ts): fence-derived row
// numbers, markdown written first, the DB mirrored with the reconcile
// primitive — and the markdown write is REQUIRED (no sync.repo_path on the
// host → 'unavailable' with detail takes_mirror_unavailable), because a
// DB-only row would be clobbered by the next md→DB reconcile.
//
// Trust model (ungated by design — the put_page precedent: writes are
// consented via scope + the holder fence; publish gates cover owner-content
// READ surfaces):
// - Holder WRITE fence reuses the read allow-list, fail-closed: remote
// effective list = ctx.takesHoldersAllowList ?? ['world'] (the stdio
// default — stdio agents write world-held takes only; OAuth tokens can
// grant more), [] = deny-all. add/supersede check the param holder;
// update/resolve/supersede check the TARGET row's holder — and a fenced
// row presents as not_found (same shape as a missing row), hiding content
// and holder. Existence-by-count is accepted: row numbers are dense per
// page, so takes_add's returned row_num reveals how many rows (including
// private ones) exist — returning it is functionally required for later
// update/resolve, and takes_list's visible-sequence gaps leak the same
// count anyway [OV10/EV3].
// - resolved_by is SERVER-STAMPED for remote callers (mcp:<clientId>) so
// agent-resolved rows stay segregable from owner-resolved ground truth;
// scorecard/calibration surface the mcp_resolved count [OV8/EV5].
// - A future permissions.takes_write_holders key could split the read/write
// axes if field use demands it.
// ---------------------------------------------------------------------------
const TAKE_KINDS = ['fact', 'take', 'bet', 'hunch'] as const;
const takes_add: Operation = {
name: 'takes_add',
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Record a take (typed claim) on a page: fact / take / bet / hunch, with a holder (who ' +
'holds the belief: world, people/<slug>, companies/<slug>, or brain), weight 0..1, and ' +
'optional source/since date. Writes the markdown takes fence first (markdown is ' +
'canonical) and mirrors to the DB. Remote callers can only write holders in their ' +
'allow-list (stdio default: world).',
params: {
request_id: WRITE_REQUEST_PARAM,
...MERGE_PRECONDITION_PARAMS,
local_dir: { type: 'string', description: 'Trusted CLI directory hint; must equal the registered source root.' },
slug: { type: 'string', required: true, description: 'Page slug to attach the take to (page must exist).' },
claim: { type: 'string', required: true, description: 'The claim text (one line).' },
kind: { type: 'string', required: true, enum: [...TAKE_KINDS], description: 'Claim type. Base kinds only; pack-extended kinds are a filed follow-up.' },
holder: { type: 'string', required: true, description: "Who HOLDS this belief (said/clearly implied it): world | people/<slug> | companies/<slug> | brain. Remote callers: must be in the caller's takes-holder allow-list." },
weight: { type: 'number', required: false, description: 'Confidence 0..1 (default 0.5; clamped server-side).' },
source: { type: 'string', required: false, description: 'Where the claim came from (free text).' },
since: { type: 'string', required: false, description: "When the belief started ('YYYY-MM' or 'YYYY-MM-DD')." },
},
scope: 'write',
mutating: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
enforceClientSlugFence(ctx, slug, 'takes_add');
validatePageSlug(slug); // defense-in-depth, matching put_page
if (ctx.dryRun) return { dry_run: true, action: 'takes_add', slug };
return submitPageMutation(ctx, { operation: 'takes_add', params: unquotedTakeParams(ctx, p) });
},
};
const takes_update: Operation = {
name: 'takes_update',
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Update a take\'s mutable fields (weight, source, since date). Claim/kind/holder are ' +
'immutable — supersede instead. Markdown-canonical: the target row must exist in the ' +
'page\'s takes fence. Remote callers can only touch rows whose holder is in their ' +
'allow-list; other rows present as not_found.',
params: {
request_id: WRITE_REQUEST_PARAM,
...MERGE_PRECONDITION_PARAMS,
local_dir: { type: 'string', description: 'Trusted CLI directory hint; must equal the registered source root.' },
slug: { type: 'string', required: true, description: 'Page slug.' },
row_num: { type: 'number', required: true, description: 'Take row number on the page (from takes_list).' },
weight: { type: 'number', required: false, description: 'New confidence 0..1.' },
source: { type: 'string', required: false, description: 'New source text.' },
since: { type: 'string', required: false, description: "New since date ('YYYY-MM' or 'YYYY-MM-DD')." },
},
scope: 'write',
mutating: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
enforceClientSlugFence(ctx, slug, 'takes_update');
validatePageSlug(slug); // defense-in-depth, matching put_page
if (ctx.dryRun) return { dry_run: true, action: 'takes_update', slug, row_num: p.row_num };
return submitPageMutation(ctx, { operation: 'takes_update', params: unquotedTakeParams(ctx, p) });
},
};
const takes_supersede: Operation = {
name: 'takes_supersede',
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Supersede a take with a replacement claim: the old row is struck through (kept for ' +
'archaeology), the replacement appends at the next fence row number. Kind/holder inherit ' +
'from the target row unless overridden; unset weight decays the target\'s by 0.1. ' +
'Markdown-canonical; remote holder fencing as in takes_update.',
params: {
request_id: WRITE_REQUEST_PARAM,
...MERGE_PRECONDITION_PARAMS,
local_dir: { type: 'string', description: 'Trusted CLI directory hint; must equal the registered source root.' },
slug: { type: 'string', required: true, description: 'Page slug.' },
row_num: { type: 'number', required: true, description: 'Row number of the take being superseded.' },
claim: { type: 'string', required: true, description: 'The replacement claim text.' },
kind: { type: 'string', required: false, enum: [...TAKE_KINDS], description: 'Override kind (default: inherit from the target row).' },
holder: { type: 'string', required: false, description: 'Override holder (default: inherit). Remote callers: an override must be in the allow-list.' },
weight: { type: 'number', required: false, description: "Replacement confidence 0..1 (default: target's weight - 0.1)." },
source: { type: 'string', required: false, description: 'Source for the replacement.' },
since: { type: 'string', required: false, description: 'Since date for the replacement.' },
},
scope: 'write',
mutating: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
enforceClientSlugFence(ctx, slug, 'takes_supersede');
validatePageSlug(slug); // defense-in-depth, matching put_page
if (ctx.dryRun) return { dry_run: true, action: 'takes_supersede', slug, row_num: p.row_num };
const out = await submitPageMutation(ctx, { operation: 'takes_supersede', params: unquotedTakeParams(ctx, p) });
recordFunnelEvent('correction');
return out;
},
};
const takes_resolve: Operation = {
name: 'takes_resolve',
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Resolve a take: quality correct / incorrect / partial / unresolvable, with optional ' +
'evidence text and measured value/unit. Resolutions feed the calibration scorecard. ' +
'Remote callers: resolved_by is SERVER-STAMPED as mcp:<client> (any passed value is ' +
'ignored) so agent resolutions stay segregable from owner ground truth; the target row ' +
'must be in the caller\'s holder allow-list. Markdown-canonical.',
params: {
request_id: WRITE_REQUEST_PARAM,
...MERGE_PRECONDITION_PARAMS,
local_dir: { type: 'string', description: 'Trusted CLI directory hint; must equal the registered source root.' },
slug: { type: 'string', required: true, description: 'Page slug.' },
row_num: { type: 'number', required: true, description: 'Take row number to resolve.' },
quality: { type: 'string', required: true, enum: ['correct', 'incorrect', 'partial', 'unresolvable'], description: 'Resolution verdict.' },
evidence: { type: 'string', required: false, description: 'What evidence resolved this (free text).' },
value: { type: 'number', required: false, description: 'Measured value, when the claim was quantitative.' },
unit: { type: 'string', required: false, description: 'Unit for value (usd | pct | count | ...).' },
resolved_by: { type: 'string', required: false, description: 'Resolver identity. Remote callers: SERVER-STAMPED mcp:<client>, client value ignored. Local default: the configured owner holder.' },
},
scope: 'write',
mutating: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
enforceClientSlugFence(ctx, slug, 'takes_resolve');
validatePageSlug(slug); // defense-in-depth, matching put_page
if (ctx.dryRun) return { dry_run: true, action: 'takes_resolve', slug, row_num: p.row_num };
return submitPageMutation(ctx, { operation: 'takes_resolve', params: p });
},
};
const takes_remove: Operation = {
name: 'takes_remove',
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Remove one take row from a page\'s takes fence and the takes table together. Local-only. ' +
'Other rows keep their numbers. Refuses a resolved row, a row another row cites as "superseded by" it, ' +
'and a row whose database copy disagrees with the fence (run `gbrain takes rebuild <slug>` first). ' +
'CLI: `gbrain takes remove <slug> --row N`.',
params: {
request_id: WRITE_REQUEST_PARAM,
...MERGE_PRECONDITION_PARAMS,
local_dir: { type: 'string', description: 'Trusted CLI directory hint; must equal the registered source root.' },
slug: { type: 'string', required: true, description: 'Page slug.' },
row_num: { type: 'number', required: true, description: 'Take row number to remove (from takes_list).' },
},
scope: 'write',
mutating: true,
localOnly: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
validatePageSlug(slug);
if (ctx.dryRun) return { dry_run: true, action: 'takes_remove', slug, row_num: p.row_num };
return submitPageMutation(ctx, { operation: 'takes_remove', params: p });
},
};
/**
* W9F item 8: `gbrain takes rebuild <slug>` as an operation, so the CLI can
* delegate it to a resident owner (`gbrain serve` holding PGLite) instead of
* waiting on the owner's lock. Same work as the local rebuild: the page's
* takes index is rebuilt from its canonical fence (`extractTakes` rebuild;
* on a managed brain `reextractCoordinated` publishes it, the integration
* point for Lane R's receipted takes intent).
*/
const takes_rebuild: Operation = {
name: 'takes_rebuild',
idempotent: true,
outputRedaction: { exempt: 'local-only: rebuild warnings quote malformed takes fence rows to the trusted local CLI owner, as the local rebuild always printed them' },
description:
'Rebuild one page\'s takes index from the takes fence the page holds. Local-only. ' +
'Rows whose number and claim still match keep their resolution; rows the index and the fence disagree on are re-inserted from the fence. ' +
'CLI: `gbrain takes rebuild <slug>`.',
params: {
request_id: WRITE_REQUEST_PARAM,
slug: { type: 'string', required: true, description: 'Page slug.' },
},
scope: 'write',
mutating: true,
localOnly: true,
area: 'takes',
handler: async (ctx, p) => {
const slug = p.slug as string;
validatePageSlug(slug);
const sourceId = ctx.sourceId ?? 'default';
if (ctx.dryRun) return { dry_run: true, action: 'takes_rebuild', slug, source_id: sourceId };
const { extractTakes } = await import('../cycle/extract-takes.ts');
return { slug, source_id: sourceId, ...await extractTakes(ctx.engine, { source: 'db', slugs: [slug], sourceId, rebuild: true }) };
},
};
// Ops in EXACTLY the canonical `operations` array order: the v0.28 trio
// (takes_list, takes_search, think), the v0.30 calibration aggregates, then
// the gap-closure write verbs.
export const takesOperations: Operation[] = [
takes_list, takes_search, think,
takes_scorecard, takes_calibration,
takes_add, takes_update, takes_resolve, takes_supersede, takes_remove, takes_rebuild,
];