@oh-my-ai-sdk/omakase 0.1.1 → 0.1.3

package/README.md

@@ -12,15 +12,16 @@ configured URI sources. No model-facing registry-management tools.
 ## CLI setup
 
 Requires Node.js 22.13 or newer. The host itself needs no model key; your calling
-Claude/Codex session supplies its own model. Registered child agents additionally
-need Bun, their bootstrap prerequisites, and their own configured credentials
-(see below). Configuration stays outside harness MCP registration.
+Claude/Codex session supplies its own model. Registered child agents and decision
+tools use their own configured credentials. Child agents additionally need Bun
+and their bootstrap prerequisites (see below). Configuration stays outside
+harness MCP registration.
 
-For a local beta candidate, install its packed `.tgz` with `bun add /absolute/path/to/archive.tgz`
+For a local candidate, install its packed `.tgz` with `bun add /absolute/path/to/archive.tgz`
 and configure your MCP client with the absolute path to that installation's
-`node_modules/.bin/omakase`. The registry commands below require the `beta`
-dist-tag to have been published; building or installing a local candidate does
-not publish it.
+`node_modules/.bin/omakase`. The registry commands below install the published
+`latest` release on the `0.1.x` line. Building or installing a local candidate
+does not publish it.
 
 Create `~/.config/omakase/host.config.mjs` (or
 `$XDG_CONFIG_HOME/omakase/host.config.mjs`):
@@ -57,6 +58,17 @@ Use `--help` for CLI options. Each invocation owns one live host. The durable
 worker is included in the same installation and starts only on the first durable
 call; ordinary calls and catalog inspection do not start it.
 
