@inhuman.tools/turn 0.0.0-stage → 0.1.0

package/src/tool-catalog/recipes.ts

@@ -0,0 +1,154 @@
+/**
+ * Bot recipes. Standing bots go through `bot/send` / `bot/ask` —
+ * not per-recipe catalog rows. No execute bodies.
+ */
+import { asSystemPrompt } from "@inhuman.tools/harness-commons";
+import { AGENT_ASK, AGENT_SEND, BotSpec, type RecipeScope, type ReasoningEffort } from "@inhuman.tools/harness-model";
+
+import { CallsCatalog } from "../agent-calls/types.js";
+
+export type { RecipeScope } from "@inhuman.tools/harness-model";
+
+export type RecipeCapability = {
+  readonly name: string;
+  readonly description?: string;
+  readonly supportsNotify?: boolean;
+};
+
+export type CatalogRecipe = {
+  readonly spec: BotSpec;
+  readonly category: "plugin" | "internal";
+  readonly capabilities: readonly RecipeCapability[];
+};
+
+export function catalogRecipe(init: {
+  readonly name: string;
+  readonly category: CatalogRecipe["category"];
+  readonly recipeScope?: RecipeScope;
+  readonly keepAlive?: boolean;
+  readonly description?: string;
+  readonly instructions?: string;
+  readonly tools?: readonly string[];
+  readonly invokes?: readonly string[];
+  readonly reasoningEffort?: ReasoningEffort;
+  readonly modelPreferences?: readonly string[];
+  readonly skills?: readonly string[];
+  readonly capabilities?: readonly RecipeCapability[];
+}): CatalogRecipe {
+  return {
+    spec: new BotSpec({
+      name: init.name,
+      recipeScope: init.recipeScope ?? "session",
+      keepAlive: init.keepAlive === true,
+      description: init.description ?? "",
+      instructions: asSystemPrompt(init.instructions ?? ""),
+      tools: init.tools ? [...init.tools] : [],
+      invokes: init.invokes ? [...init.invokes] : [],
+      reasoningEffort: init.reasoningEffort ?? null,
+      modelPreferences: init.modelPreferences ? [...init.modelPreferences] : [],
+      skills: init.skills ? [...init.skills] : [],
+    }),
+    category: init.category,
+    capabilities: init.capabilities ?? [],
+  };
+}
+
+export function findRecipe(recipes: readonly CatalogRecipe[], name: string): CatalogRecipe | undefined {
+  return recipes.find((recipe) => recipe.spec.name === name);
+}
+
+export function agentCallSupportsNotify(catalog: CallsCatalog, callName: string): boolean {
+  if (callName === AGENT_SEND || callName === AGENT_ASK) return true;
+  const entry = catalog.catalogEntry(callName);
+  if (entry?.packMeta?.kind === "bot-call") {
+    return entry.packMeta.supportsNotify === true;
+  }
+  return false;
+}
+
+/** Foreground (no recipe name) may invoke any known recipe. A worker may only invoke declared edges. */
+export function invokeDenied(
+  recipes: readonly CatalogRecipe[],
+  invokerName: string,
+  targetName: string,
+): string | undefined {
+  if (invokerName === "") return undefined;
+  const invoker = findRecipe(recipes, invokerName);
+  if (invoker == null) return `unknown invoker recipe ${invokerName}`;
+  if (!invoker.spec.invokes.includes(targetName)) return `${invokerName} cannot invoke ${targetName}`;
+  if (edgeCreatesCycle(recipes, invokerName, targetName)) return `invoke cycle ${invokerName} → ${targetName}`;
+  return undefined;
+}
+
+/** First cycle path (including return to the start), or null if the DAG is sound. */
+export function invokeCyclePath(recipes: readonly CatalogRecipe[]): readonly string[] | null {
+  const edges = new Map(recipes.map((recipe) => [recipe.spec.name, recipe.spec.invokes]));
+  const names = new Set(recipes.map((recipe) => recipe.spec.name));
+  const visiting = new Set<string>();
+  const seen = new Set<string>();
+  const stack: string[] = [];
+
+  const visit = (node: string): readonly string[] | null => {
+    if (visiting.has(node)) {
+      const at = stack.indexOf(node);
+      return at === -1 ? [node, node] : [...stack.slice(at), node];
+    }
+    if (seen.has(node)) return null;
+    visiting.add(node);
+    stack.push(node);
+    for (const next of edges.get(node) ?? []) {
+      if (!names.has(next)) continue;
+      const cycle = visit(next);
+      if (cycle != null) return cycle;
+    }
+    stack.pop();
+    visiting.delete(node);
+    seen.add(node);
+    return null;
+  };
+
+  for (const name of names) {
+    const cycle = visit(name);
+    if (cycle != null) return cycle;
+  }
+  return null;
+}
+
+export function edgeCreatesCycle(recipes: readonly CatalogRecipe[], from: string, to: string): boolean {
+  if (from === to) return true;
+  return (
+    invokeCyclePath(
+      recipes.map((recipe) => {
+        if (recipe.spec.name !== from) return recipe;
+        const spec = recipe.spec;
+        return {
+          ...recipe,
+          spec: new BotSpec({
+            name: spec.name,
+            description: spec.description,
+            recipeScope: spec.recipeScope,
+            keepAlive: spec.keepAlive,
+            instructions: spec.instructions,
+            tools: [...spec.tools],
+            invokes: [...spec.invokes, to],
+            reasoningEffort: spec.reasoningEffort,
+            skills: [...spec.skills],
+            modelPreferences: [...spec.modelPreferences],
+            error: spec.error,
+          }),
+        };
+      }),
+    ) != null
+  );
+}
+
+export function dedupeRecipes(recipes: readonly CatalogRecipe[]): CatalogRecipe[] {
+  const seen = new Set<string>();
+  const out: CatalogRecipe[] = [];
+  for (const recipe of recipes) {
+    if (seen.has(recipe.spec.name)) continue;
+    seen.add(recipe.spec.name);
+    out.push(recipe);
+  }
+  return out;
+}

