@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/turn-effects.ts

@@ -1,31 +0,0 @@
-/**
- * The current request's operations outside the workspace, read from the log
- * when a request ends (feat-external-effects-summary). The derivation is the
- * pure core function; this file only supplies what core may not read: the
- * home directory and the platform's temporary directory.
- * Nothing is recorded -- the list is a projection and is recomputed on demand.
- */
-import { realpathSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { externalEffects, type ExternalEffect, type ExternalOptions } from "../core/external-effects.ts";
-import { currentRequestEvents } from "../core/request-state.ts";
-import type { Session } from "./loop.ts";
-
-/** macOS reports /var/folders/... while processes see /private/var/folders/...; both are temporary. */
-export function hostExternalOptions(): ExternalOptions {
-  const temp = tmpdir();
-  let real = temp;
-  try { real = realpathSync(temp); } catch { /* an unreadable temp root is still the reported one */ }
-  return { home: homedir(), temp: [...new Set([temp, real])] };
-}
-
-/**
- * Synchronous on purpose: SessionControl computes this between the turn's last
- * event and releasing the turn, and an await there lets a disposal observe a
- * turn that has already ended. The cost is one known gap: a request that
- * crossed a segment boundary lists only what ran after the last cut (D8 keeps
- * the earlier part in the sealed segment, not in memory). Silence, not a guess.
- */
-export function requestExternalEffects(session: Session, options: ExternalOptions = hostExternalOptions()): ExternalEffect[] {
-  return externalEffects(currentRequestEvents(session.state.events), session.config.tools.root, options);
-}

package/src/runtime/update-check.ts

@@ -1,48 +0,0 @@
-/**
- * Ask the npm registry for the newest published xeno (docs/tasks/feat-update-check.md).
- *
- * One small GET (the dist-tags document is about 20 bytes) with a 3-second
- * 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"; 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;
-
-type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
-
-export interface LatestVersionOptions {
-  /**
-   * Ends the request early. The interactive app aborts it on close: an open
-   * socket keeps the process alive, so quitting would otherwise wait out the
-   * timeout (feat-update-check DoD 3).
-   */
-  readonly signal?: AbortSignal;
-  readonly fetcher?: Fetch;
-  readonly timeoutMs?: number;
-}
-
-export async function fetchLatestVersion(registry: string | undefined, options: LatestVersionOptions = {}): Promise<string | null> {
-  const fetcher = options.fetcher ?? ((input, init) => fetch(input, init));
-  const timeout = AbortSignal.timeout(options.timeoutMs ?? UPDATE_TIMEOUT_MS);
-  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
-  const tags = distTagsUrl(registry);
-  const attempts: [string, (body: Record<string, unknown>) => unknown][] = [
-    [tags, body => body["latest"]],
-    // Mirrors that do not serve dist-tags still serve the package's latest document.
-    [tags.replace(/\/-\/package\/([^/]+)\/dist-tags$/, "/$1/latest"), body => body["version"]],
-  ];
-  for (const [url, pick] of attempts) {
-    try {
-      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 && parseVersion(value)) return value.trim();
-    } catch { if (signal.aborted) return null; }
-  }
-  return null;
-}

package/src/runtime/usage.ts

