@visual-z/xeno 0.2.1 → 0.3.0

package/src/core/search-observation.ts

@@ -0,0 +1,97 @@
+/** R2: scan completeness and preview completeness answer different questions. */
+import { headTailSelection, isObservationArtifact, isBytePreview, type BytePreview } from "./observation-view.ts";
+import type { ArtifactRef } from "./events.ts";
+import { artifactRecovery } from "./prompt-policy.ts";
+
+export interface SearchRow { prefix: string; text: string; }
+export interface SearchScan {
+  status: "complete" | "partial" | "unknown";
+  reasons: { code: string; path?: string }[];
+  examined_files: number | null;
+  source_versions: "recorded" | "unknown";
+}
+export interface SearchObservation {
+  engine: "walk" | "ripgrep" | "fd" | "directory";
+  rows: SearchRow[];
+  scan: SearchScan;
+  sources: { path: string; sha256: string }[];
+  raw?: Uint8Array;
+  rawErrors?: Uint8Array;
+  limit: number;
+  empty: string;
+}
+
+export interface SearchReceipt {
+  kind: "search";
+  version: 1;
+  source: { host: string; workspace: string; resource: string };
+  engine: SearchObservation["engine"];
+  scan: { status: SearchScan["status"]; reasons: string[]; examined_files: number | null; source_versions: SearchScan["source_versions"] };
+  matches: number;
+  artifact: ArtifactRef;
+  manifest: ArtifactRef;
+  raw?: ArtifactRef;
+  raw_errors?: ArtifactRef;
+  preview: BytePreview;
+}
+
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isSearchReceipt(value: unknown): value is SearchReceipt {
+  if (!object(value) || value["kind"] !== "search" || value["version"] !== 1 || !isObservationArtifact(value["artifact"]) || !isObservationArtifact(value["manifest"]) || !natural(value["matches"])) return false;
+  if (!["walk", "ripgrep", "fd", "directory"].includes(String(value["engine"])) || value["raw"] !== undefined && !isObservationArtifact(value["raw"])) return false;
+  if (value["raw_errors"] !== undefined && !isObservationArtifact(value["raw_errors"])) return false;
+  const source = value["source"], scan = value["scan"];
+  if (!object(source) || !["host", "workspace", "resource"].every(key => typeof source[key] === "string" && source[key] !== "")) return false;
+  if (!object(scan) || !["complete", "partial", "unknown"].includes(String(scan["status"])) || !["recorded", "unknown"].includes(String(scan["source_versions"])) ||
+    !Array.isArray(scan["reasons"]) || !scan["reasons"].every(reason => typeof reason === "string") || scan["examined_files"] !== null && !natural(scan["examined_files"])) return false;
+  if (scan["status"] === "complete" && scan["reasons"].length !== 0 || scan["status"] !== "complete" && scan["reasons"].length === 0) return false;
+  return isBytePreview(value["preview"], value["artifact"].bytes);
+}
+
+const encoder = new TextEncoder();
+const bytes = (text: string) => encoder.encode(text).length;
+export const searchObservationText = (rows: readonly SearchRow[]): string => rows.map(row => row.prefix + row.text).join("\n");
+
+/** Map count, per-line, and UTF-8 byte cuts back to the same immutable full observation. */
+export function previewSearchObservation(observation: SearchObservation, artifact: string, maxBytes: number, maxLineChars = 500, notice = "", tools?: readonly string[]) {
+  let text = "", source = 0, view = 0;
+  const spans: { view: number; source: number; bytes: number }[] = [];
+  const mapped = (value: string) => { const size = bytes(value); if (size) spans.push({ view, source, bytes: size }); text += value; view += size; };
+  const synthetic = (value: string) => { text += value; view += bytes(value); };
+  if (notice) synthetic(notice + "\n");
+  const shown = Math.max(0, Math.min(observation.rows.length, observation.limit));
+  for (let index = 0; index < observation.rows.length; index++) {
+    const row = observation.rows[index]!;
+    if (index < shown) {
+      let end = Math.min(maxLineChars, row.text.length);
+      if (end > 0 && end < row.text.length && /[\uD800-\uDBFF]/.test(row.text[end - 1]!)) end--;
+      const kept = row.prefix + row.text.slice(0, end);
+      mapped(kept);
+      if (end < row.text.length) synthetic(`… [line truncated; ${artifactRecovery(artifact, source + bytes(kept), tools)}]`);
+    }
+    source += bytes(row.prefix + row.text);
+    if (index < observation.rows.length - 1) { if (index < shown) mapped("\n"); source++; }
+  }
+  if (!observation.rows.length) synthetic(observation.scan.status === "complete" ? observation.empty : "[No matches observed in the scanned portion]");
+  if (shown < observation.rows.length) synthetic(`[${observation.rows.length - shown} more matches omitted; ${artifactRecovery(artifact, 0, tools)}]`);
+  if (observation.scan.status !== "complete") synthetic(`\n[scan ${observation.scan.status}: ${[...new Set(observation.scan.reasons.map(reason => reason.code === "match_timeout" ? "search cut off: match_timeout" : reason.code))].join(", ")}]`);
+  const previewBytes = encoder.encode(text);
+  const selected = headTailSelection(previewBytes, previewBytes, previewBytes.length, maxBytes,
+    omitted => `\n[truncated ${omitted} preview bytes; ${artifactRecovery(artifact, 0, tools)}]\n`);
+  const visible: [number, number][] = [];
+  for (const [lo, hi] of selected.visible) for (const span of spans) {
+    const begin = Math.max(lo, span.view), end = Math.min(hi, span.view + span.bytes);
+    if (end <= begin) continue;
+    const a = span.source + begin - span.view, b = span.source + end - span.view;
+    const last = visible.at(-1);
+    if (last?.[1] === a) last[1] = b;
+    else visible.push([a, b]);
+  }
+  let next = 0;
+  for (const [lo, hi] of visible) { if (lo !== next) break; next = hi; }
+  const full = encoder.encode(searchObservationText(observation.rows));
+  const semantic = visible.map(([lo, hi]) => new TextDecoder().decode(full.subarray(lo, hi))).join("");
+  return { text: selected.text, semantic, preview: { unit: "utf8_bytes" as const, complete: next === source,
+    visible, next_offset: next === source ? null : next } };
+}

