@visual-z/xeno 0.5.0 → 0.7.0

package/src/runtime/tools.ts

@@ -54,7 +54,6 @@ import { parseQueryInput, MAX_SQL_CHARS, SQL_QUERY_HELP } from "../core/sql-quer
 import { readQuerySources } from "../store/query-source.ts";
 import {
   askWithoutTtyMessage,
-  decide,
   deniedMessage,
   permissionRequest,
   type PermissionRequest,
@@ -76,6 +75,10 @@ import { observeEnvironment } from "./environment-tools.ts";
 import { beginCommandArtifacts, prepareArtifactArguments, commandArtifactSummary } from "./command-artifacts.ts";
 import { MAX_COMMAND_ARTIFACTS } from "../core/command-artifacts.ts";
 import { checkSourceCancellation } from "../store/source-cancellation.ts";
+import { canonicalPermissionRequest } from "../store/permission-paths.ts";
+import { permissionResourceAction } from "./permission-resources.ts";
+import { parsePatch, patchPaths } from "../core/patch.ts";
+import { decideWithSessionRules } from "../core/permissions.ts";
 
 export interface ToolResult {
   /** Broker-owned identity, returned to a composer only after the original receipt commits. */
@@ -98,6 +101,15 @@ export interface ToolResult {
 }
 
 export interface ToolContext {
+  historyEvents?: () => Promise<import("../core/events.ts").LogEvent[]>;
+  checkpointBlobs?: string;
+  frozenSystem?: () => string;
+  instructionCheck?: (ctx: ToolContext, name: string, input: unknown) => Promise<ToolResult | null>;
+  workflowMode?: "build" | "plan";
+  /** CLI owns its approval defaults; SDK callers retain their supplied host policy across reload. */
+  appOwnsPermissions?: true;
+  hostPermissionRules?: PermissionRule[];
+  questionSlot?: import("./question-tool.ts").QuestionSlot;
   /** R10: model-visible names constrain new advice without granting tool admission. */
   advice?: readonly string[];
   /** Runtime adapter identity, never supplied by a model tool argument. */
@@ -115,6 +127,9 @@ export interface ToolContext {
   historyCache?: HistoryCache;
   /** O.14: opaque process ownership is supplied by Session, never by model input. */
   execOwner?: string;
+  /** Session-owned empty stdin waits; low-level/native callers retain bounded polling. */
+  processWait?: { wake(): AbortSignal };
+  onProcessWait?: (session: number, active: boolean) => void;
   /** Session-owned registrations never mutate the built-in table (D13). */
   extensions?: ReadonlyMap<string, ToolDefinition>;
   /** R11: current locally selected optional schemas, never restored as authority from historical text. */
@@ -285,6 +300,8 @@ export interface ToolDefinition extends ToolSchema {
   /** Accepted by admission but not advertised to the model: harness and test switches. */
   hiddenInputs?: readonly string[];
   prepareArguments?: (input: unknown) => unknown;
+  /** Protocol adapters with complete schemas own validation, rather than the builtin vocabulary. */
+  validateInput?: (input: unknown) => void;
   run?: (ctx: ToolContext, input: Record<string, unknown>) => Promise<ToolResult>;
 }
 
@@ -615,7 +632,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     access: "shell", execution: "exclusive", branch: "write", run: toolWriteStdin,
     description:
       "Send characters to an owned running process handle and return the output since the last call. " +
-      "Empty chars polls. Include \\n to submit a line; \\u0003 is Ctrl-C, \\u0004 is Ctrl-D (end of input). " +
+      "In an agent session, empty chars waits for new output, exit, hard timeout, cancellation or user steering without periodic model polling. Include \\n to submit a line; \\u0003 is Ctrl-C, \\u0004 is Ctrl-D (end of input). " +
       "After exit, empty chars retrieves the last receipt without rerunning or producing fresh verification. Source and byte cursor are in data; full_output recovers all captured output. " +
       "Lost handles cannot accept input; a last running observation is not an exit. Ctrl-C may interrupt a PTY foreground job while its REPL stays alive.",
     input_schema: {
@@ -623,7 +640,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       properties: {
         session_id: { type: "integer", minimum: 1 },
         chars: { type: "string", description: "Characters to write; empty to poll" },
-        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Milliseconds to wait for output; default 10000" },
+        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Bounded wait when sending input or using low-level polling; agent empty waits are owned until an observation changes" },
       },
       required: ["session_id"],
     },
@@ -702,7 +719,7 @@ export function adviceTools(ctx: ToolContext): string[] {
   return TOOL_DEFINITIONS.map(tool => tool.name).filter(name => !ctx.extensions?.has(name) &&
     (ctx.advice === undefined || ctx.advice.includes(name)) &&
     (ctx.allow === undefined || ctx.allow.includes(name)) &&
-    decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { tool: name }) !== "deny");
+    decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], { tool: name }) !== "deny");
 }
 
 /** A proposed recovery is data, not execution. Validate it against today's exact admission inputs. */