+The `omakase-skills` bin runs the same skills service as its own stdio MCP
+server. With no arguments it serves the skill collection shipped inside the
+package: the `omakase-codemode` skill under collection id `omakase` (the
+`skill/` directory next to `dist/`). It teaches this orchestration workflow —
+`agent.run` fan-out, `task.list` discovery, `agent.steer` correction, gates and
+evidence — in ordinary JS. An explicit
+`--config /absolute/skills-service.config.mjs` or an absolute skills directory
+argument behaves exactly as before. The legacy `omakase-flow` skill is
+untouched and remains only in the Claude plugin copy under
+`plugin/omakase/skills/omakase-flow`; it is not part of this npm bundle.
+
 ## Execution modes (beta)
 
 ```ts
@@ -188,7 +200,9 @@ Registered agent runs are available below; the old Flow DSL is not imported.
 `createAgentHost(options)`. Registration reuses Flow's `agent.yaml` directories,
 named profiles, ordinary AI SDK tools under `tools/`, and runtime-download cache.
 There is no new `run` DSL or separate agent MCP server: each trusted registration
-becomes `agents.NAME({ prompt, workspaceDir? })` in the existing cell catalog.
+becomes `agents.NAME({ prompt, workspaceDir? })` in the existing cell catalog,
+and the same mount adds the generic `agent.run`, `agent.steer` and `task.list`
+leaves described below.
 
 The agent feature needs **Bun >=1.3.14** on PATH in addition to Node. Bridge-backed
 Claude, Codex and OpenCode bootstraps also need **pnpm** and first-use registry
@@ -314,13 +328,207 @@ absolute Bun path.
 
 This ports registration and running agents, not Flow's verb set. JS loops,
 branches, `Promise.all`, dependent calls and unrelated host tools remain available.
-Live steering, `ask`/`pause`, and forwarding a child agent's human approval are
+Live steering of a running native turn is available through `agent.steer` for
+adapters that support it; unsupported or inactive targets fail typed, never by
+restart. `ask`/`pause` and forwarding a child agent's human approval remain
 deferred. Automatic native decisions are honored; an unresolved child approval
 fails closed. The cell host's existing approval transport is unchanged.
 The private OMP adapter is not bundled: OMP **as a child backend** requires its
 separately installed/built adapter; using an MCP-capable harness as the caller
 does not require that child adapter.
 
+## Generic agent runs, task discovery and steering
+
+The same agent mount adds three generic leaves to the cell catalog: `agent.run`,
+`agent.steer` and `task.list`. They are ordinary host tools: MCP callers submit
+them as `cell({ code })` bodies, native callers drive the same host snapshots
+and frontends with `mountAgents` imported from `/agents`, and both see identical
+names, schemas and permission policy — the CLI config file and a native
+`mountAgents` call take the same options object. A complete, commented config —
+named agent plus inline catalog — ships in the package as
+`examples/agent-tasks.config.mjs`.
+
+`agent.run` selects a backend one of two ways, never both in one call:
+
+```ts
+// Named: the same execution and the same authored result as agents.reviewer.
+const found = await agent.run({ agent: 'reviewer', prompt: 'Inspect README.md' });
+// Inline: registered harness/provider keys plus an authorized model id.
+const probe = await agent.run({
+  harness: 'claude', provider: 'zai', model: 'glm-5.3',
+  settings: 'deep', // optional: a preset key registered on the provider
+  prompt: 'List concrete risks in the install flow.',
+});
+if (probe === null || typeof probe !== 'object' ||
+    !('text' in probe) || typeof probe.text !== 'string') {
+  throw new Error('Expected text from the inline agent');
+}
+return { found, probe: probe.text };
+```
+
+Named runs return the registration's authored structured result — the exact
+`agents.NAME` output schema and value. Inline runs return `{ sessionId, text }`.
+The generic tool's static result type is `unknown` because the selected agent
+can change its shape; narrow it before accessing fields, as above. Use
+`agents.NAME` when you want the registered output schema exposed to preflight.
+`workspaceDir` is optional on both and follows the same inside-the-registered-
+workspace rule as `agents.NAME`. Ordinary cells keep one-shot behavior; there
+are no ordinary-cell run IDs.
+
+Inline authority is the host-owned `catalog` field of `mountAgents` /
+`createAgentHost`: each harness key names a trusted adapter id and its
+providers; each provider owns credential pointers and options, the authorized
+model ids, and optional named settings presets. `settings` is a preset-name
+string, never an options object — the guest selects a key, the host composes
+trusted options around it. No option fragment may declare `model`; model
+authority is the registered model key. Unregistered or mixed selections fail
+`INVALID_INPUT` before any worker starts, and the whole catalog is validated
+before registration. `cell({})` and the `agent.run` description list the
+registered selection keys. Inline specs carry no tool files: an inline child
+gets the harness's native built-ins — optionally restricted by the registration's
+`activeTools` — through the same loader, while custom tool files remain
+exclusive to named agent directories.
+
+### Discovering and steering durable agent tasks
+
+`task.list` and `agent.steer` operate on **durable** runs. Submit the run with
+`waitMs: 0`, keep the returned `runId`, then pass it back inside a separate
+ordinary control cell:
+
+```ts
+// Ordinary control cell, while the durable run above is still unfinished:
+const { tasks } = await task.list({ runId: '…' });
+// => [{ taskId, kind: 'agent', agent: 'reviewer', status: 'running' }]
+const target = tasks.find(task => task.status === 'running' && task.agent === 'reviewer');
+if (!target) return { steered: false, tasks };
+const ack = await agent.steer({ taskId: target.taskId, prompt: 'Prefer the smallest fix.' });
+return { steered: true, ack };
+```
+
+`taskId` is the admitted durable tool-call id, not a native session id; one
+task is one invocation. Statuses: `pending` (admitted, not yet claimed for
+execution), `running` (nonterminal resumable execution — live steering
+availability is **not** implied), `completed`/`failed` (terminal per-slice
+receipt, authoritative even when the run's summary is missing), and `unknown`
+(unresolved claim without a trustworthy continuation). An unknown or foreign
+`runId` fails typed (`NOT_FOUND`/`FORBIDDEN`); it never returns an empty list.
+Control resolves the live task-control port for the caller's trusted
+harness/session scope: the durable executor for that scope must be running
+(`UNAVAILABLE` otherwise; the CLI starts it on the first durable cell and keeps
+it for the host's lifetime).
+
+`agent.steer` submits an additional user message into the target's active
+native turn on the same session. `accepted` means exactly that the native
+delivery was accepted — not that the message was applied, checkpointed or
+completed. Refusals carry stable codes in the message prefix:
+`STEER_UNSUPPORTED` (the pinned adapter cannot steer this agent; a steering
+facet alone is not capability), `NOT_RUNNING` (no live slice, or the turn is
+suspending, suspended or finished), `CONFLICT` (same steer call id with a
+changed `{taskId, prompt}`), `OUTCOME_UNKNOWN` (interrupted delivery — never
+retried), and `NOT_FOUND`/`FORBIDDEN` for unknown, foreign or non-agent tasks.
+There is no cancel-and-restart fallback: a refusal never kills the agent slice,
+and steering between slices, after completion, or on unsupported adapters stays
+a typed refusal.
+
+Same-intent steering is deduplicated by the trusted steering call id bound to
+its full `{taskId, prompt}`: concurrent duplicates join one delivery, and
+replaying an accepted delivery returns the historical acknowledgement without
+redelivery — even after session loss, so an accepted but unapplied message is
+not repaired.
+
+### Upgrades and drift
+
+The whole catalog identity — including resolved named-profile contents behind
+unchanged refs, the inline catalog, and `sliceSeconds` — is part of each run's
+recovery identity. Upgrading this package while pending durable agent runs were
+admitted against a catalog that no longer matches fails closed with
+`RECOVERY_BLOCKED`: retain the admitted configuration to finish them, or
+reconcile and archive the state directory. There is no arbitrary in-flight
+migration, and no guarantee that a steer accepted but not yet checkpointed into
+native history survives a restart.
+
+## Decision controller in ordinary or durable cells
+
+`createDecisionTool({ model, configurationId })` returns an ordinary AI SDK tool.
+Register it as `tools.decision` in a custom host, or set the optional `decision`
+configuration on `createSkillsHost` to add it alongside `tools.read`. The existing
+MCP server still exposes one `cell` tool; no separate decision server is needed.
+
+Example `host.config.mjs` (install the provider beside this config, not inside
+Omakase):
+
+```js
+import { createTypeSafeAi } from '@ai-sdk/typesafe-ai';
+
+export default async ({ createSkillsHost }) => createSkillsHost({
+  collections: [],
+  cwd: '/absolute/path/to/workspace',
+  decision: {
+    model: createTypeSafeAi().decisionModel('jev-1.13.0'),
+    configurationId: 'review-controller-v1',
+  },
+});
+```
+
+This example uses `TYPESAFE_AI_API_KEY` and the tested
+`@ai-sdk/typesafe-ai@3.0.13` adapter with Omakase's pinned `ai@7.0.128`.
+The experimental decision protocol can change in patch releases: adapter
+`3.0.17` expects a newer state representation and is not compatible with this
+core version. No provider is installed, selected, or silently substituted by
+Omakase. Other SDK decision-model instances may be supplied, but their provider
+compatibility must be verified; this release does not include a Clef adapter.
+
+Native custom hosts import `createDecisionTool` from `@oh-my-ai-sdk/omakase` and
+use `await host.register('tools', { decision: createDecisionTool(options) })`.
+Include other `tools` leaves in that same registration: namespaces cannot be
+registered twice. The CLI also supplies `createDecisionTool` to its host factory.
+
+Submit this body through the existing `cell` API:
+
+```ts
+const { answers } = await tools.decision({
+  state: { reviews: ["No blocking defects"], tests: "passed" },
+  questions: {
+    blocked: { type: "boolean", instructions: "Is there a blocking defect?" },
+    next: {
+      type: "choice",
+      instructions: "Choose the next action.",
+      criteria: { fix: "Repair a defect", finish: "Verified completion" },
+    },
+    quality: {
+      type: "score",
+      instructions: "Rate completeness.",
+      criteria: ["Incomplete", "Partly complete", "Complete"],
+    },
+  },
+});
+const { blocked, next, quality } = answers;
+if (!blocked || !next || !quality ||
+    blocked.type !== "boolean" || next.type !== "choice" || quality.type !== "score")
+  throw new Error("Unexpected decision answer types");
+return { blocked: blocked.probability, next: next.choice, quality: quality.score };
+```
+
+- State and instructions accept a JSON string, object or array. Question names
+  identify answers. Criteria descriptions can additionally be `null`.
+- `boolean` returns P(true), not a Boolean flag. `choice` returns an option name.
+  `score` returns a fractional position from zero through the last rubric index.
+  Choice/score distributions are optional; calibration is not portable across
+  providers. The result contains `{ answers, modelId }`, not SDK transport data.
+- JavaScript owns branching. A judgment never grants tool permissions or bypasses
+  native approval. Malformed answers and provider errors fail the tool call;
+  no fallback judgment or automatic inference retry is supplied.
+- Ordinary cells execute directly. Durable cells record each decision invocation;
+  all questions in one call share that checkpoint. Separate calls can progress
+  independently. Recorded answers are reused; an interrupted inference without a
+  committed receipt fails `OUTCOME_UNKNOWN` rather than silently re-inferencing.
+- The configured provider/model and `configurationId` contribute to durable
+  catalog identity via `metadata.omakase.executionIdentity`. Change the revision
+  whenever endpoint, adapter or hidden settings change, and keep model instances
+  immutable. Pending runs reject configuration drift with `RECOVERY_BLOCKED`;
+  retain the admitted configuration to recover them. Do not use secrets in this
+  revision or a moving model alias when reproducibility matters.
+
 ## Skill reads through Code Mode
 
 Call `cell({})` to inspect the current full leaf catalog. Submit the following

package/dist/agent-catalog.d.ts

@@ -0,0 +1,202 @@
+import { type JSONSchema7, type JSONValue } from 'ai';
+import type { ToolHost } from './host.js';
+/** Trusted inline backend spec — the object presentation of an agent the
+ * flow provider already loads (inlineManifest): one lane plus instructions
+ * text. Host-composed only; never accepted from tool arguments. There are no
+ * tool files here — tools are files and belong to named agent directories —
+ * and no sandbox rootDir: that is per-run host state. */
+export interface InlineBackendSpec {
+    /** Adapter id (e.g. 'claude-code', 'codex', 'pi', 'omp'). */
+    readonly harness: string;
+    readonly instructions?: string;
+    readonly options?: Readonly<Record<string, JSONValue>>;
+    readonly sandbox?: {
+        readonly type?: 'local' | 'local-persistent';
+        readonly env?: Readonly<Record<string, string>>;
+        readonly inheritEnv?: boolean;
+        readonly warm?: boolean;
+    };
+    readonly processEnv?: Readonly<Record<string, string>>;
+    readonly placement?: string;
+    readonly permissionMode?: 'allow-reads' | 'allow-edits' | 'allow-all';
+    readonly toolApproval?: Readonly<Record<string, JSONValue>>;
+    readonly activeTools?: readonly string[];
+}
+/** Backend reference exactly as the bundled runtimes and the flow provider
+ * accept it: a registry-workspace ref string (named presentation) or a
+ * trusted inline spec composed by this catalog. */
+export type AgentBackendRef = string | InlineBackendSpec;
+/** Named, host-authored settings preset a guest may select by key. */
+export interface AgentSettingsRegistration {
+    /** Trusted harness options merged when this key is selected. */
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/** One authorized model on a provider. */
+export interface AgentModelRegistration {
+    /** Trusted harness options merged only when this model runs (e.g. env
+     * pinning the model id alongside options.model). */
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/** One provider under a harness: the route and credential unit. */
+export interface AgentProviderRegistration {
+    readonly description?: string;
+    /** Authorized model ids; guests must pass a key verbatim as `model`. */
+    readonly models: Readonly<Record<string, AgentModelRegistration>>;
+    /** Trusted provider-wide harness options; values may carry `${file:…}` /
+     * `${VAR}` pointers resolved against the HOST environment only. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /** Trusted sandbox environment (bridge harnesses read credentials here). */
+    readonly sandboxEnv?: Readonly<Record<string, string>>;
+    /** Trusted process-env declarations (host-process harnesses). */
+    readonly processEnv?: Readonly<Record<string, string>>;
+    /** Named trusted settings presets selectable through `settings`. */
+    readonly settings?: Readonly<Record<string, AgentSettingsRegistration>>;
+}
+/** One registered harness: the guest-visible selection unit for inline runs. */
+export interface AgentHarnessRegistration {
+    /** Adapter id placed in the inline spec — trusted, host-only. */
+    readonly harness: string;
+    readonly description?: string;
+    /** Instructions text used for every inline run of this harness. */
+    readonly instructions?: string;
+    readonly permissionMode?: 'allow-reads' | 'allow-edits' | 'allow-all';
+    readonly toolApproval?: Readonly<Record<string, unknown>>;
+    readonly activeTools?: readonly string[];
+    readonly sandbox?: {
+        readonly type?: 'local' | 'local-persistent';
+        readonly inheritEnv?: boolean;
+        readonly warm?: boolean;
+    };
+    /** Harness options merged under every provider of this harness. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly providers: Readonly<Record<string, AgentProviderRegistration>>;
+}
+/** The `catalog` field of MountAgentsOptions. */
+export interface AgentCatalogOptions {
+    readonly harnesses: Readonly<Record<string, AgentHarnessRegistration>>;
+}
+/** Validated, cloned snapshot of a catalog: what the fingerprint hashes and
+ * selection composes from. Caller mutation after mount cannot drift it. */
+export interface NormalizedAgentCatalog {
+    readonly harnesses: Readonly<Record<string, NormalizedAgentHarness>>;
+}
+export interface NormalizedAgentHarness {
+    readonly key: string;
+    readonly harness: string;
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly permissionMode?: 'allow-reads' | 'allow-edits' | 'allow-all';
+    readonly toolApproval?: Record<string, JSONValue>;
+    readonly activeTools?: string[];
+    readonly sandbox: {
+        readonly type?: 'local' | 'local-persistent';
+        readonly inheritEnv?: boolean;
+        readonly warm?: boolean;
+    };
+    readonly options?: Record<string, JSONValue>;
+    readonly providers: Readonly<Record<string, NormalizedAgentProvider>>;
+}
+export interface NormalizedAgentProvider {
+    readonly key: string;
+    readonly description?: string;
+    readonly models: Readonly<Record<string, {
+        readonly options?: Record<string, JSONValue>;
+    }>>;
+    readonly options?: Record<string, JSONValue>;
+    readonly sandboxEnv?: Record<string, string>;
+    readonly processEnv?: Record<string, string>;
+    readonly settings?: Readonly<Record<string, {
+        readonly options?: Record<string, JSONValue>;
+    }>>;
+}
+/** Guest input of `agent.run`: exactly one selection mode. */
+export interface AgentRunInput {
+    /** Named mode: a registered agent name (the `agents.NAME` key). */
+    readonly agent?: string;
+    /** Inline mode: a registered harness key. */
+    readonly harness?: string;
+    /** Inline mode: a provider key registered under that harness. */
+    readonly provider?: string;
+    /** Inline mode: a model id authorized on that provider. */
+    readonly model?: string;
+    /** Inline mode: a settings key registered on that provider. */
+    readonly settings?: string;
+    readonly prompt: string;
+    readonly workspaceDir?: string;
+}
+/** One resolved backend selection: a named registration (authored schema and
+ * result contract) or a host-composed inline spec. */
+export type AgentBackendSelection = {
+    readonly kind: 'named';
+    readonly name: string;
+    readonly ref: string;
+    readonly outputSchema?: JSONSchema7;
+} | {
+    readonly kind: 'inline';
+    readonly spec: InlineBackendSpec;
+    readonly label: string;
+};
+/** Validates and snapshots a catalog before any host effect (namespace
+ * registration, filesystem, workers). Throws typed INVALID_INPUT naming the
+ * offending field; forbidden overrides (a `model` key in any option
+ * fragment) are rejected here, before effects, per the authority contract. */
+export declare function validateAgentCatalog(catalog: unknown): NormalizedAgentCatalog;
+/** Deterministic JSON with recursively sorted object keys: equal
+ * configurations hash equal regardless of authoring key order. */
+export declare function canonicalJson(value: unknown): string;
+/** Stable, secret-free fingerprint of the whole mounted agent authority.
+ * Inputs are the validated catalog snapshot, the trusted slice budget and —
+ * critically — each named profile's RESOLVED inspect identity, so content
+ * drift behind an unchanged ref string (an agent.yaml edit on the host)
+ * rejects admission recovery even for tools a pending cell never invoked.
+ * Inline config drift is covered the same way: the selected identity embeds
+ * the resolved manifest fingerprint of the composed spec. The result is a
+ * hex hash — no configuration object, pointer or secret is serialized. */
+export declare function agentCatalogFingerprint(input: {
+    readonly named: ReadonlyArray<{
+        readonly name: string;
+        readonly identity: string;
+    }>;
+    readonly catalog: NormalizedAgentCatalog | undefined;
+    readonly sliceSeconds: number;
+}): string;
+/** In-memory memo key for one backend ref: the ref itself when named, a hash
+ * of the canonical spec otherwise. Never persisted, logged or sent. */
+export declare function agentBackendRefKey(ref: AgentBackendRef): string;
+/** Validates one agent.run input against the mounted authority and resolves
+ * the backend selection. Pure: no worker, no filesystem, no effects — every
+ * unregistered or mixed selection fails here, typed, before anything runs.
+ * Registration lookups are own-key: names inherited from Object.prototype
+ * (`constructor`, `toString`, `__proto__`, …) never grant authority. */
+export declare function resolveAgentRunSelection(input: unknown, named: ReadonlyMap<string, {
+    readonly ref: string;
+    readonly outputSchema?: JSONSchema7;
+}>, catalog: NormalizedAgentCatalog | undefined): AgentBackendSelection;
+/** What agents.ts supplies to mount the generic surface: the validated
+ * authority snapshot plus the shared execution/identity machinery (the same
+ * ordinary one-shot and durable-slice paths behind agents.NAME). */
+export interface AgentCatalogMount {
+    readonly host: ToolHost;
+    /** Whole-catalog identity; registered as the catalog inspector of every
+     * agent tool for admission drift rejection. */
+    readonly catalogFingerprint: () => Promise<string>;
+    readonly catalog: NormalizedAgentCatalog | undefined;
+    readonly named: ReadonlyMap<string, {
+        readonly ref: string;
+        readonly outputSchema?: JSONSchema7;
+    }>;
+    /** Selected per-input identity of one validated selection (worker inspect
+     * mode; memoized by agents.ts). */
+    identityForSelection(selection: AgentBackendSelection): Promise<string>;
+    /** Execute one selection with agents.NAME semantics: authored structured
+     * result for named selections, { sessionId, text } for inline; durable
+     * slice support and same-intent replay dedup included. */
+    runSelected(selection: AgentBackendSelection, input: AgentRunInput, execution: {
+        readonly toolCallId: string;
+        readonly abortSignal?: AbortSignal;
+    }): Promise<JSONValue>;
+}
+/** Registers the `agent` namespace — `run` (named or inline selection) and
+ * `steer` (routed to the task-control port) — and the recovery inspectors
+ * of `agent.run`. Called once from mountAgents after the named tools. */
+export declare function mountAgentCatalog(mount: AgentCatalogMount): Promise<void>;