@inhuman.tools/turn 0.1.0 → 0.3.0

package/src/session-runtime/summary.ts

@@ -0,0 +1,67 @@
+import {
+  AskAgentSpec,
+  latestUserPrompt,
+  outgoingAgentRelations,
+  SessionTurn,
+  type AgentNature,
+  type SessionUnfinished,
+  type SessionPlexus,
+  type SessionRoot,
+} from "@inhuman.tools/harness-model/session";
+import { comparer, reaction } from "mobx";
+
+import { glanceAskLine } from "./ask-line.js";
+
+export type SessionSummary = {
+  readonly title: string;
+  readonly recipeScope: AgentNature;
+  readonly specName: string;
+  readonly resident: boolean;
+  readonly keepAlive: boolean;
+  readonly oneShot: boolean;
+  readonly model: string;
+  readonly status: string;
+  readonly midMotion: boolean;
+  readonly openTurn: boolean;
+  readonly openToolCount: number;
+  readonly periodArmed: boolean;
+  readonly openCallbackCount: number;
+  readonly asking: boolean;
+  readonly unfinished: SessionUnfinished;
+  readonly lastPrompt: string;
+  readonly askLine: string;
+  readonly questionLine: string;
+  readonly path: string;
+  readonly calls: ReturnType<typeof outgoingAgentRelations>;
+};
+
+export function sessionSummary(root: SessionRoot): SessionSummary {
+  const spec = root.agent.spec;
+  const unfinished = root.unfinished;
+  return {
+    title: root.title,
+    recipeScope: spec.recipeScope,
+    specName: spec.name,
+    resident: spec.resident,
+    keepAlive: spec.keepAlive,
+    oneShot: spec instanceof AskAgentSpec,
+    model: (root.kvs.model ?? "").trim(),
+    status: root.turnDescription,
+    midMotion: root.midMotion,
+    openTurn: root.openTurn,
+    openToolCount: root.openToolCount,
+    periodArmed: root.periodArmed,
+    openCallbackCount: root.openCallbackCount,
+    asking: root.asking,
+    unfinished,
+    lastPrompt: latestUserPrompt(root.head),
+    askLine: unfinished === "ask" ? glanceAskLine(root.head?.approvalHead ?? null) : "",
+    questionLine: unfinished === "question" && root.head instanceof SessionTurn ? root.head.questionLine : "",
+    path: root.path,
+    calls: outgoingAgentRelations(root),
+  };
+}
+
+export function observeSessionSummary(session: SessionPlexus, publish: (summary: SessionSummary) => void): () => void {
+  return reaction(() => sessionSummary(session.root), publish, { equals: comparer.structural, fireImmediately: true });
+}

package/src/tool-catalog/bindings.ts

@@ -0,0 +1,37 @@
+import invariant from "tiny-invariant";
+
+import type { KernelToolCatalog } from "./catalog.js";
+
+const catalogsByRoot = new WeakMap<object, KernelToolCatalog>();
+const rootsByCatalog = new WeakMap<KernelToolCatalog, Set<object>>();
+
+/** Bind a session (or test) root to a kernel catalog. */
+export function bindSessionCatalog(root: object, catalog: KernelToolCatalog): void {
+  invariant(!catalog.disposed, "bindSessionCatalog: catalog is disposed");
+  const prior = catalogsByRoot.get(root);
+  if (prior != null && prior !== catalog) rootsByCatalog.get(prior)?.delete(root);
+  catalogsByRoot.set(root, catalog);
+  let roots = rootsByCatalog.get(catalog);
+  if (roots == null) {
+    roots = new Set();
+    rootsByCatalog.set(catalog, roots);
+  }
+  roots.add(root);
+}
+
+export function catalogOf(root: object | undefined | null): KernelToolCatalog | undefined {
+  if (root == null) return undefined;
+  const catalog = catalogsByRoot.get(root);
+  if (catalog == null || catalog.disposed) return undefined;
+  return catalog;
+}
+
+export function releaseCatalogRoots(catalog: KernelToolCatalog): void {
+  const roots = rootsByCatalog.get(catalog);
+  if (roots == null) return;
+  for (const root of roots) {
+    if (catalogsByRoot.get(root) === catalog) catalogsByRoot.delete(root);
+  }
+  roots.clear();
+  rootsByCatalog.delete(catalog);
+}