@@ -716,7 +733,7 @@ function scopeToolAdvice(ctx: ToolContext, result: ToolResult): ToolResult {
         const input = normalizeToolInput(ctx, recover.tool, recover.input);
         const definition = toolDefinition(recover.tool, ctx)!;
         allowed = inputError(definition.input_schema, input, "input", definition.hiddenInputs) === null &&
-          decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], permissionRequest(recover.tool, input)) !== "deny";
+          decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], permissionRequest(recover.tool, input)) !== "deny";
       } catch { /* Unavailable or invalid advice is omitted; the original failure remains. */ }
     }
     return scopeFailureGuidance(diagnostic, names, allowed);
@@ -1094,7 +1111,8 @@ async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>):
       data: { kind: "process", version: 1, session_id: id, state: "unknown", capability: "unknown", source: null, running: null, exit: null, replayed: true } };
   }
   const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), chars, ctx.signal));
+  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), chars, ctx.signal,
+    ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined));
 }
 
 /** A successful historical query proves only that the receipt was found, never a new command exit. */
@@ -1190,6 +1208,7 @@ async function toolGrep(ctx: ToolContext, input: Record<string, unknown>): Promi
   const limit = optionalLimit(input);
   const result = await grep({
     root: searchRoot(ctx, abs),
+    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "grep") === "allow" } : {}),
     path: abs,
     pattern: String(input["pattern"] ?? ""),
     engine: grepEngine(input),
@@ -1249,6 +1268,7 @@ async function toolFind(ctx: ToolContext, input: Record<string, unknown>): Promi
   const limit = optionalLimit(input);
   const result = await findFiles({
     root: searchRoot(ctx, abs),
+    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "find") === "allow" } : {}),
     path: abs,
     pattern: String(input["pattern"] ?? ""),
     timeoutMs: ctx.timeoutMs,
@@ -1264,6 +1284,7 @@ async function toolLs(ctx: ToolContext, input: Record<string, unknown>): Promise
   const limit = optionalLimit(input);
   const result = await ls({
     root: searchRoot(ctx, abs),
+    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "ls") === "allow" } : {}),
     path: abs,
     ...(ctx.signal ? { signal: ctx.signal } : {}),
     ...(limit !== undefined ? { limit } : {}),
@@ -1315,8 +1336,14 @@ export async function gateTool(
     return failure("permission_denied", `refused: ${name} is not available here (allowed: ${ctx.allow.join(", ")})`);
   }
   const definition = toolDefinition(name, ctx);
+  if (ctx.workflowMode === "plan" && definition && definition.access !== "read" &&
+    !(definition.access === "state" && (name === "note" || name === "question" && ctx.questionSlot)))
+    return failure("permission_denied", `${name} is unavailable in Plan mode; select Build at an idle checkpoint.`);
   input = repairToolInput(name, input);
