ds4-context-engine 0.2.0 → 0.3.0-alpha.1

package/src/extension/context-persistence-contract.ts

@@ -0,0 +1,150 @@
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+
+export const CONTEXT_PERSISTENCE_TOOL_CONTRACT = "ds4-context-persistence-tool-v1" as const;
+export const CONTEXT_PERSISTENCE_RESULT_CONTRACT = "ds4-context-persistence-result-v1" as const;
+export const CONTEXT_PERSISTENCE_TOOL_NAME = "context_persistence" as const;
+export const CONTEXT_PERSISTENCE_DESCRIPTION = "Inspect DS4 Pins/Memory. Write only after an explicit user request; writes require local user confirmation." as const;
+export const CONTEXT_PERSISTENCE_PROMPT_SNIPPET = "Inspect or manage user-confirmed DS4 pins and durable memory" as const;
+export const CONTEXT_PERSISTENCE_PROMPT_GUIDELINES = [
+  "Use context_persistence only to inspect DS4 persistent state or when the user explicitly requests a persistence mutation.",
+  "After an explicit persistence request, call the write action directly; context_persistence itself obtains the required local UI confirmation, so do not ask for separate confirmation in chat.",
+  "Never create a pin or memory merely because information appears useful.",
+  "Use pins for confirmed constraints or instructions that must remain prominent. Use memory for durable facts, decisions, and historical knowledge.",
+  "Default new persistence to session scope. Use project or branch scope only when explicitly requested or unambiguous; durable Memory does not support branch scope.",
+  "Before superseding, removing, invalidating, expiring, excluding, or including, read first and use the exact ID or reference plus targetRevision; never mutate from a fuzzy query.",
+  "Do not claim local-only protection if a remote model already saw the input; use /context or a local provider for data that must never reach a remote provider.",
+] as const;
+
+export const CONTEXT_PERSISTENCE_ACTIONS = [
+  "pins_list",
+  "pins_find",
+  "pin_add",
+  "pin_supersede",
+  "pin_unpin",
+  "memory_list",
+  "memory_find",
+  "memory_add",
+  "memory_supersede",
+  "memory_invalidate",
+  "memory_expire",
+  "memory_sources",
+  "memory_source_exclude",
+  "memory_source_include",
+] as const;
+
+export type ContextPersistenceAction = typeof CONTEXT_PERSISTENCE_ACTIONS[number];
+
+export const CONTEXT_PERSISTENCE_READ_ACTIONS = [
+  "pins_list",
+  "pins_find",
+  "memory_list",
+  "memory_find",
+  "memory_sources",
+] as const satisfies readonly ContextPersistenceAction[];
+
+export type ContextPersistenceReadAction = typeof CONTEXT_PERSISTENCE_READ_ACTIONS[number];
+
+export const CONTEXT_PERSISTENCE_WRITE_ACTIONS = CONTEXT_PERSISTENCE_ACTIONS.filter(
+  (action): action is Exclude<ContextPersistenceAction, ContextPersistenceReadAction> =>
+    !(CONTEXT_PERSISTENCE_READ_ACTIONS as readonly string[]).includes(action),
+);
+
+export const CONTEXT_PERSISTENCE_PARAMS = Type.Object({
+  action: StringEnum(CONTEXT_PERSISTENCE_ACTIONS),
+  scope: Type.Optional(StringEnum(["session", "branch", "project"] as const, {
+    description: "Add only; Memory excludes branch",
+  })),
+  id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+  targetRevision: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+  content: Type.Optional(Type.String({ minLength: 1, maxLength: 20_000 })),
+  key: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+  query: Type.Optional(Type.String({ minLength: 2, maxLength: 200 })),
+  reason: Type.Optional(Type.String({
+    minLength: 1,
+    maxLength: 500,
+    description: "Lifecycle or source exclusion only",
+  })),
+  classification: Type.Optional(StringEnum([
+    "normal",
+    "internal",
+    "sensitive",
+    "local-only",
+  ] as const)),
+  activeOnly: Type.Optional(Type.Boolean()),
+  maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+}, { additionalProperties: false });
+
+export type ContextPersistenceParams = Static<typeof CONTEXT_PERSISTENCE_PARAMS>;
+
+const ALLOWED_FIELDS = {
+  pins_list: ["action", "activeOnly", "maxResults"],
+  pins_find: ["action", "query", "activeOnly", "maxResults"],
+  pin_add: ["action", "content", "scope", "classification"],
+  pin_supersede: ["action", "id", "targetRevision", "content", "classification"],
+  pin_unpin: ["action", "id", "targetRevision", "reason"],
+  memory_list: ["action", "activeOnly", "maxResults"],
+  memory_find: ["action", "query", "activeOnly", "maxResults"],
+  memory_add: ["action", "content", "scope", "key", "classification"],
+  memory_supersede: ["action", "id", "targetRevision", "content", "classification"],
+  memory_invalidate: ["action", "id", "targetRevision", "reason"],
+  memory_expire: ["action", "id", "targetRevision", "reason"],
+  memory_sources: ["action", "maxResults"],
+  memory_source_exclude: ["action", "id", "targetRevision", "reason"],
+  memory_source_include: ["action", "id", "targetRevision"],
+} as const satisfies Record<ContextPersistenceAction, readonly (keyof ContextPersistenceParams)[]>;
+
+const REQUIRED_FIELDS = {
+  pins_list: [],
+  pins_find: ["query"],
+  pin_add: ["content"],
+  pin_supersede: ["id", "targetRevision", "content"],
+  pin_unpin: ["id", "targetRevision"],
+  memory_list: [],
+  memory_find: ["query"],
+  memory_add: ["content"],
+  memory_supersede: ["id", "targetRevision", "content"],
+  memory_invalidate: ["id", "targetRevision"],
+  memory_expire: ["id", "targetRevision"],
+  memory_sources: [],
+  memory_source_exclude: ["id", "targetRevision"],
+  memory_source_include: ["id", "targetRevision"],
+} as const satisfies Record<ContextPersistenceAction, readonly (keyof ContextPersistenceParams)[]>;
+
+export type ContextPersistenceValidationCode =
+  | "invalid-parameters"
+  | "invalid-scope";
+
+export type ContextPersistenceValidation =
+  | { ok: true; value: ContextPersistenceParams }
+  | { ok: false; errorCode: ContextPersistenceValidationCode };
+
+function isAction(value: unknown): value is ContextPersistenceAction {
+  return typeof value === "string"
+    && (CONTEXT_PERSISTENCE_ACTIONS as readonly string[]).includes(value);
+}
+
+export function isReadAction(action: ContextPersistenceAction): action is ContextPersistenceReadAction {
+  return (CONTEXT_PERSISTENCE_READ_ACTIONS as readonly string[]).includes(action);
+}
+
+/**
+ * Action-specific validation performed after TypeBox transport validation.
+ * Values are never included in failures so provider-visible errors stay metadata-only.
+ */
+export function validateContextPersistenceParams(
+  params: ContextPersistenceParams,
+): ContextPersistenceValidation {
+  if (!params || !isAction(params.action)) return { ok: false, errorCode: "invalid-parameters" };
+  const keys = Object.keys(params) as (keyof ContextPersistenceParams)[];
+  const allowed = new Set<keyof ContextPersistenceParams>(ALLOWED_FIELDS[params.action]);
+  if (keys.some((key) => !allowed.has(key))) {
+    return { ok: false, errorCode: "invalid-parameters" };
+  }
+  if (REQUIRED_FIELDS[params.action].some((key) => params[key] === undefined)) {
+    return { ok: false, errorCode: "invalid-parameters" };
+  }
+  if (params.scope === "branch" && params.action === "memory_add") {
+    return { ok: false, errorCode: "invalid-scope" };
+  }
+  return { ok: true, value: params };
+}

