@ai-matrx/chat 0.1.77 → 0.2.1

package/dist/agents/redux/execution-system/context-rules/request-context.d.ts

@@ -0,0 +1,202 @@
+/**
+ * THE ONE DOOR for a request's `context` — and the rows the screen shows.
+ *
+ * Contract: common-docs systems/scopes-context/context-delivery/RULES.md.
+ *
+ * Every value a turn can carry — the page's values, everything attached to the
+ * chat, the attached files, and the first turn's system values (user, client,
+ * route…) — becomes ONE `ResolvedContextRow` here, with every layer the server
+ * applies (page, agent, the person's saved rule). The composer's table renders
+ * these rows, and `buildContextWire(rows)` turns the SAME rows into the
+ * request body, so what the person sees and what the request carries cannot
+ * drift apart. The server's `context_receipt` is then compared with these rows
+ * (`compareReceipt`) and any difference is loud.
+ *
+ * `pnpm check:context-single-door` fails any other code that puts a `context`
+ * on an agent request.
+ */
+import type { ChatRootState } from "../../../../store/root-state.js";
+import { type ContextRowSource, type ResolvedContextRow } from "@ai-matrx/agents/context";
+import { getManifest } from "../../../../surfaces/runtime/registry.js";
+import type { InstanceContextEntry } from "../../../types/instance.types.js";
+export interface RequestContextOptions {
+    /**
+     * Include the first turn's system values (user, client, route brief,
+     * organization…). Leave it unset: `ambientIncluded` decides from the
+     * conversation itself, so the table and EVERY send path — resume included —
+     * agree. Tests only; `check:context-single-door` refuses it elsewhere.
+     */
+    includeAmbient?: boolean;
+    /**
+     * The Mandate's own context kill switch (`contract.auto_context_disabled`),
+     * which the client learns from the resolved mandate. The agent's switch is
+     * read from its definition here.
+     */
+    mandateKillSwitch?: boolean;
+    /**
+     * Values a send path adds for this request only (the resume's
+     * "page values read after your writes" note). They become rows like
+     * everything else — shown, governed by the person's rules, and sent only
+     * through `buildContextWire`.
+     */
+    extraSources?: readonly ContextRowSource[];
+}
+/**
+ * The request field `page_context` (common-docs context-delivery RULES.md §0):
+ * this conversation is the page's OWN (the main chat, a builder's test run, a
+ * battle column) or the person switched its page off on the chip. The server's
+ * gate withholds the page from it exactly as these rows do.
+ */
+export interface PageContextDirective {
+    mode: "own" | "off";
+    /** The keys withheld at the page layer (beside page values and surroundings). */
+    withheld: string[];
+}
+/**
+ * THE PAGE RULE, decided once for the table and every send path: the page's
+ * own conversation never receives the page nor anything that identifies itself
+ * (its manifest's `ownConversationWithholds`, default the shared baseline); a
+ * conversation whose page switch is off receives none of the page. Null = an
+ * ordinary conversation (a window or panel chat over the page) that follows it.
+ */
+export declare function pageContextFor(state: ChatRootState, conversationId: string): PageContextDirective | null;
+export interface RequestContext {
+    rows: ResolvedContextRow[];
+    /** The request body's `context`, or undefined when nothing is included. */
+    context: Record<string, unknown> | undefined;
+    /**
+     * The request body's `context_withheld`: every key this client holds a value
+     * for but is not sending (off by the page, the agent or the person's rule),
+     * from the SAME rows. The server then lists saved off-rules only for these
+     * keys. Always sent — an empty list means nothing was withheld.
+     */
+    context_withheld: string[];
+    /** The request body's `page_context`; null = omit (the conversation follows its page). */
+    page_context: PageContextDirective | null;
+    /**
+     * The request body's `context_surfaces` (`contextSurfacesFor`): the surface
+     * each mounted screen's value sits under. Null = omit.
+     */
+    context_surfaces: Record<string, string> | null;
+}
+/**
+ * Whether the next turn carries the first turn's system values: on the first
+ * turn of a conversation that sends through the agent door. The builder's
+ * manual door (`apiEndpointMode: "manual"`) never has. ONE answer, read by the
+ * table and the send path alike (a table that showed four system values the
+ * manual send never carried was found live, 2026-09-30).
+ */
+export declare function ambientIncluded(state: ChatRootState, conversationId: string): boolean;
+/**
+ * Whether the rows can name the agent's layer (its Context Policies and kill
+ * switch): true with no agent, or once its execution definition is loaded.
+ */
+export declare function agentContextLayerKnown(state: ChatRootState, conversationId: string): boolean;
+type DeclaredSurfaceValue = NonNullable<ReturnType<typeof getManifest>>["values"][number];
+/**
+ * Where one context value sits: the surface that PUBLISHED it and that
+ * surface's declaration. The publishing runtime's surface (stamped on the
+ * entry) when its manifest declares the value — it wins over the primary's
+ * own declaration of the same name; else the primary page when it declares
+ * it; else the one surface the registry says authored it (an entry written
+ * before its surface was stamped). A value a page published without declaring
+ * it still sits under that page, with no page layer. Nothing else is the
+ * page's: attachments and host-written values stay `_default` ("Attached").
+ * The platform's own keys (`surface_chain`, `window_forms`, `surface_closed`)
+ * are never a page's value.
+ */
+export declare function publishingPlace(entry: Pick<InstanceContextEntry, "key" | "surfaceName">, primarySurface: string | null, primaryDeclared?: (key: string) => DeclaredSurfaceValue | undefined): {
+    surface: string | null;
+    declared: DeclaredSurfaceValue | undefined;
+};
+/**
+ * The request body's `context_surfaces`: every page value (sent or withheld)
+ * that sits under a surface the request does not name as its primary, or
+ * that the primary page published without declaring — so the server files it
+ * exactly where this row sits. Null = nothing to name.
+ */
+export declare function contextSurfacesFor(rows: readonly ResolvedContextRow[], primarySurface: string | null): Record<string, string> | null;
+/** Every value this conversation's next turn would carry, before any rule. */
+export declare function collectContextRowSources(state: ChatRootState, conversationId: string, opts?: RequestContextOptions): ContextRowSource[];
+/**
+ * The resume path's context: the same rows the chip shows for this
+ * conversation (one rule for system values: `ambientIncluded`), plus the note
+ * that the page values were read AFTER the writes this conversation made.
+ */
+export declare function buildResumeRequestContext(state: ChatRootState, conversationId: string, mandateKillSwitch: boolean): RequestContext;
+/** The inline cap the server last reported (a platform knob), else the default. */
+export declare function selectContextInlineCap(state: ChatRootState, conversationId: string): number;
+/** Rows (what the table shows) and the request `context` built from them. */
+export declare function buildRequestContext(state: ChatRootState, conversationId: string, opts?: RequestContextOptions): RequestContext;
+/**
+ * The context fields of `POST /ai/context/preview` — what "what the agent will
+ * receive" is computed from. The SAME door call a send makes (rows, wire,
+ * withheld keys, the page rule) plus the surface the request would name, so
+ * the preview's receipt and the real turn's cannot disagree — on the page's
+ * own conversation and on a switched-off page included (RULES.md §0).
+ */
+export interface PreviewRequestContext {
+    context?: Record<string, unknown>;
+    context_withheld: string[];
+    page_context?: PageContextDirective;
+    context_surfaces?: Record<string, string>;
+    surface?: string;
+}
+export declare function buildPreviewRequestContext(state: ChatRootState, conversationId: string): PreviewRequestContext;
+/**
+ * The rows the composer's context table shows for the NEXT turn — the same
+ * function the send path uses, so the table is exactly what will be sent.
+ * Recomputed only when one of its inputs changes identity.
+ */
+export declare const selectResolvedContextRows: (conversationId: string, mandateKillSwitch?: boolean) => (state: ChatRootState) => ResolvedContextRow[];
+/** A document attached to the conversation right now (a platform.associations edge). */
+export interface DurableAttachment {
+    key: string;
+    label: string;
+}
+/**
+ * One kind of durable attachment and the key prefixes the server files it
+ * under. `items` null = not read yet: rows of that kind are left as they are.
+ */
+export interface DurableAttachmentGroup {
+    prefixes: readonly string[];
+    items: readonly DurableAttachment[] | null;
+}
+/** Documents (processed documents, files) — platform.associations edges. */
+export declare const DOCUMENT_ATTACHMENT_PREFIXES: readonly ["attached_document_", "resource_file_"];
+/** Connector resources (repos, Google files, synced records) — `attachmentContextKey`. */
+export declare const RESOURCE_ATTACHMENT_PREFIXES: readonly ["attached_resource_"];
+/**
+ * The context key the server seeds an attached document under (aidream
+ * context_sources `_attached_document_key` / `_seed_file`); null for a token
+ * the server does not seed as a document.
+ */
+export declare function durableAttachmentKey(token: string, resourceId: string): string | null;
+/**
+ * Reconcile the display rows' server-added attachments with what is attached
+ * NOW, kind by kind: one detached since the last receipt is dropped, and one
+ * attached since then is added (its size unknown until the next receipt). A
+ * kind not read yet leaves its rows unchanged.
+ */
+export declare function reconcileDurableAttachments(state: ChatRootState, conversationId: string, rows: ResolvedContextRow[], groups: readonly DurableAttachmentGroup[]): ResolvedContextRow[];
+/** Record the rows an assembled request body was built from. */
+export declare function rememberRequestContextRows(request: object, rows: ResolvedContextRow[]): void;
+/**
+ * The rows a request body was built from, without their values (the receipt
+ * check needs the rules, not a second copy of every value in the store).
+ */
+export declare function contextRowsForRequest(request: object): ResolvedContextRow[];
+/**
+ * The rows the chip and the full view DISPLAY: `selectResolvedContextRows`,
+ * with the values the server resolves itself (references, `*_id` lookups)
+ * filled in from the latest receipt — their size and delivery are the server's
+ * to report, never the client's to guess (`applyReceiptToRows`) — followed by
+ * every value the SERVER added that turn (its own attachments, scope seeds,
+ * saved off-rules: `compareReceipt(expected, receipt).systemRows`), each a
+ * governable row with the normal Include switch and Inline max, saved under
+ * the surface key the server filed it with. Display only: the send path and
+ * the receipt check use the unfilled rows, and these rows carry no value, so
+ * they can never reach the wire. No receipt yet: only the client's rows.
+ */
+export declare const selectDisplayContextRows: (conversationId: string, mandateKillSwitch?: boolean) => (state: ChatRootState) => ResolvedContextRow[];
+export {};

