@visual-z/xeno 0.4.0 → 0.6.0

package/src/runtime/session-hub.ts

@@ -0,0 +1,85 @@
+/** A hub owns live sessions, not transcript mirrors. Durable listing stays a store projection. */
+import type { SessionControl } from "./session-control.ts";
+import { basename } from "node:path";
+
+// Assumed live-owner bound includes admitted opens, so concurrent requests cannot exceed it.
+export const MAX_LIVE_SESSIONS = 32;
+
+export interface SessionHubHost {
+  list(): Promise<unknown>;
+  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl>;
+  dispose(control: SessionControl): Promise<void>;
+}
+export class SessionHub {
+  private readonly controls = new Map<string, SessionControl>();
+  private readonly opening = new Set<Promise<SessionControl>>();
+  private readonly resuming = new Map<string, Promise<SessionControl>>();
+  private readonly closing = new Map<string, Promise<void>>();
+  private reserved = 0;
+  private closed = false;
+  private disposal: Promise<void> | undefined;
+  private readonly host: SessionHubHost;
+  readonly initial: SessionControl;
+  constructor(initial: SessionControl, host: SessionHubHost) {
+    this.initial = initial; this.host = host; this.controls.set(initial.threadId, initial);
+  }
+  get(threadId: string): SessionControl {
+    if (this.closed || this.closing.has(threadId)) throw Error("session hub or thread is closing");
+    const control = this.controls.get(threadId);
+    if (!control) throw Error("unknown or closed threadId; resume the session first");
+    return control;
+  }
+  async list(): Promise<unknown> { if (this.closed) throw Error("session hub is closing"); return this.host.list(); }
+  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl> {
+    if (this.closed) return Promise.reject(Error("session hub is closing; no new session was admitted"));
+    const captured = structuredClone(params);
+    // Coalesce resume only. Two explicit new/fork requests create two distinct sessions.
+    const key = kind === "resume" ? JSON.stringify(captured) : "";
+    const pending = key ? this.resuming.get(key) : undefined;
+    if (pending) return pending;
+    const requested = captured["session"];
+    const known = kind === "resume" && [...this.controls.values()].some(control => !this.closing.has(control.threadId)
+      && [control.threadId, control.session.config.logDir, basename(control.session.config.logDir)].includes(String(requested)));
+    if (!known && this.controls.size + this.reserved >= MAX_LIVE_SESSIONS) return Promise.reject(Error("live session limit reached; close a session first"));
+    if (!known) this.reserved++;
+    const operation = (async () => {
+      try {
+        const control = await this.host.open(kind, captured), existing = this.controls.get(control.threadId);
+        if (this.closing.has(control.threadId) || !existing && this.controls.size >= MAX_LIVE_SESSIONS) {
+          if (existing !== control) await this.host.dispose(control);
+          throw Error("thread is closing or the live session limit was reached");
+        }
+        if (existing && existing !== control) { await this.host.dispose(control); if (this.closed) throw Error("session hub closed during opening"); return existing; }
+        this.controls.set(control.threadId, control);
+        if (this.closed) throw Error("session hub closed during opening; the admitted owner will be drained");
+        return control;
+      } finally { if (!known) this.reserved--; }
+    })();
+    this.opening.add(operation); if (key) this.resuming.set(key, operation);
+    // Observe rejected opens without changing the caller's promise or leaking unhandled cleanup rejections.
+    void operation.finally(() => { this.opening.delete(operation); if (key) this.resuming.delete(key); }).catch(() => {});
+    return operation;
+  }
+  close(threadId: string): Promise<void> {
+    const pending = this.closing.get(threadId); if (pending) return pending;
+    const control = this.controls.get(threadId); if (!control) return Promise.reject(Error("unknown or closed threadId"));
+    const operation = (async () => {
+      if (control.activeTurnId) control.interrupt(control.activeTurnId);
+      await control.whenIdle().catch(() => {});
+      await this.host.dispose(control); this.controls.delete(threadId);
+    })();
+    this.closing.set(threadId, operation);
+    void operation.then(() => { if (this.closing.get(threadId) === operation) this.closing.delete(threadId); }, () => {});
+    return operation;
+  }
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
+    this.closed = true;
+    return this.disposal = (async () => {
+      // Every kind is tracked; late publication belongs to this same draining generation.
+      await Promise.allSettled([...this.opening]);
+      const results = await Promise.allSettled([...this.controls.keys()].map(id => this.close(id)));
+      if (results.some(result => result.status === "rejected")) throw Error("session cleanup could not be confirmed");
+    })();
+  }
+}

package/src/runtime/tool-discovery.ts

@@ -1,7 +1,7 @@
 /** R11: a harness-owned discovery entry shares normal Session admission and result persistence. */
 import { createHash } from "node:crypto";
 import { discoverTools, MAX_DISCOVERY_QUERY, MAX_DISCOVERY_RESULTS, type DeclarationRequest } from "../core/tool-discovery.ts";
-import { decide } from "../core/permissions.ts";
+import { decideWithSessionRules } from "../core/permissions.ts";
 import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
 import type { ToolSchema } from "./provider.ts";
 import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
@@ -14,7 +14,7 @@ export const DISCOVERY_TOOL: ToolDefinition = {
     query: { type: "string", minLength: 1, maxLength: MAX_DISCOVERY_QUERY },
     limit: { type: "integer", minimum: 1, maximum: MAX_DISCOVERY_RESULTS, description: "Maximum matches to request; defaults to 5." },
   }, required: ["query"] },