package/src/extension/context-persistence-egress.ts

@@ -0,0 +1,223 @@
+import {
+  CONTEXT_PERSISTENCE_ACTIONS,
+  CONTEXT_PERSISTENCE_TOOL_NAME,
+} from "./context-persistence-contract.ts";
+import {
+  renderHistoricalContextPersistenceResult,
+  sanitizeHistoricalContextPersistenceDetails,
+} from "./context-persistence-result.ts";
+
+export const CONTEXT_PERSISTENCE_EGRESS_SENTINEL = "[omitted-by-ds4-egress-policy]" as const;
+
+const ACTIONS = new Set<string>(CONTEXT_PERSISTENCE_ACTIONS);
+const SAFE_ARGUMENT_KEYS = new Set([
+  "action",
+  "scope",
+  "id",
+  "targetRevision",
+  "classification",
+  "activeOnly",
+  "maxResults",
+]);
+const SENSITIVE_ARGUMENT_KEYS = new Set(["content", "query", "key", "reason"]);
+const OPAQUE_ID = /^(?:source_[A-Za-z0-9_-]{22,57}|[A-Za-z0-9._:-]{1,128})$/u;
+const REVISION = /^rev_[A-Za-z0-9_-]{1,60}$/u;
+const SAFE_ENUM = /^(?:session|branch|project|normal|internal|sensitive|local-only)$/u;
+const SAFE_METADATA_LINE = /^(?:pin|memory|project-memory-source) (?:source_[A-Za-z0-9_-]{22,57}|[A-Za-z0-9._:-]{1,128})(?:; (?:scope|status|classification|applicable|createdAt|updatedAt|revision|match|score|indexedMutations|activeProjectMemories|activeProjectPins|hasMalformedLines|error)=[A-Za-z0-9_-]+)+$/u;
+const SAFE_SUMMARY_LINE = /^(?:pins_list|pins_find|memory_list|memory_find|memory_sources): \d{1,3} (?:item\(s\)|match\(es\)); truncated=(?:true|false); incomplete=(?:true|false)\.$/u;
+const PREVIEW_LINE = /^(pin|memory) ([\x21-\x7e]{1,128}): /u;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function safeArgumentValue(key: string, value: unknown): unknown {
+  if (key === "action") return typeof value === "string" && ACTIONS.has(value)
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "activeOnly") return typeof value === "boolean"
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "maxResults") return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 100
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "scope" || key === "classification") {
+    return typeof value === "string" && SAFE_ENUM.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  if (key === "id") {
+    return typeof value === "string" && OPAQUE_ID.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  if (key === "targetRevision") {
+    return typeof value === "string" && REVISION.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  return CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+}
+
+/** Arguments are reduced without retaining raw content in temporary result objects. */
+export function sanitizeHistoricalContextPersistenceArguments(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) return {};
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, candidate] of Object.entries(value)) {
+    if (SAFE_ARGUMENT_KEYS.has(key)) sanitized[key] = safeArgumentValue(key, candidate);
+    else if (SENSITIVE_ARGUMENT_KEYS.has(key)) sanitized[key] = CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+    else sanitized[key] = CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  return sanitized;
+}
+
+function sanitizeArgumentContainer(value: unknown): unknown {
+  if (typeof value === "string") {
+    try {
+      return JSON.stringify(sanitizeHistoricalContextPersistenceArguments(JSON.parse(value)));
+    } catch {
+      return JSON.stringify({ omitted: CONTEXT_PERSISTENCE_EGRESS_SENTINEL });
+    }
+  }
+  return sanitizeHistoricalContextPersistenceArguments(value);
+}
+
+/** Preserves only the fixed metadata grammar emitted by the V1 result renderer. */
+export function sanitizeHistoricalContextPersistenceText(value: unknown): string {
+  if (typeof value !== "string" || value.length > 96 * 1024) return CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  const output: string[] = [];
+  for (const line of value.split("\n").slice(0, 205)) {
+    if (SAFE_SUMMARY_LINE.test(line)
+      || SAFE_METADATA_LINE.test(line)
+      || line === "Search incomplete; refine the query or use an exact opaque ID.") {
+      output.push(line);
+      continue;
+    }
+    const preview = PREVIEW_LINE.exec(line);
+    if (preview) {
+      output.push(`${preview[1]} ${preview[2]}: preview omitted by policy`);
+      continue;
+    }
+    if (/^(?:pins_|pin_|memory_)[a-z_]+ (?:ok|rejected|cancelled|unavailable|committed|committed_projection_pending|indeterminate)(?:: [a-z0-9-]{1,64})?\.$/u.test(line)) {
+      output.push(line);
+      continue;
+    }
+    output.push(CONTEXT_PERSISTENCE_EGRESS_SENTINEL);
+  }
+  return output.join("\n") || CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+}
+
+function toolName(record: Record<string, unknown>): string | undefined {
+  if (typeof record.name === "string") return record.name;
+  if (typeof record.toolName === "string") return record.toolName;
+  return undefined;
+}
+
+function identifiers(record: Record<string, unknown>): string[] {
+  return [
+    record.id,
+    record.call_id,
+    record.toolCallId,
+    record.tool_call_id,
+    record.toolUseId,
+    record.tool_use_id,
+  ].filter((value): value is string => typeof value === "string");
+}
+
+function collectToolCallIds(value: unknown, ids: Set<string>, seen: WeakSet<object>): void {
+  if (!value || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const child of value) collectToolCallIds(child, ids, seen);
+    return;
+  }
+  const record = value as Record<string, unknown>;
+  if (toolName(record) === CONTEXT_PERSISTENCE_TOOL_NAME) {
+    for (const id of identifiers(record)) ids.add(id);
+  }
+  for (const child of Object.values(record)) collectToolCallIds(child, ids, seen);
+}
+
+function sanitizeContent(value: unknown, safeText: string): unknown {
+  if (typeof value === "string") return safeText;
+  if (!Array.isArray(value)) return [{ type: "text", text: safeText }];
+  return [{ type: "text", text: safeText }];
+}
+
+function sanitizeNode(
+  value: unknown,
+  toolCallIds: ReadonlySet<string>,
+  seen: WeakMap<object, unknown>,
+): { value: unknown; changed: boolean } {
+  if (!value || typeof value !== "object") return { value, changed: false };
+  const prior = seen.get(value);
+  if (prior !== undefined) return { value: prior, changed: false };
+  if (Array.isArray(value)) {
+    const output: unknown[] = [];
+    seen.set(value, output);
+    let changed = false;
+    for (const child of value) {
+      const sanitized = sanitizeNode(child, toolCallIds, seen);
+      output.push(sanitized.value);
+      changed ||= sanitized.changed;
+    }
+    return changed ? { value: output, changed: true } : { value, changed: false };
+  }
+
+  const record = value as Record<string, unknown>;
+  const directToolCall = toolName(record) === CONTEXT_PERSISTENCE_TOOL_NAME;
+  const linkedResult = identifiers(record).some((id) => toolCallIds.has(id))
+    || (record.role === "toolResult" && record.toolName === CONTEXT_PERSISTENCE_TOOL_NAME);
+  let changed = false;
+  const output: Record<string, unknown> = {};
+  seen.set(value, output);
+
+  for (const [key, child] of Object.entries(record)) {
+    if (directToolCall && (key === "arguments" || key === "args" || key === "input")) {
+      output[key] = sanitizeArgumentContainer(child);
+      changed = true;
+      continue;
+    }
+    if (linkedResult && key === "details") {
+      const details = sanitizeHistoricalContextPersistenceDetails(child);
+      output[key] = details ?? {};
+      changed = true;
+      continue;
+    }
+    if (linkedResult && (key === "content" || key === "output")) {
+      const details = sanitizeHistoricalContextPersistenceDetails(record.details);
+      const text = details
+        ? renderHistoricalContextPersistenceResult(details)
+        : sanitizeHistoricalContextPersistenceText(
+          typeof child === "string"
+            ? child
+            : Array.isArray(child)
+              ? child.flatMap((block) => isRecord(block) && typeof block.text === "string" ? [block.text] : []).join("\n")
+              : undefined,
+        );
+      output[key] = sanitizeContent(child, text);
+      changed = true;
+      continue;
+    }
+    if (linkedResult && key === "response") {
+      const response = isRecord(child) ? child : {};
+      const responseKey = "error" in response ? "error" : "output";
+      output[key] = {
+        [responseKey]: sanitizeHistoricalContextPersistenceText(response[responseKey]),
+      };
+      changed = true;
+      continue;
+    }
+    const sanitized = sanitizeNode(child, toolCallIds, seen);
+    output[key] = sanitized.value;
+    changed ||= sanitized.changed;
+  }
+  return changed ? { value: output, changed: true } : { value, changed: false };
+}
+
+export function sanitizeContextPersistenceHistory<T>(value: T): { value: T; changed: boolean } {
+  const ids = new Set<string>();
+  collectToolCallIds(value, ids, new WeakSet());
+  const sanitized = sanitizeNode(value, ids, new WeakMap());
+  return { value: sanitized.value as T, changed: sanitized.changed };
+}