@inhuman.tools/turn 0.2.0 → 0.3.0

package/src/session/commands.ts

@@ -24,8 +24,9 @@ import {
   skillMatchesVerb,
   tapeCompletion,
   userVisualsJson,
+  decideRound,
   type UserVisualIdentity,
-} from "@inhuman.tools/harness-model";
+} from "@inhuman.tools/harness-model/session";
 
 import type { SessionCommandHost } from "./types.js";
 import { compactRejectReason, stampCompactInputs } from "../context/index.js";
@@ -73,10 +74,12 @@ function retentionStamp(host: SessionCommandHost): { readonly retentionJson?: st
 }
 
 function mintContinueTurn(host: SessionCommandHost, head: SessionTurn): void {
+  const continuation = new ReACTChunk();
+  continuation.decision = decideRound([{ cause: { kind: "user", sources: [head.uuid] } }]);
   const turn = new SessionTurn({
     turnTail: head,
     prompt: asUserPrompt(""),
-    queue: [new ReACTChunk()],
+    queue: [continuation],
     toolsDefinition: host.toolsFor(head),
     ...retentionStamp(host),
   });

package/src/session/compact-actor.ts

@@ -9,7 +9,8 @@ import {
   liveJobsCheckIn,
   SessionRoot,
   SessionTurn,
-} from "@inhuman.tools/harness-model";
+} from "@inhuman.tools/harness-model/session";
+import { runInAction } from "mobx";
 
 import { applyCompact } from "./compact-env.js";
 import { loadCompactProgram, type CompactProgram } from "./compact.js";
@@ -22,24 +23,37 @@ import {
   textOfCell,
   Transcript,
 } from "../context/index.js";
+import { parseCompactSnapshot, restoreCompactProgram, snapshotCompactProgram } from "../resources/compact-snapshot.js";
+import { pinModuleLoader } from "../resources/module-bundle.js";
 
 /** Human tape only. Not injected into the next model prompt. */
 const COMPACT_FAILED_NOTICE = "couldn't compact — try again later";
 
