@ai-matrx/agents 0.20.6 → 0.21.2

package/dist/context/index.cjs

@@ -0,0 +1,232 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// context/index.ts
+var context_exports = {};
+__export(context_exports, {
+  CONTEXT_RULES_FEATURE: () => CONTEXT_RULES_FEATURE,
+  DEFAULT_INLINE_CAP: () => DEFAULT_INLINE_CAP,
+  DEFAULT_INLINE_MAX_CHARS: () => DEFAULT_INLINE_MAX_CHARS,
+  DEFAULT_SURFACE_KEY: () => DEFAULT_SURFACE_KEY,
+  buildContextWire: () => buildContextWire,
+  compareReceipt: () => compareReceipt,
+  contextValueChars: () => contextValueChars,
+  formatChars: () => formatChars,
+  lookupSavedRule: () => lookupSavedRule,
+  resolveContextRow: () => resolveContextRow,
+  resolveContextRule: () => resolveContextRule
+});
+module.exports = __toCommonJS(context_exports);
+var CONTEXT_RULES_FEATURE = "context_rules";
+var DEFAULT_SURFACE_KEY = "_default";
+var DEFAULT_INLINE_MAX_CHARS = 200;
+var DEFAULT_INLINE_CAP = 5e4;
+var isNum = (v) => typeof v === "number" && Number.isFinite(v);
+var isValidLimit = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function resolveContextRule(input) {
+  const agent = input.agent ?? null;
+  const surface = input.surface ?? null;
+  const user = input.user ?? null;
+  const cap = isNum(input.cap) ? input.cap : DEFAULT_INLINE_CAP;
+  const agentDeclared = agent?.declared === true;
+  let include = true;
+  let includeBy = "default";
+  if (surface?.declared === true && surface.auto_context === false) {
+    if (agentDeclared) {
+      include = true;
+      includeBy = "agent";
+    } else {
+      include = false;
+      includeBy = "page";
+    }
+  }
+  if (agent?.kill_switch === true && !agentDeclared) {
+    include = false;
+    includeBy = "agent";
+  }
+  if (user && typeof user.include === "boolean") {
+    include = user.include;
+    includeBy = "you";
+  }
+  let limit = isNum(input.default_max) ? input.default_max : DEFAULT_INLINE_MAX_CHARS;
+  let limitBy = "default";
+  const a = agentDeclared && isNum(agent?.max_inline_chars) ? agent.max_inline_chars : null;
+  const s = isNum(surface?.max_inline_chars) ? surface.max_inline_chars : null;
+  if (a !== null && s !== null) {
+    if (s < a) {
+      limit = s;
+      limitBy = "page";
+    } else {
+      limit = a;
+      limitBy = "agent";
+    }
+  } else if (a !== null) {
+    limit = a;
+    limitBy = "agent";
+  } else if (s !== null) {
+    limit = s;
+    limitBy = "page";
+  }
+  if (user && isValidLimit(user.max_inline_chars)) {
+    limit = user.max_inline_chars;
+    limitBy = "you";
+  }
+  const clamped = limit > cap;
+  limit = Math.min(limit, cap);
+  const chars = input.chars;
+  const delivery = !include ? "off" : chars === null || chars === void 0 || limit === 0 || chars > limit ? "on_request" : "inline";
+  return {
+    include,
+    max_inline_chars: limit,
+    delivery,
+    decided_by: { include: includeBy, max_inline_chars: limitBy },
+    clamped
+  };
+}
+function codePoints(s) {
+  let n = 0;
+  for (const _ of s) n += 1;
+  return n;
+}
+function contextValueChars(value) {
+  if (value === void 0) return 0;
+  if (typeof value === "string") return codePoints(value);
+  let text;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    text = String(value);
+  }
+  return text === void 0 ? 0 : codePoints(text);
+}
+function sanitizeRule(raw) {
+  const out = {};
+  if (!raw || typeof raw !== "object") return out;
+  const r = raw;
+  if (typeof r.include === "boolean") out.include = r.include;
+  if (isValidLimit(r.max_inline_chars)) out.max_inline_chars = r.max_inline_chars;
+  return out;
+}
+function lookupSavedRule(rows, surfaceKey, key) {
+  if (!rows || typeof rows !== "object") return null;
+  const base = sanitizeRule(rows[DEFAULT_SURFACE_KEY]?.[key]);
+  const own = surfaceKey === DEFAULT_SURFACE_KEY ? {} : sanitizeRule(rows[surfaceKey]?.[key]);
+  const merged = { ...base, ...own };
+  return Object.keys(merged).length === 0 ? null : merged;
+}
+function resolveContextRow(source, savedRows, cap = DEFAULT_INLINE_CAP) {
+  const surfaceKey = source.surfaceKey ?? DEFAULT_SURFACE_KEY;
+  const chars = source.chars !== void 0 ? source.chars : contextValueChars(envelopeContent(source.value));
+  const userRule = lookupSavedRule(savedRows, surfaceKey, source.key);
+  const result = resolveContextRule({ ...source.layers ?? {}, chars, user: userRule, cap });
+  const row = {
+    ...result,
+    key: source.key,
+    label: source.label,
+    surfaceKey,
+    origin: source.origin,
+    value: source.value,
+    chars,
+    userRule
+  };
+  if (source.description !== void 0) row.description = source.description;
+  if (source.type !== void 0) row.type = source.type;
+  if (source.layers !== void 0) row.layers = source.layers;
+  return row;
+}
+function isEnvelope(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, "content");
+}
+function envelopeContent(value) {
+  return isEnvelope(value) ? value.content : value;
+}
+function buildContextWire(rows) {
+  const wire = {};
+  for (const row of rows) {
+    if (!row.include) continue;
+    const rich = isEnvelope(row.value);
+    const envelope = rich ? { ...row.value } : { content: row.value };
+    delete envelope.max_inline_chars;
+    if (envelope.type === void 0 && row.type !== void 0) envelope.type = row.type;
+    if (envelope.label === void 0) envelope.label = row.label;
+    if (envelope.description === void 0 && row.description !== void 0) {
+      envelope.description = row.description;
+    }
+    const pageLimit = row.layers?.surface?.max_inline_chars;
+    const ownPageLimit = rich ? row.value.max_inline_chars : void 0;
+    if (isValidLimit(pageLimit)) envelope.max_inline_chars = pageLimit;
+    else if (isValidLimit(ownPageLimit)) envelope.max_inline_chars = ownPageLimit;
+    wire[row.key] = envelope;
+  }
+  return wire;
+}
+function normalizeUserRule(rule) {
+  const clean = sanitizeRule(rule);
+  return Object.keys(clean).length === 0 ? null : clean;
+}
+function sameRule(a, b) {
+  if (a === null || b === null) return a === b;
+  return a.include === b.include && a.max_inline_chars === b.max_inline_chars;
+}
+function compareReceipt(expected, receipt) {
+  const mismatches = [];
+  const used = /* @__PURE__ */ new Set();
+  const rows = receipt.rows ?? [];
+  for (const exp of expected) {
+    const actual = rows.find((r) => !used.has(r) && r.key === exp.key && r.surface_key === exp.surfaceKey) ?? rows.find((r) => !used.has(r) && r.key === exp.key);
+    if (!actual) {
+      const withheldByOthers = !exp.include && exp.decided_by.include !== "you";
+      if (!withheldByOthers) {
+        mismatches.push({ key: exp.key, field: "missing", expected: exp.delivery, actual: null });
+      }
+      continue;
+    }
+    used.add(actual);
+    if (actual.include !== exp.include) {
+      mismatches.push({ key: exp.key, field: "include", expected: exp.include, actual: actual.include });
+    }
+    if (actual.max_inline_chars !== exp.max_inline_chars) {
+      mismatches.push({
+        key: exp.key,
+        field: "max_inline_chars",
+        expected: exp.max_inline_chars,
+        actual: actual.max_inline_chars
+      });
+    }
+    if (exp.chars !== null && actual.chars !== null && actual.delivery !== exp.delivery) {
+      mismatches.push({ key: exp.key, field: "delivery", expected: exp.delivery, actual: actual.delivery });
+    }
+    const expRule = normalizeUserRule(exp.userRule);
+    const actRule = normalizeUserRule(actual.user_rule);
+    if (!sameRule(expRule, actRule)) {
+      mismatches.push({ key: exp.key, field: "user_rule", expected: expRule, actual: actRule });
+    }
+  }
+  return { mismatches, systemRows: rows.filter((r) => !used.has(r)) };
+}
+function formatChars(n) {
+  if (n === null || n === void 0 || !Number.isFinite(n)) return "\u2014";
+  const abs = Math.abs(n);
+  const trim = (s) => s.replace(/\.0$/, "");
+  if (abs < 1e3) return String(Math.round(n));
+  if (abs < 1e5) return `${trim((n / 1e3).toFixed(1))}k`;
+  if (abs < 1e6) return `${Math.round(n / 1e3)}k`;
+  return `${trim((n / 1e6).toFixed(1))}M`;
+}
+//# sourceMappingURL=index.cjs.map