package/src/core/session-tree.ts

@@ -0,0 +1,147 @@
+/**
+ * The session tree as data. Pure: restore points + parent pointers in,
+ * a forest out; plus a flattening that the UI and the line-mode printer
+ * share. Moved from src/tui/tree.ts when the view was rewritten (D20) so the
+ * shape of history does not depend on any renderer.
+ */
+
+/** Same mark /back uses for a branch the session rewound away from. */
+export const LEFT_BRANCH_MARK = "↩";
+export const EMPTY_TREE_MESSAGE = "nothing to go back to -- no exchange has completed yet";
+
+export type TreeKind = "user" | "other";
+export type TreeFilter = "user" | "default" | "no-tools" | "user-only" | "labeled-only" | "all";
+
+export interface TreeNode {
+  readonly id: string;
+  readonly prompt: string;
+  readonly onPath: boolean;
+  readonly current: boolean;
+  readonly kind: TreeKind;
+  readonly children: readonly TreeNode[];
+  readonly category?: "tool" | "message" | "metadata";
+  readonly label?: string;
+  readonly labelAt?: string;
+  readonly at?: string;
+  readonly content?: string;
+  /** Exact event position; user messages navigate before themselves. */
+  readonly target?: string;
+}
+
+/**
+ * A restore point as the log already knows it. parent pointers are a
+ * separate map so this file never imports store.
+ */
+export interface TreePoint {
+  readonly node: number;
+  readonly atEvent: string;
+  readonly prompt: string;
+  readonly onPath: boolean;
+  readonly kind?: TreeKind;
+  readonly category?: "tool" | "message" | "metadata";
+  readonly label?: string;
+  readonly labelAt?: string;
+  readonly at?: string;
+  readonly content?: string;
+  readonly target?: string;
+}
+
+export type NodeParent = { readonly node: number; readonly at_event?: string } | null;
+
+/**
+ * Restore points plus parent pointers → the tree the view paints.
+ *
+ * Same-node exchanges stay a chain. A child node whose parent.at_event
+ * matches a point hangs off that point as a sibling of the continuation,
+ * which is how a rewind becomes a visible fork instead of a missing row.
+ */
+export function treeFromPoints(
+  points: readonly TreePoint[],
+  parents: ReadonlyMap<number, NodeParent>,
+  currentNode: number,
+): TreeNode[] {
+  const byNode = new Map<number, TreePoint[]>();
+  for (const p of points) {
+    const list = byNode.get(p.node) ?? [];
+    list.push(p);
+    byNode.set(p.node, list);
+  }
+
+  const lastHere = [...points].reverse().find((p) => p.onPath && p.node === currentNode);
+  const lastOnPath = lastHere ?? [...points].reverse().find((p) => p.onPath);
+
+  function toNode(p: TreePoint, children: readonly TreeNode[]): TreeNode {
+    return {
+      ...p,
+      id: `${p.node}:${p.atEvent}`,
+      prompt: p.prompt,
+      onPath: p.onPath,
+      current: lastOnPath !== undefined && lastOnPath.node === p.node && lastOnPath.atEvent === p.atEvent,
+      kind: p.kind ?? "user",
+      children,
+    };
+  }
+
+  // Wire event chains and branch edges separately. Recursing once per event
+  // overflows the JS stack on otherwise valid long sessions.
+  type MutableNode = TreeNode & { children: TreeNode[] };
+  const chains = new Map<number, MutableNode[]>();
+  const events = new Map<string, MutableNode>();
+  for (const [id, pts] of byNode) {
+    const nodes = pts.map(p => toNode(p, []) as MutableNode);
+    for (let i = 0; i < nodes.length; i++) {
+      events.set(nodes[i]!.id, nodes[i]!);
+      if (nodes[i + 1]) nodes[i]!.children.push(nodes[i + 1]!);
+    }
+    chains.set(id, nodes);
+  }
+  const forest: TreeNode[] = [];
+  for (const [id, nodes] of [...chains].sort(([a], [b]) => a - b)) {
+    const first = nodes[0];
+    if (!first) continue;
+    let parent = parents.get(id);
+    const visited = new Set<number>([id]);
+    while (parent && !chains.get(parent.node)?.length && !visited.has(parent.node)) {
+      visited.add(parent.node); parent = parents.get(parent.node);
+    }
+    const anchor = parent && !visited.has(parent.node) ? events.get(`${parent.node}:${parent.at_event}`) ?? chains.get(parent.node)?.at(-1) : undefined;
+    if (anchor) anchor.children.push(first); else forest.push(first);
+  }
+  return forest;
+}
+
+
+export interface TreeRow { readonly node: TreeNode; readonly depth: number; readonly branch: string }
+
+/** Depth-first rows with connector prefixes; iterative so a 10k-event session cannot overflow the stack. */
+export function flattenTree(nodes: readonly TreeNode[], filter: TreeFilter = "all"): TreeRow[] {
+  const rows: TreeRow[] = [];
+  const stack = visibleTree(nodes, filter).map((node, i, all) => ({ node, prefix: "", root: true, last: i === all.length - 1 })).reverse();
+  while (stack.length) {
+    const { node, prefix, root, last } = stack.pop()!;
+    rows.push({ node, depth: prefix.length / 3, branch: root ? "" : prefix + (last ? "└─ " : "├─ ") });
+    const next = root ? "" : prefix + (last ? "   " : "│  ");
+    const children = node.children;
+    for (let i = children.length - 1; i >= 0; i--) stack.push({ node: children[i]!, prefix: next.length > 30 ? next.slice(-30) : next, root: false, last: i === children.length - 1 });
+  }
+  return rows;
+}
+
+/**
+ * Filtering hides a node but keeps its descendants: they re-attach to the
+ * nearest visible ancestor, so a "user only" view is still a tree.
+ */
+export function visibleTree(nodes: readonly TreeNode[], filter: TreeFilter): TreeNode[] {
+  if (filter === "all") return [...nodes];
+  const out: TreeNode[] = [];
+  const stack = [...nodes].reverse().map(node => ({ node, into: out }));
+  while (stack.length) {
+    const { node: n, into } = stack.pop()!;
+    const include = filter === "user" || filter === "user-only" ? n.kind === "user" :
+      filter === "labeled-only" ? Boolean(n.label) : filter === "no-tools" ? n.category !== "tool" && n.category !== "metadata" : n.category !== "metadata";
+    const children: TreeNode[] = [];
+    if (include) into.push({ ...n, children });
+    for (let i = n.children.length - 1; i >= 0; i--) stack.push({ node: n.children[i]!, into: include ? children : into });
+  }
+  return out;
+}