package/src/tool-catalog/types.ts

@@ -0,0 +1,110 @@
+/**
+ * Catalog row identity. wireName is a model-edge projection — never durable
+ * routing. Connection tools route by connectionKey + serverToolName.
+ */
+import type { RuleInput } from "../context/retention/schema.js";
+
+export type CatalogSource =
+  | { readonly kind: "pack"; readonly pluginName: string }
+  | {
+      readonly kind: "connection";
+      /** Kernel `connections` map key (slug). Lawful cross-doc pointer to ConnectionSpec. */
+      readonly connectionKey: string;
+      readonly serverToolName: string;
+    };
+
+export type CatalogExecute = (
+  raw: unknown,
+  ctx: {
+    root?: string;
+    signal?: AbortSignal;
+    sessionId?: string;
+    background?: unknown;
+    catalog?: unknown;
+    onPriorContent?: (text: string | null) => void;
+    invocation?: unknown;
+    shellTailBytes?: number;
+    onTail?: (frame: { readonly text: string; readonly totalBytes: number }) => void;
+  },
+) => Promise<unknown>;
+
+/** `tool` is completions tools[]. `symbol` is a scheme_repl name. `both` is both. */
+export type ToolRepresentation = "tool" | "symbol" | "both";
+
+export type PackToolMeta =
+  | { readonly kind: "function" }
+  | {
+      readonly kind: "bot-call";
+      readonly pluginName: string;
+      readonly target: string;
+      readonly background: boolean;
+      readonly lifetime: "turn" | "call";
+      readonly show: "result" | "omit" | "turn";
+      readonly deadlineMs?: number;
+      readonly supportsNotify: boolean;
+    };
+
+export type CatalogEntry = {
+  readonly wireName: string;
+  readonly description: string;
+  readonly parameters: Record<string, unknown>;
+  /** Catalog class: `read` | `write` | `effect` | `meta`. Missing / unknown → `effect`. */
+  readonly class: string;
+  /**
+   * Model face. Omitted is a scheme symbol and stays off completions tools[].
+   * Native tools set this on `InhumanTool`; the catalog row copies it.
+   */
+  readonly representation?: ToolRepresentation;
+  readonly source: CatalogSource;
+  /**
+   * Pack / host plugins carry execute (InhumanTool.execute).
+   * Connection tools are projection-only — BODY is MCP PEW on the connection.
+   */
+  readonly execute?: CatalogExecute;
+  readonly packMeta?: PackToolMeta;
+  readonly triggersReactLoop?: boolean;
+  /** Skips the license floor. Copied from the tool that declared it. */
+  readonly isSideChannel?: boolean;
+  readonly tapeHidden?: boolean;
+  /**
+   * Self-declared retention hint (e.g. ephemeral output). Narrowing only, and
+   * only for this tool's own key: it can shorten what the policy says, never lengthen it.
+   */
+  readonly retention?: RuleInput;
+  /** Mustache the TUI paints while the call is open, after it seals, and as a caption. */
+  readonly question?: string | null;
+  readonly effect?: string | null;
+  readonly caption?: string | null;
+  /**
+   * Exam admit bag. Structural so this package does not import plugin-sdk.
+   * Plugin ExamAdmit is assignable.
+   */
+  readonly exam?: {
+    readonly program: (state: any, input: any) => string | { readonly error: string };
+    readonly admit: (state: any, input: any) => any;
+    readonly settle?: (state: any, input: any, result: any) => any;
+  };
+};
+
+/** What a recipe needs to grant a wire beyond its plain tool list. */
+export type RecipeGrantSpec = {
+  readonly recipeScope: "session" | "project" | "global";
+  readonly mcpJson: string;
+  readonly tools: readonly string[];
+};
+
+/**
+ * Host-owned parts of the worker tool ceiling (bot-granted MCP, private plugin MCP). The ceiling
+ * itself lives in one place, `workerToolAllowed`; the host only answers these two questions.
+ */
+export type WorkerToolHost = {
+  /** Does the recipe grant this wire through its tool list or its `mcpJson` grants? */
+  readonly recipeGrantsWire: (catalog: object, spec: RecipeGrantSpec, wire: string, projectPath: string) => boolean;
+  /** Is this wire one of the recipe's private plugin MCP tools, not (yet) in the catalog view? */
+  readonly privateWireAllowed: (recipeName: string, wire: string, sessionRoot: object | undefined) => boolean;
+};
+
+export const PLAIN_WORKER_HOST: WorkerToolHost = {
+  recipeGrantsWire: (_catalog, spec, wire) => spec.tools.includes(wire),
+  privateWireAllowed: () => false,
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Cancel and generic outcome stamps on the leaf. Payload construction lives
+ * 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 { action } from "mobx";
+
+export function stampToolOutcome(leaf: ApprovableJob, text: "denied" | "cancelled", reason?: unknown): void {
+  applyToolOutcomeReceipt(leaf, text, reason);
+}
+
+/**
+ * Unstarted (or allow-side but not yet BODY) cancel. Does not write
+ * `approved` or `orchestrationResult`.
+ */
+export const cancelUnstartedTool = action((leaf: ApprovableJob, reason?: unknown): void => {
+  if (leaf.completed || leaf.cancelled) return;
+  cancelUnstarted(leaf, reason);
+});

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

@@ -0,0 +1,29 @@
+/**
+ * Dist `policy.json` is the never-throwing program in policy-processor.
+ * `{kernelFsRoot}/policy.json` wins when present and non-empty.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { reasonableDefaultsSource } from "@inhuman.tools/policy/floor";
+
+export function distPolicySource(): string {
+  return reasonableDefaultsSource;
+}
+
+function readOperatorPolicySource(kernelFsRoot: string): string | undefined {
+  try {
+    const user = readFileSync(join(kernelFsRoot, "policy.json"), "utf8");
+    if (user.trim() !== "") return user;
+  } catch {
+    /* missing operator policy is dist */
+  }
+  return undefined;
+}
+
+/**
+ * Body of the one policy program. Never throws. Missing operator → dist.
+ */
+export function loadPolicySource(kernelFsRoot: string): string | undefined {
+  return readOperatorPolicySource(kernelFsRoot) ?? distPolicySource();
+}

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

