@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/skills.ts

@@ -8,6 +8,7 @@
  */
 
 import { parseFrontmatter } from "./frontmatter.ts";
+import type { LogEvent } from "./events.ts";
 
 /** Agent Skills name rule. Assumed from the spec, not measured. */
 const MAX_NAME_LENGTH = 64;
@@ -25,6 +26,28 @@ export interface Skill {
   readonly filePath: string;
   readonly body: string;
   readonly disableModelInvocation: boolean;
+  readonly userInvocable?: boolean;
+  readonly context?: "fork";
+  readonly allowedTools?: readonly string[];
+  readonly disallowedTools?: readonly string[];
+  /** Stored outside the model prefix so resource reads reproduce the loaded bytes. */
+  readonly sourceText?: string;
+}
+
+export type LoadedSkill = { name: string; path: string; sha256: string; artifact: string;
+  mode: "inline" | "fork" | "read"; origin: "user" | "model"; node: number; event: string };
+
+/** O.12: explicit capability intersection, never an approval grant. */
+export function skillTools(parent: readonly string[], skill: Skill): string[] {
+  return parent.filter(name => (skill.allowedTools === undefined || skill.allowedTools.includes(name)) && !skill.disallowedTools?.includes(name));
+}
+
+export function deriveLoadedSkills(previous: readonly LoadedSkill[], events: readonly LogEvent[], node: number): LoadedSkill[] {
+  const loaded = new Map(previous.map(item => [item.path, item]));
+  for (const e of events) if (e.t === "skill_loaded") loaded.set(e.path, {
+    name: e.name, path: e.path, sha256: e.sha256, artifact: e.artifact, mode: e.mode, origin: e.origin, node, event: e.id,
+  });
+  return [...loaded.values()];
 }
 
 export function isValidSkillName(name: string): boolean {
@@ -38,6 +61,22 @@ export function parseSkill(input: {
 }): { skill: Skill | null; diagnostics: readonly string[] } {
   const parsed = parseFrontmatter(input.text);
   const diagnostics = [...parsed.diagnostics];
+  const supported = ["name", "description", "disable-model-invocation", "user-invocable", "context", "allowed-tools", "disallowed-tools", "license", "compatibility"];
+  for (const key of Object.keys(parsed.fields)) if (!supported.includes(key)) diagnostics.push(`${input.filePath}: unsupported skill field ${key}`);
+  for (const key of ["disable-model-invocation", "user-invocable"]) {
+    if (parsed.fields[key] !== undefined && typeof parsed.fields[key] !== "boolean") diagnostics.push(`${input.filePath}: ${key} must be boolean`);
+  }
+  if (parsed.fields["context"] !== undefined && parsed.fields["context"] !== "fork") diagnostics.push(`${input.filePath}: context must be fork`);
+  const toolNames = (key: string): string[] | undefined => {
+    const value = parsed.fields[key];
+    if (value === undefined) return undefined;
+    const aliases: Record<string, string> = { Read: "read", Write: "write", Edit: "edit", Grep: "grep", Glob: "find", Bash: "bash" };
+    const names = Array.isArray(value) ? value : typeof value === "string" ? value.split(/[\s,]+/).filter(Boolean) : [];
+    if ((names.length === 0 && value !== "") || names.some(name => !/^[A-Za-z][A-Za-z0-9_-]*$/.test(name))) diagnostics.push(`${input.filePath}: ${key} requires explicit tool names; permission patterns are unsupported`);
+    return [...new Set(names.map(name => aliases[name] ?? name))];
+  };
+  const allowedTools = toolNames("allowed-tools"), disallowedTools = toolNames("disallowed-tools");
+  if (diagnostics.length > 0) return { skill: null, diagnostics };
   const desc = parsed.fields["description"];
   const description = typeof desc === "string" ? desc.trim() : "";
   if (description.length === 0) {
@@ -62,6 +101,11 @@ export function parseSkill(input: {
       filePath: input.filePath,
       body: parsed.body,
       disableModelInvocation: disable,
+      userInvocable: parsed.fields["user-invocable"] !== false,
+      sourceText: input.text,
+      ...(parsed.fields["context"] === "fork" ? { context: "fork" as const } : {}),
+      ...(allowedTools ? { allowedTools } : {}),
+      ...(disallowedTools ? { disallowedTools } : {}),
     },
     diagnostics,
   };

package/src/core/sql-query.ts

@@ -0,0 +1,211 @@
+/** Q.17: an optional syntax for DataQuery, never an alternate execution path. */
+import { parseDataQuery, type DataQuery } from "./data-query.ts";
+import { isRecord } from "./event-validation.ts";
+
+// Assumed synchronous parsing budgets, not measured model or database limits.
+// Reject over-budget input before lexing; never execute a parsed prefix.
+export const MAX_SQL_CHARS = 16_384;
+export const MAX_SQL_TOKENS = 4_096;
+export const SQL_QUERY_HELP = "SQL-style subset: SELECT * or fields/COUNT/SUM/AVG/MIN/MAX(field) AS alias FROM source; optional WHERE comparisons, IS [NOT] NULL or CONTAINS(field, literal), joined by AND; GROUP BY; ORDER BY field [ASC|DESC]. No comments, joins, subqueries, OR, HAVING, DISTINCT, LIMIT/OFFSET or multiple statements. Use artifact pages for large results.";
+
+type Token = { kind: "word" | "identifier" | "string" | "number" | "symbol" | "end"; text: string; at: number };
+type Aggregate = NonNullable<DataQuery["aggregate"]>[number];
+type Predicate = NonNullable<DataQuery["where"]>[number];
+const OPERATIONS = ["count", "sum", "avg", "min", "max"] as const;
+const RESERVED = new Set(("SELECT FROM SOURCE WHERE GROUP BY ORDER ASC DESC AS AND IS NOT NULL TRUE FALSE CONTAINS " +
+  "COUNT SUM AVG MIN MAX DISTINCT LIMIT OFFSET HAVING JOIN INNER LEFT RIGHT OUTER ON UNION WITH OR IN LIKE BETWEEN " +
+  "INSERT UPDATE DELETE DROP CREATE ALTER INTO VALUES RETURNING").split(" "));
+const JSON_OPERATORS = ["where", "select", "group_by", "aggregate", "order_by"] as const;
+
+function sqlError(at: number, message: string): never {
+  // Locations refer to UTF-16 offsets in the supplied string, without echoing data literals.
+  throw new Error("SQL at offset " + at + ": " + message + ". " + SQL_QUERY_HELP);
+}
+function tokenize(sql: string): Token[] {
+  if (sql.length > MAX_SQL_CHARS) sqlError(MAX_SQL_CHARS, "input exceeds " + MAX_SQL_CHARS + " characters");
+  const tokens: Token[] = [];
+  let at = 0;
+  const emit = (kind: Token["kind"], text: string, start: number) => {
+    if (tokens.length >= MAX_SQL_TOKENS) sqlError(start, "input exceeds " + MAX_SQL_TOKENS + " tokens");
+    tokens.push({ kind, text, at: start });
+  };
+  while (at < sql.length) {
+    const c = sql[at]!;
+    if (/\s/.test(c)) { at++; continue; }
+    const start = at;
+    if (c === "'" || c === '"') {
+      const quote = c;
+      let value = "", closed = false;
+      at++;
+      while (at < sql.length) {
+        const next = sql[at++]!;
+        if (next !== quote) value += next;
+        else if (sql[at] === quote) { value += quote; at++; }
+        else { closed = true; break; }
+      }
+      if (!closed) sqlError(start, "unterminated quoted value");
+      emit(quote === "'" ? "string" : "identifier", value, start);
+    } else if (/[A-Za-z_]/.test(c)) {
+      at++;
+      while (at < sql.length && /[A-Za-z0-9_$]/.test(sql[at]!)) at++;
+      emit("word", sql.slice(start, at), start);
+    } else if (/[0-9+-]/.test(c) || (c === "." && /[0-9]/.test(sql[at + 1] ?? ""))) {
+      const numeric = /^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?/.exec(sql.slice(at));
+      if (!numeric || !Number.isFinite(Number(numeric[0]))) sqlError(start, "expected a finite numeric literal; comments are unsupported");
+      at += numeric[0].length;
+      emit("number", numeric[0], start);
+    } else {
+      const pair = sql.slice(at, at + 2);
+      if (["<=", ">=", "!=", "<>"].includes(pair)) { at += 2; emit("symbol", pair, start); }
+      else if (",().*;=<>".includes(c)) { at++; emit("symbol", c, start); }
+      else sqlError(start, "unsupported character");
+    }
+  }
+  tokens.push({ kind: "end", text: "", at: sql.length });
+  return tokens;
+}
+
+class SqlParser {
+  private readonly tokens: readonly Token[];
+  private index = 0;
+  constructor(sql: string) { this.tokens = tokenize(sql); }
+  private get current(): Token { return this.tokens[this.index]!; }
+  private isWord(word: string): boolean { return this.current.kind === "word" && this.current.text.toUpperCase() === word; }
+  private word(word: string): boolean {
+    if (!this.isWord(word)) return false;
+    this.index++; return true;
+  }
+  private symbol(text: string): boolean {
+    if (this.current.kind !== "symbol" || this.current.text !== text) return false;
+    this.index++; return true;
+  }
+  private requireWord(word: string): void {
+    if (!this.word(word)) sqlError(this.current.at, "expected " + word);
+  }
+  private requireSymbol(text: string): void {
+    if (!this.symbol(text)) sqlError(this.current.at, "expected " + text);
+  }
+  private identifier(): string {
+    const token = this.current;
+    if (token.kind !== "identifier" && (token.kind !== "word" || RESERVED.has(token.text.toUpperCase()))) {
+      sqlError(token.at, 'expected a field or alias; quote reserved names with double quotes');
+    }
+    if (!token.text) sqlError(token.at, "field and alias names must be nonempty");
+    this.index++;
+    return token.text;
+  }
+  private field(): string {
+    const parts = [this.identifier()];
+    while (this.symbol(".")) parts.push(this.identifier());
+    return parts.join(".");
+  }
+  private fields(): string[] {
+    const fields = [this.field()];
+    while (this.symbol(",")) fields.push(this.field());
+    return fields;
+  }
+  private literal(): string | number | boolean {
+    const token = this.current;
+    if (token.kind === "number") { this.index++; return Number(token.text); }
+    if (token.kind === "string") { this.index++; return token.text; }
+    if (this.word("TRUE")) return true;
+    if (this.word("FALSE")) return false;
+    sqlError(token.at, "expected a string, finite number or boolean literal; use IS NULL for null checks");
+  }
+  private predicate(): Predicate {
+    if (this.word("CONTAINS")) {
+      this.requireSymbol("(");
+      const field = this.field();
+      this.requireSymbol(",");
+      const value = this.literal();
+      this.requireSymbol(")");
+      return { field, op: "contains", value };
+    }
+    const field = this.field();
+    if (this.word("IS")) {
+      const not = this.word("NOT");
+      this.requireWord("NULL");
+      return { field, op: not ? "ne" : "eq", value: null };
+    }
+    const token = this.current;
+    const ops: Record<string, Predicate["op"]> = { "=": "eq", "!=": "ne", "<>": "ne", "<": "lt", "<=": "lte", ">": "gt", ">=": "gte" };
+    const op = token.kind === "symbol" ? ops[token.text] : undefined;
+    if (op === undefined) sqlError(token.at, "expected a comparison operator or IS [NOT] NULL");
+    this.index++;
+    return { field, op, value: this.literal() };
+  }
+  parse(source: Pick<DataQuery, "format" | "pointer">): DataQuery {
+    this.requireWord("SELECT");
+    const wildcard = this.symbol("*");
+    const selected: string[] = [], fields: string[] = [], aggregates: Aggregate[] = [];
+    if (!wildcard) {
+      do {
+        const token = this.current;
+        const op = OPERATIONS.find(value => token.kind === "word" && value.toUpperCase() === token.text.toUpperCase());
+        if (op !== undefined) {
+          this.index++;
+          this.requireSymbol("(");
+          const star = this.symbol("*");
+          if (star && op !== "count") sqlError(token.at, "only COUNT accepts *");
+          const field = star ? undefined : this.field();
+          this.requireSymbol(")"); this.requireWord("AS");
+          const alias = this.identifier();
+          aggregates.push({ op, ...(field === undefined ? {} : { field }), as: alias });
+          selected.push(alias);
+        } else {
+          const field = this.field();
+          selected.push(field); fields.push(field);
+        }
+      } while (this.symbol(","));
+    }
+    this.requireWord("FROM"); this.requireWord("SOURCE");
+    const query: DataQuery = { ...source, ...(!wildcard ? { select: selected } : {}) };
+    if (this.word("WHERE")) {
+      const where = [this.predicate()];
+      while (this.word("AND")) where.push(this.predicate());
+      query.where = where;
+    }
+    if (this.word("GROUP")) { this.requireWord("BY"); query.group_by = this.fields(); }
+    if (this.word("ORDER")) {
+      this.requireWord("BY");
+      const order: NonNullable<DataQuery["order_by"]>[number][] = [];
+      do {
+        const field = this.field(), descending = this.word("DESC");
+        if (!descending) this.word("ASC");
+        order.push({ field, ...(descending ? { descending: true } : {}) });
+      } while (this.symbol(","));
+      query.order_by = order;
+    }
+    this.symbol(";");
+    if (this.current.kind !== "end") sqlError(this.current.at, "unexpected clause or additional statement");
+    if (aggregates.length) {
+      query.aggregate = aggregates;
+      const grouped = query.group_by ?? [];
+      if (fields.length !== grouped.length || fields.some(field => !grouped.includes(field))) {
+        sqlError(this.current.at, "GROUP BY must match the selected non-aggregate fields");
+      }
+      if (query.order_by?.some(order => !selected.includes(order.field))) {
+        sqlError(this.current.at, "aggregate ORDER BY must name a selected group field or aggregate alias");
+      }
+    }
+    // The existing algebra owns arity, duplicate names, and grouping invariants.
+    try { return parseDataQuery(query); }
+    catch (error) { return sqlError(this.current.at, String(error)); }
+  }
+}
+
+/** Compiles one finite statement. It neither opens sources nor evaluates code. */
+export function compileSqlQuery(sql: string, source: Pick<DataQuery, "format" | "pointer">): DataQuery {
+  return new SqlParser(sql).parse(parseDataQuery(source));
+}
+
+/** Both syntaxes converge before source I/O, permissions, execution and archival. */
+export function parseQueryInput(input: unknown): DataQuery {
+  if (!isRecord(input) || !Object.hasOwn(input, "sql")) return parseDataQuery(input);
+  if (typeof input["sql"] !== "string") throw new Error("sql must be a string");
+  if (JSON_OPERATORS.some(key => Object.hasOwn(input, key))) {
+    throw new Error("sql cannot be combined with where, select, group_by, aggregate or order_by");
+  }
+  const source = parseDataQuery({ format: input["format"], ...(input["pointer"] === undefined ? {} : { pointer: input["pointer"] }) });
+  return compileSqlQuery(input["sql"], source);
+}

package/src/core/theme.ts

@@ -37,7 +37,7 @@ export const THEME_TOKENS = [
 export type ThemeToken = (typeof THEME_TOKENS)[number];
 
 export type ThemeColors = { readonly [K in ThemeToken]: string } & Readonly<Record<string, string>>;
-const PI_THEME_TOKENS: readonly string[] = ["accent","border","borderAccent","borderMuted","success","error","warning","muted","dim","text","thinkingText","scrollbarTrack","scrollbarThumb","searchMatchText","userMessageText","customMessageText","customMessageLabel","toolTitle","toolOutput","mdHeading","mdLink","mdLinkUrl","mdCode","mdCodeBlock","mdCodeBlockBorder","mdQuote","mdQuoteBorder","mdHr","mdListBullet","toolDiffAdded","toolDiffRemoved","toolDiffContext","syntaxComment","syntaxKeyword","syntaxFunction","syntaxVariable","syntaxString","syntaxNumber","syntaxType","syntaxOperator","syntaxPunctuation","thinkingOff","thinkingMinimal","thinkingLow","thinkingMedium","thinkingHigh","thinkingXhigh","thinkingMax","bashMode","selectedBg","searchMatchBg","userMessageBg","customMessageBg","toolPendingBg","toolSuccessBg","toolErrorBg"];
+const PI_THEME_TOKENS: readonly string[] = ["background","accent","border","borderAccent","borderMuted","success","error","warning","muted","dim","text","thinkingText","scrollbarTrack","scrollbarThumb","searchMatchText","userMessageText","customMessageText","customMessageLabel","toolTitle","toolOutput","mdHeading","mdLink","mdLinkUrl","mdCode","mdCodeBlock","mdCodeBlockBorder","mdQuote","mdQuoteBorder","mdHr","mdListBullet","toolDiffAdded","toolDiffRemoved","toolDiffContext","syntaxComment","syntaxKeyword","syntaxFunction","syntaxVariable","syntaxString","syntaxNumber","syntaxType","syntaxOperator","syntaxPunctuation","thinkingOff","thinkingMinimal","thinkingLow","thinkingMedium","thinkingHigh","thinkingXhigh","thinkingMax","bashMode","selectedBg","searchMatchBg","userMessageBg","customMessageBg","toolPendingBg","toolSuccessBg","toolErrorBg"];
 
 export interface Theme {
   readonly name: string;
@@ -50,64 +50,33 @@ export interface ThemeParse {
 }
 
 /**
- * Palette adapted from pi (earendil-works/pi, MIT), coding-agent theme/dark.json
- * and light.json at 3390bd93630965a12a0a1a5c36ce890ec22f7e1d. Existing custom
- * tokens remain accepted; missing presentation tokens inherit these defaults.
+ * Built-in appearances own no colours of their own: every token is one of the
+ * terminal's 16 slots or its default (empty), and no token paints a
+ * background (docs/tasks/refactor-tui-terminal-colors.md). The interactive
+ * view derives finer greys from the terminal's reported palette; these
+ * tokens are what line mode and an unreporting terminal get.
+ *
+ * `dark` and `light` differ only in which half of the palette stays legible:
+ * bright slots on a dark ground, normal slots on a light one. Muted text is a
+ * grey slot, never SGR faint (faint made muted arguments unreadable).
  */
-const DARK_COLORS: ThemeColors = {
-  "text": "38;2;212;212;212",
-  "thinkingText": "38;2;128;128;128",
-  "toolTitle": "38;2;212;212;212",
-  "toolOutput": "38;2;128;128;128",
-  "error": "38;2;204;102;102",
-  "toolDiffAdded": "38;2;181;189;104",
-  "toolDiffRemoved": "38;2;204;102;102",
-  "status": "38;2;128;128;128",
-  "prompt": "38;2;212;212;212",
-  "selectedBg": "48;2;58;58;74",
-  "muted": "38;2;128;128;128",
-  "warning": "38;2;255;255;0",
-  "mdHeading": "38;2;240;198;116",
-  "mdCode": "38;2;138;190;183",
-  "mdLink": "38;2;129;162;190",
-  "userMessageBg": "48;2;52;53;65",
-  "toolPendingBg": "48;2;40;40;50",
-  "toolSuccessBg": "48;2;40;50;40",
-  "toolErrorBg": "48;2;60;40;40",
-  "thinkingLow": "38;2;95;135;175",
-  "thinkingMedium": "38;2;129;162;190",
-  "thinkingHigh": "38;2;178;148;187",
-  "thinkingXhigh": "38;2;209;131;232",
-  "thinkingMax": "38;2;255;95;255"
-};
+const DARK_COLORS: ThemeColors = terminalTokens({ muted: "37", red: "91", green: "92", yellow: "93", blue: "94", magenta: "95", cyan: "96", rule: "90" });
+const LIGHT_COLORS: ThemeColors = terminalTokens({ muted: "90", red: "31", green: "32", yellow: "33", blue: "34", magenta: "35", cyan: "36", rule: "37" });
 
-/** Distinct from dark so `--theme light` is visible without OSC 11 probing. */
-const LIGHT_COLORS: ThemeColors = {
-  "text": "38;2;31;35;40",
-  "thinkingText": "38;2;108;108;108",
-  "toolTitle": "38;2;31;35;40",
-  "toolOutput": "38;2;108;108;108",
-  "error": "38;2;170;85;85",
-  "toolDiffAdded": "38;2;88;132;88",
-  "toolDiffRemoved": "38;2;170;85;85",
-  "status": "38;2;108;108;108",
-  "prompt": "38;2;31;35;40",
-  "selectedBg": "48;2;208;208;224",
-  "muted": "38;2;108;108;108",
-  "warning": "38;2;154;115;38",
-  "mdHeading": "38;2;154;115;38",
-  "mdCode": "38;2;90;128;128",
-  "mdLink": "38;2;84;125;167",
-  "userMessageBg": "48;2;232;232;232",
-  "toolPendingBg": "48;2;232;232;240",
-  "toolSuccessBg": "48;2;232;240;232",
-  "toolErrorBg": "48;2;240;232;232",
-  "thinkingLow": "38;2;84;125;167",
-  "thinkingMedium": "38;2;90;128;128",
-  "thinkingHigh": "38;2;135;95;135",
-  "thinkingXhigh": "38;2;139;0;139",
-  "thinkingMax": "38;2;175;0;95"
-};
+function terminalTokens(slot: { muted: string; red: string; green: string; yellow: string; blue: string; magenta: string; cyan: string; rule: string }): ThemeColors {
+  return {
+    text: "", prompt: "", background: "",
+    thinkingText: slot.magenta, toolTitle: "", toolOutput: slot.muted,
+    error: slot.red, toolDiffAdded: slot.green, toolDiffRemoved: slot.red,
+    status: slot.muted, muted: slot.muted, dim: slot.muted, warning: slot.yellow, success: slot.green, accent: slot.blue,
+    mdHeading: slot.blue, mdCode: slot.cyan, mdLink: slot.blue,
+    selectedBg: "", userMessageBg: "", toolPendingBg: "", toolSuccessBg: "", toolErrorBg: "",
+    border: slot.rule, borderMuted: slot.rule,
+    thinkingOff: slot.muted, thinkingMinimal: slot.magenta, thinkingLow: slot.magenta, thinkingMedium: slot.magenta,
+    thinkingHigh: slot.magenta, thinkingXhigh: slot.magenta, thinkingMax: slot.magenta,
+    syntaxKeyword: slot.magenta, syntaxString: slot.green, syntaxNumber: slot.yellow, syntaxFunction: slot.blue, syntaxComment: slot.muted,
+  };
+}
 
 export function builtinTheme(name: "dark" | "light"): Theme {
   return name === "light"
@@ -115,6 +84,15 @@ export function builtinTheme(name: "dark" | "light"): Theme {
     : { name: "dark", colors: DARK_COLORS };
 }
 
+/**
+ * A built-in appearance (dark, light, or system/auto, which reuse them) as
+ * opposed to a theme file. Identity, not name: a file may call itself "dark",
+ * and parseTheme always copies colours into a new object.
+ */
+export function isBuiltinTheme(theme: Theme): boolean {
+  return theme.colors === DARK_COLORS || theme.colors === LIGHT_COLORS;
+}
+
 export function parseTheme(json: unknown): ThemeParse {
   const fallback = builtinTheme("dark");
   if (typeof json !== "object" || json === null || Array.isArray(json)) {
@@ -153,7 +131,7 @@ export function parseTheme(json: unknown): ThemeParse {
       diagnostics.push(`invalid colour for ${token}; using built-in`);
       continue;
     }
-    colors[token] = token.endsWith("Bg") ? parsed.replace(/^38;/, "48;") : parsed;
+    colors[token] = (token.endsWith("Bg") || token === "background") ? parsed.replace(/^38;/, "48;") : parsed;
   }
 
   if (!("status" in src) && "dim" in colors) colors.status = colors["dim"]!;

package/src/core/tool-contract.ts

@@ -1,9 +1,17 @@
 /** O.3: one declarative input contract serves model schemas and runtime admission. */
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
 export type ToolDiagnostic = {
-  code: "invalid_input" | "version_mismatch" | "not_found" | "ambiguous_edit" | "permission_denied" | "execution_failed";
+  code: "invalid_input" | "version_mismatch" | "not_found" | "ambiguous_edit" | "permission_denied" | "execution_failed" |
+    "environment_missing" | "transient" | "cancelled" | "timeout" | "unknown_effect" | "command_failed";
   message: string;
   recover?: { tool: string; input: { readonly [key: string]: JsonValue } };
+  /** R3: optional only for legacy records; supplied together by current failure owners. */
+  execution?: "not_started" | "started" | "unknown";
+  effects?: "none" | "possible";
+  retry?: "never" | "after_change" | "after_inspection" | "backoff";
+  next?: string;
+  /** A schema-valid shape with placeholders, never an automatically executable recovery. */
+  example?: { readonly [key: string]: JsonValue };
 };
 
 export function isJsonValue(value: unknown): value is JsonValue {
@@ -15,7 +23,17 @@ export function isJsonValue(value: unknown): value is JsonValue {
 export function isToolDiagnostic(value: unknown): value is ToolDiagnostic {
   if (value === null || typeof value !== "object") return false;
   const item = value as Record<string, unknown>;
-  if (!["invalid_input", "version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "execution_failed"].includes(String(item["code"])) || typeof item["message"] !== "string") return false;
+  if (!["invalid_input", "version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "execution_failed",
+    "environment_missing", "transient", "cancelled", "timeout", "unknown_effect", "command_failed"].includes(String(item["code"])) || typeof item["message"] !== "string") return false;
+  if (["execution", "effects", "retry", "next"].some(key => item[key] !== undefined)) {
+    if (!["not_started", "started", "unknown"].includes(String(item["execution"])) ||
+      !["none", "possible"].includes(String(item["effects"])) ||
+      !["never", "after_change", "after_inspection", "backoff"].includes(String(item["retry"])) || typeof item["next"] !== "string") return false;
+    if (item["retry"] === "backoff" && (item["code"] !== "transient" || item["effects"] !== "none")) return false;
+    if (item["code"] === "permission_denied" && (item["retry"] !== "never" || item["recover"] !== undefined)) return false;
+    if (item["code"] === "unknown_effect" && item["retry"] !== "after_inspection") return false;
+  }
+  if (item["example"] !== undefined && (item["example"] === null || typeof item["example"] !== "object" || Array.isArray(item["example"]) || !isJsonValue(item["example"]))) return false;
   const recover = item["recover"];
   if (recover === undefined) return true;
   if (recover === null || typeof recover !== "object") return false;
@@ -24,6 +42,37 @@ export function isToolDiagnostic(value: unknown): value is ToolDiagnostic {
     typeof recovery["input"] === "object" && !Array.isArray(recovery["input"]) && isJsonValue(recovery["input"]);
 }
 
+/** Required fields only; examples express a valid shape, not permission or a safe command. */
+export function minimalInput(schema: unknown): JsonValue | undefined {
+  if (schema === null || typeof schema !== "object") return undefined;
+  const s = schema as Record<string, unknown>;
+  if (Array.isArray(s["enum"]) && s["enum"].length && isJsonValue(s["enum"][0])) return s["enum"][0];
+  switch (s["type"]) {
+    case "string": return "<value>".padEnd(typeof s["minLength"] === "number" ? Math.min(4096, s["minLength"]) : 0, "x");
+    case "number": case "integer": return typeof s["minimum"] === "number" ? s["minimum"] : 0;
+    case "boolean": return false;
+    case "array": return [];
+    case "object": {
+      const value: { [key: string]: JsonValue } = {};
+      const properties = s["properties"];
+      for (const key of Array.isArray(s["required"]) ? s["required"] : []) {
+        if (typeof key !== "string" || properties === null || typeof properties !== "object") return undefined;
+        const item = minimalInput((properties as Record<string, unknown>)[key]);
+        if (item === undefined) return undefined;
+        value[key] = item;
+      }
+      return value;
+    }
+    default: return null;
+  }
+}
+
+/** Diagnostics are projected as tool data; they never become trusted system instructions. */
+export function diagnosticContent(content: string, diagnostic?: ToolDiagnostic): string {
+  if (diagnostic?.execution === undefined) return content;
+  return content + "\nTool diagnostic: " + JSON.stringify(diagnostic);
+}
+
 import { editDistance } from "./text-normalize.ts";
 
 /**

package/src/core/tool-discovery.ts

@@ -0,0 +1,87 @@
+/** R11 / D6 / D8: local discovery proposes declarations; only a paired checkpoint installs them. */
+import type { LogEvent, ToolInvocationEvent } from "./events.ts";
+
+/** Assumed response bounds, not measured model optima; prevent a directory dump from replacing a lookup. */
+export const MAX_DISCOVERY_RESULTS = 8;
+export const MAX_DISCOVERY_QUERY = 256;
+const MAX_PARAMETER_HINTS = 8;
+const MAX_PURPOSE_CHARS = 320;
+
+export interface DiscoverableTool {
+  readonly name: string;
+  readonly description: string;
+  readonly input_schema: { readonly properties: Readonly<Record<string, unknown>>; readonly required: readonly string[] };
+}
+export interface DeclarationRequest { readonly name: string; readonly fingerprint: string }
+export interface DiscoveryMatch {
+  name: string; purpose: string; inputs: { name: string; type: string; required: boolean }[]; omitted_inputs: number;
+}
+export function declaredToolNames(tools: readonly unknown[]): string[] {
+  return tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" ? [tool.name] : []);
+}
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+function record(raw: unknown): Record<string, unknown> | undefined {
+  return raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : undefined;
+}
+function parameterType(raw: unknown): string {
+  if (raw === null || typeof raw !== "object") return "schema";
+  const type = (raw as Record<string, unknown>)["type"];
+  if (typeof type === "string") return type.slice(0, 64);
+  if (Array.isArray(type) && type.every(item => typeof item === "string")) return type.join("|").slice(0, 64);
+  return "schema";
+}
+
+/** Pure, deterministic matching over the caller's already-selected directory; never perform discovery I/O. */
+export function discoverTools(catalog: readonly DiscoverableTool[], query: string, limit = 5): DiscoveryMatch[] {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_DISCOVERY_RESULTS) throw new Error("invalid discovery limit");
+  const normalized = query.trim().toLowerCase();
+  if (!normalized || query.length > MAX_DISCOVERY_QUERY) throw new Error("query must contain 1 to 256 characters");
+  const terms = normalized.split(/[^\p{L}\p{N}_-]+/u).filter(Boolean);
+  if (terms.length === 0) return [];
+  return catalog.map(tool => {
+    const name = tool.name.toLowerCase(), text = `${name} ${tool.description.toLowerCase()}`;
+    const score = name === normalized ? 100 : terms.every(term => text.includes(term))
+      ? 1 + terms.filter(term => name.includes(term)).length : 0;
+    return { tool, score };
+  }).filter(item => item.score > 0).sort((a, b) => b.score - a.score || compare(a.tool.name, b.tool.name))
+    .slice(0, limit).map(({ tool }) => {
+      const required = new Set(tool.input_schema.required);
+      const parameters = Object.entries(tool.input_schema.properties).sort(([a], [b]) =>
+        Number(required.has(b)) - Number(required.has(a)) || compare(a, b));
+      return { name: tool.name, purpose: tool.description.slice(0, MAX_PURPOSE_CHARS),
+        inputs: parameters.slice(0, MAX_PARAMETER_HINTS).map(([name, raw]) => ({ name: name.slice(0, 128), type: parameterType(raw), required: required.has(name) })),
+        omitted_inputs: Math.max(0, parameters.length - MAX_PARAMETER_HINTS) };
+    });
+}
+
+/** A model assertion or another extension's data cannot authorize a declaration (D11). */
+export function recordedDeclarations(events: readonly LogEvent[]): DeclarationRequest[] {
+  const invocations = new Map<string, ToolInvocationEvent>();
+  const requested = new Map<string, { request: DeclarationRequest; user: string | undefined }>();
+  let user: string | undefined;
+  for (const event of events) {
+    if (event.t === "user") { user = event.id; continue; }
+    if (event.t === "interrupt") {
+      for (const [name, value] of requested) if (value.user === event.user_id) requested.delete(name);
+      continue;
+    }
+    if (event.t === "tool_invocation") { invocations.set(event.id, event); continue; }
+    if (event.t !== "tool_result" || !event.ok || !event.invocation_ref) continue;
+    if (event.outcome !== undefined && event.outcome.status !== "completed") continue;
+    const invocation = invocations.get(event.invocation_ref.event);
+    if (invocation?.name !== "tool_search" || invocation.call_id !== event.call_id) continue;
+    const data = record(event.data);
+    if (!data || data["kind"] !== "tool_discovery" || data["version"] !== 1) continue;
+    const entries = data["requested"];
+    if (!Array.isArray(entries) || entries.length > MAX_DISCOVERY_RESULTS) continue;
+    for (const entry of entries) {
+      const item = record(entry);
+      if (!item) continue;
+      const name = item["name"], fingerprint = item["fingerprint"];
+      if (typeof name === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(name) && typeof fingerprint === "string" && /^[a-f0-9]{64}$/.test(fingerprint)) {
+        requested.set(name, { request: { name, fingerprint }, user });
+      }
+    }
+  }
+  return [...requested.values()].map(value => value.request);
+}

package/src/core/tool-failure.ts

@@ -0,0 +1,60 @@
+/** R3 / D11: failure policy follows observed execution facts, never output keywords. */
+import type { ToolDiagnostic } from "./tool-contract.ts";
+
+export type FailureFacts = { execution: "not_started" | "started" | "unknown"; effects: "none" | "possible" };
+export const NOT_STARTED: FailureFacts = { execution: "not_started", effects: "none" };
+export const READ_ATTEMPTED: FailureFacts = { execution: "started", effects: "none" };
+export const UNKNOWN_EFFECT: FailureFacts = { execution: "unknown", effects: "possible" };
+
+const guidance: Record<ToolDiagnostic["code"], string> = {
+  invalid_input: "Correct the named argument using the tool schema; example values are placeholders.",
+  version_mismatch: "Read the current resource and derive a new edit from that version.",
+  not_found: "Verify the resource path or identifier before changing the request.",
+  ambiguous_edit: "Read the indicated range and choose a unique match before editing.",
+  permission_denied: "This operation was denied. Do not bypass it through another tool or wrapper; a user policy change is required.",
+  execution_failed: "Inspect the failure and change its cause before retrying.",
+  environment_missing: "Verify the working directory and required executable in this environment before retrying. If available and permitted, use environment with the exact program; use its python probe for actual Python API support.",
+  transient: "Retry with bounded backoff only if no side effect is possible.",
+  cancelled: "Respect cancellation; inspect any partial effects before a user-authorized continuation.",
+  timeout: "Inspect partial output and effects before deciding whether a new invocation is needed.",
+  unknown_effect: "Execution or effects are uncertain. Inspect existing state and output before any replay.",
+  command_failed: "Use the actual exit and output to diagnose the command; a nonzero exit alone does not identify its cause.",
+};
+
+export function failureDiagnostic(code: ToolDiagnostic["code"], message: string, facts: FailureFacts,
+  extra: Pick<ToolDiagnostic, "recover" | "example"> = {}): ToolDiagnostic {
+  const retry = code === "permission_denied" || code === "cancelled" ? "never"
+    : code === "unknown_effect" || facts.effects === "possible" ? "after_inspection"
+    : code === "transient" ? "backoff" : "after_change";
+  return { code, message, ...facts, retry, next: guidance[code], ...(code === "permission_denied" ? {} : extra) };
+}
+
+/** R10: only new advice is scoped; execution facts and historical records are never rewritten. */
+export function scopeFailureGuidance(diagnostic: ToolDiagnostic, tools: readonly string[], recoverAllowed = true): ToolDiagnostic {
+  const { recover, ...facts } = diagnostic;
+  const next = diagnostic.execution !== undefined && diagnostic.code === "environment_missing" && !tools.includes("environment")
+    ? { next: "Verify the working directory and required executable in the current executor using permitted observations. If the needed capability is unavailable, report that evidence gap before retrying." } : {};
+  return { ...facts, ...next, ...(recover && recoverAllowed && tools.includes(recover.tool) && diagnostic.code !== "permission_denied" ? { recover } : {}) };
+}
+
+/** Runtime and store throw only facts they own; the outer boundary must retain these facts. */
+export class ToolFault extends Error {
+  readonly diagnostic: ToolDiagnostic;
+  constructor(code: ToolDiagnostic["code"], message: string, facts: FailureFacts, extra: Pick<ToolDiagnostic, "recover"> = {}) {
+    super(message); this.name = "ToolFault";
+    this.diagnostic = failureDiagnostic(code, message, facts, extra);
+  }
+}
+
+/** OS codes are facts; words like "denied" in arbitrary output are not classification evidence. */
+export function failureFromError(error: unknown, facts: FailureFacts): ToolDiagnostic {
+  if (error instanceof ToolFault) return error.diagnostic;
+  const message = error instanceof Error ? error.message : String(error);
+  const os = error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+  const code = os === "ENOENT" || os === "ENOTDIR" ? "not_found"
+    : os === "EACCES" || os === "EPERM" ? "permission_denied"
+    : os === "EISDIR" ? "invalid_input"
+    : ["EAGAIN", "ETIMEDOUT", "ECONNRESET", "EMFILE"].includes(String(os)) ? "transient"
+    : facts.effects === "possible" ? "unknown_effect" : "execution_failed";
+  return failureDiagnostic(code, message, facts);
+}

package/src/core/tool-input.ts

@@ -12,6 +12,12 @@
  */
 type Input = Record<string, unknown>;
 
+/** O.3: incomplete wire JSON remains the original input so admission can refuse it without effects. */
+export function completedToolInput(raw: string): unknown {
+  try { return JSON.parse(raw) as unknown; }
+  catch { return raw; }
+}
+
 function parsedJson(value: unknown): unknown {
   if (typeof value !== "string") return value;
   const trimmed = value.trim();