package/dist/context/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../context/index.ts"],"sourcesContent":["/**\n * @ai-matrx/agents/context — the context value rules, headless.\n *\n * Contract: common-docs/systems/scopes-context/context-delivery/RULES.md.\n * Parity corpus: ./rules-corpus.json (run here by rules.test.ts and by aidream's\n * pytest against the Python twin `resolve_context_rule`). Every function here\n * is pure, zero-React, and safe to import on a server.\n *\n * The one flow a client runs per turn:\n *   rows    = values.map(v => resolveContextRow(v, savedRows, cap))   // what the table shows\n *   context = buildContextWire(rows)                                   // what the request sends\n *   …on `context_receipt`: compareReceipt(rows, receipt)               // screen vs server\n */\n\n// ── Constants ───────────────────────────────────────────────────────────────\n\n/** `users.user_surface_state.feature` for the person's saved rules. */\nexport const CONTEXT_RULES_FEATURE = \"context_rules\";\n/** Surface key for values no surface emitted (attachments, server-added values). */\nexport const DEFAULT_SURFACE_KEY = \"_default\";\n/** The server's default inline threshold when no layer sets one. */\nexport const DEFAULT_INLINE_MAX_CHARS = 200;\n/** The default ceiling every resolved limit is clamped to (a server knob). */\nexport const DEFAULT_INLINE_CAP = 50000;\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\n/** Which layer decided a field — lowest to highest. */\nexport type ContextLayer = \"default\" | \"page\" | \"agent\" | \"you\";\nexport type ContextDelivery = \"inline\" | \"on_request\" | \"off\";\n\n/** One saved per-person rule (one key on one surface). Both fields optional. */\nexport interface SavedContextRule {\n  include?: boolean;\n  max_inline_chars?: number;\n}\n\n/** `{ [surface_key]: { [context key]: SavedContextRule } }` — the person's rows. */\nexport type SavedContextRuleRows = Record<string, Record<string, SavedContextRule>>;\n\n/** The agent layer for one key (RULES.md §2). */\nexport interface ContextAgentLayer {\n  /** The agent's Context Policy declares this key (or the value is the agent's own seed). */\n  declared?: boolean;\n  /** The policy's ceiling; only read when `declared`. */\n  max_inline_chars?: number | null;\n  /** `auto_context_disabled` — closes every undeclared key. */\n  kill_switch?: boolean;\n}\n\n/** The page layer for one key: the surface that emitted the value. */\nexport interface ContextSurfaceLayer {\n  /** The surface declares this value (a `ui_surface_value` row / manifest entry). */\n  declared?: boolean;\n  /** `false` drops the value unless the agent declares it. */\n  auto_context?: boolean | null;\n  /** `inlineUpTo` / envelope `max_inline_chars` / DB column. */\n  max_inline_chars?: number | null;\n}\n\n/** The non-person layers for one value — what the table's layer breakdown shows. */\nexport interface ContextRuleLayers {\n  /** The server's per-key default limit; `null`/absent = 200. */\n  default_max?: number | null;\n  agent?: ContextAgentLayer | null;\n  surface?: ContextSurfaceLayer | null;\n}\n\n/**\n * Input to `resolveContextRule`. Snake case on purpose: it is the corpus shape\n * and the Python twin's shape. `user` is typed loosely because invalid saved\n * values (non-boolean include, non-integer or negative limit) must be ignored,\n * not trusted.\n */\nexport interface ContextRuleInput extends ContextRuleLayers {\n  /** Size in code points; `null` = an unresolved lazy source. */\n  chars: number | null;\n  user?: { include?: unknown; max_inline_chars?: unknown } | null;\n  /** Ceiling; default `DEFAULT_INLINE_CAP`. */\n  cap?: number;\n}\n\nexport interface ContextRuleResult {\n  include: boolean;\n  /** Effective limit, after the clamp. */\n  max_inline_chars: number;\n  delivery: ContextDelivery;\n  decided_by: { include: ContextLayer; max_inline_chars: ContextLayer };\n  clamped: boolean;\n}\n\n/** One receipt row — RULES.md §5, wire fields exactly. */\nexport interface ContextReceiptRow {\n  key: string;\n  label: string;\n  surface_key: string;\n  origin: \"client\" | \"server\" | \"surroundings\" | \"rule\";\n  chars: number | null;\n  include: boolean;\n  max_inline_chars: number;\n  delivery: ContextDelivery;\n  decided_by: { include: ContextLayer; max_inline_chars: ContextLayer };\n  user_rule: { include?: boolean; max_inline_chars?: number } | null;\n  clamped: boolean;\n  /** The CLIENT itself sent a value the person turned off. */\n  client_sent_excluded: boolean;\n  /** `\"model\"`: nothing reached a model that reads no context. */\n  blocked_by: \"model\" | null;\n}\n\n/** The per-turn receipt the server streams as `context_receipt` — RULES.md §5. */\nexport interface ContextReceipt {\n  version: 1;\n  surface: string | null;\n  cap: number;\n  /** False: this turn's model cannot read context at all (every row `blocked_by: \"model\"`). */\n  model_reads_context: boolean;\n  /** The person's saved rules could not be read; the turn ran without them. */\n  rules_error: string | null;\n  rows: ContextReceiptRow[];\n}\n\nexport type ContextRowOrigin = \"page\" | \"attached\" | \"system\";\n\n/** A client's resolved row: what its table renders and what `buildContextWire` sends. */\nexport interface ResolvedContextRow extends ContextRuleResult {\n  key: string;\n  label: string;\n  surfaceKey: string;\n  origin: ContextRowOrigin;\n  /** The raw value, or an already-rich envelope (`{ content, type, … }`). */\n  value: unknown;\n  chars: number | null;\n  /** The saved rule that was applied (merged `_default` + surface row), or null. */\n  userRule: SavedContextRule | null;\n  description?: string;\n  /** Context object type for the wire envelope (`text`, `json`, …). */\n  type?: string;\n  /** The non-person layers the rule was resolved from. Absent = default only. */\n  layers?: ContextRuleLayers;\n}\n\n/** What a client knows about one value before resolution. */\nexport interface ContextRowSource {\n  key: string;\n  label: string;\n  surfaceKey?: string;\n  origin: ContextRowOrigin;\n  value: unknown;\n  /** Override the measured size (e.g. `null` for an unresolved lazy source). */\n  chars?: number | null;\n  description?: string;\n  type?: string;\n  layers?: ContextRuleLayers;\n}\n\n// ── Helpers ─────────────────────────────────────────────────────────────────\n\nconst isNum = (v: unknown): v is number => typeof v === \"number\" && Number.isFinite(v);\nconst isValidLimit = (v: unknown): v is number =>\n  typeof v === \"number\" && Number.isInteger(v) && v >= 0;\n\n// ── resolveContextRule — RULES.md §2, line for line ─────────────────────────\n\nexport function resolveContextRule(input: ContextRuleInput): ContextRuleResult {\n  const agent = input.agent ?? null;\n  const surface = input.surface ?? null;\n  const user = input.user ?? null;\n  const cap = isNum(input.cap) ? input.cap : DEFAULT_INLINE_CAP;\n  const agentDeclared = agent?.declared === true;\n\n  let include = true;\n  let includeBy: ContextLayer = \"default\";\n  if (surface?.declared === true && surface.auto_context === false) {\n    if (agentDeclared) {\n      include = true;\n      includeBy = \"agent\";\n    } else {\n      include = false;\n      includeBy = \"page\";\n    }\n  }\n  if (agent?.kill_switch === true && !agentDeclared) {\n    include = false;\n    includeBy = \"agent\";\n  }\n  if (user && typeof user.include === \"boolean\") {\n    include = user.include;\n    includeBy = \"you\";\n  }\n\n  let limit = isNum(input.default_max) ? input.default_max : DEFAULT_INLINE_MAX_CHARS;\n  let limitBy: ContextLayer = \"default\";\n  const a = agentDeclared && isNum(agent?.max_inline_chars) ? agent.max_inline_chars : null;\n  const s = isNum(surface?.max_inline_chars) ? surface.max_inline_chars : null;\n  if (a !== null && s !== null) {\n    if (s < a) {\n      limit = s;\n      limitBy = \"page\";\n    } else {\n      limit = a;\n      limitBy = \"agent\";\n    }\n  } else if (a !== null) {\n    limit = a;\n    limitBy = \"agent\";\n  } else if (s !== null) {\n    limit = s;\n    limitBy = \"page\";\n  }\n  if (user && isValidLimit(user.max_inline_chars)) {\n    limit = user.max_inline_chars;\n    limitBy = \"you\";\n  }\n  const clamped = limit > cap;\n  limit = Math.min(limit, cap);\n\n  const chars = input.chars;\n  const delivery: ContextDelivery = !include\n    ? \"off\"\n    : chars === null || chars === undefined || limit === 0 || chars > limit\n      ? \"on_request\"\n      : \"inline\";\n\n  return {\n    include,\n    max_inline_chars: limit,\n    delivery,\n    decided_by: { include: includeBy, max_inline_chars: limitBy },\n    clamped,\n  };\n}\n\n// ── contextValueChars — RULES.md §1 ─────────────────────────────────────────\n\n/** Count Unicode code points (never UTF-16 units: `\"😀\".length` is 2). */\nfunction codePoints(s: string): number {\n  let n = 0;\n  for (const _ of s) n += 1;\n  return n;\n}\n\n/**\n * Size of a value in code points, exactly as the server's `content_as_str()`:\n * a string is itself; anything else is `JSON.stringify(value, null, 2)`\n * (Python `json.dumps(value, ensure_ascii=False, indent=2)`). `undefined` → 0.\n */\nexport function contextValueChars(value: unknown): number {\n  if (value === undefined) return 0;\n  if (typeof value === \"string\") return codePoints(value);\n  let text: string | undefined;\n  try {\n    text = JSON.stringify(value, null, 2);\n  } catch {\n    text = String(value);\n  }\n  return text === undefined ? 0 : codePoints(text);\n}\n\n// ── lookupSavedRule — RULES.md §3 ───────────────────────────────────────────\n\nfunction sanitizeRule(raw: unknown): SavedContextRule {\n  const out: SavedContextRule = {};\n  if (!raw || typeof raw !== \"object\") return out;\n  const r = raw as Record<string, unknown>;\n  if (typeof r.include === \"boolean\") out.include = r.include;\n  if (isValidLimit(r.max_inline_chars)) out.max_inline_chars = r.max_inline_chars;\n  return out;\n}\n\n/**\n * The person's rule for one key on one surface: `_default[key]` merged per\n * field under `rows[surfaceKey][key]`, invalid fields stripped. `null` when\n * nothing valid is saved.\n */\nexport function lookupSavedRule(\n  rows: SavedContextRuleRows | null | undefined,\n  surfaceKey: string,\n  key: string,\n): SavedContextRule | null {\n  if (!rows || typeof rows !== \"object\") return null;\n  const base = sanitizeRule(rows[DEFAULT_SURFACE_KEY]?.[key]);\n  const own = surfaceKey === DEFAULT_SURFACE_KEY ? {} : sanitizeRule(rows[surfaceKey]?.[key]);\n  const merged: SavedContextRule = { ...base, ...own };\n  return Object.keys(merged).length === 0 ? null : merged;\n}\n\n// ── resolveContextRow — the glue a client runs per value ────────────────────\n\n/** Resolve one value into the row the table renders and the wire sends. */\nexport function resolveContextRow(\n  source: ContextRowSource,\n  savedRows: SavedContextRuleRows | null | undefined,\n  cap: number = DEFAULT_INLINE_CAP,\n): ResolvedContextRow {\n  const surfaceKey = source.surfaceKey ?? DEFAULT_SURFACE_KEY;\n  const chars =\n    source.chars !== undefined ? source.chars : contextValueChars(envelopeContent(source.value));\n  const userRule = lookupSavedRule(savedRows, surfaceKey, source.key);\n  const result = resolveContextRule({ ...(source.layers ?? {}), chars, user: userRule, cap });\n  const row: ResolvedContextRow = {\n    ...result,\n    key: source.key,\n    label: source.label,\n    surfaceKey,\n    origin: source.origin,\n    value: source.value,\n    chars,\n    userRule,\n  };\n  if (source.description !== undefined) row.description = source.description;\n  if (source.type !== undefined) row.type = source.type;\n  if (source.layers !== undefined) row.layers = source.layers;\n  return row;\n}\n\n// ── buildContextWire — the ONLY producer of a request's `context` ──────────\n\nfunction isEnvelope(value: unknown): value is Record<string, unknown> {\n  return (\n    !!value &&\n    typeof value === \"object\" &&\n    !Array.isArray(value) &&\n    Object.prototype.hasOwnProperty.call(value, \"content\")\n  );\n}\n\nfunction envelopeContent(value: unknown): unknown {\n  return isEnvelope(value) ? value.content : value;\n}\n\n/**\n * Build the request's `context` object from the resolved rows. This is the\n * ONLY function that may produce it, so what the table shows and what the\n * request carries cannot drift apart.\n *\n * - A row whose `include` is false is omitted entirely — it never reaches the\n *   wire (RULES.md §1: off means off everywhere).\n * - An included row becomes `{ content, type?, label, description?,\n *   max_inline_chars? }`. An already-rich envelope (a value with its own\n *   `content`, e.g. a working document carrying `source`/`mutable`/`persist`)\n *   keeps every non-rule field it already has; `label`/`description`/`type`\n *   are only filled when missing.\n * - `max_inline_chars` on the envelope is the PAGE layer's value only\n *   (`layers.surface.max_inline_chars`, else the envelope's own page value).\n *   The server reads the person's saved rules itself every turn (RULES.md §3)\n *   and the agent layer from its own policy, so the wire must never carry the\n *   person's number or the resolved effective limit dressed up as a page rule\n *   — that would make a stale client value outrank the server's fresh read.\n */\nexport function buildContextWire(rows: readonly ResolvedContextRow[]): Record<string, unknown> {\n  const wire: Record<string, unknown> = {};\n  for (const row of rows) {\n    if (!row.include) continue;\n    const rich = isEnvelope(row.value);\n    const envelope: Record<string, unknown> = rich\n      ? { ...(row.value as Record<string, unknown>) }\n      : { content: row.value };\n    delete envelope.max_inline_chars;\n    if (envelope.type === undefined && row.type !== undefined) envelope.type = row.type;\n    if (envelope.label === undefined) envelope.label = row.label;\n    if (envelope.description === undefined && row.description !== undefined) {\n      envelope.description = row.description;\n    }\n    const pageLimit = row.layers?.surface?.max_inline_chars;\n    const ownPageLimit = rich ? (row.value as Record<string, unknown>).max_inline_chars : undefined;\n    if (isValidLimit(pageLimit)) envelope.max_inline_chars = pageLimit;\n    else if (isValidLimit(ownPageLimit)) envelope.max_inline_chars = ownPageLimit;\n    wire[row.key] = envelope;\n  }\n  return wire;\n}\n\n// ── compareReceipt — RULES.md §6 ────────────────────────────────────────────\n\nexport interface ContextReceiptMismatch {\n  key: string;\n  field: \"include\" | \"max_inline_chars\" | \"delivery\" | \"user_rule\" | \"missing\";\n  expected: unknown;\n  actual: unknown;\n}\n\nfunction normalizeUserRule(rule: SavedContextRule | null | undefined): SavedContextRule | null {\n  const clean = sanitizeRule(rule);\n  return Object.keys(clean).length === 0 ? null : clean;\n}\n\nfunction sameRule(a: SavedContextRule | null, b: SavedContextRule | null): boolean {\n  if (a === null || b === null) return a === b;\n  return a.include === b.include && a.max_inline_chars === b.max_inline_chars;\n}\n\n/**\n * Compare the rows the client resolved (and rendered, and sent) with the\n * receipt the server emitted for the same turn.\n *\n * For each expected row, the receipt row is matched by key + surface key, then\n * by key alone. Compared: `include`, `max_inline_chars`, `delivery` (only when\n * both sides know the size) and `user_rule`. An expected row absent from the\n * receipt is a `missing` mismatch — except a row the client correctly withheld\n * for a reason other than the person's own rule (page `auto_context` off, the\n * agent's kill switch): the client never sent it and the server lists only\n * the person's saved `include: false` rules as `origin: \"rule\"` rows, so its\n * absence is the truth, not a lie. Receipt rows nobody expected are returned\n * as `systemRows` — shown, never hidden.\n */\nexport function compareReceipt(\n  expected: readonly ResolvedContextRow[],\n  receipt: ContextReceipt,\n): { mismatches: ContextReceiptMismatch[]; systemRows: ContextReceiptRow[] } {\n  const mismatches: ContextReceiptMismatch[] = [];\n  const used = new Set<ContextReceiptRow>();\n  const rows = receipt.rows ?? [];\n\n  for (const exp of expected) {\n    const actual =\n      rows.find((r) => !used.has(r) && r.key === exp.key && r.surface_key === exp.surfaceKey) ??\n      rows.find((r) => !used.has(r) && r.key === exp.key);\n    if (!actual) {\n      const withheldByOthers = !exp.include && exp.decided_by.include !== \"you\";\n      if (!withheldByOthers) {\n        mismatches.push({ key: exp.key, field: \"missing\", expected: exp.delivery, actual: null });\n      }\n      continue;\n    }\n    used.add(actual);\n    if (actual.include !== exp.include) {\n      mismatches.push({ key: exp.key, field: \"include\", expected: exp.include, actual: actual.include });\n    }\n    if (actual.max_inline_chars !== exp.max_inline_chars) {\n      mismatches.push({\n        key: exp.key,\n        field: \"max_inline_chars\",\n        expected: exp.max_inline_chars,\n        actual: actual.max_inline_chars,\n      });\n    }\n    if (exp.chars !== null && actual.chars !== null && actual.delivery !== exp.delivery) {\n      mismatches.push({ key: exp.key, field: \"delivery\", expected: exp.delivery, actual: actual.delivery });\n    }\n    const expRule = normalizeUserRule(exp.userRule);\n    const actRule = normalizeUserRule(actual.user_rule);\n    if (!sameRule(expRule, actRule)) {\n      mismatches.push({ key: exp.key, field: \"user_rule\", expected: expRule, actual: actRule });\n    }\n  }\n\n  return { mismatches, systemRows: rows.filter((r) => !used.has(r)) };\n}\n\n// ── Display ─────────────────────────────────────────────────────────────────\n\n/** Compact size for a tabular column: `950`, `18.4k`, `184k`, `1.2M`, `—` for unknown. */\nexport function formatChars(n: number | null | undefined): string {\n  if (n === null || n === undefined || !Number.isFinite(n)) return \"—\";\n  const abs = Math.abs(n);\n  const trim = (s: string) => s.replace(/\\.0$/, \"\");\n  if (abs < 1000) return String(Math.round(n));\n  if (abs < 100_000) return `${trim((n / 1000).toFixed(1))}k`;\n  if (abs < 1_000_000) return `${Math.round(n / 1000)}k`;\n  return `${trim((n / 1_000_000).toFixed(1))}M`;\n}\n"],"mappings":"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","names":[]}