package/src/core/settings.ts

@@ -4,8 +4,12 @@ import { packageDeclaration, type PackageDeclaration } from "./packages.ts";
 /** Validated configuration. D19: display policy never mutates the log. */
 export interface Settings {
   readonly theme?: string;
+  /** Presentation only: no animation is allowed to advance a log or block input. */
+  readonly animations?: boolean;
   readonly thinking?: string;
   readonly statusBar?: boolean;
+  /** Look for a newer published xeno once a day and say so (docs/tasks/feat-update-check.md). Default on. */
+  readonly updateCheck?: boolean;
   readonly hideThinkingBlock?: boolean;
   readonly showCacheMissNotices?: boolean;
   readonly defaultProvider?: string;
@@ -13,9 +17,11 @@ export interface Settings {
   readonly defaultThinking?: string;
   readonly modelThinkingLevels?: Readonly<Record<string, ThinkingLevel>>;
   readonly scopedModels?: readonly string[];
+  /** provider/model keys, most recent first; the /model picker's first section. */
+  readonly recentModels?: readonly string[];
   readonly steeringMode?: "all" | "one-at-a-time";
   readonly followUpMode?: "all" | "one-at-a-time";
-  readonly tuiMode?: "regular" | "fullscreen";
+  readonly tuiMode?: "auto" | "regular" | "fullscreen";
   readonly fullscreenExitOutput?: "transcript" | "resume-hint";
   readonly fullscreenScrollbar?: "auto" | "always" | "hidden";
   readonly fullscreenCopyOnSelect?: boolean;
@@ -35,12 +41,14 @@ export interface Settings {
   readonly packages?: readonly PackageDeclaration[];
   readonly enableSkillCommands?: boolean;
   readonly defaultProjectTrust?: "ask" | "always" | "never";
-  readonly terminal?: { readonly clearOnShrink?: boolean; readonly showTerminalProgress?: boolean; readonly showImages?: boolean; readonly imageWidthCells?: number };
+  readonly terminal?: { readonly clearOnShrink?: boolean; readonly showTerminalProgress?: boolean; readonly showImages?: boolean; readonly imageWidthCells?: number;
+    /** How pictures are drawn; `auto` names them instead when the terminal can only draw block characters. */
+    readonly imageProtocol?: "auto" | "kitty" | "sixel" | "blocks" };
   readonly images?: { readonly autoResize?: boolean; readonly blockImages?: boolean };
   readonly markdown?: { readonly mermaid?: "off" | "final" | "streaming" };
 }
-export const SETTINGS_KEYS = ["theme", "thinking", "statusBar", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
-  "modelThinkingLevels", "scopedModels", "steeringMode", "followUpMode", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar",
+export const SETTINGS_KEYS = ["theme", "animations", "thinking", "statusBar", "updateCheck", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
+  "modelThinkingLevels", "scopedModels", "recentModels", "steeringMode", "followUpMode", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar",
   "fullscreenCopyOnSelect", "fullscreenWheelScrollLines", "editorPaddingX", "outputPad", "autocompleteMaxVisible",
   "showHardwareCursor", "quietStartup", "doubleEscapeAction", "treeFilterMode", "externalEditor", "terminal", "images", "markdown",
   "skills", "prompts", "themes", "extensions", "packages", "enableSkillCommands", "defaultProjectTrust"] as const;
@@ -52,11 +60,11 @@ type Rule = { readonly kind: "boolean" | "string" | "strings" } | { readonly kin
 const levels: Rule = { kind: "enum", values: THINKING_LEVELS };
 const delivery: Rule = { kind: "enum", values: ["all", "one-at-a-time"] };
 const rules: Readonly<Record<string, Rule>> = {
-  theme: { kind: "string" }, thinking: levels, statusBar: { kind: "boolean" },
+  theme: { kind: "string" }, animations: { kind: "boolean" }, thinking: levels, statusBar: { kind: "boolean" }, updateCheck: { kind: "boolean" },
   hideThinkingBlock: { kind: "boolean" }, showCacheMissNotices: { kind: "boolean" },
   defaultProvider: { kind: "string" }, defaultModel: { kind: "string" }, defaultThinking: levels,
-  scopedModels: { kind: "strings" }, steeringMode: delivery, followUpMode: delivery,
-  tuiMode: { kind: "enum", values: ["regular", "fullscreen"] },
+  scopedModels: { kind: "strings" }, recentModels: { kind: "strings" }, steeringMode: delivery, followUpMode: delivery,
+  tuiMode: { kind: "enum", values: ["auto", "regular", "fullscreen"] },
   fullscreenExitOutput: { kind: "enum", values: ["transcript", "resume-hint"] },
   fullscreenScrollbar: { kind: "enum", values: ["auto", "always", "hidden"] },
   fullscreenCopyOnSelect: { kind: "boolean" },
@@ -70,6 +78,7 @@ const rules: Readonly<Record<string, Rule>> = {
   externalEditor: { kind: "string" }, "terminal.clearOnShrink": { kind: "boolean" },
   "terminal.showTerminalProgress": { kind: "boolean" },
   "terminal.showImages": { kind: "boolean" }, "terminal.imageWidthCells": { kind: "integer", min: 1, max: 240 },
+  "terminal.imageProtocol": { kind: "enum", values: ["auto", "kitty", "sixel", "blocks"] },
   "images.autoResize": { kind: "boolean" }, "images.blockImages": { kind: "boolean" },
   "markdown.mermaid": { kind: "enum", values: ["off", "final", "streaming"] },
   skills: { kind: "strings" }, prompts: { kind: "strings" }, themes: { kind: "strings" }, extensions: { kind: "strings" },
@@ -77,19 +86,22 @@ const rules: Readonly<Record<string, Rule>> = {
 };
 /** One catalog supplies menu values and command validation. */
 export const DISPLAY_SETTINGS = [
+  { id: "animations", label: "Animations", fallback: "on" },
   { id: "hideThinkingBlock", label: "Hide thinking blocks", fallback: "on" },
   { id: "showCacheMissNotices", label: "Cache miss notices", fallback: "off" },
   { id: "enableSkillCommands", label: "Skill commands", fallback: "on" },
   { id: "defaultProjectTrust", label: "Default project trust", fallback: "ask" },
+  { id: "updateCheck", label: "Check for updates", fallback: "on" },
   { id: "terminal.showImages", label: "Show images", fallback: "on" },
+  { id: "terminal.imageProtocol", label: "Image protocol", fallback: "auto" },
   { id: "terminal.imageWidthCells", label: "Image width", fallback: "60" },
   { id: "images.autoResize", label: "Resize images", fallback: "on" },
   { id: "images.blockImages", label: "Block image transmission", fallback: "off" },
   { id: "markdown.mermaid", label: "Mermaid diagrams", fallback: "streaming" },
-  { id: "tuiMode", label: "TUI mode", fallback: "regular" },
+  { id: "tuiMode", label: "TUI mode", fallback: "fullscreen" },
   { id: "fullscreenExitOutput", label: "Fullscreen exit output", fallback: "transcript" },
-  { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "auto" },
-  { id: "fullscreenCopyOnSelect", label: "Fullscreen copy on select", fallback: "on" },
+  { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "hidden" },
+  { id: "fullscreenCopyOnSelect", label: "Copy on select", fallback: "on" },
   { id: "fullscreenWheelScrollLines", label: "Fullscreen wheel scroll lines", fallback: "auto" },
   { id: "editorPaddingX", label: "Editor padding", fallback: "0" },
   { id: "outputPad", label: "Output padding", fallback: "1" },
@@ -166,6 +178,10 @@ function validate(key: string, raw: unknown, out: Record<string, unknown>, diagn
   else diagnostics.push("settings." + key + " must be " + (rule.kind === "enum" ? rule.values.join("|") : rule.kind === "integer" ? rule.min + ".." + rule.max + (rule.auto ? " or auto" : "") : rule.kind));
 }
 export function settingValues(key: string): string[] {
+  // `auto` is the unset default and stays valid in settings.json; cycling it in
+  // the menu would be a press that visibly does nothing on a terminal where
+  // auto already means fullscreen, so the menu toggles the two real screens.
+  if (key === "tuiMode") return ["regular", "fullscreen"];
   const rule = rules[key];
   if (rule?.kind === "enum") return [...rule.values];
   if (rule?.kind === "boolean") return ["on", "off"];

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);
+}