-export type CompactHost = {
+type CompactRunHost = {
   readonly turn: SessionTurn;
   readonly session: SessionRoot;
   readonly compactKeepTurns: number;
-  readonly compactStrategy: string;
-  readonly kernelFsRoot: string;
   readonly connectionId: string;
   readonly model: string;
   complete?: PromptComplete;
-  loadProgram?: (spec: string | undefined, kernelFsRoot: string) => CompactProgram;
   log?: (message: string) => void;
   fail?: (label: string, error: unknown) => void;
 };
 
+export type CompactHost = CompactRunHost &
+  (
+    | {
+        readonly program: CompactProgram | Promise<CompactProgram>;
+        checkpoint(job: CompactJob): Promise<void>;
+      }
+    | {
+        readonly compactStrategy: string;
+        readonly kernelFsRoot: string;
+        loadProgram?: (spec: string | undefined, kernelFsRoot: string) => CompactProgram | Promise<CompactProgram>;
+        checkpoint?: (job: CompactJob) => Promise<void>;
+      }
+  );
+
 function compactRead(
   configFloor: number,
   kv: Readonly<Record<string, string>>,
@@ -51,21 +65,56 @@ function compactRead(
 }
 
 function failCompact(job: CompactJob): void {
-  job.failed = true;
-  job.notice = COMPACT_FAILED_NOTICE;
-  job.standIn = "";
-  job.markComplete();
+  runInAction(() => {
+    job.failed = true;
+    job.notice = COMPACT_FAILED_NOTICE;
+    job.standIn = "";
+    job.markComplete();
+  });
 }
 
-function loadStrategy(host: CompactHost): CompactProgram {
+async function loadStrategy(host: CompactHost): Promise<CompactProgram> {
+  if ("program" in host) return host.program;
   return (host.loadProgram ?? loadCompactProgram)(host.compactStrategy, host.kernelFsRoot);
 }
 
+async function prepareStrategy(job: CompactJob, host: CompactHost, signal?: AbortSignal): Promise<CompactProgram> {
+  signal?.throwIfAborted();
+  if (job.resourceSnapshotJson != null && job.resourceSnapshotJson !== "") {
+    const program = restoreCompactProgram(parseCompactSnapshot(job.resourceSnapshotJson));
+    await host.checkpoint?.(job);
+    signal?.throwIfAborted();
+    return program;
+  }
+  const program = await loadStrategy(host);
+  const snapshot = snapshotCompactProgram(program);
+  const persist = async (): Promise<void> => {
+    signal?.throwIfAborted();
+    runInAction(() => {
+      job.resourceSnapshotJson = JSON.stringify(snapshot);
+    });
+    await host.checkpoint?.(job);
+    signal?.throwIfAborted();
+  };
+  await persist();
+  return program.moduleLoader === undefined
+    ? program
+    : {
+        ...program,
+        moduleLoader: pinModuleLoader(program.moduleLoader, async (path, content) => {
+          snapshot.modules[path] = content;
+          await persist();
+        }),
+      };
+}
+
 /** Abort leaves the job open: an incomplete compact is not a cutoff, and its owner settles it. */
 export async function runCompactJob(job: CompactJob, host: CompactHost, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return;
   const rejected = compactRejectReason(host.turn);
   if (rejected != null) {
     host.log?.(`compact ${rejected}`);
+    if (signal?.aborted) return;
     job.markComplete();
     return;
   }
@@ -81,11 +130,13 @@ export async function runCompactJob(job: CompactJob, host: CompactHost, signal?:
     const zones = sliceCompactZones(eat, floors);
     if (zones.prefix.cells.length === 0) {
       host.log?.("compact keep-all");
+      signal?.throwIfAborted();
       job.markComplete();
       return;
     }
     const focus = job.reason === "user" ? host.turn.prompt.trim() || need?.focus || "" : (need?.focus ?? "");
-    const strategy = loadStrategy(host);
+    const strategy = await prepareStrategy(job, host, signal);
+    signal?.throwIfAborted();
     if (strategy.failsafe != null) {
       // Keep-first is a failsafe, not a strategy: it keeps one cell and drops the
       // rest. Say so, or a broken install looks like a working compaction.
@@ -98,18 +149,23 @@ export async function runCompactJob(job: CompactJob, host: CompactHost, signal?:
       kv: session.kvs,
       forced: job.reason === "user",
       sourcePath: strategy.sourcePath,
+      moduleLoader: strategy.moduleLoader,
       job: host.turn,
       complete: host.complete,
       connectionId: host.connectionId === "" ? undefined : host.connectionId,
       completionModel: host.model === "" ? undefined : host.model,
       signal,
     });
+    signal?.throwIfAborted();
     if (!result.ok) {
       host.fail?.("compact strategy", result.reason);
+      signal?.throwIfAborted();
       failCompact(job);
       return;
     }
-    const jobs = liveJobsCheckIn(await liveBackgroundJobs(session.motionWork()));
+    const background = await liveBackgroundJobs(session.motionWork());
+    signal?.throwIfAborted();
+    const jobs = liveJobsCheckIn(background);
     const body = result.checkIn
       .map((cell) => textOfCell(cell).trim())
       .filter((line) => line !== "")
@@ -117,16 +173,20 @@ export async function runCompactJob(job: CompactJob, host: CompactHost, signal?:
     const checkIn = [jobs, body].filter((line) => line !== "").join("\n\n");
     if (checkIn === "") {
       host.fail?.("compact strategy", "empty-check-in");
+      signal?.throwIfAborted();
       failCompact(job);
       return;
     }
-    job.standIn = checkIn;
-    job.failed = false;
-    job.notice = "";
-    job.markComplete();
+    runInAction(() => {
+      job.standIn = checkIn;
+      job.failed = false;
+      job.notice = "";
+      job.markComplete();
+    });
   } catch (error) {
     if (signal?.aborted) return;
     host.fail?.("compact strategy", error);
+    if (signal?.aborted) return;
     failCompact(job);
   }
 }

package/src/session/compact-env.ts

@@ -24,8 +24,6 @@
  * are `pipe` — pure transforms that mint nothing. `transcript/warm?` is the
  * one argument-reader that stays `source`: `isWarm` reads the live clock.
  */
-import { dirname } from "node:path";
-
 import {
   EnvCapability,
   execState,
@@ -36,7 +34,7 @@ import {
   type SchemeValue,
 } from "@here.build/arrival";
 import { applyCallback, is_callable_value } from "@here.build/arrival/host-internals";
-import { arrivalLoaderCapability } from "@here.build/arrival-modules";
+import { arrivalLoaderCapability, type Loader } from "@here.build/arrival-modules";
 import { promptIsolatedCapability, type PromptComplete } from "@inhuman.tools/env-capability-module-prompt";
 import {
   CompactJob,
@@ -48,9 +46,8 @@ import {
   TurnApprovalNoteChunk,
   TurnNotificationChunk,
   TurnSteerChunk,
-} from "@inhuman.tools/harness-model";
+} from "@inhuman.tools/harness-model/session";
 import { Job } from "@inhuman.tools/plexus-expectations";
-import { programSourceLoader } from "@inhuman.tools/scheme-program/fs";
 import invariant from "tiny-invariant";
 import { z } from "zod";
 
@@ -63,6 +60,7 @@ import {
   Transcript,
   type EatCell,
 } from "../context/index.js";
+import { spawnHistoryText } from "../context/spawn-history.js";
 import { charsOf } from "../context/transcript.js";
 
 /** Same door as scheme_repl `load`: last-write-wins over `require`. */
@@ -95,11 +93,10 @@ export type CompactStrategyOpts = {
   readonly plan?: string | null;
   readonly forced?: boolean;
   /**
-   * Absolute path the program source was read from. Enables `(require "…")` —
-   * `.prompt` pretreats ship next to the strategy — jailed under its dirname.
-   * Null for the inline fallback: no `require` surface.
+   * Source label for diagnostics; imports require an explicitly supplied loader.
    */
   readonly sourcePath?: string | null;
+  readonly moduleLoader?: Loader;
   /**
    * Live completion wiring for the summarizer call a `.prompt` performs. The
    * prompt capability admits an agent/ask on this job; absent → the strategy
@@ -316,6 +313,9 @@ export const compactReducerCapability = EnvCapability.define("harness/compact",
                 if (cell instanceof TurnNotificationChunk) return textOfCell(cell);
                 if (cell instanceof TurnApprovalNoteChunk) return `user: ${cell.approvalNoteText()}`;
                 if (cell instanceof TurnSteerChunk) return `user: ${cell.completionMessage}`;
+                const spawnText =
+                  cell instanceof ToolCallJob || cell instanceof ProgrammaticJob ? spawnHistoryText(cell) : null;
+                if (spawnText !== null) return spawnText;
                 if (cell instanceof ToolCallJob) {
                   const scheme = cell.children.find(
                     (child): child is ProgrammaticJob => child instanceof ProgrammaticJob,
@@ -404,32 +404,41 @@ export async function applyCompact(
   fullTranscript: Transcript,
   opts: CompactStrategyOpts = {},
 ): Promise<CompactApplyResult> {
+  opts.signal?.throwIfAborted();
   invariant(program.trim() !== "", "compact strategy program is empty");
   const names = opts.forced === true ? (["forced-compact", "compact"] as const) : (["compact"] as const);
-  // `(require "compact.prompt")` — the threaded-snapshot strategy is a
-  // `.scm` + `.prompt` pair. `require` is a loader symbol, and the loader is
-  // jailed under the strategy file's directory (same rule as scheme_repl:
-  // `programSourceLoader`). Without these the strategy throws
-  // `Unbound variable require` and the compact silently degrades to the fallback.
-  const moduleRoot = opts.sourcePath != null && opts.sourcePath !== "" ? dirname(opts.sourcePath) : undefined;
+  const suppliedLoader = opts.moduleLoader;
+  const loader: Loader | undefined =
+    suppliedLoader === undefined
+      ? undefined
+      : {
+          resolve: (specifier, fromDir) => suppliedLoader.resolve(specifier, fromDir),
+          async read(path) {
+            opts.signal?.throwIfAborted();
+            const content = await suppliedLoader.read(path);
+            opts.signal?.throwIfAborted();
+            return content;
+          },
+          resolvers: suppliedLoader.resolvers,
+        };
   // `require` only needs the loader. The isolated host is assembled when a
   // parent job and a connection exist; without them a stub strategy still
   // loads, and `dotprompt/run` is not a symbol.
   const connectionId = opts.connectionId ?? "";
-  const isolated = moduleRoot != null && opts.job != null && connectionId !== "";
+  const isolated = loader != null && opts.job != null && connectionId !== "";
   const state = await execState(program, {
     capabilities:
-      moduleRoot == null
+      loader == null
         ? [compactReducerCapability]
         : isolated
           ? [compactReducerCapability, promptIsolatedCapability, schemeLoadAliasCapability]
           : [compactReducerCapability, schemeLoadAliasCapability],
     config: {
       ...compactConfig(opts, fullTranscript.cells),
-      ...(moduleRoot == null
+      ...(loader == null
         ? {}
         : {
-            loader: programSourceLoader(moduleRoot),
+            loader,
             dirname: "",
             ...(isolated
               ? {

package/src/session/compact.ts

@@ -13,17 +13,22 @@
  * `failsafe` set tells the caller to log a diagnostic.
  */
 
+import type { Loader } from "@here.build/arrival-modules";
+
+import type { ResourceIdentity } from "../resources/module-bundle.js";
+
 const INLINE_KEEP_FIRST =
   "(define (compact compact-transcript full-transcript) (let ((xs (transcript/cells compact-transcript))) (if (null? xs) xs (list (car xs)))))";
 
 export type CompactProgram = {
   readonly source: string;
   /**
-   * Absolute path the source was read from. `require` (`.prompt` pretreats) is
-   * jailed under its dirname; absent for the inline fallback and a dist stub
-   * that has no `compact.prompt` next to it.
+   * Source label for diagnostics. Local adapters can supply an absolute path;
+   * it never grants module access by itself.
    */
   readonly sourcePath: string | null;
+  readonly resource?: ResourceIdentity;
+  readonly moduleLoader?: Loader;
   /**
    * Set only on the inline keep-first failsafe: why no real program could be
    * loaded. The caller must surface it; a silent failsafe would hide a broken

package/src/session/index.ts

@@ -1,9 +1,14 @@
 export { type SessionCommandHost } from "./types.js";
-export { failLeftoverApprovables, turnLoopStopped } from "./cancel.js";
+export { failLeftoverApprovables, isWorkReachable, turnLoopStopped } from "./cancel.js";
 export { abortParkableWork, dispatchedMcpSettled, liveEvalWork, mcpJobOnWire } from "./park.js";
 export { admitCompact, admitTurn, cancelTurnCommand, drainPromptQueue, retryTurn, rewindTurn } from "./commands.js";
 export { type CompactProgram, type CompactStrategyResolve, loadCompactProgram } from "./compact.js";
-export { applyCompact, compactReducerCapability } from "./compact-env.js";
+export {
+  applyCompact,
+  compactReducerCapability,
+  type CompactApplyResult,
+  type CompactStrategyOpts,
+} from "./compact-env.js";
 export { type CompactHost, runCompactJob } from "./compact-actor.js";
 export {
   CONTEXT_NEED_REMINDER,

package/src/session/park.ts

@@ -3,7 +3,13 @@
  * program / turn handlers do not seal. On-wire MCP and live eval bags hold
  * the wrap until they settle; undispatched MCP is aborted without a receipt.
  */
-import { evalProgramOf, MCPToolJob, McpToolExpectation, SessionRoot, SessionTurn } from "@inhuman.tools/harness-model";
+import {
+  evalProgramOf,
+  MCPToolJob,
+  McpToolExpectation,
+  SessionRoot,
+  SessionTurn,
+} from "@inhuman.tools/harness-model/session";
 import { Job, walkWork } from "@inhuman.tools/plexus-expectations";
 
 import type { ParkWork } from "./types.js";

package/src/session/side-channel-reminder.ts

@@ -34,7 +34,7 @@ import {
   UPDATE_METADATA_TOOL_NAME,
   type SessionUnit,
   type TurnChunk,
-} from "@inhuman.tools/harness-model";
+} from "@inhuman.tools/harness-model/session";
 
 /** Quiet sealed session rounds before the armed round carries the nag. */
 export const SIDE_CHANNEL_REMINDER_EVERY = 5;

package/src/session/types.ts

@@ -10,7 +10,7 @@ import type {
   SessionSystemPrompt,
   SessionTurn,
   SkillSpec,
-} from "@inhuman.tools/harness-model";
+} from "@inhuman.tools/harness-model/session";
 import type { Job, WorkExpectation } from "@inhuman.tools/plexus-expectations";
 
 export type SessionCommandHost = {

package/src/session-runtime/ask-line.ts

@@ -0,0 +1,39 @@
+/**
+ * Glance-sized sitting-ask question. Family + optional description.
+ * Not pretty-mcp interpolation — command/path stay off KernelRoot.
+ */
+import {
+  AgentMessageJob,
+  type ApprovableJob,
+  BotCallJob,
+  CallJob,
+  clampChars,
+  flattenOverviewLine,
+  GLANCE_ASK_DESCRIPTION_MAX_CHARS,
+  GLANCE_ASK_LINE_MAX_CHARS,
+  MCPToolJob,
+  ToolCallJob,
+} from "@inhuman.tools/harness-model/session";
+
+export function glanceAskLine(head: ApprovableJob | null): string {
+  if (head == null) return "";
+  if (!(head instanceof ToolCallJob)) return "";
+  const args = head.args;
+  const description =
+    args != null && typeof args.description === "string"
+      ? flattenOverviewLine(args.description, GLANCE_ASK_DESCRIPTION_MAX_CHARS)
+      : "";
+  if (description !== "") return clampChars(`approve ${description}?`, GLANCE_ASK_LINE_MAX_CHARS);
+  if (head instanceof BotCallJob) return "confirm bot?";
+  if (head instanceof CallJob || head instanceof AgentMessageJob) return "confirm agent?";
+  if (head instanceof MCPToolJob) {
+    const tool = head.serverToolName.trim() || head.name.trim();
+    return tool === "" ? "" : clampChars(`confirm ${tool}?`, GLANCE_ASK_LINE_MAX_CHARS);
+  }
+  const name = head.name.trim();
+  if (name === "shell") return "confirm shell command?";
+  if (name === "edit_file") return "confirm edit?";
+  if (name === "write_file") return "confirm write?";
+  if (name === "") return "";
+  return clampChars(`confirm ${name}?`, GLANCE_ASK_LINE_MAX_CHARS);
+}

package/src/session-runtime/durability.ts

@@ -0,0 +1,41 @@
+export type SessionCheckpoint = {
+  readonly sessionId: string;
+  readonly incarnation: string;
+  readonly revision: number;
+  readonly state: Uint8Array;
+};
+
+export type SessionReceipt = {
+  readonly sessionId: string;
+  readonly incarnation: string;
+  readonly revision: number;
+};
+
+export type SessionDurability =
+  | { readonly kind: "memory" }
+  | {
+      readonly kind: "durable";
+      commit(checkpoint: SessionCheckpoint): Promise<SessionReceipt>;
+    };
+
+export function receiptCovers(receipt: SessionReceipt, checkpoint: SessionCheckpoint): boolean {
+  return (
+    receipt.sessionId === checkpoint.sessionId &&
+    receipt.incarnation === checkpoint.incarnation &&
+    receipt.revision >= checkpoint.revision
+  );
+}
+
+export class SessionPersistenceError extends Error {
+  constructor(message = "session checkpoint was not durably acknowledged") {
+    super(message);
+    this.name = "SessionPersistenceError";
+  }
+}
+
+export class SessionOwnershipError extends Error {
+  constructor(message = "session execution no longer owns this document") {
+    super(message);
+    this.name = "SessionOwnershipError";
+  }
+}

package/src/session-runtime/effects.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+export type SessionEffectRequest = {
+  readonly sessionId: string;
+  readonly operationId: string;
+  readonly incarnation: string;
+  readonly method: string;
+  readonly payload: string;
+};
+
+export const sessionEffectOutcomeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("success"), payload: z.string() }),
+  z.object({ kind: z.literal("refused"), message: z.string() }),
+  z.object({ kind: z.literal("unknown"), message: z.string() }),
+]);
+
+export type SessionEffectOutcome = z.infer<typeof sessionEffectOutcomeSchema>;
+
+export type SessionEffectPort = {
+  invoke(request: SessionEffectRequest, signal: AbortSignal): Promise<SessionEffectOutcome>;
+  reconcile?(request: SessionEffectRequest, signal: AbortSignal): Promise<SessionEffectOutcome>;
+};
+
+const requestSchema = z.object({
+  sessionId: z.string(),
+  operationId: z.string(),
+  incarnation: z.string(),
+  method: z.string(),
+  payload: z.string(),
+});
+
+export const effectRecordSchema = z.discriminatedUnion("phase", [
+  z.object({ phase: z.literal("intent"), request: requestSchema }),
+  z.object({ phase: z.literal("result"), request: requestSchema, outcome: sessionEffectOutcomeSchema }),
+]);

package/src/session-runtime/index.ts

@@ -0,0 +1,19 @@
+export { SessionRuntime, type SessionRecoveryPolicy } from "./runtime.js";
+export {
+  receiptCovers,
+  SessionOwnershipError,
+  SessionPersistenceError,
+  type SessionCheckpoint,
+  type SessionDurability,
+  type SessionReceipt,
+} from "./durability.js";
+export {
+  sessionEffectOutcomeSchema,
+  type SessionEffectOutcome,
+  type SessionEffectPort,
+  type SessionEffectRequest,
+} from "./effects.js";
+export { recoverSessionJobs, type JobRecoveryOptions, type RecoveredJob } from "./recovery.js";
+export { interruptSession } from "./interrupt.js";
+export { sessionSummary, observeSessionSummary, type SessionSummary } from "./summary.js";
+export { glanceAskLine } from "./ask-line.js";

package/src/session-runtime/interrupt.ts

@@ -0,0 +1,34 @@
+import {
+  CallJob,
+  CompactJob,
+  CompletionJob,
+  ProgrammaticJob,
+  ToolCallJob,
+  type SessionRoot,
+} from "@inhuman.tools/harness-model/session";
+import { WorkExpectation, walkWork } from "@inhuman.tools/plexus-expectations";
+import { runInAction } from "mobx";
+
+export function interruptSession(root: SessionRoot, message: string): void {
+  runInAction(() => {
+    for (const turn of root.liveTurns) {
+      if (turn.reducerExited) continue;
+      for (const node of walkWork(turn)) {
+        if (node instanceof CallJob) continue;
+        if (node instanceof WorkExpectation && !node.isDone) node.fail("cancel", message, "null");
+        if ((node instanceof ToolCallJob || node instanceof ProgrammaticJob) && !node.completed) {
+          node.outcomeSnap ??= { ok: false, text: message };
+          node.markComplete();
+        } else if (node instanceof CompactJob && !node.completed) {
+          node.failed = true;
+          node.notice = message;
+          node.markComplete();
+        } else if (node instanceof CompletionJob && !node.completed) node.markComplete();
+      }
+      turn.cancelRequested = true;
+      turn.broke = message;
+      turn.reducerExited = true;
+      turn.markComplete();
+    }
+  });
+}