-  access: "state", execution: "exclusive", branch: "none",
+  access: "read", execution: "exclusive", branch: "none",
   run: async () => ({ ok: false, content: "Tool discovery requires a live Session checkpoint." }),
 };
 
@@ -23,7 +23,8 @@ export function discoveryFingerprint(tool: ToolSchema): string {
   return createHash("sha256").update(JSON.stringify({ name: tool.name, description: tool.description, input_schema: tool.input_schema })).digest("hex");
 }
 export function discoveryPermitted(ctx: ToolContext, name: string): boolean {
-  return decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { tool: name }) !== "deny";
+  if (ctx.workflowMode === "plan" && ctx.extensions?.get(name)?.access !== "read") return false;
+  return decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], { tool: name }) !== "deny";
 }
 /** A directory entry without its matching live implementation is unavailable, regardless of history. */
 export function currentDeferredTools(ctx: ToolContext): readonly ToolSchema[] {

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. */
@@ -285,6 +297,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>;
 }
 
@@ -370,7 +384,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     description:
       "Read a file. Returns the contents with 1-indexed line numbers. " +
       "Optionally limit to an inclusive line range. Reports total lines and the next range; end beyond EOF is clamped. " +
-      "Returns read_handle and whole-file sha256 for version checks. Long lines and large previews retain an immutable artifact. Line ranges describe the selection; the observation receipt describes exactly what was visible. An unavailable artifact-recovery capability leaves a gap, not proof of full coverage.",
+      "Session remembers the whole-file version for later changes; no digest copying is needed. Returns read_handle and whole-file sha256 for selecting an explicit observation. Long lines and large previews retain an immutable artifact. Line ranges describe the selection; the observation receipt describes exactly what was visible. An unavailable artifact-recovery capability leaves a gap, not proof of full coverage.",
     input_schema: {
       type: "object",
       properties: {
@@ -384,14 +398,14 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: "write",
     access: "write", execution: "exclusive", branch: "write", run: toolWrite,
-    description: "Write a file, creating parent directories. Replaces existing content. Pass read_handle or expected_sha256 for an explicit version check; otherwise Session uses its last observed version. create_only requires absence. A conflict requires a fresh read. Identical content makes no change.",
+    description: "Write a file, creating parent directories. Replaces existing content. Normally omit read_handle and expected_sha256: Session checks its latest observed version. Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. create_only requires absence. A conflict requires a fresh read. Identical content makes no change.",
     input_schema: {
       type: "object",
       properties: {
         path: { type: "string" },
         content: { type: "string" },
-        read_handle: { type: "string", description: "Descriptor SHA from an observation of this file, workspace and host" },
-        expected_sha256: { type: "string", description: "Expected whole-file raw-byte SHA-256" },
+        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
+        expected_sha256: { type: "string", description: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
         create_only: { type: "boolean", description: "Require that the target does not exist; excludes read_handle and expected_sha256" },
       },
       required: ["path", "content"],
@@ -400,14 +414,16 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: "edit",
     example: { path: "src/main.ts", old_string: "const size = 1;", new_string: "const size = 2;" },
-    guidance: [{ requires: ["read"], text: "Use read to obtain current text and a version receipt before an edit." }],
+    guidance: [{ requires: ["read"], text: "Use read to obtain current text before an edit; Session remembers its version automatically." }],
     access: "write", execution: "exclusive", branch: "write", run: toolEdit,
     description:
-      "Replace exact text in a file. old_string must match once unless replace_all is set; copy it from observed file content, " +
+      "Replace exact text in a file. Normally omit read_handle and expected_sha256: Session checks its latest observed version. " +
+      "Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. " +
+      "old_string must match once unless replace_all is set; copy it from observed file content, " +
       "including indentation (line numbers are not part of the file). For several changes to one file pass edits[], " +
       "each matched against the original; all apply or none do. If there is no exact match, a unique match that differs only in " +
       "trailing whitespace, quote or dash style is applied and flagged fuzzy. A failure shows the closest text in the file. " +
-      "Pass read_handle or expected_sha256 from a file observation to reject stale edits; when omitted, Session uses its last observed version. A conflict requires a fresh observation. A partial read handle checks the whole file version, not permission to edit unseen lines.",
+      "A conflict requires a fresh observation. A partial read handle checks the whole file version, not permission to edit unseen lines.",
     input_schema: {
       type: "object",
       properties: {
@@ -419,8 +435,8 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
           type: "object", required: ["old_string", "new_string"], properties: {
             old_string: { type: "string", minLength: 1 }, new_string: { type: "string" }, replace_all: { type: "boolean" },
           } } },
-        expected_sha256: { type: "string", description: "Observed whole-file version; mismatch leaves the file unchanged" },
-        read_handle: { type: "string", description: "Descriptor SHA from an observation of this file, workspace and host" },
+        expected_sha256: { type: "string", description: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
+        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
       },
       required: ["path"],
     },
@@ -700,7 +716,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. */
@@ -714,7 +730,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);
@@ -1188,6 +1204,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),
@@ -1247,6 +1264,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,
@@ -1262,6 +1280,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 } : {}),
@@ -1313,8 +1332,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) &&
@@ -1322,9 +1347,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;
@@ -1403,6 +1433,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/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");
+}