-  const invalid = definition ? inputError(definition.input_schema, input, "input", definition.hiddenInputs) : null;
+  let invalid: string | null = null;
+  if (definition?.validateInput) {
+    try { definition.validateInput(input); } catch (error) { return caughtFailure(error, NOT_STARTED, "Invalid tool arguments: "); }
+  } else if (definition) invalid = inputError(definition.input_schema, input, "input", definition.hiddenInputs);
   if (invalid) {
     const example = minimalInput(definition!.input_schema);
     return failure("invalid_input", invalid, NOT_STARTED, example !== null && typeof example === "object" && !Array.isArray(example) &&
@@ -1324,9 +1351,14 @@ export async function gateTool(
   }
   if (ctx.rules === undefined) return null;
 
-  const request = permissionRequest(name, input);
-  const rules = [...(ctx.sessionRules ?? []), ...ctx.rules];
-  const decision = decide(rules, request);
+  const permissionInput = name === "apply_patch" && input && typeof input === "object" && "patchText" in input ? { paths: patchPaths(parsePatch(String(input.patchText))) } : input;
+  const request = await canonicalPermissionRequest(ctx.root, name, permissionInput);
+  let decision = decideWithSessionRules(ctx.rules, ctx.sessionRules ?? [], request);
+  if (definition?.access === "read" && request.paths) for (const path of request.paths) {
+    const resource = await permissionResourceAction(ctx.root, path, ctx.rules, ctx.sessionRules ?? [], name);
+    if (resource === "deny") { decision = "deny"; break; }
+    if (resource === "ask" && decision === "allow") decision = "ask";
+  }
   switch (decision) {
     case "allow":
       return null;
@@ -1405,6 +1437,8 @@ export async function prepareNormalizedTool(ctx: ToolContext, name: string, inpu
   try {
     const gated = await gateTool(ctx, name, input);
     if (gated) return scopeToolAdvice(ctx, finishToolResult(gated));
+    const instructions = await ctx.instructionCheck?.(ctx, name, input);
+    if (instructions) return scopeToolAdvice(ctx, finishToolResult(instructions));
     const veto = await scoped(() => ctx.extensionHooks?.before(name, observerValue(input), ctx.callId, ctx.parentCallId));
     await ctx.drainNested?.();
     if (veto) return scopeToolAdvice(ctx, finishToolResult(failure("permission_denied", veto)));

package/src/runtime/update-check.ts

@@ -5,9 +5,10 @@
  * timeout, falling back to the package's `latest` document. It carries
  * Bun's default User-Agent and nothing that identifies the person: the
  * registry sees an IP address, the time and the package name. Failure of
- * any kind is "no answer"; it never reaches the screen as an error.
+ * any kind is "no answer"; callers decide whether an explicit check needs feedback.
  */
 import { distTagsUrl } from "../core/update-check.ts";
+import { parseVersion } from "../core/version.ts";
 
 /** How long to wait for the registry. Codex and pi wait longer; startup never waits on it anyway. Assumed. */
 export const UPDATE_TIMEOUT_MS = 3000;
@@ -40,7 +41,7 @@ export async function fetchLatestVersion(registry: string | undefined, options:
       const response = await fetcher(url, { signal, headers: { accept: "application/json" } });
       if (!response.ok) continue;
       const value = pick(await response.json() as Record<string, unknown>);
-      if (typeof value === "string" && value.length <= 64) return value;
+      if (typeof value === "string" && value.length <= 64 && parseVersion(value)) return value.trim();
     } catch { if (signal.aborted) return null; }
   }
   return null;

package/src/runtime/web-http.ts

@@ -0,0 +1,56 @@
+/** Shared bounded network leaves; request errors never include arbitrary peer text or credentials. */
+import { webUrl } from "../core/web-content.ts";
+import { READ_ATTEMPTED, ToolFault } from "../core/tool-failure.ts";
+
+// Assumed resource bounds follow OpenCode's 5 MiB response cap; streamed enforcement prevents oversized allocation.
+export const MAX_WEB_RESPONSE_BYTES = 5 * 1024 * 1024;
+export const MAX_WEB_REDIRECTS = 5;
+export type WebFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export async function boundedResponseBytes(response: Response, limit = MAX_WEB_RESPONSE_BYTES): Promise<Uint8Array> {
+  const length = Number(response.headers.get("content-length"));
+  if (Number.isFinite(length) && length > limit) {
+    await response.body?.cancel(); throw new ToolFault("execution_failed", `Response exceeds ${limit} bytes`, READ_ATTEMPTED);
+  }
+  if (!response.body) return new Uint8Array();
+  const reader = response.body.getReader(), chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      size += next.value.byteLength;
+      if (size > limit) { await reader.cancel(); throw new ToolFault("execution_failed", `Response exceeds ${limit} bytes`, READ_ATTEMPTED); }
+      chunks.push(next.value);
+    }
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return bytes;
+}
+export async function boundedWebRequest(url: string, init: RequestInit, timeoutMs: number, signal: AbortSignal | undefined,
+  fetcher: WebFetch = fetch, redirects = MAX_WEB_REDIRECTS): Promise<{ response: Response; bytes: Uint8Array; url: string; redirects: string[] }> {
+  const deadline = new AbortController(), combined = AbortSignal.any([deadline.signal, ...(signal ? [signal] : [])]);
+  const timer = setTimeout(() => deadline.abort(), timeoutMs), history: string[] = [];
+  let target = webUrl(url);
+  try {
+    combined.throwIfAborted();
+    for (;;) {
+      const response = await fetcher(target, { ...init, redirect: "manual", signal: combined });
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        await response.body?.cancel();
+        const location = response.headers.get("location");
+        if (!location || history.length >= redirects) throw new ToolFault("execution_failed", "Redirect limit exceeded or Location missing", READ_ATTEMPTED);
+        const next = webUrl(new URL(location, target).href);
+        if (target.startsWith("https:") && next.startsWith("http:")) throw new ToolFault("execution_failed", "HTTPS redirects cannot downgrade to HTTP", READ_ATTEMPTED);
+        history.push(target); target = next;
+        continue;
+      }
+      return { response, bytes: await boundedResponseBytes(response), url: target, redirects: history };
+    }
+  } catch (error) {
+    if (signal?.aborted) throw new ToolFault("cancelled", "Network request cancelled", READ_ATTEMPTED);
+    if (deadline.signal.aborted) throw new ToolFault("timeout", "Network request timed out", READ_ATTEMPTED);
+    if (error instanceof ToolFault) throw error;
+    throw new ToolFault("execution_failed", "Network request failed; verify the URL and network connection", READ_ATTEMPTED);
+  } finally { clearTimeout(timer); }
+}

package/src/runtime/web-tools.ts

@@ -0,0 +1,88 @@
+/** Network adapters share the normal tool admission and append-only observation path (D11/D13). */
+import { join } from "node:path";
+import { webFetchArguments, webSearchArguments, webSearchHits, webSearchProjection, decodeWebEntities,
+  type WebFormat, type WebSearchConfig } from "../core/web-content.ts";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { archiveObservation } from "../store/observations.ts";
+import { presentObservation, type ToolContext, type ToolDefinition } from "./tools.ts";
+import { boundedWebRequest, type WebFetch } from "./web-http.ts";
+
+/** Bun's native HTML parser handles malformed/quoted markup; no homegrown HTML tokeniser or new dependency. */
+export async function extractWebHtml(html: string, url: string, format: Exclude<WebFormat, "html">): Promise<{ title: string; content: string }> {
+  let title = "";
+  const cleaned = await new HTMLRewriter().on("title", { text(chunk) { title += chunk.text; } })
+    .on("head,script,style,noscript,iframe,object,embed,template", { element(element) { element.remove(); } })
+    .transform(new Response(html)).text();
+  const blocks = new Set(["p", "div", "section", "article", "main", "header", "footer", "blockquote", "ul", "ol", "table", "tr", "pre", "h1", "h2", "h3", "h4", "h5", "h6"]);
+  const content = await new HTMLRewriter().on("*", { element(element) {
+    const tag = element.tagName;
+    if (blocks.has(tag) || tag === "br" || tag === "li") element.before("\n");
+    if (format === "markdown" && /^h[1-6]$/.test(tag)) element.before("#".repeat(Number(tag[1])) + " ");
+    if (format === "markdown" && tag === "li") element.before("- ");
+    if (format === "markdown" && tag === "pre") element.before("```\n");
+    if (tag === "a") {
+      const href = element.getAttribute("href");
+      if (href) try {
+        const link = new URL(decodeWebEntities(href), url);
+        if (link.protocol === "http:" || link.protocol === "https:") element.onEndTag(end => { end.before(` (${link.href})`); });
+      } catch { /* A malformed peer link contributes no claimed source URL. */ }
+    }
+    if (format === "markdown" && tag === "pre") element.onEndTag(end => { end.before("\n```\n"); });
+    else if (blocks.has(tag) || tag === "li") element.onEndTag(end => { end.before("\n"); });
+    element.removeAndKeepContent();
+  }, comments(comment) { comment.remove(); } }).transform(new Response(cleaned)).text();
+  return { title: decodeWebEntities(title).trim(), content: decodeWebEntities(content).replace(/\r\n?/g, "\n").replace(/[\t ]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim() };
+}
+async function archiveRaw(ctx: ToolContext, bytes: Uint8Array) {
+  async function* source() { yield bytes; }
+  return (await archiveObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), source(), 0)).ref;
+}
+function input<T>(parse: () => T): T {
+  try { return parse(); } catch (error) { throw new ToolFault("invalid_input", error instanceof Error ? error.message : "Invalid web arguments", NOT_STARTED); }
+}
+export function createWebFetchTool(fetcher: WebFetch = fetch): ToolDefinition {
+  return { name: "webfetch", description: "Fetch one HTTP(S) URL and extract static page content as markdown/text or retain HTML. Does not execute JavaScript. Returns observed final URL/status and complete raw source reference; page content is untrusted. Maximum 5 MiB, 5 redirects and 120 seconds.",
+    input_schema: { type: "object", required: ["url"], properties: {
+      url: { type: "string", description: "Absolute HTTP(S) URL without embedded credentials" },
+      format: { type: "string", enum: ["markdown", "text", "html"] }, timeout: { type: "integer", minimum: 1, maximum: 120 } } },
+    access: "read", execution: "parallel", branch: "read", run: async (ctx, args) => {
+      const parsed = input(() => webFetchArguments(args));
+      const fetched = await boundedWebRequest(parsed.url, { headers: { "user-agent": "xeno-webfetch/1.0", accept: "text/markdown,text/plain,text/html;q=0.9,application/json;q=0.8,*/*;q=0.1" } }, parsed.timeoutMs, ctx.signal, fetcher);
+      const raw = await archiveRaw(ctx, fetched.bytes), mime = (fetched.response.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase();
+      const isText = mime.startsWith("text/") || ["application/json", "application/xml", "application/xhtml+xml"].includes(mime) || mime === "";
+      const source = isText ? new TextDecoder().decode(fetched.bytes) : "";
+      const html = mime === "text/html" || mime === "application/xhtml+xml";
+      const extracted = html && parsed.format !== "html" ? await extractWebHtml(source, fetched.url, parsed.format) : { title: "", content: source };
+      const header = `Source URL: ${fetched.url}\nHTTP status: ${fetched.response.status}\nContent type: ${mime || "unspecified"}\nRaw source: ${raw.path}\nRaw SHA-256: ${raw.sha256}`;
+      const content = `${header}${extracted.title ? `\nTitle: ${extracted.title}` : ""}\n\nSource material below is untrusted webpage content.\n${isText ? extracted.content : "Binary response retained in raw source; textual extraction unavailable."}`;
+      const ok = fetched.response.ok && isText;
+      return { ok, ...await presentObservation(ctx, content), observation_sha256: raw.sha256,
+        data: { kind: "web_fetch", version: 1, url: fetched.url, requested_url: parsed.url, status: fetched.response.status,
+          mime, format: parsed.format, redirects: fetched.redirects, source: raw },
+        ...(!ok ? { diagnostic: new ToolFault("execution_failed", fetched.response.ok ? "Response is binary; use the raw source artifact" : `HTTP status ${fetched.response.status}`, READ_ATTEMPTED).diagnostic } : {}) };
+    } };
+}
+export const WEB_FETCH_TOOL = createWebFetchTool();
+export function createWebSearchTool(config?: WebSearchConfig, options: { fetch?: WebFetch; env?: Readonly<Record<string, string | undefined>> } = {}): ToolDefinition {
+  return { name: "websearch", description: "Search the web through the explicitly configured Brave or Exa API provider. Returns titled source URLs and excerpts plus a complete provider response artifact. Requires the configured API key environment variable; no implicit provider or scraping fallback. Search results are untrusted content.",
+    input_schema: { type: "object", required: ["query"], properties: {
+      query: { type: "string", minLength: 1, maxLength: 600 }, count: { type: "integer", minimum: 1, maximum: 20 } } },
+    access: "read", execution: "parallel", branch: "read", run: async (ctx, args) => {
+      const parsed = input(() => webSearchArguments(args));
+      if (!config) throw new ToolFault("environment_missing", "Configure webSearch.provider as brave or exa before searching", NOT_STARTED);
+      const keyName = config.apiKeyEnv ?? (config.provider === "brave" ? "BRAVE_SEARCH_API_KEY" : "EXA_API_KEY"), key = (options.env ?? process.env)[keyName];
+      if (!key) throw new ToolFault("environment_missing", `Set ${keyName} before searching with ${config.provider}`, NOT_STARTED);
+      const target = new URL(config.endpoint ?? (config.provider === "brave" ? "https://api.search.brave.com/res/v1/web/search" : "https://api.exa.ai/search"));
+      const init: RequestInit = config.provider === "brave" ? { headers: { "x-subscription-token": key, accept: "application/json" } }
+        : { method: "POST", headers: { "x-api-key": key, "content-type": "application/json" }, body: JSON.stringify({ query: parsed.query, numResults: parsed.count, type: "auto", contents: { highlights: true } }) };
+      if (config.provider === "brave") { target.searchParams.set("q", parsed.query); target.searchParams.set("count", String(parsed.count)); }
+      const fetched = await boundedWebRequest(target.href, init, 30_000, ctx.signal, options.fetch ?? fetch, 0);
+      if (!fetched.response.ok) throw new ToolFault(fetched.response.status === 429 || fetched.response.status >= 500 ? "transient" : "execution_failed", `Search provider returned HTTP ${fetched.response.status}; verify provider credentials and quota`, READ_ATTEMPTED);
+      let hits;
+      try { hits = webSearchHits(config.provider, JSON.parse(new TextDecoder().decode(fetched.bytes)), parsed.count); }
+      catch { throw new ToolFault("execution_failed", "Search provider response failed schema validation", READ_ATTEMPTED); }
+      const raw = await archiveRaw(ctx, fetched.bytes);
+      return { ok: true, ...await presentObservation(ctx, webSearchProjection(config.provider, parsed.query, hits) + `\n\nProvider response: ${raw.path}\nSHA-256: ${raw.sha256}`),
+        observation_sha256: raw.sha256, data: { kind: "web_search", version: 1, provider: config.provider, query: parsed.query, results: hits.map(hit => ({ ...hit })), source: raw } };
+    } };
+}

package/src/runtime/workspace-lifecycle.ts

@@ -1,6 +1,6 @@
 /** P.3: execution owns checkpoints; session opening owns no filesystem baseline. */
 import { randomUUID } from "node:crypto";
-import type { CheckpointEvent, FileVersion, WorkspaceObservationEvent } from "../core/checkpoints.ts";
+import type { CheckpointEvent, FileVersion, FileChanges, WorkspaceObservationEvent } from "../core/checkpoints.ts";
 import { sameVersion } from "../core/checkpoints.ts";
 import { blobAddress } from "../store/blobs.ts";
 import { archiveEdit, replaceFile, readEditableFile } from "../store/file-checkpoints.ts";
@@ -28,6 +28,19 @@ export class WorkspaceLifecycle {
   private interfere(): void {
     for (const checkpoint of this.pending.values()) checkpoint.unavailable = "overlapping mutations prevent attributing a command checkpoint";
   }
+  async patch(changes: FileChanges, execute: () => Promise<void>, signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted(); this.interfere();
+    const operation = randomUUID();
+    await this.record({ t: "checkpoint", operation, source: "edit", phase: "prepared", changes });
+    try {
+      await execute();
+      for (const [path, change] of Object.entries(changes)) if (!sameVersion((await readEditableFile(this.root, path)).version, change.after)) throw Error(`file changed concurrently after patch: ${path}`);
+      await this.record({ t: "checkpoint", operation, source: "edit", phase: "applied", changes });
+    } catch (error) {
+      await this.record({ t: "checkpoint", operation, source: "edit", phase: "unavailable", changes, reason: "patch did not establish the expected versions; inspect before retrying" });
+      throw error;
+    }
+  }
   async edit(path: string, before: { bytes: Uint8Array | null; version: FileVersion }, after: Uint8Array, signal?: AbortSignal): Promise<void> {
     this.interfere();
     await archiveEdit(this.blobs, before.bytes, after);

package/src/store/agent-profile-files.ts

@@ -0,0 +1,13 @@
+/** R13: profile files are inert JSON; project trust is decided by the app. */
+import { readFile } from "node:fs/promises";
+
+export async function readAgentProfileFile(path: string): Promise<{ value: unknown; diagnostic?: string } | null> {
+  let body: string;
+  try { body = await readFile(path, "utf8"); }
+  catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return null;
+    return { value: null, diagnostic: `${path}: unable to read agents configuration` };
+  }
+  try { return { value: JSON.parse(body) as unknown }; }
+  catch { return { value: null, diagnostic: `${path}: invalid JSON in agents configuration` }; }
+}

package/src/store/blobs.ts

@@ -121,8 +121,9 @@ export async function getBlob(dir: string, sha: string): Promise<string | null>
 }
 
 /** Restore uses bytes; decoding binary data is an irreversible transformation. */
-export async function getBlobBytes(dir: string, sha: string): Promise<Uint8Array | null> {
+export async function getBlobBytes(dir: string, sha: string, maxBytes?: number): Promise<Uint8Array | null> {
   try {
+    if (maxBytes !== undefined && (await stat(blobFilePath(dir, sha))).size > maxBytes) throw new RangeError("Blob exceeds byte limit");
     const bytes = await readFile(blobFilePath(dir, sha));
     if (blobAddress(bytes) !== sha) throw new Error(`blob integrity failure: ${sha}`);
     return bytes;

package/src/store/context-files.ts

@@ -18,9 +18,11 @@
  * frozen at startup; an explicit reload checkpoints a changed prefix.
  */
 
-import { readFile, stat } from "node:fs/promises";
+import { readFile, stat, lstat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { assertNever } from "../core/exhaustive.ts";
+import { blobAddress } from "./blobs.ts";
+import { gitBytes } from "./workspace-observation.ts";
 
 /**
  * Per-file cap. Assumed, not measured: a rule file larger than this is a
@@ -354,3 +356,77 @@ export function formatNotice(notice: ContextNotice): string {
       return assertNever(notice, "formatNotice");
   }
 }
+
+/** Startup uses the actual repository instruction chain; loadContext remains explicit/compatible. */
+export async function resolveContextWorkspace(cwd: string): Promise<string> {
+  try {
+    const bytes = await gitBytes(cwd, ["--no-pager", "rev-parse", "--show-prefix"]);
+    const prefix = new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/\n$/, "");
+    // Git canonicalizes macOS /var to /private/var. Ascending the known prefix
+    // keeps root and cwd in the same spelling, preserving the instruction chain.
+    let root = resolve(cwd);
+    const levels = prefix.split("/").filter(Boolean).length;
+    for (let level = 0; level < levels; level++) root = dirname(root);
+    return root;
+  } catch { return resolve(cwd); }
+}
+
+export interface TargetInstruction extends LoadedFile { scope: string; key: string }
+export interface TargetInstructionOptions {
+  workspace: string;
+  paths: readonly string[];
+  /** Digests from frozen startup files and durable instruction events, never model claims. */
+  known?: ReadonlySet<string>;
+  noContextFiles?: boolean;
+  /** Admission runs before instruction bytes are captured. */
+  canRead?: (path: string) => Promise<boolean>;
+}
+export const instructionKey = (file: Pick<LoadedFile, "path" | "content">): string =>
+  `${resolve(file.path)}:${blobAddress(file.content)}`;
+
+/** Target paths are explicit. No recursive scan, sibling instruction loading or prefix surgery. */
+export async function discoverTargetInstructions(options: TargetInstructionOptions): Promise<{ files: TargetInstruction[]; notices: ContextNotice[] }> {
+  if (options.noContextFiles) return { files: [], notices: [] };
+  const root = resolve(options.workspace), directories = new Set<string>();
+  for (const path of options.paths) {
+    const absolute = resolve(root, path);
+    if (!isInside(absolute, root)) throw new Error(`instruction target escapes workspace: ${path}`);
+    for (const directory of projectDirectories(root, dirname(absolute))) directories.add(directory);
+  }
+  const ordered = [...directories].sort((a, b) => a.split(sep).length - b.split(sep).length || a.localeCompare(b));
+  const files: TargetInstruction[] = [], notices: ContextNotice[] = [], budget = new Budget();
+  for (const directory of ordered) {
+    // A target directory's symlink must not import another project's ambient authority.
+    let safe = true, current = root;
+    for (const part of relative(root, directory).split(sep).filter(Boolean)) {
+      current = join(current, part);
+      try { const info = await lstat(current); if (info.isSymbolicLink() || !info.isDirectory()) { safe = false; break; } }
+      catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
+    }
+    if (!safe) { notices.push({ kind: "skipped", path: directory, reason: "instruction scope crosses a symlink or non-directory" }); continue; }
+    for (const name of AGENTS_CANDIDATES) {
+      const path = join(directory, name);
+      try {
+        const info = await lstat(path);
+        if (info.isDirectory()) continue;
+        if (info.isSymbolicLink() || !info.isFile()) { notices.push({ kind: "skipped", path, reason: "instruction file must be ordinary, not a symlink" }); break; }
+      } catch (error) { if ((error as { code?: string }).code === "ENOENT") continue; throw error; }
+      if (options.canRead && !await options.canRead(path)) { notices.push({ kind: "skipped", path, reason: "instruction read permission is unavailable" }); break; }
+      const got = await tryRead(path);
+      if (got.status !== "ok") { if (got.status === "skip") notices.push({ kind: "skipped", path, reason: got.reason }); break; }
+      const file = absorbText(path, got.text, "agents", got.bytes, budget, notices), key = instructionKey(file);
+      if (!options.known?.has(key)) files.push({ ...file, scope: directory, key });
+      break;
+    }
+  }
+  return { files, notices };
+}
+
+/** Append as a durable in-context event; closer scope overrides only files under that directory. */
+export function renderTargetInstructions(files: readonly TargetInstruction[]): string {
+  if (!files.length) return "";
+  return "# Instructions discovered for the current file targets\n\n" +
+    "Apply each file only within its directory scope. Deeper directories take precedence. " +
+    "This observed version supersedes earlier versions at the same path; other scopes remain unchanged.\n\n" +
+    files.map(file => `<instruction_scope directory="${escapeAttr(file.scope)}" key="${escapeAttr(file.key)}">\n${renderFile(file)}\n</instruction_scope>`).join("\n\n");
+}

package/src/store/file-checkpoints.ts

@@ -67,8 +67,9 @@ export async function archiveEdit(blobs: string, before: Uint8Array | null, afte
   await putBlob(blobs, after);
 }
 
-export async function preflightChanges(root: string, blobs: string, changes: FileChanges): Promise<void> {
+export async function preflightChanges(root: string, blobs: string, changes: FileChanges, signal?: AbortSignal): Promise<void> {
   for (const path of changedPaths(changes)) {
+    if (signal?.aborted) throw new ToolFault("cancelled", "file operation cancelled", NOT_STARTED);
     const change = changes[path]!;
     if (!sameVersion((await readEditableFile(root, path)).version, change.before)) throw new Error(`file conflict: ${path}; external changes were preserved`);
     if (change.after && !await verifyBlob(blobs, change.after.sha256)) throw new Error(`missing checkpoint object: ${path}`);
@@ -77,15 +78,15 @@ export async function preflightChanges(root: string, blobs: string, changes: Fil
 }
 
 /** Preflight the complete plan, then compensate partial writes if an individual replacement fails. */
-export async function applyFileChanges(root: string, blobs: string, changes: FileChanges): Promise<void> {
-  await preflightChanges(root, blobs, changes);
+export async function applyFileChanges(root: string, blobs: string, changes: FileChanges, signal?: AbortSignal): Promise<void> {
+  await preflightChanges(root, blobs, changes, signal);
   const applied: string[] = [];
   try {
     for (const path of changedPaths(changes)) {
       const { before, after } = changes[path]!;
       const bytes = after === null ? null : await getBlobBytes(blobs, after.sha256);
       if (after && bytes === null) throw new Error(`missing checkpoint object: ${path}`);
-      await replaceFile(root, path, before, bytes, after?.mode ?? 0o644);
+      await replaceFile(root, path, before, bytes, after?.mode ?? 0o644, signal);
       applied.push(path);
     }
   } catch (error) {

package/src/store/foundation-config.ts

@@ -0,0 +1,24 @@
+/** Trusted executable configuration follows the same user/project boundary as extensions. */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function readFoundationConfig(configDirectory: string, workspace: string, trusted: boolean): Promise<Record<string, unknown>> {
+  let value: Record<string, unknown> = {};
+  for (const path of [join(configDirectory, "foundation.json"), ...(trusted ? [join(workspace, ".xeno", "foundation.json")] : [])]) {
+    let text: string;
+    try { text = await readFile(path, "utf8"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
+    const parsed: unknown = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw Error(`${path}: expected an object`);
+    const allowed = ["mcp", "webSearch", "formatters", "lsp", "permissions"];
+    if (Object.keys(parsed).some(key => !allowed.includes(key))) throw Error(`${path}: unknown foundation setting`);
+    value = { ...value, ...parsed };
+  }
+  return value;
+}
+
+export async function readOutputSchema(path: string): Promise<unknown> {
+  const text = await readFile(path, "utf8");
+  if (Buffer.byteLength(text) > 1_048_576) throw Error("output schema exceeds 1 MiB");
+  return JSON.parse(text) as unknown;
+}

package/src/store/git-status.ts

@@ -0,0 +1,15 @@
+/** Local Git reads are asynchronous and bounded; a paint never launches a process. */
+import { execFile } from "node:child_process";
+import { parseGitStatus, type GitStatus } from "../core/git-status.ts";
+/** Assumed cold-disk allowance; Git failure remains unavailable rather than "clean". */
+const GIT_STATUS_TIMEOUT_MS = 1000;
+/** A busy repository cannot flood memory or the status view with paths. */
+const GIT_STATUS_MAX_BYTES = 1024 * 1024;
+
+export function readGitStatus(cwd: string): Promise<GitStatus | null> {
+  return new Promise(resolve => {
+    execFile("git", ["--no-optional-locks", "status", "--porcelain=v2", "--branch", "-z", "--untracked-files=normal"],
+      { cwd, timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: GIT_STATUS_MAX_BYTES, encoding: "utf8" },
+      (error, output) => resolve(error ? null : parseGitStatus(output)));
+  });
+}

package/src/store/lsp-document.ts

@@ -0,0 +1,30 @@
+import { editablePath } from "./file-checkpoints.ts";
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { blobAddress } from "./blobs.ts";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+// Operational memory ceiling: a language server is optional and must not read arbitrarily large files.
+const MAX_LSP_DOCUMENT = 2 * 1024 * 1024;
+export async function readLspDocument(root: string, path: string, signal?: AbortSignal): Promise<{ uri: string; text: string; sha256: string }> {
+  signal?.throwIfAborted();
+  const absolute = await editablePath(root, path);
+  const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.nlink > 1) throw Error("LSP requires an existing ordinary workspace file");
+    if (info.size > MAX_LSP_DOCUMENT) throw Error("LSP document exceeds 2 MiB");
+    const bytes = new Uint8Array(MAX_LSP_DOCUMENT + 1); let length = 0;
+    for (;;) {
+      signal?.throwIfAborted();
+      const result = await file.read(bytes, length, bytes.length - length, null);
+      if (!result.bytesRead) break;
+      length += result.bytesRead;
+      if (length > MAX_LSP_DOCUMENT) throw Error("LSP document exceeds 2 MiB");
+    }
+    signal?.throwIfAborted();
+    const content = bytes.subarray(0, length);
+    return { uri: pathToFileURL(resolve(root, path)).href, text: new TextDecoder("utf8", { fatal: true }).decode(content), sha256: blobAddress(content) };
+  } finally { await file.close(); }
+}