@tangleai/context 0.21.1

package/src/recall.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The slot name for one archived round. Content-addressed: same bytes,
+ * same name, so a re-compaction overwrites rather than duplicates.
+ * @param {string} text - the round's serialized wire messages
+ * @returns {string}
+ */
+export function roundSlotName(text: string): string;
+/**
+ * The slot name for the index of one archived set. Content-addressed the
+ * same way, over the listing itself — so a request that dropped the same
+ * rounds names the same index.
+ * @param {string} text - the index listing
+ * @returns {string}
+ */
+export function indexSlotName(text: string): string;
+/**
+ * One address, written the one way it is ever written — the call a model
+ * would make to follow it. Everything that names a slot in prose goes
+ * through here, so `slotAddressesIn` has a single syntax to read and a
+ * reader following an address is never following a second convention.
+ * @param {string} name
+ * @returns {string}
+ */
+export function slotRef(name: string): string;
+/**
+ * The address as it appears in a synopsis line. Short on purpose: it is
+ * paid for out of the same character budget the rounds were cut to fit.
+ * @param {string} name
+ * @param {number} size - the archived round's size in characters
+ * @returns {string}
+ */
+export function slotAddress(name: string, size: number): string;
+/**
+ * Every slot address named in a piece of text, in order, without
+ * duplicates. The one reader of the address syntax — a probe, a test or
+ * a host auditing what a request can still reach uses this rather than
+ * writing the pattern a second time.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function slotAddressesIn(text: string): string[];
+/**
+ * The `recall` tool definition, bound to a ledger.
+ *
+ * Registered by `createAgent` when it is given a ledger, and exported so
+ * a host can add it to its own toolbox — the same tool either way, since
+ * a second implementation is exactly how the address a synopsis promises
+ * and the address a tool answers would come to differ.
+ *
+ * The result is deliberately plain `{ slot, size, content }`: the agent
+ * loop truncates every tool result to `maxToolResultChars` on the way
+ * into the transcript, so a slot bigger than that is cut there, once, by
+ * the same rule as any other oversized result.
+ *
+ * @param {{ readSlot: (name: string) => Promise<any> }} ledger
+ * @param {{ index?: string }} [options] - `index` is the address of the
+ *   listing to point at when a name is unknown; it travels in the
+ *   rejection because a model that mistyped an address needs the place
+ *   the real ones are written down, not just a refusal.
+ * @returns {{ name: string, description: string, inputSchema: any,
+ *   execute: (input: any) => Promise<any> }}
+ */
+export function createRecallTool(ledger: {
+    readSlot: (name: string) => Promise<any>;
+}, options?: {
+    index?: string;
+}): {
+    name: string;
+    description: string;
+    inputSchema: any;
+    execute: (input: any) => Promise<any>;
+};
+/** The tool's name. A host that registers its own `recall` keeps it. */
+export const RECALL_TOOL_NAME: "recall";

package/src/recall.js