package/dist/agents/redux/execution-system/context-rules/request-context.js

@@ -0,0 +1,423 @@
+import {
+  DEFAULT_INLINE_CAP,
+  DEFAULT_SURFACE_KEY,
+  applyReceiptToRows,
+  buildContextWire,
+  compareReceipt,
+  resolveContextRow,
+  systemRowsToResolved,
+  withheldKeys,
+  isServerAuthoritativeKey,
+  CONTEXT_ROW_BLOCKS
+} from "@ai-matrx/agents/context";
+import { getDeclaringSurface, getManifest } from "../../../../surfaces/runtime/registry.js";
+import { humanizeIdentifier } from "@ai-matrx/kit/text-case";
+import {
+  BASELINE_VALUES,
+  OWN_CONVERSATION_WITHHELD,
+  PAGE_OFF_WITHHELD,
+  PAGELESS_CONTENT_INLINE_CEILING,
+  PERSON_CONTEXT_VALUES,
+  PLATFORM_RESERVED_NAMES,
+  POINTER_INLINE_CEILINGS
+} from "../../../../surfaces/manifests/_baseline.manifest.js";
+import { pageOwningConversation } from "../../../../surfaces/runtime/SurfaceRuntimeContext.js";
+import {
+  companionSurfaceOpen,
+  SURFACE_CHAIN_KEY
+} from "../../../../surfaces/runtime/surface-chain.js";
+import { selectPageContextOff } from "../instance-ui-state/instance-ui-state.selectors.js";
+import {
+  selectAgentAutoContextDisabled,
+  selectAgentContextPolicies,
+  selectAgentReadyForExecution
+} from "../../agent-definition/selectors.js";
+import { selectResourceContextPayload } from "../instance-resources/instance-resources.selectors.js";
+import {
+  buildAmbientContext,
+  isFirstTurn
+} from "../../../ui-first-tools/redux/build-ambient-context.js";
+import { selectSavedContextRuleRows } from "./context-rules.thunks.js";
+import { deliveredFieldsFor, toContextReceipt } from "./receipt-check.js";
+import { resolveClientSurface } from "../utils/build-tool-injection.js";
+import { surfaceWritesNoteSource } from "../utils/surface-writes-note.js";
+function pageContextFor(state, conversationId) {
+  const owner = pageOwningConversation(conversationId);
+  if (owner) {
+    const listed = getManifest(owner)?.ownConversationWithholds ?? OWN_CONVERSATION_WITHHELD;
+    const companionOpen = companionSurfaceOpen();
+    return {
+      mode: "own",
+      withheld: listed.filter(
+        (key) => !PERSON_CONTEXT_VALUES.has(key) && !(companionOpen && key === SURFACE_CHAIN_KEY)
+      )
+    };
+  }
+  if (selectPageContextOff(conversationId)(state)) {
+    return { mode: "off", withheld: [...PAGE_OFF_WITHHELD] };
+  }
+  return null;
+}
+function pageWithholds(page, key, surfaceKey) {
+  if (!page || PERSON_CONTEXT_VALUES.has(key)) return false;
+  if (page.withheld.includes(key)) return true;
+  return Boolean(surfaceKey && surfaceKey !== DEFAULT_SURFACE_KEY);
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function validLimit(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function rowLabel(key, ...written) {
+  for (const label of written) {
+    const text = label?.trim();
+    if (text && text !== key) return text;
+  }
+  return humanizeIdentifier(key) || key;
+}
+function attachedFileLabel(state, conversationId, fileId) {
+  const resources = state.instanceResources?.byConversationId[conversationId];
+  for (const resource of Object.values(resources ?? {})) {
+    const source = resource.source;
+    if (!isRecord(source)) continue;
+    if (source.file_id !== fileId && source.fileId !== fileId) continue;
+    for (const field of ["filename", "file_name", "name", "title", "label"]) {
+      const v = source[field];
+      if (typeof v === "string" && v.trim()) return v.trim();
+    }
+  }
+  return "Attached file";
+}
+function ambientIncluded(state, conversationId) {
+  const mode = state.messages?.byConversationId?.[conversationId]?.apiEndpointMode ?? "agent";
+  return mode !== "manual" && isFirstTurn(state, conversationId);
+}
+function agentContextLayerKnownFor(state, agentId) {
+  return Boolean(agentId && selectAgentReadyForExecution(state, agentId));
+}
+function agentContextLayerKnown(state, conversationId) {
+  const agentId = state.conversations?.byConversationId[conversationId]?.agentId ?? null;
+  return !agentId || agentContextLayerKnownFor(state, agentId);
+}
+function publishingPlace(entry, primarySurface, primaryDeclared = (key) => primarySurface ? getManifest(primarySurface)?.values.find((v) => v.name === key) : void 0) {
+  const own = entry.surfaceName && !PLATFORM_RESERVED_NAMES.values.includes(entry.key) ? entry.surfaceName : null;
+  const ownDeclared = own ? getManifest(own)?.values.find((v) => v.name === entry.key) : void 0;
+  if (own && ownDeclared) return { surface: own, declared: ownDeclared };
+  const onPrimary = primaryDeclared(entry.key);
+  if (onPrimary && primarySurface) return { surface: primarySurface, declared: onPrimary };
+  if (own) return { surface: own, declared: void 0 };
+  if (entry.surfaceName) return { surface: null, declared: void 0 };
+  const author = getDeclaringSurface(entry.key);
+  if (author) {
+    return { surface: author, declared: getManifest(author)?.values.find((v) => v.name === entry.key) };
+  }
+  return { surface: null, declared: void 0 };
+}
+function contextSurfacesFor(rows, primarySurface) {
+  const out = {};
+  for (const row of rows) {
+    if (row.origin !== "page" || row.fromReceipt) continue;
+    if (!row.surfaceKey || row.surfaceKey === DEFAULT_SURFACE_KEY) continue;
+    if (row.surfaceKey === primarySurface && row.layers?.surface?.declared !== false) continue;
+    out[row.key] = row.surfaceKey;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+function collectContextRowSources(state, conversationId, opts = {}) {
+  const conversation = state.conversations?.byConversationId[conversationId];
+  const surfaceName = resolveClientSurface(state, conversationId) ?? null;
+  const manifest = surfaceName ? getManifest(surfaceName) : void 0;
+  const declaredValue = (key) => manifest?.values.find((v) => v.name === key);
+  const surfaceLayer = (key, pageLimit = null) => {
+    const declared = declaredValue(key);
+    if (!declared) return { surfaceKey: DEFAULT_SURFACE_KEY, surface: null };
+    return {
+      surfaceKey: surfaceName ?? DEFAULT_SURFACE_KEY,
+      surface: {
+        declared: true,
+        auto_context: declared.autoContext ?? true,
+        max_inline_chars: pageLimit ?? validLimit(declared.inlineUpTo)
+      }
+    };
+  };
+  const agentId = conversation?.agentId ?? null;
+  const agentLoaded = agentContextLayerKnownFor(state, agentId);
+  const policies = agentLoaded ? selectAgentContextPolicies(state, agentId) : void 0;
+  const killSwitch = agentLoaded && selectAgentAutoContextDisabled(state, agentId) || opts.mandateKillSwitch === true;
+  const policyFor = (key) => policies?.find((p) => p.key === key);
+  const agentLayer = (key) => {
+    const policy = policyFor(key);
+    return {
+      declared: Boolean(policy),
+      max_inline_chars: validLimit(policy?.max_inline_chars),
+      kill_switch: killSwitch
+    };
+  };
+  const byKey = /* @__PURE__ */ new Map();
+  const entries = Object.values(state.instanceContext?.byConversationId[conversationId] ?? {});
+  for (const entry of entries) {
+    const place = publishingPlace(entry, surfaceName, declaredValue);
+    const declared = place.declared;
+    const pointer = POINTER_INLINE_CEILINGS[entry.key];
+    const ownLimit = isRecord(entry.value) && "content" in entry.value ? validLimit(entry.value.max_inline_chars) : null;
+    const pageLimit = pointer ? Math.max(pointer, declared?.inlineUpTo ?? 0) : validLimit(declared?.inlineUpTo) ?? (!surfaceName && !place.surface && entry.key === "content" ? PAGELESS_CONTENT_INLINE_CEILING : ownLimit);
+    const baseline = BASELINE_VALUES[entry.key];
+    const policy = policyFor(entry.key);
+    byKey.set(entry.key, {
+      key: entry.key,
+      label: rowLabel(entry.key, policy?.label, declared?.label, entry.label),
+      // The server files the value under the same surface: the primary's own,
+      // or the one `context_surfaces` names (RULES.md §3).
+      surfaceKey: place.surface ?? DEFAULT_SURFACE_KEY,
+      origin: place.surface ? "page" : "attached",
+      value: entry.value,
+      type: entry.type,
+      // The person's pointer says they are pointing at this text; a page value
+      // the page asked to inline carries the page's own description of it.
+      ...pointer && baseline?.description ? { description: baseline.description } : declared?.inlineUpTo && declared.description ? { description: declared.description } : {},
+      layers: {
+        agent: agentLayer(entry.key),
+        surface: {
+          declared: Boolean(declared),
+          auto_context: declared ? declared.autoContext ?? true : null,
+          max_inline_chars: pageLimit
+        }
+      }
+    });
+  }
+  const resourceContext = selectResourceContextPayload(conversationId)(state);
+  for (const [key, value] of Object.entries(resourceContext ?? {})) {
+    const fileId = key.replace(/^resource_file_/, "");
+    const page2 = surfaceLayer(key);
+    byKey.set(key, {
+      key,
+      label: attachedFileLabel(state, conversationId, fileId),
+      surfaceKey: page2.surfaceKey,
+      origin: "attached",
+      value,
+      // The server measures a reference after resolving it.
+      chars: null,
+      layers: { agent: agentLayer(key), surface: page2.surface }
+    });
+  }
+  const includeAmbient = opts.includeAmbient ?? ambientIncluded(state, conversationId);
+  if (includeAmbient) {
+    const ambient = buildAmbientContext(state, conversationId);
+    for (const [key, value] of Object.entries(ambient ?? {})) {
+      const page2 = surfaceLayer(key);
+      byKey.set(key, {
+        key,
+        label: rowLabel(key, declaredValue(key)?.label),
+        surfaceKey: page2.surfaceKey,
+        origin: "system",
+        value,
+        layers: { agent: agentLayer(key), surface: page2.surface }
+      });
+    }
+  }
+  for (const source of opts.extraSources ?? []) byKey.set(source.key, source);
+  const page = pageContextFor(state, conversationId);
+  if (!page) return [...byKey.values()];
+  return [...byKey.values()].map(
+    (source) => pageWithholds(page, source.key, source.surfaceKey) ? {
+      ...source,
+      layers: {
+        ...source.layers ?? {},
+        surface: {
+          declared: true,
+          auto_context: false,
+          max_inline_chars: source.layers?.surface?.max_inline_chars ?? null
+        }
+      }
+    } : source
+  );
+}
+function buildResumeRequestContext(state, conversationId, mandateKillSwitch) {
+  const writesNote = surfaceWritesNoteSource(state, conversationId);
+  return buildRequestContext(state, conversationId, {
+    mandateKillSwitch,
+    extraSources: writesNote ? [writesNote] : []
+  });
+}
+function selectContextInlineCap(state, conversationId) {
+  return state.instanceContext?.receiptByConversationId?.[conversationId]?.receipt.cap ?? DEFAULT_INLINE_CAP;
+}
+function buildRequestContext(state, conversationId, opts = {}) {
+  const saved = selectSavedContextRuleRows(state);
+  const cap = selectContextInlineCap(state, conversationId);
+  const primarySurface = resolveClientSurface(state, conversationId) ?? null;
+  const rows = collectContextRowSources(state, conversationId, opts).map(
+    (source) => resolveContextRow(source, saved, cap, primarySurface)
+  );
+  const wire = buildContextWire(rows);
+  return {
+    rows,
+    context: Object.keys(wire).length > 0 ? wire : void 0,
+    context_withheld: withheldKeys(rows),
+    page_context: pageContextFor(state, conversationId),
+    context_surfaces: contextSurfacesFor(rows, primarySurface)
+  };
+}
+function buildPreviewRequestContext(state, conversationId) {
+  const door = buildRequestContext(state, conversationId);
+  const surface = resolveClientSurface(state, conversationId);
+  return {
+    ...door.context ? { context: door.context } : {},
+    context_withheld: door.context_withheld,
+    ...door.page_context ? { page_context: door.page_context } : {},
+    ...door.context_surfaces ? { context_surfaces: door.context_surfaces } : {},
+    ...surface ? { surface } : {}
+  };
+}
+const EMPTY_ROWS = [];
+function displayInputs(state, conversationId) {
+  const conversation = state.conversations?.byConversationId[conversationId];
+  const agentId = conversation?.agentId ?? null;
+  return [
+    state.instanceContext?.byConversationId[conversationId],
+    conversation?.surfaceName ?? null,
+    agentId ? state.agentDefinition?.agents[agentId] : null,
+    state.instanceResources?.byConversationId[conversationId],
+    selectSavedContextRuleRows(state),
+    state.instanceContext?.receiptByConversationId?.[conversationId]?.receipt.cap ?? null,
+    ambientIncluded(state, conversationId),
+    resolveClientSurface(state, conversationId) ?? null,
+    pageOwningConversation(conversationId),
+    selectPageContextOff(conversationId)(state)
+  ];
+}
+const rowsMemo = /* @__PURE__ */ new Map();
+const selectResolvedContextRows = (conversationId, mandateKillSwitch = false) => (state) => {
+  const inputs = [...displayInputs(state, conversationId), mandateKillSwitch];
+  const memoKey = conversationId;
+  const hit = rowsMemo.get(memoKey);
+  if (hit && hit.inputs.length === inputs.length && hit.inputs.every((v, i) => v === inputs[i])) {
+    return hit.rows;
+  }
+  const { rows } = buildRequestContext(state, conversationId, { mandateKillSwitch });
+  const out = rows.length === 0 ? EMPTY_ROWS : rows;
+  rowsMemo.set(memoKey, { inputs, rows: out });
+  return out;
+};
+const DOCUMENT_ATTACHMENT_PREFIXES = ["attached_document_", "resource_file_"];
+const RESOURCE_ATTACHMENT_PREFIXES = ["attached_resource_"];
+function durableAttachmentKey(token, resourceId) {
+  if (token === "processed_document") return `attached_document_${resourceId}`;
+  if (token === "file") return `resource_file_${resourceId}`;
+  return null;
+}
+function reconcileDurableAttachments(state, conversationId, rows, groups) {
+  const read = groups.filter((g) => g.items !== null);
+  if (read.length === 0) return rows;
+  const current = new Set(read.flatMap((g) => g.items.map((a) => a.key)));
+  const governed = (key) => read.some((g) => g.prefixes.some((p) => key.startsWith(p)));
+  const kept = rows.filter((row) => !(row.fromReceipt && governed(row.key)) || current.has(row.key));
+  const shown = new Set(kept.map((row) => row.key));
+  const saved = selectSavedContextRuleRows(state);
+  const cap = selectContextInlineCap(state, conversationId);
+  const primarySurface = resolveClientSurface(state, conversationId) ?? null;
+  const added = read.flatMap((g) => g.items).filter((a) => !shown.has(a.key)).map((a) => {
+    const row = resolveContextRow(
+      { key: a.key, label: a.label, surfaceKey: DEFAULT_SURFACE_KEY, origin: "attached", value: void 0, chars: null },
+      saved,
+      cap,
+      primarySurface
+    );
+    return { ...row, serverResolved: true, delivery: row.include ? "server" : "off" };
+  });
+  return added.length === 0 && kept.length === rows.length ? rows : [...kept, ...added];
+}
+const rowsByRequest = /* @__PURE__ */ new WeakMap();
+function rememberRequestContextRows(request, rows) {
+  rowsByRequest.set(request, rows);
+}
+function contextRowsForRequest(request) {
+  return (rowsByRequest.get(request) ?? EMPTY_ROWS).map((row) => ({ ...row, value: void 0 }));
+}
+const isServerOwnedKey = isServerAuthoritativeKey;
+const ROW_BLOCK_IDS = CONTEXT_ROW_BLOCKS;
+function statedBlockChars(receipt, key) {
+  const ids = ROW_BLOCK_IDS[key] ?? [];
+  return (receipt.blocks ?? []).filter((b) => ids.includes(b.id)).reduce((n, b) => n + b.delivered.chars, 0);
+}
+function lastPersistedReceipt(state, conversationId) {
+  const entry = state.messages?.byConversationId?.[conversationId];
+  const ids = entry?.orderedIds ?? [];
+  for (let i = ids.length - 1; i >= 0; i--) {
+    const record = entry?.byId?.[ids[i]];
+    if (record?.role !== "user") continue;
+    const receipt = record.modelContext?.delivery?.receipt;
+    if (receipt) return receipt;
+  }
+  return void 0;
+}
+const displayMemo = /* @__PURE__ */ new Map();
+const selectDisplayContextRows = (conversationId, mandateKillSwitch = false) => (state) => {
+  const rows = selectResolvedContextRows(conversationId, mandateKillSwitch)(state);
+  const live = state.instanceContext?.receiptByConversationId?.[conversationId]?.receipt;
+  const receipt = live ?? lastPersistedReceipt(state, conversationId);
+  if (!receipt) return rows;
+  const expected = live ? state.instanceContext?.expectedByConversationId?.[conversationId] : void 0;
+  const saved = selectSavedContextRuleRows(state);
+  const hit = displayMemo.get(conversationId);
+  if (hit && hit.rows === rows && hit.receipt === receipt && hit.expected === expected && hit.saved === saved) {
+    return hit.out;
+  }
+  const actual = toContextReceipt(receipt);
+  const shown = new Set(rows.map((row) => row.key));
+  const unsent = expected ? compareReceipt(expected.rows, actual).systemRows : actual.rows.filter((row) => row.origin !== "client");
+  const cap = selectContextInlineCap(state, conversationId);
+  const primarySurface = resolveClientSurface(state, conversationId) ?? null;
+  const serverAdded = systemRowsToResolved(unsent).filter((row) => !shown.has(row.key)).map((row) => ({
+    ...resolveContextRow(
+      {
+        key: row.key,
+        label: row.label,
+        surfaceKey: row.surfaceKey,
+        origin: row.origin,
+        value: void 0,
+        chars: row.chars,
+        layers: row.layers
+      },
+      saved,
+      cap,
+      primarySurface
+    ),
+    serverResolved: true,
+    fromReceipt: true
+  }));
+  const receiptLabel = (row) => (actual.rows.find((r) => r.key === row.key && r.surface_key === row.surfaceKey) ?? actual.rows.find((r) => r.key === row.key))?.label;
+  const filled = applyReceiptToRows(rows, actual).map((row) => {
+    const label = row.fromReceipt ? receiptLabel(row) : void 0;
+    return label && label !== row.label ? { ...row, label } : row;
+  });
+  const out = [...filled, ...serverAdded].map((row) => {
+    const fields = deliveredFieldsFor(receipt, row.key, row.surfaceKey);
+    if (Object.keys(fields).length === 0) return row;
+    const stated = fields.delivered && isServerOwnedKey(row.key) ? fields.delivered.chars + statedBlockChars(receipt, row.key) : null;
+    return { ...row, ...fields, ...stated !== null ? { chars: stated } : {} };
+  });
+  displayMemo.set(conversationId, { rows, receipt, expected, saved, out });
+  return out;
+};
+export {
+  DOCUMENT_ATTACHMENT_PREFIXES,
+  RESOURCE_ATTACHMENT_PREFIXES,
+  agentContextLayerKnown,
+  ambientIncluded,
+  buildPreviewRequestContext,
+  buildRequestContext,
+  buildResumeRequestContext,
+  collectContextRowSources,
+  contextRowsForRequest,
+  contextSurfacesFor,
+  durableAttachmentKey,
+  pageContextFor,
+  publishingPlace,
+  reconcileDurableAttachments,
+  rememberRequestContextRows,
+  selectContextInlineCap,
+  selectDisplayContextRows,
+  selectResolvedContextRows
+};

package/dist/agents/redux/execution-system/context-rules/surface-context-rows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A PAGE'S OWN VALUES AS CONTEXT ROWS — what the Surface Context window
+ * renders, through the SAME table and hierarchy as the composer's chip and
+ * full view (one renderer, one data source: the resolved manifest + the live
+ * scope + the person's saved rules).
+ *
+ * Every declared value is a row (supplied or not), plus every key the page's
+ * runtime emits that its manifest never declared. Each row's Include and
+ * Inline max are the person's real rules for this page — the same rows the
+ * server reads — so the inspector is also a control, never a second list.
+ */
+import { type ResolvedContextRow, type SavedContextRuleRows } from "@ai-matrx/agents/context";
+/** What the inspector marks beside a row. */
+export interface SurfaceValueStatus {
+    /** `absent` = the key is not in the live scope; `empty` = present and empty. */
+    supplied: "present" | "empty" | "absent";
+    /** The manifest says the page always supplies it. */
+    required: boolean;
+    /** The manifest declares it (false: the runtime emitted an undeclared key). */
+    declared: boolean;
+}
+export interface SurfaceContextRows {
+    rows: ResolvedContextRow[];
+    status: Record<string, SurfaceValueStatus>;
+}
+export declare function surfaceContextRows(surfaceName: string, scope: Record<string, unknown>, saved: SavedContextRuleRows | null | undefined, cap?: number): SurfaceContextRows;