package/src/tool-catalog/catalog.ts

@@ -12,9 +12,12 @@ import { DisposableClass, disposableGuard, prompt, type SystemPrompt } from "@in
 import { action, computed, observable } from "mobx";
 import invariant from "tiny-invariant";
 
+import { releaseCatalogRoots } from "./bindings.js";
 import { type CatalogRecipe, dedupeRecipes, findRecipe, invokeCyclePath } from "./recipes.js";
 import { type CatalogEntry, PLAIN_WORKER_HOST, type WorkerToolHost } from "./types.js";
 
+export { bindSessionCatalog, catalogOf } from "./bindings.js";
+
 export type CompiledPluginContribution = {
   readonly compiledRecipes: readonly CatalogRecipe[];
 };
@@ -224,21 +227,16 @@ export class KernelToolCatalog extends DisposableClass {
     this.behaviorEntries = [];
     this.connectionHost = undefined;
     this.botRevisions = new Map();
-    const roots = rootsByCatalog.get(this);
-    if (roots == null) return;
-    for (const root of roots) {
-      if (catalogsByRoot.get(root) === this) catalogsByRoot.delete(root);
-    }
-    roots.clear();
-    rootsByCatalog.delete(this);
+    releaseCatalogRoots(this);
   }
 }
 
 export function catalogTriggersReactLoop(catalog: KernelToolCatalog, wire: string): boolean {
   const entry = catalog.catalogEntry(wire);
+  if (entry?.continuation != null) return entry.continuation.kind === "observation";
   if (entry?.triggersReactLoop === false) return false;
   if (entry?.triggersReactLoop === true) return true;
-  return entry?.isSideChannel !== true;
+  return true;
 }
 
 export function requireCatalog<T extends KernelToolCatalog>(catalog: T | undefined, what: string): T {
@@ -246,8 +244,6 @@ export function requireCatalog<T extends KernelToolCatalog>(catalog: T | undefin
   return catalog;
 }
 
-const catalogsByRoot = new WeakMap<object, KernelToolCatalog>();
-const rootsByCatalog = new WeakMap<KernelToolCatalog, Set<object>>();
 const behaviorEntriesByRoot = observable.map<object, readonly CatalogEntry[]>(new Map(), { deep: false });
 
 /** Tools the session's pinned behavior declares. Replaced whenever the pin reattaches. */
@@ -259,24 +255,3 @@ export const bindBehaviorEntries = action((root: object, entries: readonly Catal
 export function behaviorEntriesOf(root: object | undefined | null): readonly CatalogEntry[] {
   return root == null ? [] : (behaviorEntriesByRoot.get(root) ?? []);
 }
-
-/** Bind a session (or test) root to a kernel catalog. */
-export function bindSessionCatalog(root: object, catalog: KernelToolCatalog): void {
-  invariant(!catalog.disposed, "bindSessionCatalog: catalog is disposed");
-  const prior = catalogsByRoot.get(root);
-  if (prior != null && prior !== catalog) rootsByCatalog.get(prior)?.delete(root);
-  catalogsByRoot.set(root, catalog);
-  let roots = rootsByCatalog.get(catalog);
-  if (roots == null) {
-    roots = new Set();
-    rootsByCatalog.set(catalog, roots);
-  }
-  roots.add(root);
-}
-
-export function catalogOf(root: object | undefined | null): KernelToolCatalog | undefined {
-  if (root == null) return undefined;
-  const catalog = catalogsByRoot.get(root);
-  if (catalog == null || catalog.disposed) return undefined;
-  return catalog;
-}

package/src/tool-catalog/types.ts

@@ -2,6 +2,8 @@
  * Catalog row identity. wireName is a model-edge projection — never durable
  * routing. Connection tools route by connectionKey + serverToolName.
  */
+import type { ToolContinuation } from "@inhuman.tools/harness-commons";
+
 import type { RuleInput } from "../context/retention/schema.js";
 
 export type CatalogSource =
@@ -23,6 +25,11 @@ export type CatalogExecute = (
     catalog?: unknown;
     onPriorContent?: (text: string | null) => void;
     invocation?: unknown;
+    storage?: {
+      readonly session: unknown;
+      readonly invocation: unknown;
+      propose(action: unknown): void;
+    };
     shellTailBytes?: number;
     onTail?: (frame: { readonly text: string; readonly totalBytes: number }) => void;
   },
@@ -62,6 +69,8 @@ export type CatalogEntry = {
    */
   readonly execute?: CatalogExecute;
   readonly packMeta?: PackToolMeta;
+  readonly continuation?: ToolContinuation;
+  /** @deprecated Use continuation; explicit policy takes precedence. */
   readonly triggersReactLoop?: boolean;
   /** Skips the license floor. Copied from the tool that declared it. */
   readonly isSideChannel?: boolean;

package/src/tool-runtime/approval/approved.ts

@@ -3,7 +3,7 @@
  * in harness-model. Cancel writes `cancelled`, not `approved`. Human
  * `approvalComment` is a `TurnApprovalNoteChunk`, not this receipt.
  */
-import { ApprovableJob, applyToolOutcomeReceipt, cancelUnstarted } from "@inhuman.tools/harness-model";
+import { ApprovableJob, applyToolOutcomeReceipt, cancelUnstarted } from "@inhuman.tools/harness-model/session";
 import { action } from "mobx";
 
 export function stampToolOutcome(leaf: ApprovableJob, text: "denied" | "cancelled", reason?: unknown): void {

package/src/tool-runtime/handler.ts

@@ -2,13 +2,14 @@
  * Project-bound mint of one model tool_call. Does not execute.
  * Connection-sourced names are MCPToolJob; write_file / edit_file are
  * FileMutateToolJob; pack / unknown are SystemToolJob.
- * `agentCallFromWire` mints `agent__ask` / `agent__send`. `admit` wraps it; the turn calls it directly.
+ * `agentCallFromWire` mints `agent__ask` / `agent__send`. `admit` wraps it with frozen policy and retention facts.
  * Both append onto `AdmitContext.parent` when the caller passes one. They do not enqueue.
  * Bot-call pack tools and standing bot invocations mint BotCallJob.
  * `scheme_repl` is a ProgrammaticJob bag. Inner admits reuse this door.
  */
 import { createHash } from "node:crypto";
 
+import type { ToolContinuation } from "@inhuman.tools/harness-commons";
 import {
   AgentCallJob,
   BotCallJob,
@@ -23,8 +24,6 @@ import {
   AGENT_SEND,
   AGENT_VOID,
   CallDelivery,
-  CONTEXT_NEED_TOOL_NAME,
-  ContextNeedToolJob,
   FailureOutcome,
   FileMutateToolJob,
   MCPToolJob,
@@ -50,6 +49,7 @@ import {
 } from "@inhuman.tools/harness-model";
 import { parseJsonRecord } from "@inhuman.tools/harness-model/json-record";
 import type { ToolCall } from "@inhuman.tools/tool-call-normalize";
+import { action } from "mobx";
 
 import { externalizePrior } from "./blob-port.js";
 import { peelAgentCallArgs, requestIdOf } from "./peel.js";
@@ -57,7 +57,12 @@ import { workerToolAllowed } from "./worker-tools.js";
 import { lineStartOfSpan, writeFileAdmitSnap } from "./write-admit.js";
 import { policyOfTurn, stampJobRetention } from "../context/retention/index.js";
 import { peelShellCwd } from "../policy-processor/peel-cwd.js";
-import { agentCallSupportsNotify, type CatalogEntry, type KernelToolCatalog } from "../tool-catalog/index.js";
+import {
+  agentCallSupportsNotify,
+  behaviorEntriesOf,
+  type CatalogEntry,
+  type KernelToolCatalog,
+} from "../tool-catalog/index.js";
 
 /** Catalog face the handler proxies to. A kernel host satisfies this. */
 export type ToolCallKernel = {
@@ -106,12 +111,17 @@ function priorProps(text: string | null): { readonly priorContent?: string; read
 }
 
 function catalogFlags(entry: CatalogEntry | undefined): {
+  readonly continuationJson: string;
   readonly triggersReactLoop: boolean;
   readonly tapeHidden: boolean;
   readonly isSideChannel: boolean;
 } {
+  const continuation: ToolContinuation = entry?.continuation ?? {
+    kind: entry?.triggersReactLoop === false ? "none" : "observation",
+  };
   return {
-    triggersReactLoop: entry?.triggersReactLoop ?? true,
+    continuationJson: JSON.stringify(continuation),
+    triggersReactLoop: continuation.kind === "observation",
     tapeHidden: entry?.tapeHidden ?? false,
     isSideChannel: entry?.isSideChannel === true,
   };
@@ -171,15 +181,15 @@ function admitExam(call: ToolCall, ctx: AdmitContext, entry: CatalogEntry): Prog
     bag.outcomeSnap ??= { ok: true, value: { job_id: bag.toolCallId, background: true } };
   }
   ctx.originTurn?.pushChild(bag);
-  const action = exam.admit(prefix, input);
-  let jobUuid = "";
+  const admittedAction = exam.admit(prefix, input);
+  let jobUuid: string;
   try {
     jobUuid = bag.uuid;
   } catch {
     jobUuid = "";
   }
-  const actionRec = asRecord(action);
-  writePluginMeta(bag, pluginId, actionRec == null ? action : { ...actionRec, jobUuid }, true);
+  const actionRec = asRecord(admittedAction);
+  writePluginMeta(bag, pluginId, actionRec == null ? admittedAction : { ...actionRec, jobUuid }, true);
   return bag;
 }
 
@@ -233,6 +243,11 @@ export function agentCallFromWire(
   if (ctx.session != null && !workerToolAllowed(catalog, ctx.session.agent.spec.name, name, ctx.session)) {
     return appendJob(ctx, ceilingJob(call));
   }
+  const flags = catalogFlags(
+    catalog.catalogEntry(call.function.name) ??
+      catalog.privateWorkerEntries.find((row) => row.wireName === call.function.name) ??
+      behaviorEntriesOf(ctx.session).find((row) => row.wireName === call.function.name),
+  );
   const peeled = peelAgentCallArgs(call.function.arguments);
   const spec = parseJsonRecord(peeled.argsJson)?.spec;
   // Select the explicit child or bot node at admission;
@@ -246,6 +261,7 @@ export function agentCallFromWire(
         argsJson: peeled.argsJson,
         botName: spec.trim(),
         voidLegal: name === AGENT_SEND ? peeled.voidLegal : false,
+        ...flags,
         readonly: peeled.readonly,
         responseSchema: peeled.responseSchema,
         ...stamp(peeled.argsJson),
@@ -260,6 +276,7 @@ export function agentCallFromWire(
       argsJson: peeled.argsJson,
       regenerateable: false,
       voidLegal: name === AGENT_SEND ? peeled.voidLegal : false,
+      ...flags,
       readonly: peeled.readonly,
       responseSchema: peeled.responseSchema,
       constitution: peeled.constitution,
@@ -275,16 +292,26 @@ export function agentCallFromWire(
 export class ToolCallHandler {
   constructor(readonly kernel: ToolCallKernel) {}
 
+  @action
   admit(call: ToolCall, catalog: KernelToolCatalog = this.kernel.catalog, ctx: AdmitContext = {}): AdmittedCall {
-    const job = this.#admit(call, catalog, ctx);
+    const job = this.#admit(call, catalog, { ...ctx, parent: undefined });
     // R2: the horizon is resolved once, here, from the turn's R1 policy and the catalog as it is now.
-    const entry = catalog.catalogEntry(call.function.name) ?? this.kernel.catalog.catalogEntry(call.function.name);
+    const entry =
+      catalog.catalogEntry(call.function.name) ??
+      this.kernel.catalog.catalogEntry(call.function.name) ??
+      catalog.privateWorkerEntries.find((row) => row.wireName === call.function.name) ??
+      behaviorEntriesOf(ctx.session).find((row) => row.wireName === call.function.name);
+    const policy = catalogFlags(entry);
+    job.continuationJson = policy.continuationJson;
+    job.triggersReactLoop = policy.triggersReactLoop;
+    job.isSideChannel = policy.isSideChannel;
+    job.tapeHidden = policy.tapeHidden;
     const turn = ctx.originTurn ?? ctx.session?.head ?? null;
     stampJobRetention(job, policyOfTurn(turn instanceof SessionTurn ? turn : null), {
       ...(entry?.class === undefined ? {} : { entryClass: entry.class }),
       ...(entry?.retention === undefined ? {} : { hint: entry.retention }),
     });
-    return job;
+    return appendJob(ctx, job);
   }
 
   #admit(call: ToolCall, catalog: KernelToolCatalog, ctx: AdmitContext): AdmittedCall {
@@ -302,6 +329,7 @@ export class ToolCallHandler {
         toolName: name,
         toolCallId,
         argsJson,
+        ...catalogFlags(catalog.catalogEntry(name) ?? this.kernel.catalog.catalogEntry(name)),
         ...flagged,
       });
       if (job.background && job.toolCallId.trim() !== "") {
@@ -437,18 +465,6 @@ export class ToolCallHandler {
         }),
       );
     }
-    if (name === CONTEXT_NEED_TOOL_NAME) {
-      return place(
-        new ContextNeedToolJob({
-          toolCallId,
-          name,
-          argsJson,
-          regenerateable: false,
-          ...stamp(argsJson),
-          ...catalogFlags(entry),
-        }),
-      );
-    }
     if (name === WEB_SEARCH_TOOL_NAME) {
       const parsed = parseWebSearchArgs(argsJson);
       return place(

package/src/tool-runtime/run-system-tool.ts

@@ -27,7 +27,6 @@ import { z } from "zod";
 import { externalizePrior } from "./blob-port.js";
 import { runWithExtraRoot } from "./extra-root.js";
 import { pendingPropose, pluginCallContextOf } from "./plugin-context.js";
-import { CONTEXT_RECALL_TOOL_NAME, recallContext } from "./recall.js";
 import { ToolError } from "./tool-error.js";
 import { workerToolAllowed } from "./worker-tools.js";
 import { lineStartOfSpan } from "./write-admit.js";
@@ -39,7 +38,10 @@ function cancelledSnap(signal: AbortSignal): ToolOutcomeSnap {
 
 const TAIL_MS = 50;
 
-function tailPublisher(job: SystemToolJob): {
+function tailPublisher(
+  job: SystemToolJob,
+  canApplyResults: () => boolean,
+): {
   push: (frame: { readonly text: string; readonly totalBytes: number }) => void;
   flush: () => void;
 } {
@@ -47,6 +49,7 @@ function tailPublisher(job: SystemToolJob): {
   let timer: ReturnType<typeof setTimeout> | undefined;
   let latest: { text: string; totalBytes: number } | undefined;
   const send = (frame: { text: string; totalBytes: number }): void => {
+    if (!canApplyResults()) return;
     if (job.receiptJson != null && job.receiptJson !== "") return;
     latest = undefined;
     lastAt = Date.now();
@@ -54,6 +57,7 @@ function tailPublisher(job: SystemToolJob): {
   };
   return {
     push(frame) {
+      if (!canApplyResults()) return;
       const now = Date.now();
       if (now - lastAt >= TAIL_MS) {
         if (timer !== undefined) clearTimeout(timer);
@@ -104,6 +108,7 @@ function asToolResult(out: unknown): ToolOutcomeSnap {
       ok?: unknown;
       text?: unknown;
       value?: unknown;
+      json?: unknown;
       truncated?: unknown;
     };
     if (typeof row.ok === "boolean") {
@@ -111,6 +116,7 @@ function asToolResult(out: unknown): ToolOutcomeSnap {
         ok: row.ok,
         ...(typeof row.text === "string" ? { text: row.text } : {}),
         ...("value" in row ? { value: row.value } : {}),
+        ...("json" in row ? { json: row.json } : {}),
         ...(row.truncated === true ? { truncated: true } : {}),
       };
     }
@@ -133,14 +139,19 @@ export async function executeSystemTool(
   signal: AbortSignal,
   opts?: {
     readonly shellTailBytes?: number;
+    readonly canApplyResults?: () => boolean;
     /** Host list/stop for `job_stop`. The tool body has no job table of its own. */
     readonly stopJob?: (jobId: string) => JobStopReport | Promise<JobStopReport>;
   },
 ): Promise<void> {
+  const canApplyResults = opts?.canApplyResults ?? (() => true);
   const seal = (outcome: ToolOutcomeSnap): void => {
+    if (!canApplyResults()) return;
     sealToolCall(job, outcome);
   };
+  pendingPropose.delete(job);
   try {
+    if (!canApplyResults() || job.outcomeSnap != null) return;
     if (signal.aborted) {
       seal(cancelledSnap(signal));
       return;
@@ -180,11 +191,6 @@ export async function executeSystemTool(
       return;
     }
 
-    if (name === CONTEXT_RECALL_TOOL_NAME) {
-      seal(recallContext(session, args));
-      return;
-    }
-
     if (name === "job_stop") {
       const jobIdRaw = args.job_id;
       const jobId = typeof jobIdRaw === "string" ? jobIdRaw : "";
@@ -203,7 +209,7 @@ export async function executeSystemTool(
     // reads under it (a session read root), so it opens the same door through `licenseAllows`; nothing is remembered
     // from a single outside read.
     const tailBytes = parseShellTailBytes(opts?.shellTailBytes ?? DEFAULT_SHELL_TAIL_BYTES);
-    const live = name === "shell" && tailBytes > 0 ? tailPublisher(job) : undefined;
+    const live = name === "shell" && tailBytes > 0 ? tailPublisher(job, canApplyResults) : undefined;
     let dispatched: unknown;
     try {
       ToolError.invariant(entry?.execute, () =>
@@ -214,13 +220,13 @@ export async function executeSystemTool(
       try {
         dispatched = await runWithExtraRoot(job.licenseAllows, () =>
           entry.execute!(args, {
-            root,
             catalog,
             signal,
             sessionId: session.sessionId,
             onPriorContent:
               job instanceof FileMutateToolJob
                 ? (text) => {
+                    if (!canApplyResults()) return;
                     stampPrior(job, text);
                     if (typeof text === "string" && name === "edit_file") {
                       const old = typeof args.old_string === "string" ? args.old_string : "";
@@ -232,6 +238,7 @@ export async function executeSystemTool(
             shellTailBytes: tailBytes,
             onTail: live?.push,
             ...pluginCallContextOf(session, job, signal, entry.source.kind === "pack" ? entry.source.pluginName : ""),
+            root,
           }),
         );
       } catch (error) {
@@ -246,7 +253,13 @@ export async function executeSystemTool(
     }
     const proposed = pendingPropose.get(job);
     pendingPropose.delete(job);
-    if (proposed != null) {
+    if (!canApplyResults()) return;
+    const outcome = asToolResult(dispatched);
+    if (signal.aborted) {
+      seal(outcome.ok ? cancelledSnap(signal) : outcome);
+      return;
+    }
+    if (proposed != null && outcome.ok) {
       const projection = projectionsOf(job).get(proposed.pluginId);
       if (projection?.hostOnly?.(proposed.action) === true) {
         seal({ ok: false, text: `${proposed.pluginId}: host-only metadata` });
@@ -254,8 +267,9 @@ export async function executeSystemTool(
       }
       writePluginMeta(job, proposed.pluginId, proposed.action, false);
     }
-    seal(asToolResult(dispatched));
+    seal(outcome);
   } catch (error) {
+    if (!canApplyResults()) return;
     if (signal.aborted) {
       seal(cancelledSnap(signal));
       return;
@@ -269,5 +283,7 @@ export async function executeSystemTool(
       return;
     }
     seal({ ok: false, text: `error: ${error instanceof Error ? error.message : String(error)}` });
+  } finally {
+    pendingPropose.delete(job);
   }
 }

package/src/tool-runtime/worker-tools.ts

@@ -15,7 +15,7 @@ import {
   SessionRoot,
 } from "@inhuman.tools/harness-model";
 
-import { behaviorEntriesOf, catalogTriggersReactLoop, type KernelToolCatalog } from "../tool-catalog/index.js";
+import { behaviorEntriesOf, type KernelToolCatalog } from "../tool-catalog/index.js";
 
 function isAgentComms(wire: string): boolean {
   return (
@@ -67,7 +67,7 @@ export function workerToolAllowed(
   if (
     wire === SCHEME_REPL_TOOL_NAME ||
     wire === SCHEME_WATCH_TOOL_NAME ||
-    !catalogTriggersReactLoop(catalog, wire) ||
+    entry.isSideChannel === true ||
     isAgentComms(wire)
   ) {
     return true;