@@ -0,0 +1,50 @@
+/**
+ * LICENSE WHEN is the Approvable guard. Sequences typically return true;
+ * inbound Turn waits predecessors without returning false (false is deny).
+ */
+import { FieldAwareness } from "@here.build/plexus";
+import {
+  ApprovableJob,
+  applyDenyReceipt,
+  SessionTurn,
+  type PermissionMode,
+  type SessionPlexus,
+} from "@inhuman.tools/harness-model";
+import { when } from "mobx";
+
+function inboundPredecessorClosed(turn: SessionTurn): boolean {
+  if (!turn.inbound) return true;
+  const seen = new Set<SessionTurn>([turn]);
+  let prior = turn.turnTail;
+  while (prior instanceof SessionTurn && !seen.has(prior)) {
+    seen.add(prior);
+    if (!prior.reducerExited) return false;
+    if (!prior.inbound) break;
+    prior = prior.turnTail;
+  }
+  return true;
+}
+
+/** Sequence guard: wait, then true. Never false — that would deny BODY. */
+export function inboundTurnGuard(turn: SessionTurn): boolean | Promise<true> {
+  if (inboundPredecessorClosed(turn)) return true;
+  return (async () => {
+    await when(() => inboundPredecessorClosed(turn) || turn.cancelled || turn.completed);
+    return true as const;
+  })();
+}
+
+export function publishPolicyError(session: SessionPlexus, text: string | null): void {
+  try {
+    const lane = new FieldAwareness(session.awareness, "policyError");
+    if (text == null || text === "") lane.clear();
+    else lane.set(text);
+  } catch {
+    /* presence must not block the floor vote */
+  }
+}
+
+/** Floor produce is policy-processor `license`. `_policy` is unused — writing it would fork the receipt. */
+export function stampLicenseDeny(leaf: ApprovableJob, _policy: PermissionMode): void {
+  applyDenyReceipt(leaf);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Unattended coded receipts. Residual ask under auto is the judge, not
+ * `policy_denied`. Operator throw is awareness + dist, not `policy_error`.
+ */
+import { isEvalPermissionMode, type EvalFailureCode, type EvalPermissionMode } from "@inhuman.tools/harness-model";
+
+export function resolveEvalPermissionMode(policy: string): EvalPermissionMode | null {
+  return isEvalPermissionMode(policy) ? policy : null;
+}
+
+export function unattendedFailureText(code: EvalFailureCode, policyId: string, reason?: string): string {
+  switch (code) {
+    case "interaction_required":
+      return `Operation requires human authorization under policy ${policyId}`;
+    case "policy_denied":
+      return `Operation denied under policy ${policyId}`;
+    case "policy_error":
+      return reason != null && reason !== ""
+        ? `Policy evaluation failed under policy ${policyId}: ${reason}`
+        : `Policy evaluation failed under policy ${policyId}`;
+    case "policy_unavailable":
+      return `Policy ${policyId} is not available`;
+  }
+}

package/src/tool-runtime/blob-port.ts

@@ -0,0 +1,64 @@
+/**
+ * Write seam for blobs that leave the session document. The kernel's bucket
+ * belongs to the daemon; the places that stamp a large text (a file's prior,
+ * an isolated completion's prompt, the vacuum of a stored session) put through
+ * here and never import the store. Reads go the other way, through
+ * `readBlob` in harness-provider-sdk.
+ */
+import { blobHeadOf, exceedsInlineMax, storedBlobJson, type BlobRef } from "@inhuman.tools/harness-model";
+
+/** Synchronous because the stamping paths are: admit mints a job in one tick. */
+export type BlobWriter = (bytes: Uint8Array, mime: string) => BlobRef;
+
+/** What a `FileMutateToolJob` takes for its prior text: the text itself, or the reference to it. */
+export type PriorProps = { readonly priorContent: string } | { readonly priorBlobJson: string };
+
+/**
+ * What {@link externalizeText} decided for a text. `inline` is the text itself. `blob` carries what the
+ * document keeps instead: the head for the text field, and the reference (a `StoredBlob` as JSON) for the
+ * `*BlobJson` field beside it.
+ */
+export type TextStamp =
+  | { readonly kind: "inline"; readonly text: string }
+  | { readonly kind: "blob"; readonly head: string; readonly blobJson: string };
+
+const TEXT_MIME = "text/plain";
+
+let writer: BlobWriter | null = null;
+
+/** The host that owns the bucket binds it once at boot. `null` unbinds. */
+export function bindBlobWriter(write: BlobWriter | null): void {
+  writer = write;
+}
+
+/**
+ * Puts bytes through the bound writer and returns the reference. Throws while no writer is bound and when the
+ * bucket refuses. For a path that has no inline fallback (the vacuum moves text that is already in the
+ * document; a refused put must stop it, not pass silently). The stamping paths use {@link externalizeText}.
+ */
+export function writeBlob(bytes: Uint8Array, mime: string): BlobRef {
+  if (writer === null) throw new Error("no blob writer is bound");
+  return writer(bytes, mime);
+}
+
+/**
+ * Text within the inline limit stays inline. Larger text goes to the bucket as UTF-8 and the document keeps the
+ * reference with the head that paint and stubs read. With no writer bound, or a bucket that refuses the write,
+ * the text stays inline as it always did: a text is never lost to a full disk.
+ */
+export function externalizeText(text: string, mime: string = TEXT_MIME): TextStamp {
+  if (writer === null || !exceedsInlineMax(text)) return { kind: "inline", text };
+  try {
+    const ref = writer(Buffer.from(text, "utf8"), mime);
+    const head = blobHeadOf(text);
+    return { kind: "blob", head, blobJson: storedBlobJson({ ...ref, head }) };
+  } catch {
+    return { kind: "inline", text };
+  }
+}
+
+/** {@link externalizeText} in the shape a `FileMutateToolJob` takes. */
+export function externalizePrior(text: string): PriorProps {
+  const stamp = externalizeText(text);
+  return stamp.kind === "inline" ? { priorContent: stamp.text } : { priorBlobJson: stamp.blobJson };
+}

package/src/tool-runtime/extra-root.ts

@@ -0,0 +1,16 @@
+/**
+ * Dispatch-time extra-root flag. Human allow / remainder grant / yolo
+ * shell is this spawn, not a file-read grant. Effect bodies read it;
+ * they do not set it.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const extraRootAls = new AsyncLocalStorage<boolean>();
+
+export function runWithExtraRoot<T>(allow: boolean, fn: () => T): T {
+  return extraRootAls.run(allow, fn);
+}
+
+export function extraRootAllowed(): boolean {
+  return extraRootAls.getStore() === true;
+}