@inhuman.tools/turn 0.0.0-stage → 0.2.0

package/src/agent-calls/runtime.ts

@@ -0,0 +1,310 @@
+/**
+ * Call settlement and reclaim. Worker never Plexus-writes the caller.
+ * `completed` is kernel-only (respond / void / exceptional).
+ *
+ * Child calls reclaim their owned worker after the last callback row. Bot
+ * requests release their callback without reclaiming the bot. Leftovers become
+ * completed+orchestrated rejected even if approved. keepAlive true stretches
+ * the same loop. Two open rows: first respond is not final.
+ */
+import {
+  AgentCallJob,
+  CallJob,
+  AgentCallbackJob,
+  AgentNotifyJob,
+  ApprovableJob,
+  ProgrammaticJob,
+  tapeCompletion,
+  demoteSteers,
+  SessionRoot,
+  SessionTurn,
+  ToolCallJob,
+  FailureOutcome,
+  cancelUnstarted,
+  type CallFailCode,
+  BotCallJob,
+  CompactJob,
+  CompletionJob,
+  ReACTChunk,
+  TurnApprovalNoteChunk,
+  TurnNotificationChunk,
+  TurnPromptChunk,
+  TurnSteerChunk,
+} from "@inhuman.tools/harness-model";
+import { Job, walkWork, WorkExpectation } from "@inhuman.tools/plexus-expectations";
+import { runInAction } from "mobx";
+
+import { shouldSkipTurnCancel } from "./acceptance.js";
+import type { AgentRuntimeHost, CallsCatalog } from "./types.js";
+
+function rejectLeaf(leaf: ApprovableJob, reason?: unknown): void {
+  if (leaf.completed || leaf.cancelled) return;
+  cancelUnstarted(leaf, reason);
+  if (leaf instanceof CallJob) return;
+}
+
+/** Omitted-spec session bit, or this bag's enclosing Call. Not every open Call. */
+export function schemeDeskReadonly(session: SessionRoot, enclosingCall?: CallJob | null): boolean {
+  return session.agent.spec.readonly || enclosingCall?.readonly === true;
+}
+
+/**
+ * Honest host cancel / timeout. Completes the Call, deletes the worker row,
+ * does not fabricate a respond. First-write-wins: a later respond cannot
+ * replace this receipt.
+ */
+export function completeCallExceptionally(
+  call: CallJob,
+  host: AgentRuntimeHost,
+  code: CallFailCode,
+  message = "",
+  abort?: (job: Job) => void,
+): void {
+  call.settleResult(new FailureOutcome({ code, message }));
+  const workerId = call.workerSessionId;
+  if (workerId === "") return;
+  const worker = host.scope.replica(workerId);
+  if (worker == null) return;
+  worker.root.removeAgentCallback(call.uuid);
+  // The request owns its receipt, not the independently managed bot process.
+  if (call instanceof BotCallJob) return;
+  if (!(call instanceof AgentCallJob)) return;
+  forceStopLoop(
+    worker.root,
+    abort ?? (host.scope.abortJob == null ? undefined : (leaf) => host.scope.abortJob?.(workerId, leaf)),
+    undefined,
+    (nested) => completeCallExceptionally(nested, host, "rejected"),
+    host.catalog,
+  );
+}
+
+/**
+ * keepAlive false + last row: leftovers on the originating turn become
+ * `cancelled` + completed with a rejected receipt. `approved` stays —
+ * it is a human write. Abort the turn so ReACT cannot mint further calls.
+ */
+export function forceStopLoop(
+  root: SessionRoot,
+  abort?: (job: Job) => void,
+  except?: ApprovableJob,
+  cancelCall?: (call: CallJob) => void,
+  catalog?: CallsCatalog,
+): void {
+  if (root.agent.spec.keepAlive) return;
+  if (Object.keys(root.agentCallbacks).length > 0) return;
+  // Originating turn for `except`. A closed origin must not stop a successor head.
+  let turn: SessionTurn | null = except == null ? root.findRunningTurn() : null;
+  if (except != null) {
+    for (const live of root.liveTurns) {
+      for (const node of walkWork(live)) {
+        if (node === except) {
+          turn = live;
+          break;
+        }
+      }
+      if (turn != null) break;
+    }
+  }
+  if (turn == null) return;
+  closeTurn(turn, { kind: "forced", except }, { abort, cancelCall, catalog, session: root });
+}
+
+/**
+ * How a turn ends. Every ending closes what is open under the turn; the
+ * cause only says how the leaves are told and what the turn records.
+ *
+ * - `finish`: the reducer returned. Background work outlives the turn.
+ * - `cancel`: the user stopped it (`cancelRequested`). Acks with `cancelled`.
+ * - `broke`: the reducer threw, or a boundary refused. `detail` lands on `turn.broke`.
+ * - `rewound`: the turn left the live chain before or while it ran.
+ * - `forced`: the last Call row of a worker that must not outlive it.
+ */
+export type TurnEnding =
+  | { readonly kind: "finish" }
+  | { readonly kind: "cancel" }
+  | { readonly kind: "broke"; readonly detail: string }
+  | { readonly kind: "rewound" }
+  | { readonly kind: "forced"; readonly except?: ApprovableJob };
+
+export type CloseTurnOptions = {
+  readonly catalog?: CallsCatalog;
+  /** Reclaim a Call's worker before the Call is rejected. */
+  readonly releaseCall?: (call: CallJob) => void;
+  /** Complete a worker Call exceptionally before it is rejected (forced ending). */
+  readonly cancelCall?: (call: CallJob) => void;
+  /** Abort an in-flight body or executor. */
+  readonly abort?: (job: Job) => void;
+  /** End an open expectation through its actor, when it has one. */
+  readonly terminate?: (expectation: WorkExpectation) => void;
+  /**
+   * The session inbox. Passed, the close demotes the steers composed against
+   * this turn, but only while the turn is on the live chain: the close of a
+   * turn that is not touches nothing but itself.
+   */
+  readonly session?: SessionRoot;
+};
+
+/**
+ * THE turn close. The executor's `finally`, a cancel that finds no executor
+ * inside the turn, recovery of a cancelled turn, a forced stop and a rewound
+ * away turn all end a turn here, so the same obligations close in every case:
+ *
+ * 1. the failure, if any, is recorded on the turn (`broke`);
+ * 2. every open Job and expectation under the turn ends (a finish leaves
+ *    them alone: background work outlives the turn);
+ * 3. the cancel ack (`cancelled`) follows a cancel request;
+ * 4. unclaimed steers composed against this turn move to the queue lane (also
+ *    on cancel: Stop does not discard what the user already sent), only for a
+ *    turn on the live chain;
+ * 5. `reducerExited` and `markComplete` last, in the same transaction, so no
+ *    observer sees a closed turn with work still open under it.
+ *
+ * Idempotent: a second close sweeps what is still open and leaves the rest.
+ */
+export function closeTurn(turn: SessionTurn, ending: TurnEnding, options: CloseTurnOptions = {}): void {
+  runInAction(() => {
+    const first = !turn.reducerExited;
+    if (ending.kind === "broke" && turn.broke === "")
+      turn.broke = ending.detail === "" ? "turn stopped" : ending.detail;
+    // A normal finish leaves what is open (background jobs, their attempts) to outlive the turn.
+    for (const node of ending.kind === "finish" ? [] : walkWork(turn)) {
+      if (node instanceof WorkExpectation) {
+        if (!node.isDone) endExpectation(node, options);
+        continue;
+      }
+      if (!(node instanceof Job) || node.completed) continue;
+      if (ending.kind === "forced") {
+        if (node === ending.except) continue;
+        endForced(node, options);
+      } else {
+        endCancelled(node, options);
+      }
+    }
+    const cancelled = ending.kind === "cancel" || turn.cancelRequested;
+    if (cancelled) turn.cancelled = true;
+    const session = options.session;
+    if (first && session != null && session.liveChain.includes(turn)) demoteSteers(session, turn.uuid);
+    turn.reducerExited = true;
+    turn.markComplete();
+    if (ending.kind === "forced" && first) options.abort?.(turn);
+  });
+}
+
+function endExpectation(expectation: WorkExpectation, options: CloseTurnOptions): void {
+  if (options.terminate != null) options.terminate(expectation);
+  if (!expectation.isDone) expectation.fail("cancel", "terminated with the turn", "null");
+}
+
+function endForced(node: Job, options: CloseTurnOptions): void {
+  if (node instanceof AgentCallbackJob || node instanceof AgentNotifyJob) return;
+  if (node instanceof CallJob && node.workerSessionId !== "") {
+    if (shouldSkipTurnCancel(node, options.catalog)) return;
+    options.cancelCall?.(node);
+    options.abort?.(node);
+    node.cancelled = true;
+    node.settleResult(new FailureOutcome({ code: "rejected", message: "rejected" }));
+    return;
+  }
+  if (node instanceof ApprovableJob) {
+    if (node.orchestrated) options.abort?.(node);
+    node.cancelled = true;
+    if (node instanceof CallJob) node.settleResult(new FailureOutcome({ code: "rejected", message: "rejected" }));
+    else if (node instanceof ToolCallJob && (node.receiptJson == null || node.receiptJson === "")) {
+      node.outcomeSnap = { ok: false, text: "rejected" };
+    }
+    node.markComplete();
+    return;
+  }
+  if (node instanceof ProgrammaticJob) {
+    options.abort?.(node);
+    node.outcomeSnap ??= { ok: false, text: "rejected" };
+    node.cancelled = true;
+    node.markComplete();
+  }
+}
+
+function endCancelled(node: Job, options: CloseTurnOptions): void {
+  if (node instanceof CallJob) {
+    if (shouldSkipTurnCancel(node, options.catalog)) return;
+    options.releaseCall?.(node);
+    rejectLeaf(node);
+    if (!node.completed) node.markComplete();
+    return;
+  }
+  if (node instanceof ApprovableJob) {
+    if (node.orchestrated) options.abort?.(node);
+    rejectLeaf(node);
+    if (!node.completed) node.markComplete();
+    return;
+  }
+  if (node instanceof ProgrammaticJob) {
+    if (node.orchestrated) options.abort?.(node);
+    node.outcomeSnap ??= { ok: false, text: "cancelled" };
+    node.cancelled = true;
+    node.markComplete();
+  }
+}
+
+/** Roster names plus live Call worker ids — reattach walks this, not a second index. */
+export function namedWorkerIds(root: SessionRoot): readonly string[] {
+  const ids = new Set<string>(Object.values(root.botsRoster));
+  for (const node of root.motionWork()) {
+    if (node instanceof CallJob && node.workerSessionId !== "") ids.add(node.workerSessionId);
+  }
+  return [...ids];
+}
+
+/** Close a cancelled turn. Does not reclaim the worker. */
+export function settleCancelledTurn(
+  turn: SessionTurn,
+  catalog?: CallsCatalog,
+  releaseCall?: (call: CallJob) => void,
+  session?: SessionRoot,
+): void {
+  closeTurn(turn, { kind: "cancel" }, { catalog, releaseCall, session });
+}
+
+/**
+ * The cell the loop had already shifted is still the live seat: an open
+ * completion or tool, or a loop token still owed a round (`queuedContinuation`).
+ * Claim cells appended behind the token stay claimed.
+ *
+ * A model round the park or a restart interrupted is not replayed: a
+ * CompletionJob is one attempt, and recovery closes it as unknown. The turn
+ * gets a fresh round (a new attempt) unless the user stopped it.
+ */
+export function restorePendingRound(turn: SessionTurn): void {
+  if (turn.reducerExited || !turn.orchestrated || turn.completed) return;
+  let index = turn.doneWork.length - 1;
+  while (index >= 0 && isClaimCell(turn.doneWork[index])) index -= 1;
+  const cell = turn.doneWork[index];
+  if (cell == null || !interrupted(cell, turn)) return;
+  if (cell instanceof CompletionJob && cell.orchestrated) {
+    if (turn.cancelRequested) return;
+    runInAction(() => turn.enqueue(new ReACTChunk()));
+    return;
+  }
+  runInAction(() => {
+    turn.doneWork.splice(index, 1);
+    turn.queue.unshift(cell);
+  });
+}
+
+function isClaimCell(cell: unknown): boolean {
+  return (
+    cell instanceof TurnSteerChunk || cell instanceof TurnNotificationChunk || cell instanceof TurnApprovalNoteChunk
+  );
+}
+
+function interrupted(cell: unknown, turn: SessionTurn): boolean {
+  if (
+    cell instanceof TurnPromptChunk ||
+    (cell instanceof ReACTChunk && !cell.skipped) ||
+    (cell instanceof CompactJob && !cell.completed)
+  ) {
+    return turn.queuedContinuation;
+  }
+  const pew = tapeCompletion(cell);
+  if (pew != null) return !pew.isDone;
+  return (cell instanceof ProgrammaticJob || cell instanceof ToolCallJob) && !cell.completed;
+}