@@ -1,253 +0,0 @@
-/**
- * Per-request usage accounting.
- *
- * This exists to answer the question the whole design rests on: is the prompt
- * prefix actually stable? The core's claim is that appending within a node
- * only appends, so every turn should read the entire accumulated prefix from
- * cache and write only what the last turn added. That is checkable, and the
- * shape of a healthy loop is specific:
- *
- *   cache_read grows turn over turn and covers the whole prior prefix
- *   cache_creation is small -- only the delta
- *   input_tokens (uncached) stays near zero after the first turn
- *
- * A cache_read that sits at zero across turns with the same prefix means a
- * silent invalidator got in. Since that failure costs money without ever
- * raising an error, measuring it is the only way to know.
- *
- * Pure: the aggregator takes samples and returns totals. The caller records
- * the timestamps.
- *
- * The field names below are a NORMALISED internal vocabulary, not one
- * provider's wire format. Every adapter maps onto them: a provider that bills
- * nothing for cache writes reports 0 there rather than leaving the field to
- * mean something else.
- */
-
-import type { CacheKind, CacheRates, Price } from "./model.ts";
-
-/** What one API response reports, normalised by the adapter. */
-export interface UsageSample {
-  input_tokens: number;
-  output_tokens: number;
-  cache_creation_input_tokens: number;
-  cache_read_input_tokens: number;
-  /** Which node the request belonged to, so per-node costs stay separable. */
-  node: number;
-  /** Wall-clock milliseconds for the request. */
-  ms: number;
-}
-
-export interface UsageTotals {
-  requests: number;
-  input_tokens: number;
-  output_tokens: number;
-  cache_creation_input_tokens: number;
-  cache_read_input_tokens: number;
-  ms: number;
-  /**
-   * Total prompt size is the sum of all three input fields -- `input_tokens`
-   * alone is only the uncached remainder. An agent that ran for hours can show
-   * 4K there while the real prefix was 200K.
-   */
-  prompt_tokens: number;
-  /**
-   * Fraction of prompt tokens served from cache. The number that says whether
-   * the append-only property is holding in practice.
-   */
-  cache_hit_rate: number;
-}
-
-export function emptyTotals(): UsageTotals {
-  return {
-    requests: 0,
-    input_tokens: 0,
-    output_tokens: 0,
-    cache_creation_input_tokens: 0,
-    cache_read_input_tokens: 0,
-    ms: 0,
-    prompt_tokens: 0,
-    cache_hit_rate: 0,
-  };
-}
-
-export function totalUsage(samples: readonly UsageSample[]): UsageTotals {
-  const t = emptyTotals();
-  for (const s of samples) {
-    t.requests += 1;
-    t.input_tokens += s.input_tokens;
-    t.output_tokens += s.output_tokens;
-    t.cache_creation_input_tokens += s.cache_creation_input_tokens;
-    t.cache_read_input_tokens += s.cache_read_input_tokens;
-    t.ms += s.ms;
-  }
-  t.prompt_tokens =
-    t.input_tokens + t.cache_creation_input_tokens + t.cache_read_input_tokens;
-  t.cache_hit_rate =
-    t.prompt_tokens === 0 ? 0 : t.cache_read_input_tokens / t.prompt_tokens;
-  return t;
-}
-
-/**
- * Below this a request's speed is not shown: a response that returns at once
- * (a test double, a local cache) would divide into thousands of tokens per
- * second. Assumed, not measured.
- */
-export const SPEED_MIN_MS = 250;
-
-/**
- * Output tokens per second over a set of model requests, or undefined when
- * none can be measured (feat-sidebar-goal-and-speed). OpenCode's built-in
- * turnTokensPerSecond uses the same definition: output over the time the
- * requests took, each request counted once. Not output over the time since
- * the first visible output -- output counts include reasoning that providers
- * do not always stream (OpenAI summaries arrive late, Anthropic can omit
- * them), so that would keep reasoning tokens and drop reasoning time, and
- * overstate. Whole request time never overstates; an overloaded upstream
- * reads slow, which is what the user is waiting on.
- */
-export function generationSpeed(samples: readonly UsageSample[]): number | undefined {
-  let tokens = 0, ms = 0;
-  for (const sample of samples) {
-    if (sample.output_tokens <= 0 || !(sample.ms >= SPEED_MIN_MS)) continue;
-    tokens += sample.output_tokens;
-    ms += sample.ms;
-  }
-  return ms > 0 ? tokens / (ms / 1000) : undefined;
-}
-
-/**
- * Cost in equivalent base-input tokens, the unit appendix A's model uses.
- *
- * Reported as a multiplier rather than dollars so it stays true across models
- * and price changes. The rates come from the model rather than from this
- * module: they are not a property of the unit, they are a property of the
- * provider's contract, and they differ by an order of magnitude. Anthropic
- * bills reads at 0.1x and 5-minute writes at 1.25x; DeepSeek bills reads at
- * 0.033x and writes at nothing. Output is counted separately because its rate
- * is a different multiple of input and varies by model.
- */
-export interface EquivalentCost {
-  input_equivalent: number;
-  output_tokens: number;
-  /** What the same prompts would have cost with no caching at all. */
-  uncached_equivalent: number;
-  /** uncached / actual. 1.0 means caching bought nothing. */
-  savings_ratio: number;
-}
-
-/**
- * Dollar cost of a session: complete, partial, or an explicit unknown.
- *
- * Unknown is a distinct member, not the number 0: a missing price times any
- * token count is not "this session was free", and collapsing the two is how
- * `/usage` would silently misreport every unpriced model.
- *
- * Partial is a distinct member, not `{kind:"usd", amount, note}`. A caller
- * that only reads `amount` on `usd` must not be able to print a total that
- * silently omitted cache spend as if the unknown rate were zero. `known`
- * is the part we can prove; `uncounted` is why it is not a complete bill.
- */
-export type ReportedCost =
-  | { kind: "unknown" }
-  | { kind: "usd"; amount: number }
-  | { kind: "partial"; known: number; uncounted: "cache" };
-
-export function reportedCost(t: UsageTotals, price: Price | undefined): ReportedCost {
-  if (price === undefined) return { kind: "unknown" };
-  const known =
-    (t.input_tokens * price.input + t.output_tokens * price.output) / 1_000_000;
-  if (price.cacheRead !== undefined && price.cacheWrite !== undefined) {
-    const amount =
-      known +
-      (t.cache_read_input_tokens * price.cacheRead +
-        t.cache_creation_input_tokens * price.cacheWrite) /
-        1_000_000;
-    return { kind: "usd", amount };
-  }
-  // One or both cache rates are missing. Add the ones we have; never
-  // substitute 0 for the ones we do not — that is the low-bill path.
-  let extra = 0;
-  if (price.cacheRead !== undefined) {
-    extra += (t.cache_read_input_tokens * price.cacheRead) / 1_000_000;
-  }
-  if (price.cacheWrite !== undefined) {
-    extra += (t.cache_creation_input_tokens * price.cacheWrite) / 1_000_000;
-  }
-  return { kind: "partial", known: known + extra, uncounted: "cache" };
-}
-
-export function equivalentCost(t: UsageTotals, rates: CacheRates): EquivalentCost {
-  const actual =
-    t.input_tokens +
-    t.cache_creation_input_tokens * rates.write +
-    t.cache_read_input_tokens * rates.read;
-  const uncached = t.prompt_tokens;
-  return {
-    input_equivalent: actual,
-    output_tokens: t.output_tokens,
-    uncached_equivalent: uncached,
-    savings_ratio: actual === 0 ? 1 : uncached / actual,
-  };
-}
-
-/**
- * Per-turn diagnosis of whether the prefix held.
- *
- * `cache_creation` above the delta means something ahead of the new content
- * changed, which is the signature of an invalidator rather than of growth.
- *
- * What counts as a symptom depends on who controls the cache. Under `explicit`
- * caching the caller placed the breakpoint, so a miss on a follow-up request
- * means the prefix moved and that is worth shouting about. Under `automatic`
- * caching the provider decides: DeepSeek documents its cache as best-effort
- * with no guaranteed hit rate and writes that "take seconds", so an early miss
- * is the normal case. Reporting it would light a warning at the start of every
- * session, and a warning that is always on stops being read.
- */
-export type PrefixVerdict =
-  | { kind: "cold"; detail: string }
-  | { kind: "healthy"; read: number; wrote: number }
-  | { kind: "suspicious"; detail: string };
-
-export function diagnosePrefix(
-  sample: UsageSample,
-  previous: UsageSample | undefined,
-  cache: CacheKind,
-): PrefixVerdict {
-  if (!previous) {
-    return { kind: "cold", detail: "first request of the session; nothing to reuse yet" };
-  }
-  if (sample.cache_read_input_tokens === 0) {
-    return cache === "automatic"
-      ? {
-          kind: "cold",
-          detail:
-            "no cache hit yet -- this provider caches on its own, best-effort, and " +
-            "a write takes seconds to land. Only a problem if it persists across turns",
-        }
-      : {
-          kind: "suspicious",
-          detail:
-            "cache_read is 0 on a follow-up request -- the prefix changed, or it is " +
-            "below the model's minimum cacheable size",
-        };
-  }
-  const previousPrompt =
-    previous.input_tokens +
-    previous.cache_creation_input_tokens +
-    previous.cache_read_input_tokens;
-  if (sample.cache_read_input_tokens < previousPrompt * 0.5) {
-    return {
-      kind: "suspicious",
-      detail:
-        `cache_read (${sample.cache_read_input_tokens}) covers less than half of the ` +
-        `previous prompt (${previousPrompt}) -- part of the prefix was invalidated`,
-    };
-  }
-  return {
-    kind: "healthy",
-    read: sample.cache_read_input_tokens,
-    wrote: sample.cache_creation_input_tokens,
-  };
-}