@@ -0,0 +1,160 @@
+//@ts-check
+/**
+ * `recall` — the address scheme compaction writes, and the tool that
+ * reads it back.
+ *
+ * Compaction used to be a one-way door: a dropped tool round left the
+ * request as a 60-character excerpt and the rest of it was gone. The
+ * excerpt is now a *preview* of something that still exists, and this
+ * module owns both halves of that promise — the address a synopsis line
+ * carries, and the tool a model calls to follow it. They live together
+ * because they are one contract: a name written by `agent.js` and read
+ * by a model has to be produced and parsed in exactly one place, or the
+ * two drift and a request ends up naming an address nothing answers.
+ *
+ * Three decisions:
+ *
+ *  - **The name is content-addressed.** A round's slot name is derived
+ *    from the round's own bytes, so compacting the same history twice
+ *    writes the same slot instead of a second copy — idempotence falls
+ *    out of the naming rather than being bolted on with a counter. The
+ *    character length rides beside the 32-bit fingerprint. These can
+ *    collide, so compaction compares exact bytes and refuses a conflicting
+ *    address before dropping anything from the transcript.
+ *  - **Recall is a tool, not a mechanism.** Nothing re-expands a dropped
+ *    round automatically. Automatic re-expansion is a guess about which
+ *    round matters, and a wrong guess spends the budget it was trying to
+ *    save; the model already knows what it is looking for. It also keeps
+ *    the machinery inspectable — a recall appears in `steps` like any
+ *    other call.
+ *  - **It never throws.** An unknown address answers `{ error }` with the
+ *    index address to try instead, exactly as every other tool in this
+ *    package answers a content-level problem.
+ */
+
+import { hashContent } from '@jarenjs/core/string';
+
+/** The tool's name. A host that registers its own `recall` keeps it. */
+export const RECALL_TOOL_NAME = 'recall';
+
+/** Address prefixes: one archived round, and the index that lists them. */
+const ROUND_PREFIX = 'r-';
+const INDEX_PREFIX = 'rx-';
+
+/**
+ * The slot name for one archived round. Content-addressed: same bytes,
+ * same name, so a re-compaction overwrites rather than duplicates.
+ * @param {string} text - the round's serialized wire messages
+ * @returns {string}
+ */
+export function roundSlotName(text) {
+  return `${ROUND_PREFIX}${hashContent(text)}-${text.length}`;
+}
+
+/**
+ * The slot name for the index of one archived set. Content-addressed the
+ * same way, over the listing itself — so a request that dropped the same
+ * rounds names the same index.
+ * @param {string} text - the index listing
+ * @returns {string}
+ */
+export function indexSlotName(text) {
+  return `${INDEX_PREFIX}${hashContent(text)}-${text.length}`;
+}
+
+/**
+ * One address, written the one way it is ever written — the call a model
+ * would make to follow it. Everything that names a slot in prose goes
+ * through here, so `slotAddressesIn` has a single syntax to read and a
+ * reader following an address is never following a second convention.
+ * @param {string} name
+ * @returns {string}
+ */
+export function slotRef(name) {
+  return `recall("${name}")`;
+}
+
+/**
+ * The address as it appears in a synopsis line. Short on purpose: it is
+ * paid for out of the same character budget the rounds were cut to fit.
+ * @param {string} name
+ * @param {number} size - the archived round's size in characters
+ * @returns {string}
+ */
+export function slotAddress(name, size) {
+  return `[${slotRef(name)} · ${size}B]`;
+}
+
+/**
+ * Every slot address named in a piece of text, in order, without
+ * duplicates. The one reader of the address syntax — a probe, a test or
+ * a host auditing what a request can still reach uses this rather than
+ * writing the pattern a second time.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function slotAddressesIn(text) {
+  /** @type {string[]} */
+  const names = [];
+  for (const match of String(text ?? '').matchAll(/recall\("([^"\s]+)"\)/g)) {
+    if (!names.includes(match[1])) names.push(match[1]);
+  }
+  return names;
+}
+
+/**
+ * The `recall` tool definition, bound to a ledger.
+ *
+ * Registered by `createAgent` when it is given a ledger, and exported so
+ * a host can add it to its own toolbox — the same tool either way, since
+ * a second implementation is exactly how the address a synopsis promises
+ * and the address a tool answers would come to differ.
+ *
+ * The result is deliberately plain `{ slot, size, content }`: the agent
+ * loop truncates every tool result to `maxToolResultChars` on the way
+ * into the transcript, so a slot bigger than that is cut there, once, by
+ * the same rule as any other oversized result.
+ *
+ * @param {{ readSlot: (name: string) => Promise<any> }} ledger
+ * @param {{ index?: string }} [options] - `index` is the address of the
+ *   listing to point at when a name is unknown; it travels in the
+ *   rejection because a model that mistyped an address needs the place
+ *   the real ones are written down, not just a refusal.
+ * @returns {{ name: string, description: string, inputSchema: any,
+ *   execute: (input: any) => Promise<any> }}
+ */
+export function createRecallTool(ledger, options = {}) {
+  return {
+    name: RECALL_TOOL_NAME,
+    description: 'Fetch an archived conversation round in full by its address. Earlier rounds'
+      + ' that did not fit the history budget were archived, not deleted: each synopsis line'
+      + ' carries its address as recall("name"), and the index address listed in the synopsis'
+      + ' header returns every address there is.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slot: {
+          type: 'string',
+          minLength: 1,
+          description: 'The address from a synopsis line, e.g. the name inside recall("…").',
+        },
+      },
+      required: ['slot'],
+      additionalProperties: false,
+    },
+    execute: async ({ slot }) => {
+      const content = await ledger.readSlot(slot);
+      if (content?.status === 'evicted') return { error: `slot '${slot}' was evicted`, ...content };
+      if (content === undefined || content === null) {
+        return {
+          error: `unknown slot '${slot}'`,
+          ...(options.index === undefined ? {} : { index: options.index }),
+          hint: options.index === undefined
+            ? 'use an address exactly as it appears inside recall("…") in the synopsis'
+            : `${slotRef(options.index)} lists every address that exists`,
+        };
+      }
+      return { slot, size: String(content).length, content };
+    },
+  };
+}