package/src/agent-calls/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Catalog and replica surfaces this package observes.
+ * Creation/activation of sessions stays in runtime composition.
+ */
+import type { SessionRoot } from "@inhuman.tools/harness-model";
+import type { Job } from "@inhuman.tools/plexus-expectations";
+
+import type { CatalogEntry } from "../tool-catalog/index.js";
+
+export type CallsCatalog = {
+  catalogEntry(wireName: string): CatalogEntry | undefined;
+  readonly botRevisions: ReadonlyMap<string, string>;
+  readonly pluginInstall?: {
+    readonly plugins: ReadonlyMap<string, { readonly definition: unknown }>;
+  };
+};
+
+/** Already-acquired session replica. Lookup here must not mint or hydrate. */
+export type AcquiredReplica = {
+  readonly root: SessionRoot;
+  loadEntity(uuid: string): unknown;
+};
+
+export type AgentCallScope = {
+  replica(sessionId: string): AcquiredReplica | undefined;
+  abortJob?(sessionId: string, job: Job): void;
+};
+
+export type AgentRuntimeHost = {
+  readonly caller: SessionRoot;
+  readonly catalog: CallsCatalog;
+  readonly scope: AgentCallScope;
+};

package/src/context/compact-floors.ts

@@ -0,0 +1,76 @@
+/**
+ * Keep floors. The dial is `compactKeepTurns`; a ContextNeed preserve and the
+ * session kv only raise it. Empty is never valid — 0 orphans the in-flight
+ * exchange — so the mode default stands in when nothing is set.
+ */
+import type { CompactJob, ContextNeed } from "@inhuman.tools/harness-model";
+
+/**
+ * Minimum recent rounds kept when the floors are otherwise empty. 0 replaces the
+ * whole eat — the in-flight exchange is orphaned and the model re-does work.
+ * Mid-turn keeps the current round; explicit `/compact` keeps a little more
+ * thread when the user opted in. A config dial >= 1 replaces both.
+ */
+export const DEFAULT_COMPACT_KEEP_TURNS = {
+  midTurn: 1,
+  explicit: 2,
+} as const;
+
+/** Session kv `compact.keep-turns` as a positive integer; 0 when unset or invalid. */
+export function kvKeepTurnsOf(kv: Readonly<Record<string, string>> = {}): number {
+  const raw = kv["compact.keep-turns"] ?? kv[":compact.keep-turns"];
+  const parsed = raw == null ? Number.NaN : Number(raw);
+  return Number.isInteger(parsed) && parsed >= 1 ? parsed : 0;
+}
+
+/**
+ * Record on the job the settings its cut is computed from (F8). Call once, when
+ * the job is minted. After this the job's boundaries come from these stamped
+ * values only: a later change to `compactKeepTurns` or session kv
+ * `compact.keep-turns` moves neither this cutoff nor any earlier one, so a
+ * round is neither lost nor shown twice. The ContextNeed `preserve` widths are
+ * the other input; they are facts on the tape and read from there.
+ */
+export function stampCompactInputs(
+  job: CompactJob,
+  configFloor: number,
+  kv: Readonly<Record<string, string>> = {},
+): void {
+  job.keepTurns = Math.max(Number.isInteger(configFloor) ? configFloor : 1, 1);
+  job.kvKeepTurns = kvKeepTurnsOf(kv);
+}
+
+/**
+ * Floors for a job's cut. A stamped job reads only its own stamps; the live
+ * `kv` and `configFloor` apply to a job that was never stamped.
+ */
+export function keepFloorsOfJob(
+  job: CompactJob,
+  need: ContextNeed | null,
+  live: { readonly kv: Readonly<Record<string, string>>; readonly configFloor: number },
+): { readonly userTurns: number; readonly rounds: number } {
+  if (job.keepTurns == null || job.keepTurns < 1) {
+    return keepFloors(need, live.kv, job.reason === "user", live.configFloor);
+  }
+  const kv: Record<string, string> = job.kvKeepTurns >= 1 ? { "compact.keep-turns": String(job.kvKeepTurns) } : {};
+  return keepFloors(need, kv, job.reason === "user", job.keepTurns);
+}
+
+export function keepFloors(
+  need: ContextNeed | null,
+  kv: Readonly<Record<string, string>> = {},
+  forced = false,
+  configFloor = 0,
+): { readonly userTurns: number; readonly rounds: number } {
+  const raw = kv["compact.keep-turns"] ?? kv[":compact.keep-turns"];
+  const parsed = raw == null ? Number.NaN : Number(raw);
+  const fromKv = Number.isInteger(parsed) && parsed >= 1 ? parsed : 0;
+  const fromConfig = Number.isInteger(configFloor) && configFloor >= 1 ? configFloor : 0;
+  const highest = Math.max(fromKv, fromConfig);
+  const floor =
+    highest > 0 ? highest : forced ? DEFAULT_COMPACT_KEEP_TURNS.explicit : DEFAULT_COMPACT_KEEP_TURNS.midTurn;
+  return {
+    userTurns: Math.max(floor, need?.preserve?.user_turns ?? 0),
+    rounds: Math.max(floor, need?.preserve?.rounds ?? 0),
+  };
+}