package/dist/context/index.d.cts

@@ -0,0 +1,212 @@
+/**
+ * @ai-matrx/agents/context — the context value rules, headless.
+ *
+ * Contract: common-docs/systems/scopes-context/context-delivery/RULES.md.
+ * Parity corpus: ./rules-corpus.json (run here by rules.test.ts and by aidream's
+ * pytest against the Python twin `resolve_context_rule`). Every function here
+ * is pure, zero-React, and safe to import on a server.
+ *
+ * The one flow a client runs per turn:
+ *   rows    = values.map(v => resolveContextRow(v, savedRows, cap))   // what the table shows
+ *   context = buildContextWire(rows)                                   // what the request sends
+ *   …on `context_receipt`: compareReceipt(rows, receipt)               // screen vs server
+ */
+/** `users.user_surface_state.feature` for the person's saved rules. */
+declare const CONTEXT_RULES_FEATURE = "context_rules";
+/** Surface key for values no surface emitted (attachments, server-added values). */
+declare const DEFAULT_SURFACE_KEY = "_default";
+/** The server's default inline threshold when no layer sets one. */
+declare const DEFAULT_INLINE_MAX_CHARS = 200;
+/** The default ceiling every resolved limit is clamped to (a server knob). */
+declare const DEFAULT_INLINE_CAP = 50000;
+/** Which layer decided a field — lowest to highest. */
+type ContextLayer = "default" | "page" | "agent" | "you";
+type ContextDelivery = "inline" | "on_request" | "off";
+/** One saved per-person rule (one key on one surface). Both fields optional. */
+interface SavedContextRule {
+    include?: boolean;
+    max_inline_chars?: number;
+}
+/** `{ [surface_key]: { [context key]: SavedContextRule } }` — the person's rows. */
+type SavedContextRuleRows = Record<string, Record<string, SavedContextRule>>;
+/** The agent layer for one key (RULES.md §2). */
+interface ContextAgentLayer {
+    /** The agent's Context Policy declares this key (or the value is the agent's own seed). */
+    declared?: boolean;
+    /** The policy's ceiling; only read when `declared`. */
+    max_inline_chars?: number | null;
+    /** `auto_context_disabled` — closes every undeclared key. */
+    kill_switch?: boolean;
+}
+/** The page layer for one key: the surface that emitted the value. */
+interface ContextSurfaceLayer {
+    /** The surface declares this value (a `ui_surface_value` row / manifest entry). */
+    declared?: boolean;
+    /** `false` drops the value unless the agent declares it. */
+    auto_context?: boolean | null;
+    /** `inlineUpTo` / envelope `max_inline_chars` / DB column. */
+    max_inline_chars?: number | null;
+}
+/** The non-person layers for one value — what the table's layer breakdown shows. */
+interface ContextRuleLayers {
+    /** The server's per-key default limit; `null`/absent = 200. */
+    default_max?: number | null;
+    agent?: ContextAgentLayer | null;
+    surface?: ContextSurfaceLayer | null;
+}
+/**
+ * Input to `resolveContextRule`. Snake case on purpose: it is the corpus shape
+ * and the Python twin's shape. `user` is typed loosely because invalid saved
+ * values (non-boolean include, non-integer or negative limit) must be ignored,
+ * not trusted.
+ */
+interface ContextRuleInput extends ContextRuleLayers {
+    /** Size in code points; `null` = an unresolved lazy source. */
+    chars: number | null;
+    user?: {
+        include?: unknown;
+        max_inline_chars?: unknown;
+    } | null;
+    /** Ceiling; default `DEFAULT_INLINE_CAP`. */
+    cap?: number;
+}
+interface ContextRuleResult {
+    include: boolean;
+    /** Effective limit, after the clamp. */
+    max_inline_chars: number;
+    delivery: ContextDelivery;
+    decided_by: {
+        include: ContextLayer;
+        max_inline_chars: ContextLayer;
+    };
+    clamped: boolean;
+}
+/** One receipt row — RULES.md §5, wire fields exactly. */
+interface ContextReceiptRow {
+    key: string;
+    label: string;
+    surface_key: string;
+    origin: "client" | "server" | "surroundings" | "rule";
+    chars: number | null;
+    include: boolean;
+    max_inline_chars: number;
+    delivery: ContextDelivery;
+    decided_by: {
+        include: ContextLayer;
+        max_inline_chars: ContextLayer;
+    };
+    user_rule: {
+        include?: boolean;
+        max_inline_chars?: number;
+    } | null;
+    clamped: boolean;
+    /** The CLIENT itself sent a value the person turned off. */
+    client_sent_excluded: boolean;
+    /** `"model"`: nothing reached a model that reads no context. */
+    blocked_by: "model" | null;
+}
+/** The per-turn receipt the server streams as `context_receipt` — RULES.md §5. */
+interface ContextReceipt {
+    version: 1;
+    surface: string | null;
+    cap: number;
+    /** False: this turn's model cannot read context at all (every row `blocked_by: "model"`). */
+    model_reads_context: boolean;
+    /** The person's saved rules could not be read; the turn ran without them. */
+    rules_error: string | null;
+    rows: ContextReceiptRow[];
+}
+type ContextRowOrigin = "page" | "attached" | "system";
+/** A client's resolved row: what its table renders and what `buildContextWire` sends. */
+interface ResolvedContextRow extends ContextRuleResult {
+    key: string;
+    label: string;
+    surfaceKey: string;
+    origin: ContextRowOrigin;
+    /** The raw value, or an already-rich envelope (`{ content, type, … }`). */
+    value: unknown;
+    chars: number | null;
+    /** The saved rule that was applied (merged `_default` + surface row), or null. */
+    userRule: SavedContextRule | null;
+    description?: string;
+    /** Context object type for the wire envelope (`text`, `json`, …). */
+    type?: string;
+    /** The non-person layers the rule was resolved from. Absent = default only. */
+    layers?: ContextRuleLayers;
+}
+/** What a client knows about one value before resolution. */
+interface ContextRowSource {
+    key: string;
+    label: string;
+    surfaceKey?: string;
+    origin: ContextRowOrigin;
+    value: unknown;
+    /** Override the measured size (e.g. `null` for an unresolved lazy source). */
+    chars?: number | null;
+    description?: string;
+    type?: string;
+    layers?: ContextRuleLayers;
+}
+declare function resolveContextRule(input: ContextRuleInput): ContextRuleResult;
+/**
+ * Size of a value in code points, exactly as the server's `content_as_str()`:
+ * a string is itself; anything else is `JSON.stringify(value, null, 2)`
+ * (Python `json.dumps(value, ensure_ascii=False, indent=2)`). `undefined` → 0.
+ */
+declare function contextValueChars(value: unknown): number;
+/**
+ * The person's rule for one key on one surface: `_default[key]` merged per
+ * field under `rows[surfaceKey][key]`, invalid fields stripped. `null` when
+ * nothing valid is saved.
+ */
+declare function lookupSavedRule(rows: SavedContextRuleRows | null | undefined, surfaceKey: string, key: string): SavedContextRule | null;
+/** Resolve one value into the row the table renders and the wire sends. */
+declare function resolveContextRow(source: ContextRowSource, savedRows: SavedContextRuleRows | null | undefined, cap?: number): ResolvedContextRow;
+/**
+ * Build the request's `context` object from the resolved rows. This is the
+ * ONLY function that may produce it, so what the table shows and what the
+ * request carries cannot drift apart.
+ *
+ * - A row whose `include` is false is omitted entirely — it never reaches the
+ *   wire (RULES.md §1: off means off everywhere).
+ * - An included row becomes `{ content, type?, label, description?,
+ *   max_inline_chars? }`. An already-rich envelope (a value with its own
+ *   `content`, e.g. a working document carrying `source`/`mutable`/`persist`)
+ *   keeps every non-rule field it already has; `label`/`description`/`type`
+ *   are only filled when missing.
+ * - `max_inline_chars` on the envelope is the PAGE layer's value only
+ *   (`layers.surface.max_inline_chars`, else the envelope's own page value).
+ *   The server reads the person's saved rules itself every turn (RULES.md §3)
+ *   and the agent layer from its own policy, so the wire must never carry the
+ *   person's number or the resolved effective limit dressed up as a page rule
+ *   — that would make a stale client value outrank the server's fresh read.
+ */
+declare function buildContextWire(rows: readonly ResolvedContextRow[]): Record<string, unknown>;
+interface ContextReceiptMismatch {
+    key: string;
+    field: "include" | "max_inline_chars" | "delivery" | "user_rule" | "missing";
+    expected: unknown;
+    actual: unknown;
+}
+/**
+ * Compare the rows the client resolved (and rendered, and sent) with the
+ * receipt the server emitted for the same turn.
+ *
+ * For each expected row, the receipt row is matched by key + surface key, then
+ * by key alone. Compared: `include`, `max_inline_chars`, `delivery` (only when
+ * both sides know the size) and `user_rule`. An expected row absent from the
+ * receipt is a `missing` mismatch — except a row the client correctly withheld
+ * for a reason other than the person's own rule (page `auto_context` off, the
+ * agent's kill switch): the client never sent it and the server lists only
+ * the person's saved `include: false` rules as `origin: "rule"` rows, so its
+ * absence is the truth, not a lie. Receipt rows nobody expected are returned
+ * as `systemRows` — shown, never hidden.
+ */
+declare function compareReceipt(expected: readonly ResolvedContextRow[], receipt: ContextReceipt): {
+    mismatches: ContextReceiptMismatch[];
+    systemRows: ContextReceiptRow[];
+};
+/** Compact size for a tabular column: `950`, `18.4k`, `184k`, `1.2M`, `—` for unknown. */
+declare function formatChars(n: number | null | undefined): string;
+
+export { CONTEXT_RULES_FEATURE, type ContextAgentLayer, type ContextDelivery, type ContextLayer, type ContextReceipt, type ContextReceiptMismatch, type ContextReceiptRow, type ContextRowOrigin, type ContextRowSource, type ContextRuleInput, type ContextRuleLayers, type ContextRuleResult, type ContextSurfaceLayer, DEFAULT_INLINE_CAP, DEFAULT_INLINE_MAX_CHARS, DEFAULT_SURFACE_KEY, type ResolvedContextRow, type SavedContextRule, type SavedContextRuleRows, buildContextWire, compareReceipt, contextValueChars, formatChars, lookupSavedRule, resolveContextRow, resolveContextRule };