package/src/retention.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Exact whole-map accounting. Braces belong to overhead; each member owns its
+ * leading comma. Archive metadata, contents, reports and tombstones stay visible.
+ * @param {Record<string, any>} records
+ */
+export function ledgerFootprint(records: Record<string, any>): {
+    bytes: any;
+    overhead: number;
+    classes: {};
+};
+/** Lossless checkpoint: repeated note/evidence pairs share a dictionary entry. */
+export function checkpointProgress(goal: any): {
+    version: number;
+    sources: any[];
+    records: any[];
+};
+/** Validate exact source coverage and evidence, including prior checkpoints. */
+export function validateCheckpoint(checkpoint: any, goal: any): {
+    valid: boolean;
+    errors: any[];
+};
+/** Complete goal context. No excerpting or silent clipping of evidence. */
+export function goalPrompt(goal: any): string;
+export function jsonBytes(value: any): number;

package/src/retention.js

@@ -0,0 +1,91 @@
+//@ts-check
+import { JarenValidator } from '@jarenjs/validate';
+import { GOAL_SCHEMA } from './schemas/ledger.js';
+import { checkOutcome } from '@jarenjs/core/check';
+const checkpointCheck = new JarenValidator({ collectErrors: true, skipErrors: false, unknownFormats: 'ignore' }).compile(GOAL_SCHEMA.properties.checkpoint);
+
+/** Serialized UTF-8 bytes, including JSON escaping and punctuation. */
+export const jsonBytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+
+/**
+ * Exact whole-map accounting. Braces belong to overhead; each member owns its
+ * leading comma. Archive metadata, contents, reports and tombstones stay visible.
+ * @param {Record<string, any>} records
+ */
+export function ledgerFootprint(records) {
+  const classes = {};
+  Object.keys(records).sort().forEach((key, index) => {
+    let kind = 'other';
+    if (key.startsWith('ai/snap/')) kind = 'snapshots';
+    else if (key.startsWith('ai/counters/')) kind = 'counters';
+    else if (key.startsWith('ai/state/memory/')) kind = 'memories';
+    else if (key.startsWith('ai/state/skill/')) kind = 'skills';
+    else if (key.startsWith('ai/state/goal/')) kind = 'goals';
+    else if (key.startsWith('ai/state/evicted/') || key.startsWith('ai/state/retention/')) kind = 'retention';
+    else if (key.startsWith('ai/state/slot/')) kind = records[key]?.kind?.startsWith('agent-round') ? 'archives' : 'slots';
+    else if (key.startsWith('ai/state/slot-content/')) {
+      const name = key.slice('ai/state/slot-content/'.length);
+      kind = records[`ai/state/slot/${name}`]?.kind?.startsWith('agent-round') ? 'archives' : 'slots';
+    }
+    const entry = classes[kind] ??= { bytes: 0, items: 0 };
+    entry.bytes += jsonBytes(key) + 1 + jsonBytes(records[key]) + (index ? 1 : 0);
+    entry.items++;
+  });
+  return { bytes: 2 + Object.values(classes).reduce((n, entry) => n + entry.bytes, 0), overhead: 2, classes };
+}
+
+/** Lossless checkpoint: repeated note/evidence pairs share a dictionary entry. */
+export function checkpointProgress(goal) {
+  const records = [], sources = [];
+  const add = (source, record) => {
+    if (typeof source?.id !== 'string' || source.id === '' || !record) throw new TypeError('checkpoint needs identified source entries');
+    let index = records.findIndex((held) => held.note === record.note && held.evidence === record.evidence);
+    if (index < 0) { index = records.length; records.push({ note: record.note, evidence: record.evidence }); }
+    sources.push({ id: source.id, at: source.at, record: index });
+  };
+  for (const source of goal.checkpoint?.sources ?? []) add(source, goal.checkpoint.records[source.record]);
+  for (const entry of goal.progress) add(entry, entry);
+  return { version: 1, sources, records };
+}
+
+/** Validate exact source coverage and evidence, including prior checkpoints. */
+export function validateCheckpoint(checkpoint, goal) {
+  const shape = checkOutcome(checkpointCheck(checkpoint));
+  if (!shape.valid) return { valid: false, errors: shape.errors.map((error) => ({ ...error,
+    code: 'GOAL_CHECKPOINT', docPath: `/checkpoint${error.instancePath ?? ''}` })) };
+  let expected;
+  try { expected = checkpointProgress(goal); }
+  catch { return { valid: false, errors: [{ code: 'GOAL_CHECKPOINT', docPath: '/goal', message: 'invalid checkpoint source goal' }] }; }
+  const errors = [];
+  const add = (path, message) => errors.push({ code: 'GOAL_CHECKPOINT', docPath: path, instancePath: path, message });
+  if (checkpoint?.version !== 1 || !Array.isArray(checkpoint?.sources) || !Array.isArray(checkpoint?.records))
+    add('/checkpoint', 'expected a versioned checkpoint with sources and records');
+  else {
+    const sources = new Map(expected.sources.map((source) => [source.id, source]));
+    const seen = new Set();
+    checkpoint.sources.forEach((source, index) => {
+      const held = sources.get(source?.id), record = checkpoint.records[source?.record];
+      if (!held || seen.has(source.id) || source.at !== held.at || !Number.isSafeInteger(source.record)
+        || (record?.note !== expected.records[held.record].note || record?.evidence !== expected.records[held.record].evidence))
+        add(`/checkpoint/sources/${index}`, 'source is invented, duplicated or changes its note/evidence');
+      seen.add(source?.id);
+    });
+    if (seen.size !== sources.size || [...sources.keys()].some((id) => !seen.has(id)))
+      add('/checkpoint/sources', 'every retired source id must remain covered');
+    if (checkpoint.records.some((_, index) => !checkpoint.sources.some((source) => source.record === index)))
+      add('/checkpoint/records', 'unreferenced checkpoint record');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/** Complete goal context. No excerpting or silent clipping of evidence. */
+export function goalPrompt(goal) {
+  const progress = Array.isArray(goal.progress) ? goal.progress : [];
+  const lines = ['## Your objective (persistent, across sessions)', goal.objective];
+  if (goal.checkpoint) lines.push('', 'Validated checkpoint — this work is DONE, do not repeat it:', JSON.stringify(goal.checkpoint));
+  if (progress.length) {
+    lines.push('', `Progress recorded so far (${progress.length} entr${progress.length === 1 ? 'y' : 'ies'}) — this work is DONE, do not repeat it:`);
+    for (const entry of progress) lines.push(`- [${entry.at}] ${entry.note} (evidence: ${entry.evidence})`);
+  }
+  return lines.join('\n');
+}

package/src/schemas/evidence.d.ts

@@ -0,0 +1,54 @@
+/** An admitted artifact describes identity and location; validation never fetches it. */
+export const ARTIFACT_SCHEMA: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: false;
+};
+/** Evidence selects content from one admitted artifact. */
+export const EVIDENCE_SCHEMA: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: false;
+};
+/** Status is an explicit author assertion, not an entailment or authority score. */
+export const CLAIM_SCHEMA: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: false;
+};
+export namespace CLAIM_EVIDENCE_SCHEMA {
+    let type: "object";
+    let properties: Record<string, object>;
+    let required: string[];
+    let additionalProperties: false;
+}
+export type ArtifactRecord = {
+    id: string;
+    kind: string;
+    locator?: string;
+    digest?: string;
+    metadata?: Record<string, any>;
+};
+export type EvidenceRecord = {
+    id: string;
+    artifact: string;
+    selector?: string;
+    quote?: string;
+};
+export type ClaimRecord = {
+    id: string;
+    text: string;
+    critical: boolean;
+    status: "supported" | "unresolved";
+    evidence: string[];
+};
+export type ClaimEvidenceEnvelope = {
+    version: 1;
+    artifacts: ArtifactRecord[];
+    evidence: EvidenceRecord[];
+    claims: ClaimRecord[];
+    visibleEvidence: string[];
+};