package/src/context/compact.ts

@@ -0,0 +1,176 @@
+/**
+ * Compact calculations. The Scheme program that writes the card is session-runtime.
+ *
+ * Occupancy that fires compact is config.json compactTriggers (hard / soft).
+ * Empty eat and compact-on-compact REJECT before a strategy runs.
+ * Keep-all (empty prefix, nonempty keep) skips auto compact, including hard overflow.
+ */
+import {
+  CompactJob,
+  CompletionExpectation,
+  jobTriggersReactLoop,
+  reactChunks,
+  ProgrammaticJob,
+  SessionTurn,
+  ToolCallJob,
+  TurnApprovalNoteChunk,
+  TurnNotificationChunk,
+  TurnSteerChunk,
+  type CompletionMessage,
+  type ContextNeed,
+  type SessionUnit,
+} from "@inhuman.tools/harness-model";
+
+import { Transcript, walkTranscript } from "./transcript.js";
+
+export function compactDue(head: SessionUnit | null, ratio: number | null): boolean {
+  if (head == null || ratio == null || !(ratio > 0)) return false;
+  if (!(head instanceof SessionTurn)) return false;
+  const used = head.contextUsed;
+  const limit = head.contextLimit;
+  if (!(used > 0 && limit > 0)) return false;
+  return used / limit >= ratio;
+}
+
+/** Unknown occupancy is not a deficit. */
+export function needDeficit(turn: SessionTurn, need: ContextNeed | null): boolean {
+  if (need?.min_remaining_tokens == null) return false;
+  const used = turn.contextUsed;
+  const limit = turn.contextLimit;
+  if (!(used > 0 && limit > 0)) return false;
+  const want = Math.min(Math.max(0, need.min_remaining_tokens), limit);
+  return limit - used < want;
+}
+
+/**
+ * Keep floors + requested runway cannot exceed the window.
+ * Card budget is not estimated — keep occupancy is the host retain.
+ */
+export function needFeasible(turn: SessionTurn, need: ContextNeed | null, keepTokens: number): boolean {
+  if (need?.min_remaining_tokens == null) return true;
+  const limit = turn.contextLimit;
+  if (!(limit > 0)) return false;
+  const runway = Math.min(Math.max(0, need.min_remaining_tokens), limit);
+  return keepTokens + runway <= limit;
+}
+
+/**
+ * Forced tail splice. Slash is `#mintCompactTurn`, not this.
+ * Keep-all (empty prefix, nonempty keep) vetoes hard overflow.
+ * Does not read `contextNeed` — a need is an ambient option, not a tail node.
+ * Null = do not enqueue `CompactJob`.
+ */
+export function tailCompactCandidate(
+  turn: SessionTurn,
+  hardRatio: number | null,
+  sliced?: { readonly prefix: Transcript; readonly keep: Transcript },
+): "overflow" | null {
+  if (sliced != null && sliced.prefix.cells.length === 0 && sliced.keep.cells.length > 0) return null;
+  if (!compactDue(turn, hardRatio)) return null;
+  return "overflow";
+}
+
+/**
+ * Ambient option, not a cutoff. A live need with a real prefix is worth a
+ * background completion when the runway is short, the need names a preserve
+ * cutoff, or the phase is settled. Hard overflow is `tailCompactCandidate`.
+ * Null = do not spend a summarizer. Infeasible retain does not block the option.
+ */
+export function compactDecision(
+  turn: SessionTurn,
+  sliced?: { readonly prefix: Transcript; readonly keep: Transcript },
+): { readonly focus: string } | null {
+  if (sliced == null || sliced.prefix.cells.length === 0) return null;
+  const need = turn.contextNeed;
+  if (need == null) return null;
+  if (compactRejectReason(turn) != null) return null;
+  const named = needDeficit(turn, need) || need.preserve != null || need.current_phase_settled === true;
+  if (!named) return null;
+  return { focus: need.focus ?? "" };
+}
+
+export type CompactReject = "empty" | "already-compacted";
+
+export function compactRejectReason(unit: SessionUnit | null, current?: CompactJob): CompactReject | null {
+  if (unit == null) return "empty";
+  const seen = new Set<SessionUnit>();
+  for (
+    let cell: SessionUnit | null = unit;
+    cell != null && !seen.has(cell);
+    cell = cell instanceof SessionTurn ? cell.turnTail : null
+  ) {
+    seen.add(cell);
+    if (!(cell instanceof SessionTurn)) continue;
+    const own = eatSinceCutoff(reactChunks(cell).filter((chunk) => chunk !== current));
+    if (Array.isArray(own)) return null;
+    if (own === "already-compacted") return "already-compacted";
+  }
+  return "empty";
+}
+
+function eatSinceCutoff(chunks: readonly unknown[]): CompletionMessage[] | CompactReject {
+  let sawCutoff = false;
+  let last: CompletionExpectation | null = null;
+  const tools: Array<ToolCallJob | ProgrammaticJob> = [];
+  const notifies: TurnNotificationChunk[] = [];
+  const notes: TurnApprovalNoteChunk[] = [];
+  const steers: TurnSteerChunk[] = [];
+  for (const event of walkTranscript(chunks)) {
+    switch (event.kind) {
+      case "compact": {
+        sawCutoff = true;
+        last = null;
+        tools.length = 0;
+        notifies.length = 0;
+        notes.length = 0;
+        steers.length = 0;
+
+        break;
+      }
+      case "completion": {
+        last = event.chunk;
+        tools.length = 0;
+        notifies.length = 0;
+        notes.length = 0;
+        steers.length = 0;
+
+        break;
+      }
+      case "tool": {
+        if (jobTriggersReactLoop(event.chunk)) tools.push(event.chunk);
+
+        break;
+      }
+      case "scheme": {
+        tools.push(event.chunk);
+
+        break;
+      }
+      case "notify": {
+        notifies.push(event.chunk);
+
+        break;
+      }
+      case "approval-note": {
+        notes.push(event.chunk);
+
+        break;
+      }
+      case "steer": {
+        steers.push(event.chunk);
+
+        break;
+      }
+      case "cell": {
+        break;
+      }
+      default: {
+        const _kind: never = event;
+        void _kind;
+      }
+    }
+  }
+  if (last != null) return [...last.messages, last, ...tools, ...notifies, ...notes, ...steers];
+  if (notifies.length > 0 || notes.length > 0 || steers.length > 0) return [...notifies, ...notes, ...steers];
+  return sawCutoff ? "already-compacted" : "empty";
+}

package/src/context/delivery.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure call-delivery projection for history.
+ * Acceptance, leases, and settlement stay in agent-calls.
+ */
+import type { CatalogEntry } from "../tool-catalog/index.js";
+
+export type DeliveryCatalog = {
+  catalogEntry(wireName: string): CatalogEntry | undefined;
+};
+
+/** Omit / turn catalog visibility. Not a lease or marker. */
+export function usesGenericSilentProjection(call: { readonly name: string }, catalog: DeliveryCatalog): boolean {
+  const meta = catalog.catalogEntry(call.name)?.packMeta;
+  return meta?.kind === "bot-call" && (meta.show === "omit" || meta.show === "turn");
+}