package/src/runtime/version.ts

@@ -1,12 +0,0 @@
-/**
- * The one place xeno's version is known (S.4: a release edits package.json and
- * nothing else). It is sent as the User-Agent (D18: xeno names itself
- * honestly) and compared against npm for update notices.
- *
- * Read at load rather than imported: `bun run check` requires every import to
- * be a literal relative `.ts` path. package.json ships in every install, so
- * this resolves the same way from a checkout and from a global install.
- */
-import { readFileSync } from "node:fs";
-
-export const XENO_VERSION: string = (JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }).version;

package/src/runtime/web-http.ts

@@ -1,56 +0,0 @@
-/** 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

@@ -1,88 +0,0 @@
-/** 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/working-notes.ts

@@ -1,60 +0,0 @@
-/** O.2/O.6: validate annotations against the full projection before they can be appended. */
-import type { LogEvent } from "../core/events.ts";
-import { deriveHandoff } from "../core/derive.ts";
-import { scopedWorkId, workChangeError } from "../core/work-state.ts";
-import { resolveEvidence, type EvidenceResolution } from "../core/evidence.ts";
-import { unknownWorkClaimDiagnostic, unverifiedNoteDiagnostic } from "../core/note-guidance.ts";
-import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
-import type { ToolDiagnostic } from "../core/tool-contract.ts";
-import { replayContext } from "../store/replay.ts";
-import { digestNode, nodePath } from "../store/log.ts";
-import { resolveEvidenceNote } from "./evidence-notes.ts";
-import type { ToolResult } from "./tools.ts";
-
-function rejected(message: string, diagnostic = failureDiagnostic("invalid_input", message, NOT_STARTED)): { out: ToolResult } {
-  return { out: { ok: false, content: message, data: { recorded: false }, diagnostic } };
-}
-function claimResult(annotation: Extract<LogEvent, { t: "claim" }>, proof: EvidenceResolution, openedAt?: string): ToolResult {
-  const diagnostic: ToolDiagnostic | undefined = proof.ok ? undefined : unverifiedNoteDiagnostic(proof, annotation.id, openedAt);
-  return { ok: proof.ok, content: JSON.stringify({ recorded: true, claim_event: annotation.id,
-    verification: proof.ok ? "verified" : "unverified", ...(proof.ok ? { evidence: proof.evidence } : { reason: proof.reason }) }),
-    ...(diagnostic ? { diagnostic } : {}) };
-}
-
-export async function prepareWorkingNote(logDir: string, node: number, namespace: string, annotation: LogEvent | undefined, out: ToolResult): Promise<{ out: ToolResult; annotation?: LogEvent }> {
-  if (!annotation) return { out };
-  if (annotation.t !== "claim" && annotation.t !== "evidence_link" && !("work_id" in annotation && annotation.work_id !== undefined)) return { out, annotation };
-  const replayed = await replayContext(logDir, node);
-  const input = { prev: replayed.fullHandoff, events: replayed.events, depth: replayed.depth,
-    self: { node, log_ref: nodePath(logDir, node), sha256: await digestNode(logDir, node) } };
-  const current = deriveHandoff(input);
-  if (annotation.t === "evidence_link") {
-    const resolved = await resolveEvidenceNote(logDir, node, namespace, current, annotation);
-    return { out: resolved.result, ...(resolved.event ? { annotation: resolved.event } : {}) };
-  }
-  if (annotation.t === "claim" && annotation.work_id === undefined) {
-    return { annotation, out: claimResult(annotation, resolveEvidence(input.events, annotation.evidence)) };
-  }
-  if (!("work_id" in annotation) || annotation.work_id === undefined) throw new Error("missing identified work annotation");
-  const workId = scopedWorkId(namespace, annotation.work_id, current.state.work_items ?? []);
-  annotation = { ...annotation, work_id: workId };
-  const owned = current.state.work_items?.find(item => item.id === workId);
-  if (owned?.owner && owned.owner !== namespace) return rejected(`work ${workId} is owned by ${owned.owner}`);
-  if ((annotation.t === "next_action" || annotation.t === "work_dependencies") && annotation.depends_on !== undefined) annotation = {
-    ...annotation, depends_on: annotation.depends_on.map(id => scopedWorkId(namespace, id, current.state.work_items ?? [])),
-  };
-  if ((annotation.t === "decision" || annotation.t === "pitfall") && !current.state.work_items?.some(item => item.id === workId)) {
-    return rejected(`unknown work_id ${workId}; record a next note first`);
-  }
-  if (!owned && annotation.t === "claim") {
-    const diagnostic = unknownWorkClaimDiagnostic(input.events, annotation);
-    return rejected(diagnostic.message, diagnostic);
-  }
-  const error = workChangeError(current.state.work_items ?? [], annotation);
-  if (error) return rejected(error);
-  const proposed = deriveHandoff({ ...input, events: [...input.events, annotation] });
-  const item = proposed.state.work_items?.find(item => item.id === workId);
-  const claim = annotation.t === "claim" ? claimResult(annotation, resolveEvidence(input.events, annotation.evidence, owned?.opened_at), owned?.opened_at) : undefined;
-  return { annotation, out: { ...claim, ok: annotation.t !== "claim" || item?.verification === "verified",
-    content: JSON.stringify({ recorded: true, work_item: item }) } };
-}