@inhuman.tools/scheme-program 0.0.0-stage → 0.2.0

package/dist/source.js

@@ -0,0 +1,76 @@
+/**
+ * Module `require` jail. Eval with `sourcePath` stays under the entry file's
+ * directory. Interactive `scheme_repl` / `scheme_watch` jail at the workspace
+ * (`host.root`). Skill inputs stay on licensed `read_file`.
+ */
+import { toJS } from "@here.build/arrival";
+import { makeFsLoader } from "@here.build/arrival-modules";
+export function programSourceOf(raw, allow) {
+    if (!allow || raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const rec = raw;
+    const source = typeof rec.source === "string" && rec.source !== "" ? rec.source : undefined;
+    const sourcePath = typeof rec.sourcePath === "string" && rec.sourcePath.trim() !== "" ? rec.sourcePath.trim() : undefined;
+    return { source, sourcePath };
+}
+function parentDir(path) {
+    const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    if (slash <= 0)
+        return slash === 0 ? path.slice(0, 1) : ".";
+    return path.slice(0, slash);
+}
+export function moduleRootOf(sourcePath, override, workspaceRoot) {
+    if (override != null && override !== "")
+        return override;
+    if (sourcePath != null && sourcePath !== "")
+        return parentDir(sourcePath);
+    if (workspaceRoot != null && workspaceRoot !== "")
+        return workspaceRoot;
+    return undefined;
+}
+/** Replay read. The live loader records the same key the first time it touches disk. */
+export function recordedModuleLoader(job) {
+    return makeFsLoader({
+        readFile(key) {
+            const text = job.modules[key];
+            if (text === undefined)
+                throw new Error(`replay: no recorded module ${key}`);
+            return text;
+        },
+    });
+}
+/** toJS of a dict or list is an egress proxy. structuredClone rejects proxies. */
+function plainData(value, seen = new WeakSet()) {
+    if (typeof value === "function")
+        throw new Error("not json");
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        throw new Error("cycle");
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => plainData(item, seen));
+    const out = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string")
+            throw new Error("not json");
+        out[key] = plainData(value[key], seen);
+    }
+    return out;
+}
+/** Objects/arrays become the additive `json` sibling. Scalars stay display-only. */
+export function structuredJson(value) {
+    const js = toJS(value);
+    if (typeof js === "function")
+        return { jsonError: "value is not JSON-compatible" };
+    if (js === null || typeof js !== "object")
+        return {};
+    try {
+        const cloned = structuredClone(plainData(js));
+        return { json: cloned };
+    }
+    catch {
+        return { jsonError: "value is not JSON-compatible" };
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@inhuman.tools/scheme-program",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Scheme program tool. Evaluates one ProgrammaticJob. The host passes the EnvCapabilities; this package does not know the catalog or the tool bodies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./eval": {
+      "types": "./dist/eval.d.ts",
+      "import": "./dist/eval.js",
+      "default": "./dist/eval.js"
+    },
+    "./fs": {
+      "types": "./dist/source-fs.d.ts",
+      "import": "./dist/source-fs.js",
+      "default": "./dist/source-fs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__"
+  ],
+  "dependencies": {
+    "@here.build/arrival": "^0.10.2",
+    "@here.build/arrival-modules": "^0.10.0",
+    "@here.build/arrival-serializer": "^0.10.2",
+    "mobx": "6.16.1",
+    "tiny-invariant": "^1.3.3",
+    "@inhuman.tools/harness-model": "^0.2.0",
+    "@inhuman.tools/substrate": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "9.39.2",
+    "typescript": "6.0.2",
+    "vitest": "4.1.0",
+    "@-internal-/eslint-configs": "0.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/here-build/inhuman-harness.git",
+    "directory": "packages-runtime/scheme-program"
+  },
+  "browserslist": [
+    "last 2 chrome versions",
+    "last 2 firefox versions",
+    "last 2 safari versions",
+    "ios_saf >= 16.4",
+    "node >= 22"
+  ],
+  "author": "Merkle Bonsai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/src/emission.ts

@@ -0,0 +1,82 @@
+/**
+ * Closure windows for one evaluation. The store is discarded: the track is
+ * stamped on the child, and that is the record a replay matches.
+ */
+import type { ExecOptions, SchemeValue } from "@here.build/arrival";
+import { buildWireframe } from "@here.build/arrival/provenance";
+
+export type ProgramEmission = NonNullable<ExecOptions["emission"]>;
+
+const store: ProgramEmission["store"] = {
+  async append() {},
+  async allocateSeq() {
+    return 0;
+  },
+  async readStream() {
+    return [];
+  },
+  async getHeader() {
+    return undefined;
+  },
+  async putHeader() {},
+};
+
+const payloads: ProgramEmission["payloads"] = {
+  async put() {},
+  async get() {
+    throw new Error("program emission does not read payloads");
+  },
+  async settle() {},
+  async evict() {},
+};
+
+/** Verbs that start one track per element. Anything else is a source, so a lambda that calls it is a closure. */
+const FANS = new Set([
+  "map",
+  "for-each",
+  "filter",
+  "filter-map",
+  "partition",
+  "append-map",
+  "fold",
+  "fold-right",
+  "vector-map",
+  "vector-for-each",
+  "string-map",
+  "string-for-each",
+  "pair-for-each",
+]);
+
+const wireframeOptions = {
+  classifier: {
+    roleOf(op: string): "fan" | "source" {
+      return FANS.has(op) ? "fan" : "source";
+    },
+  },
+  isBaseName: (): boolean => false,
+};
+
+export function harnessEmission(forms: readonly SchemeValue[]): ProgramEmission {
+  const closureSites = new Map<object, { readonly templateHash: string; readonly rootOrdinal: number }>();
+  const emission: ProgramEmission = {
+    store,
+    payloads,
+    regionId: "harness",
+    coordinate: { templateHash: "harness", ordinalPath: [0], regionEpoch: "run" },
+    closureSites,
+  };
+  extendEmission(emission, forms);
+  return emission;
+}
+
+/** Same parsed pairs the following `execState` will run. Sites are keyed by pair identity. */
+export function extendEmission(emission: ProgramEmission, forms: readonly SchemeValue[]): void {
+  if (forms.length === 0 || !(emission.closureSites instanceof Map)) return;
+  try {
+    const built = buildWireframe(forms, wireframeOptions).closureSites;
+    if (built === undefined) return;
+    for (const [form, site] of built) emission.closureSites.set(form, site);
+  } catch {
+    // A program the wireframe refuses still runs. Its crossings share the root window.
+  }
+}

package/src/eval.ts

@@ -0,0 +1,20 @@
+export { appendNotify } from "./failure.js";
+export {
+  cancelLiveInvocations,
+  cancelled,
+  displayPrinted,
+  evaluateForms,
+  fail,
+  guardProgram,
+  hostAbortReason,
+  observationText,
+  observed,
+  parked,
+  printedValues,
+  sealChunk,
+  waitPeriod,
+} from "./evaluate.js";
+export { type ProgramHost } from "./host.js";
+export { openProgram } from "./open.js";
+export { programRuntimeOf } from "./runtime.js";
+export { moduleRootOf } from "./source.js";

package/src/evaluate.ts

@@ -0,0 +1,398 @@
+/**
+ * One Arrival evaluation of a ProgrammaticJob. Inner tools parent onto
+ * `job.children`. Wait is Arrival's trampoline. Not catalog execute.
+ */
+import { execState, type LexicalScope, type SchemeValue } from "@here.build/arrival";
+import { createDisplaySink } from "@here.build/arrival/host-internals";
+import { EvalTrace } from "@here.build/arrival/provenance";
+import { AString, AVoid } from "@here.build/arrival/reflect-internals";
+import { toSExprString } from "@here.build/arrival-serializer";
+import {
+  armCrossings,
+  crossingEpoch,
+  markReplaying,
+  CallJob,
+  type ApprovableJob,
+  cancelOutcomeText,
+  isAbortError,
+  isTimeoutAbortReason,
+  MCPToolJob,
+  ProgrammaticJob,
+  cancelUnstarted,
+  rememberJobResult,
+  RESULT_NOTE_CHARS,
+  SCHEME_REPL_NAMING,
+  ToolCallJob,
+} from "@inhuman.tools/harness-model";
+import { isTopLevelDisplay, stripTopLevelDisplay } from "@inhuman.tools/substrate";
+import { importDoor, unboundInExprDoor } from "@inhuman.tools/substrate/doors";
+import { type TopLevelSplice } from "@inhuman.tools/substrate/unwrap-begin";
+import { action } from "mobx";
+
+import { extendEmission, harnessEmission, type ProgramEmission } from "./emission.js";
+import { failureCodeOf } from "./failure.js";
+import { filePathOf } from "./file-path.js";
+import type { ProgramHost, ProgramRuntime } from "./host.js";
+import { SCHEME_REPL_DISPLAY_NOTE, SCHEME_REPL_UNWRAP_NOTES } from "./notes.js";
+import { structuredJson } from "./source.js";
+
+const rejectInner = action((leaf: ApprovableJob, reason?: unknown): void => {
+  cancelUnstarted(leaf, reason);
+  if (leaf instanceof CallJob) return;
+});
+
+const UNBOUND_VARIABLE = /Unbound variable [`']?([^`'\s]+)/;
+
+export type FailResult = { readonly ok: false; readonly text: string; readonly code?: string };
+export type FilePrint = {
+  readonly text: string;
+  readonly face: { readonly kind: "file"; readonly path: string };
+};
+export type PrintedValue = string | FilePrint;
+export type ValueResult = {
+  readonly ok: boolean;
+  readonly value: PrintedValue[];
+  readonly json?: unknown;
+  readonly jsonError?: string;
+};
+export type CallResult = FailResult | ValueResult;
+
+export type EvalOutcome =
+  | {
+      readonly kind: "ok";
+      readonly values: PrintedValue[];
+      readonly json?: unknown;
+      readonly jsonError?: string;
+    }
+  | { readonly kind: "fail"; readonly values: PrintedValue[]; readonly code?: string }
+  | { readonly kind: "halt"; readonly result: FailResult }
+  | { readonly kind: "park" };
+
+export type SharedEval = {
+  scope?: LexicalScope;
+  readonly signal: AbortSignal;
+  emission?: ProgramEmission;
+};
+
+export type EvaluateOpts = {
+  readonly timeoutMs: number | undefined;
+  readonly maxInternalCalls: number | undefined;
+  /** The host's trace for this run. Absent: a period tick mints its own, a one-shot goes untraced. */
+  readonly trace?: EvalTrace;
+} & (
+  | { readonly kind: "once" }
+  | { readonly kind: "period"; readonly tick: { readonly origin: number } }
+  | { readonly kind: "source-load"; readonly shared: SharedEval }
+  | { readonly kind: "source-body"; readonly shared: SharedEval }
+);
+
+export function errorText(error: unknown): string {
+  if (isAbortError(error) && !isTimeoutAbortReason(error)) return "Error: Scheme REPL call cancelled";
+  if (isTimeoutAbortReason(error)) {
+    const text = cancelOutcomeText(error);
+    return text.startsWith("Error:") ? text : `Error: ${text}`;
+  }
+  const raw = error instanceof Error ? error.message : String(error);
+  return raw.startsWith("Error:") ? raw : `Error: ${raw}`;
+}
+
+export function fail(text: string, code?: string): FailResult {
+  return code != null && code !== "" ? { ok: false, text, code } : { ok: false, text };
+}
+
+/** Strings stay raw (display); path-stamped file strings keep a TUI face. */
+export function observationText(value: SchemeValue): PrintedValue {
+  if (typeof value === "string") return value;
+  if (value instanceof AString) {
+    const text = value.valueOf();
+    const path = filePathOf(value);
+    if (path !== undefined && path !== "") return { text, face: { kind: "file", path } };
+    return text;
+  }
+  return toSExprString(value);
+}
+
+export function displayPrinted(value: PrintedValue): string {
+  return typeof value === "string" ? value : value.text;
+}
+
+function isParkAbort(signal: AbortSignal): boolean {
+  return signal.aborted && signal.reason === "park";
+}
+
+function timedOutText(timeoutMs: number | undefined): string {
+  return timeoutMs == null ? "Error: evaluation timed out" : `Error: evaluation timed out after ${timeoutMs}ms`;
+}
+
+function haltResult(signal: AbortSignal, timeoutMs: number | undefined, error?: unknown): FailResult | undefined {
+  if (isParkAbort(signal)) return undefined;
+  if (signal.aborted) {
+    const text = cancelOutcomeText(signal.reason);
+    if (text === "timed out") return fail(timedOutText(timeoutMs));
+    return fail(text === "cancelled" ? "Error: Scheme REPL call cancelled" : `Error: ${text}`);
+  }
+  if (error instanceof Error && /execution budget exceeded/.test(error.message)) {
+    return fail(timedOutText(timeoutMs));
+  }
+  return undefined;
+}
+
+function resultNoteText(result: CallResult): string {
+  if ("text" in result) return result.text;
+  return result.value.map((item) => (typeof item === "string" ? item : item.text)).join(" ");
+}
+
+export function sealChunk(chunk: ProgrammaticJob, result: CallResult): void {
+  if (chunk.completed) return;
+  rememberJobResult(chunk, resultNoteText(result), RESULT_NOTE_CHARS);
+  chunk.outcomeSnap = result;
+  chunk.markComplete();
+}
+
+export function cancelLiveInvocations(job: ProgrammaticJob, host: ProgramHost, reason?: unknown): void {
+  for (const inner of job.children) {
+    if (!(inner instanceof ToolCallJob)) continue;
+    if (inner.completed || inner.cancelled) continue;
+    if (inner instanceof MCPToolJob && inner.dispatched) continue; // on-wire mutation — do not cancel a dispatched call
+
+    if (inner.orchestrated) {
+      host.abort?.(inner, reason);
+      inner.cancelled = true;
+      continue;
+    }
+    rejectInner(inner, reason);
+  }
+}
+
+export function hostAbortReason(host: ProgramHost): unknown {
+  return host.signal?.aborted === true ? host.signal.reason : undefined;
+}
+
+export function parked(host: ProgramHost): boolean {
+  return host.signal != null && isParkAbort(host.signal);
+}
+
+export function cancelled(host: ProgramHost): boolean {
+  return host.signal != null && host.signal.aborted && !isParkAbort(host.signal);
+}
+
+export async function waitPeriod(ms: number, signal?: AbortSignal): Promise<"elapsed" | "park" | "abort"> {
+  if (signal == null) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+    return "elapsed";
+  }
+  const live = signal;
+  if (live.aborted) return isParkAbort(live) ? "park" : "abort";
+  return await new Promise((resolve) => {
+    const timer = setTimeout(() => finish("elapsed"), ms);
+    const onAbort = (): void => finish(isParkAbort(live) ? "park" : "abort");
+    function finish(result: "elapsed" | "park" | "abort"): void {
+      clearTimeout(timer);
+      live.removeEventListener("abort", onAbort);
+      resolve(result);
+    }
+    live.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export function createEvaluationTimeout(
+  hostSignal: AbortSignal | undefined,
+  timeoutMs: number | undefined,
+): { readonly signal: AbortSignal; readonly dispose: () => void } {
+  const controller = new AbortController();
+  const timer =
+    timeoutMs == null
+      ? undefined
+      : setTimeout(() => controller.abort(new Error(`evaluation timed out after ${timeoutMs}ms`)), timeoutMs);
+  const signal =
+    timeoutMs == null
+      ? (hostSignal ?? controller.signal)
+      : hostSignal == null
+        ? controller.signal
+        : AbortSignal.any([hostSignal, controller.signal]);
+  return { signal, dispose: () => clearTimeout(timer) };
+}
+
+function handleEvaluationStop(
+  chunk: ProgrammaticJob,
+  host: ProgramHost,
+  signal: AbortSignal,
+  timeoutMs: number | undefined,
+  error: unknown,
+): Extract<EvalOutcome, { kind: "park" | "halt" }> | undefined {
+  if (parked(host) || isParkAbort(signal)) return { kind: "park" };
+  if (cancelled(host)) {
+    cancelLiveInvocations(chunk, host, hostAbortReason(host));
+    return { kind: "halt", result: fail("Error: Scheme REPL call cancelled") };
+  }
+  const halt = haltResult(signal, timeoutMs, error);
+  if (halt) {
+    cancelLiveInvocations(chunk, host, signal.reason);
+    return { kind: "halt", result: halt };
+  }
+  return undefined;
+}
+
+/** One run under the host's trace, if it keeps one. */
+export function observed<T>(host: ProgramHost, run: (trace: EvalTrace | undefined) => Promise<T>): Promise<T> {
+  return host.observe === undefined ? run(undefined) : host.observe(run);
+}
+
+export async function evaluateForms(
+  chunk: ProgrammaticJob,
+  host: ProgramHost,
+  forms: readonly SchemeValue[],
+  opts: EvaluateOpts,
+  runtime: ProgramRuntime,
+): Promise<EvalOutcome> {
+  const { timeoutMs, maxInternalCalls } = opts;
+  const tick = opts.kind === "period" ? opts.tick : undefined;
+  const shared = opts.kind === "source-load" || opts.kind === "source-body" ? opts.shared : undefined;
+  const loadSource = opts.kind === "source-load";
+  const collectPrintedValues = !loadSource;
+  const tools = host.tools();
+  const capabilities = runtime.capabilities;
+  const config = runtime.config;
+  const stopOnFormError = tick != null || loadSource;
+  // Per tick, not per watch: remint so numeric provenance ids are path-stable across periods.
+  const trace = opts.trace ?? (tick == null ? undefined : new EvalTrace());
+  let timeout: { readonly signal: AbortSignal; readonly dispose: () => void } | undefined;
+  let signal: AbortSignal | undefined = shared?.signal;
+
+  try {
+    // Rooting the prelude is not the program. A short eval limit must not fire during that setup.
+    let scope = shared?.scope;
+    if (scope === undefined) {
+      const setupSignal = shared?.signal ?? host.signal;
+      const rooted = await execState("", {
+        capabilities,
+        config,
+        ...(setupSignal != null ? { signal: setupSignal } : {}),
+      });
+      scope = rooted.scope;
+      if (shared !== undefined) shared.scope = scope;
+    }
+    if (shared == null) {
+      timeout = createEvaluationTimeout(host.signal, timeoutMs);
+      signal = timeout.signal;
+    }
+    const origin = tick?.origin ?? 0;
+    runtime.beginTick({ signal: signal ?? new AbortController().signal, origin, maxInternalCalls });
+    const evaluated = forms.map((raw) => ({ raw, form: stripTopLevelDisplay(raw) }));
+    let emission = shared?.emission;
+    if (emission === undefined) {
+      emission = harnessEmission(evaluated.map((item) => item.form));
+      if (shared !== undefined) shared.emission = emission;
+    } else if (opts.kind === "source-body") {
+      extendEmission(
+        emission,
+        evaluated.map((item) => item.form),
+      );
+    }
+    const epoch = crossingEpoch(chunk, origin);
+    armCrossings(emission, origin, epoch, opts.kind !== "source-body");
+    if (host.replayOnly === true) markReplaying(emission);
+    const started = Date.now();
+    const values: PrintedValue[] = [];
+    const displaySink = createDisplaySink();
+    let lastRaw: SchemeValue | undefined;
+    let failures = 0;
+    let failureCode: string | undefined;
+    for (const item of evaluated) {
+      runtime.clearFailure();
+      const remainingMs = timeoutMs == null ? undefined : timeoutMs - (Date.now() - started);
+      try {
+        const state = await execState(item.form, {
+          capabilities,
+          config,
+          scope,
+          signal,
+          display: displaySink,
+          emission,
+          ...(remainingMs == null ? {} : { budgetMs: remainingMs }),
+          ...(trace == null ? {} : { tap: trace }),
+        });
+        const wasTopLevelDisplay = tick == null && isTopLevelDisplay(item.raw);
+        for (const value of state.values) {
+          if (value instanceof AVoid) continue;
+          lastRaw = value;
+          if (!collectPrintedValues) continue;
+          const printed = observationText(value);
+          values.push(wasTopLevelDisplay ? withDisplayNote(printed) : printed);
+        }
+        for (const rec of displaySink.drain()) {
+          values.push(`#| ${rec.src}:  ${toSExprString(rec.value)} |#`);
+        }
+      } catch (error) {
+        const stopped = signal == null ? undefined : handleEvaluationStop(chunk, host, signal, timeoutMs, error);
+        if (stopped != null) return stopped;
+        const raw = errorText(error).replace(/^Error:\s*/, "");
+        // A failed form leaves its defines unbound. Later "Unbound variable" is the cascade, not a second fault.
+        const attempted = UNBOUND_VARIABLE.exec(raw)?.[1];
+        if (attempted != null && failures > 0) continue;
+        let text = raw.startsWith("Error:") ? raw : `Error: ${raw}`;
+        if (attempted != null) {
+          const door =
+            unboundInExprDoor(
+              attempted,
+              [...tools.keys()],
+              tools,
+              SCHEME_REPL_NAMING,
+              new Map([...tools].map(([name, tool]) => [name, tool.schema])),
+            ) ?? importDoor(attempted);
+          if (door !== undefined) text = `${text}${host.doors.enrichInline(door, attempted)}`;
+        }
+        values.push(text);
+        failures += 1;
+        failureCode ??= failureCodeOf(error) ?? runtime.failureCode();
+        if (stopOnFormError) break;
+      }
+    }
+    if (failures > 0) return { kind: "fail", values, code: failureCode };
+    if (lastRaw === undefined || host.evalProgram !== true) return { kind: "ok", values };
+    return { kind: "ok", values, ...structuredJson(lastRaw) };
+  } catch (error) {
+    const stopped = signal == null ? undefined : handleEvaluationStop(chunk, host, signal, timeoutMs, error);
+    if (stopped != null) return stopped;
+    return { kind: "fail", values: [errorText(error)] };
+  } finally {
+    timeout?.dispose();
+    try {
+      if (opts.trace === undefined) trace?.clear();
+    } catch {
+      /* mid-eval abort — next tick remints */
+    }
+  }
+}
+
+function withDisplayNote(value: PrintedValue): PrintedValue {
+  if (typeof value === "string") return `${SCHEME_REPL_DISPLAY_NOTE}\n${value}`;
+  return { ...value, text: `${SCHEME_REPL_DISPLAY_NOTE}\n${value.text}` };
+}
+
+export function printedValues(values: readonly PrintedValue[], kinds: readonly TopLevelSplice[]): PrintedValue[] {
+  return [...kinds.map((kind) => SCHEME_REPL_UNWRAP_NOTES[kind]), ...values];
+}
+
+export async function guardProgram(
+  chunk: ProgrammaticJob,
+  host: ProgramHost,
+  body: () => Promise<void>,
+): Promise<void> {
+  try {
+    await body();
+  } catch (error) {
+    if (!chunk.completed && !parked(host) && !cancelled(host)) {
+      cancelLiveInvocations(chunk, host, error);
+      sealChunk(chunk, fail(errorText(error)));
+    }
+  } finally {
+    if (!chunk.completed && !parked(host)) {
+      cancelLiveInvocations(chunk, host, hostAbortReason(host));
+      if (cancelled(host)) chunk.cancelled = true;
+      sealChunk(chunk, fail("Error: Scheme REPL call cancelled"));
+    }
+  }
+}

package/src/failure.ts

@@ -0,0 +1,35 @@
+import { AgentCallNotification, type ProgrammaticJob } from "@inhuman.tools/harness-model";
+
+export class SchemeReplToolFailure extends Error {
+  readonly code?: string;
+  constructor(message: string, code?: string) {
+    super(message);
+    this.name = "SchemeReplToolFailure";
+    this.code = code;
+  }
+}
+
+export function failureCodeOf(error: unknown): string | undefined {
+  let current = error;
+  for (let i = 0; i < 6; i++) {
+    if (!(current instanceof Error)) return undefined;
+    if (current instanceof SchemeReplToolFailure && current.code != null && current.code !== "") {
+      return current.code;
+    }
+    current = current.cause;
+  }
+  return undefined;
+}
+
+export function appendNotify(
+  job: ProgrammaticJob,
+  host: { readonly notify?: (note: AgentCallNotification) => void },
+  message: string,
+): void {
+  const note = new AgentCallNotification({ message });
+  if (host.notify != null) {
+    host.notify(note);
+    return;
+  }
+  job.notifications.push(note);
+}