@oh-my-ai-sdk/omakase 0.1.2 → 0.1.4

package/README.md

@@ -58,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
@@ -189,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
@@ -315,13 +328,125 @@ 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.
@@ -580,11 +705,22 @@ exactly once.
 
 ## Automatic releases
 
-Merging a new package version to `main` triggers `release.yml`. The publisher
-requires successful CI on that exact commit, builds once, and runs the installed
-ordinary/durable MCP proof before publishing the tested tarball. It checks npm's
-integrity and repeats the proof against a registry installation. Published
-versions are immutable; normal pushes skip versions already on npm.
+An eligible merge to `main` triggers `release.yml`. CI automatically assigns the
+next **patch** on the owner-approved release line: `0.1.3` → `0.1.4` → `0.1.5`.
+Do not hand-bump the patch in `package.json`. Its major/minor must match the
+`OMAKASE_RELEASE_LINE` variable in GitHub's **npm-omakase** environment; changing
+source to `0.2.0` alone fails closed. Only Charles may authorize changing that
+setting and the source manifest to a new major/minor line.
+
+The publisher requires successful CI on that exact commit, reserves a
+package-scoped `omakase@<version>` tag, installs locked dependencies, then stamps
+the artifact's version and source commit. It builds once and runs the installed
+ordinary/durable MCP proof before publishing the tested tarball, checks npm's
+integrity, and repeats the proof against a registry installation.
+Reservations are immutable: retries reuse the same version, including after a
+publish whose registry visibility was delayed. Failed builds can leave patch
+gaps; do not delete or move their tags. A superseded unpublished reservation
+cannot replace a newer release on `latest`.
 
 Omakase continues on the `0.1.x` release line: `0.1.1` includes the functionality
 previously published as `0.2.0-beta.3`. Durable execution remains an opt-in beta
@@ -593,17 +729,28 @@ Normal installs use `@oh-my-ai-sdk/omakase` on `latest`. Previously published
 prereleases remain available; existing pins or `@beta` installs must switch to
 `0.1.1` or `@latest` to follow this release line.
 
-Prereleases use their named `alpha`, `beta`, or `rc` channel; only stable versions
-update `latest`.
+Automatic publication produces stable `0.1.x` versions on `latest`; it does not
+infer minor/major bumps or prereleases from commit messages. The early-stage
+patch policy includes reviewed features, not just fixes; it is not a claim that
+all APIs are stable.
 
 One-time npm setup: in this package's **Settings → Trusted publishing**, authorize
 GitHub owner `archeism`, repository `oh-my-ai`, workflow **`release.yml`**, environment
 **`npm-omakase`**, with direct **`npm publish`** allowed. The GitHub environment
 permits only branch `main`, with no required reviewers or per-release approval.
 A staged-publish permission alone does not enable automatic releases. No npm token secret is used.
+Set the environment variable `OMAKASE_RELEASE_LINE` to `0.1` during setup.
+The publisher has tag-writing permission, not environment-administration
+permission. Moving to `0.2` or `1.0` is an explicit owner decision, not a routine
+release approval.
+Bootstrap an existing publication with its verified `omakase@<version>` source
+tag before enabling this allocator (Omakase's baseline is `omakase@0.1.3`).
+New allocations must descend from the newest reservation, not necessarily equal
+the current main tip: an unrelated main merge must not strand an eligible release.
 See [npm's trusted-publisher setup](https://docs.npmjs.com/trusted-publishers/).
 
-After fixing a publishing failure, retry from reviewed `main`:
+After fixing a publishing failure, rerun the failed Actions run to resume its
+exact source reservation. To release or verify the current reviewed `main`:
 
 ```sh
 gh workflow run release.yml --repo archeism/oh-my-ai --ref main

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>;