package/src/schemas/evidence.js

@@ -0,0 +1,32 @@
+//@ts-check
+const ID = { type: 'string', minLength: 1 };
+/**
+ * @param {Record<string, object>} properties
+ * @param {string[]} required
+ * @returns {{ type: 'object', properties: Record<string, object>, required: string[], additionalProperties: false }}
+ */
+const record = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+
+/** An admitted artifact describes identity and location; validation never fetches it. */
+export const ARTIFACT_SCHEMA = record({ id: ID, kind: ID, locator: ID, digest: ID,
+  metadata: { type: 'object' } }, ['id', 'kind']);
+/** Evidence selects content from one admitted artifact. */
+export const EVIDENCE_SCHEMA = record({ id: ID, artifact: ID, selector: ID, quote: ID }, ['id', 'artifact']);
+/** Status is an explicit author assertion, not an entailment or authority score. */
+export const CLAIM_SCHEMA = record({ id: ID, text: ID, critical: { type: 'boolean' },
+  status: { enum: ['supported', 'unresolved'] },
+  evidence: { type: 'array', items: ID, uniqueItems: true } }, ['id', 'text', 'critical', 'status', 'evidence']);
+/** Versioned referential envelope; visible ids are the evidence admitted to this view. */
+export const CLAIM_EVIDENCE_SCHEMA = {
+  ...record({ version: { const: 1 }, artifacts: { type: 'array', items: ARTIFACT_SCHEMA },
+    evidence: { type: 'array', items: EVIDENCE_SCHEMA }, claims: { type: 'array', items: CLAIM_SCHEMA },
+    visibleEvidence: { type: 'array', items: ID, uniqueItems: true } },
+  ['version', 'artifacts', 'evidence', 'claims', 'visibleEvidence']),
+};
+
+/**
+ * @typedef {{ id: string, kind: string, locator?: string, digest?: string, metadata?: Record<string, any> }} ArtifactRecord
+ * @typedef {{ id: string, artifact: string, selector?: string, quote?: string }} EvidenceRecord
+ * @typedef {{ id: string, text: string, critical: boolean, status: 'supported'|'unresolved', evidence: string[] }} ClaimRecord
+ * @typedef {{ version: 1, artifacts: ArtifactRecord[], evidence: EvidenceRecord[], claims: ClaimRecord[], visibleEvidence: string[] }} ClaimEvidenceEnvelope
+ */