@oh-my-ai-sdk/omakase 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,9 +1,9 @@
 # Omakase
 
-A local tool host for Claude Code, Codex and native AI SDK ToolLoopAgent.
-Register capabilities in the host; models see one `code_mode` tool. Its JavaScript
-runs in the upstream AI SDK QuickJS engine and calls the original tool
-implementations through validated host dispatch.
+A local tool host for Claude Code, Codex and native AI SDK agents.
+One package and one MCP server expose one `cell` tool. Ordinary execution remains
+the default; `execution: "durable"` opts into the WDK-backed beta. Both use the
+same live tool catalog, bindings, validation and host permission policy.
 
 The bundled skills MCP service owns collections and exposes one `list` tool plus
 standard skill/resource endpoints. One regular reader handles local files and
@@ -15,6 +15,12 @@ Requires Node.js22.13 or newer. No model key is needed by the host: your existin
 Claude/Codex session supplies the model. Configuration stays outside harness MCP
 registration.
 
+For a local beta 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.
+
 Create `~/.config/omakase/host.config.mjs` (or
 `$XDG_CONFIG_HOME/omakase/host.config.mjs`):
 
@@ -35,8 +41,8 @@ remote pulls are explicit application operations. Nothing is copied into native
 harness skill directories.
 
 ```sh
-claude mcp add --scope user --transport stdio omakase -- npx -y @oh-my-ai-sdk/omakase
-codex mcp add omakase -- npx -y @oh-my-ai-sdk/omakase
+claude mcp add --scope user --transport stdio omakase -- npx -y @oh-my-ai-sdk/omakase@beta
+codex mcp add omakase -- npx -y @oh-my-ai-sdk/omakase@beta
 ```
 
 Restart the client and ask it to use Omakase to list and read a skill. Automatic
@@ -44,18 +50,121 @@ skill-name injection into harness prompts is not implemented. Native skills can
 remain installed while you try this route.
 
 For a fixed config path, launch
-`npx -y @oh-my-ai-sdk/omakase --config /absolute/host.config.mjs`.
+`npx -y @oh-my-ai-sdk/omakase@beta --config /absolute/host.config.mjs`.
 Existing `--mcp-config /absolute/.mcp.json` imports ordinary downstream MCP tools.
-Use `--help` for CLI options. Each invocation owns a separate in-memory host;
-there is no cross-machine state or remote daemon.
+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.
+
+## Execution modes (beta)
+
+```ts
+cell({ code: 'return await skills.list({ server: "self" });' });
+cell({ code: 'return await skills.list({ server: "self" });', execution: 'ordinary' });
+cell({ code: 'return await skills.list({ server: "self" });', execution: 'durable' });
+```
+
+`code` accepts a JavaScript or TypeScript function body with top-level `await`
+and `return`; an omitted return becomes `null`. Results still pass runtime JSON
+validation. `{}` inspects the catalog without executing tools or loading the
+compiler. A mode without code is invalid.
+
+Both modes run semantic preflight with pinned TypeScript
+`7.1.0-dev.20260902.1` before **any** tool effect, using the admitted catalog's
+input/output schemas. Diagnostics include cell locations and `TS` codes.
+The native compiler starts lazily and is reused until the last owning host
+closes. Guest declarations do not expose Node, Bun, filesystem imports, or
+`fetch`; host capabilities remain explicit tools. Checking is not a security
+boundary. Tools without an output schema return `unknown`: narrow their results
+before accessing fields. Runtime validation and permissions remain authoritative.
+
+`parallel()` takes thunks and returns a typed tuple of
+`{ok:true,value}` or `{ok:false,error:string}` outcomes:
+
+```ts
+const [title, count] = await parallel([
+  async () => "report",
+  async () => 3,
+]);
+if (!title.ok || !count.ok) throw new Error("A branch failed");
+return { title: title.value.toUpperCase(), count: count.value + 1 };
+```
+
+Use `Promise.all` when a rejected branch should reject the combined expression.
+Tool bridges are lazy: start independent work together rather than constructing
+unawaited calls and awaiting them sequentially. A fast branch can await a
+dependent tool inside its own async function while a slow sibling is unfinished.
+Durable recovery reuses the admitted prepared source and tool contract; it does
+not type-check the cell again. Catalog-contract drift fails closed on advancement.
+
+Ordinary mode uses the existing AI SDK Code Mode caller. Durable mode promotes
+the tested `run@2.1.7` cell engine and uses separate WDK checkpoints for guest
+advancement and each tool invocation, not one retryable step around the cell.
+The worker bundles stock `workflow@4.8.12`, `@workflow/core@4.8.12` and
+`@workflow/world-local@4.4.2`; it does not use the monorepo's Workflow patches.
+Registered functions stay in the server, so no second tool registry or host
+configuration is reconstructed in the worker.
+
+Both modes use the same configured approval port. MCP approvals require a client
+with form elicitation support; missing support fails closed. A denied operation
+does not enter its tool body. Durable mode rejects tools explicitly marked
+`metadata.omakase.replay: "unsafe"` before body entry. Missing metadata retains
+the existing legacy policy; it is not evidence that an external effect is safe.
+Approval policies may be consulted more than once during admission and replay;
+keep the decision check safe to repeat. An effect belongs in the tool body,
+not in the approval policy.
+
+**Recovery boundary:** this beta automatically replaces a failed WDK worker and
+reattaches accepted calls to their original runs while the MCP server stays alive.
+Completed checkpoints and parent receipts are reused; a still-running tool in the
+parent is reattached rather than invoked again. Whole-MCP-server replacement,
+cross-machine recovery and reconnecting a lost client request are not supported.
+An ambiguous entered-but-unsettled receipt is refused as `OUTCOME_UNKNOWN`; this
+is not an exactly-once guarantee for external systems.
+
+`OMAKASE_DURABLE_DIR` optionally selects an absolute private state directory.
+Otherwise each server gets a directory below `~/.local/share/omakase/durable/`.
+Each live durable host holds a kernel-released SQLite exclusive transaction on
+`ownership.sqlite`. Competing hosts cannot own the same directory. After a host
+crash, a new owner starts a **fresh** `generations/<id>/` World; this permits new
+work, not recovery of the previous host's calls. Worker replacement within one
+generation still resumes its original runs.
+
+World history, admissions, receipts, continuation keys and replaced ownership
+pointers are retained without automatic pruning. Keep the directory private.
+Archive/prune a retired directory only after its hosts and workers are stopped
+and unknown external outcomes have been reconciled. Never remove or replace
+`ownership.sqlite` while any host may use it. Graceful close holds ownership
+until active bridge handlers finish their state writes.
+
+Upgrading an earlier beta with a PID-only `host.lock` requires stopping that
+server first. If it crashed, archive the legacy pointer only after confirming
+the process is stopped, or use a fresh directory. Ambiguous legacy ownership
+fails closed rather than bypassing the old lock.
+
+Request cancellation does not cancel an accepted durable run while its server
+remains alive. Closing the server stops its worker and drains admitted handlers.
+Repeating `cell` creates a new intent, **not** a resume request; tools still need
+application idempotency or reconciliation for external effects.
+
+Keep ordinary mode for work that does not need these checkpoints. Parent–child
+agent enhancements and legacy Flow migration are not included in this beta.
+
 
 ## Skill reads through Code Mode
 
-Call `code_mode({})` to inspect the current full leaf catalog. Then:
+Call `cell({})` to inspect the current full leaf catalog. Submit the following
+body as `cell({ code: "..." })`:
 
-```js
+```ts
 const listed = await skills.list({server: 'self'});
-const entry = listed.structuredContent.entries.find(s => s.frontmatter.name === 'eli5');
+if (!listed || typeof listed !== "object" || !("structuredContent" in listed))
+  throw new Error("Missing skill list");
+const data = listed.structuredContent;
+if (!data || typeof data !== "object" || !("entries" in data) || !Array.isArray(data.entries))
+  throw new Error("Invalid skill entries");
+const entry = data.entries.find(s => s?.frontmatter?.name === "eli5");
+if (!entry || typeof entry.uri !== "string") throw new Error("Skill not found");
 return await tools.read({path: entry.uri});
 ```
 
@@ -95,10 +204,13 @@ execute-free declarations with trusted binding/executor seams, host availability
 and per-call approval policies. These are application configuration, never
 model-issued grants. Existing approval adapters support trusted callbacks,
 native SDK approval messages and request-scoped MCP elicitation; client support
-varies. Resume state is in memory, not durable.
+varies. Ordinary approval state stays in memory. In the durable beta, the live
+host retains approval state across worker replacement; whole-host recovery is
+not claimed.
 
 Exports: root host/caller/reader APIs, `/mcp-sdk` for the official SDK client,
-`/skills-server` for the standalone service and `/skills-host` for the bundled host.
+`/skills-server` for the standalone service, `/skills-host` for the bundled host,
+and `/workflow` plus `/workflow-host` for Workflow-backed cells.
 For custom ESM CLI factories, import APIs from your own installed dependencies;
 the injected helper covers the simple skills configuration shown above.
 
@@ -108,12 +220,132 @@ Trusted local single-user implementation. Node22.13+, QuickJS glue execution,
 input/output validation, cancellation and bounded source/result/bridge calls.
 QuickJS limits do not bound arbitrary native effects or undo completed operations.
 Tools requiring unsupported provider/context/approval semantics are rejected.
-No persistence, production authorization, durable resume, agentic skill selector,
-per-skill management UI or harness disclosure hooks. Collections are configured
-by the application; the MCP service exposes only list and read endpoints.
-
-The source checkout passed192tests, real ToolLoopAgent generate/stream and actual
-Codex/Claude skill reads and instruction following. Claude recovered from a
-namespace-shadowing error. Release verification separately tests an installed
-archive without the monorepo's patches, workspace links or dev dependencies.
+This is not a hostile-code sandbox or a production multi-user authorization
+system. Collections are application-configured; skill management and harness
+disclosure hooks are not added by this beta.
+
+The existing programmatic `createCodeModeCaller` and `createToolHostFrontend`
+APIs still use `code_mode({ js })`. The CLI now registers only `cell({ code,
+execution? })`; there is no second MCP entrypoint or automatic durable fallback.
+Release verification must exercise an installed archive without monorepo patches,
+workspace links or dev dependencies. The combined MCP acceptance also checks real
+approval decisions, independent progress, worker replacement and effect receipts.
 License: Apache-2.0.
+
+## Consumer-owned Workflow adapter (earlier prototype)
+
+`./workflow` exports a workflow-safe `runWorkflowCell` driver and an ordinary
+`createWorkflowCodeModeTool` wrapper compatible with the existing MCP facade.
+`./workflow-host` exports `advanceWorkflowCell` for a consumer-owned `"use step"`
+function. The application recreates its trusted host inside that step and supplies
+its stable signing key. `maxAgeMs` sets the trusted continuation lifetime;
+the upstream default is one hour, so durable human waits need an explicitly
+appropriate lifetime. Expired continuations cannot resume merely because the
+workflow itself is durable. Registered tools keep their ordinary AI SDK schemas.
+
+```ts
+// Called in workflow scope; the application supplies compiled step functions.
+const value = await runWorkflowCell({ js, toolCallId }, {
+  advance: advanceCell, // "use step": recreate host, call advanceWorkflowCell
+  execute: request => dispatchRegisteredOperation(request),
+});
+```
+
+The dispatcher runs **from workflow scope**, so functions marked `"use step"`
+retain their own checkpoints. Ordinary pure functions can use the same dispatcher.
+Host admission validates input, availability, bindings and policy before exposing
+an operation; continuation rechecks admission and validates the returned output.
+The dispatcher must resolve the approved `bindingId` to the same trusted target;
+the adapter deliberately serializes identifiers, never live target objects.
+
+Parallel guest calls dispatch concurrently. The driver retains unfinished calls by
+call ID and supplies finished results in their recorded completion order, so a
+fast branch can request its next tool without waiting for siblings. Calls with
+identical arguments still receive separate identities. Already dispatched work
+remains accounted for even when a guest race chooses a winner.
+
+This path requires the carried patches for Code Mode 1.0.84 and `run` 2.0.0.
+They add opt-in incremental continuation, arbitrary authenticated pending-result
+selection and fresh worker idle acknowledgments. Default Code Mode callers keep
+full-batch continuation. The host refuses an unpatched SDK rather than silently
+attach a result to the wrong pending call.
+
+For streaming under Workflow 5.0.1, apply its carried patch and configure
+`WORKFLOW_MAX_INLINE_STEPS=0` in the workflow execution backend. It queues steps
+individually and replays after each completion; default inline batching is
+unchanged. This adds queue hops in exchange for independent branch progress.
+The lab's direct Workflow control and cell streaming test exercise the same
+250 ms slow / 10 ms fast fixture.
+
+This prototype still reads **authenticated, readonly internal batch metadata
+from pinned Code Mode 1.0.84**. Upstream documents continuations as opaque; this
+shim and the owned patch API are pinned integration code, not compatibility
+claims for other SDK versions.
+
+Both cell adapters accept a trusted `prelude` string for helper libraries, such as
+Flow's `CELL_FLOW_SOURCE`; the host does not depend on Flow. Native/MCP callers use
+`createWorkflowCodeModeTool` with a callback that starts or resumes the cell
+workflow. WFA can use a callback that runs it in the parent workflow. Empty-input
+catalog inspection requires the optional trusted catalog callback.
+
+Interactive approvals remain unsupported on the Workflow path: in-memory approval
+records are not durable and cannot be resumed after host recreation. Denied calls
+remain denied. Admission/binding policy can change between suspension and resume;
+reconciliation is application-owned. A checkpoint does not provide exactly-once
+external effects or decide whether uncertain operations are safe to retry.
+Cancellation of an MCP request does not automatically cancel a durable workflow:
+the wrapper passes the abort signal to the application's start/resume callback,
+which owns that lifecycle. Default guest limits match the ordinary caller.
+
+### Replay constraints at execution
+
+Tool authors may declare `metadata: { omakase: { replay: 'unsafe' } }` when
+executing an unfinished invocation again could duplicate an effect. `safe` permits
+such execution; it does not guarantee exactly-once effects or enable retries.
+Disclosure and checkpoint storage remain independent.
+
+The host captures this constraint at registration. Its ordinary SDK executor
+has `replays: false`. A custom `HostExecutor` declares `replays: false` for
+single-attempt execution or `true` if recovery/retries can invoke the implementation
+again. Unsafe tools are rejected before invocation when the executor declares
+`true` or leaves the behavior unspecified, including snapshot executor overrides.
+Executor declarations are trusted application contracts, not model inputs.
+Tools without replay metadata retain legacy behavior; invalid declarations fail
+registration rather than silently becoming safe.
+
+Both Workflow cell adapters conservatively declare `replays: true`. Their
+interruption requests carry the captured policy, and the prototype leaf dispatchers
+check the current declaration again before executing. Unsafe implementations are
+therefore unavailable through these durable paths, even with zero automatic
+retries; no safe recovery policy for an unknown in-flight outcome is claimed.
+Committed-result reuse is not implementation replay. The host does not intercept
+retries inside a tool implementation or make arbitrary external side effects
+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.
+
+Prereleases use their named `alpha`, `beta`, or `rc` channel; only stable versions
+update `latest`. Install the durable beta with `@oh-my-ai-sdk/omakase@beta`.
+
+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.
+See [npm's trusted-publisher setup](https://docs.npmjs.com/trusted-publishers/).
+
+After fixing a publishing failure, retry from reviewed `main`:
+
+```sh
+gh workflow run release.yml --repo archeism/oh-my-ai --ref main
+```
+
+The retry also checks the registry installation when the version already exists.
+The run retains its tarball and proof receipts for 14 days. A green merge without
+a successful publication and registry proof is not a completed release.

package/dist/approval.d.ts

@@ -1,7 +1,11 @@
+import type { ToolReplayPolicy } from './execution-policy.js';
 import type { ToolHost } from './host.js';
 import type { JSONValue } from 'ai';
+import type { ToolExecutionOptions } from 'ai';
+import type { WorkflowToolRequest } from './workflow.js';
 export type HostApprovalStatus = 'approved' | 'denied' | 'user-approval' | 'not-applicable';
 export interface HostInvocation {
+    readonly replay?: ToolReplayPolicy;
     readonly executionId: string;
     readonly sessionId?: string;
     readonly harnessId?: string;
@@ -39,8 +43,13 @@ export interface HostControl {
         sessionId?: string;
         harnessId?: string;
         signal?: AbortSignal;
+        deferApproval?: boolean;
     }): HostExecution;
+    /** Re-admit a previously bound durable request through its original executor. */
+    invokeBound(request: WorkflowToolRequest, options: ToolExecutionOptions<any>): Promise<unknown>;
     recordCount(): number;
+    /** Bind internal resources to host.close without reserving a tool namespace. */
+    addDisposer(dispose: () => Promise<void>): void;
 }
 export declare function registerHostControl(host: ToolHost, control: HostControl): void;
 export declare function getHostControl(host: ToolHost): HostControl;

package/dist/cell-checker.d.ts

@@ -0,0 +1,46 @@
+import type { ToolHost } from './host.js';
+/**
+ * Semantic TypeScript 7.1 preflight for cell sources, adapted from
+ * labs/oma/src/ts71-native-checker.prototype.ts for the virtual-only cell
+ * sandbox: no workspace discovery, no Bun/Node ambient types, one synthetic
+ * module checked against the exact generated guest contract. The native
+ * compiler modules are imported lazily so catalog-only cold paths never load
+ * or spawn the compiler child.
+ */
+export type CellPreflightDiagnosticCategory = 'error' | 'warning' | 'suggestion' | 'message';
+export type CellPreflightDiagnostic = Readonly<{
+    category: CellPreflightDiagnosticCategory;
+    code: number;
+    message: string;
+    origin: 'cell' | 'context' | 'global';
+    line?: number;
+    column?: number;
+}>;
+export type CellPreflightResult = Readonly<{
+    ok: boolean;
+    version: string;
+    generation: number;
+    cache: 'cold' | 'incremental';
+    diagnostics: readonly CellPreflightDiagnostic[];
+    summary: Readonly<{
+        total: number;
+        returned: number;
+        truncated: boolean;
+    }>;
+}>;
+export interface CellTypeCompiler {
+    check(source: string, declarations: string): Promise<CellPreflightResult>;
+    transpile(code: string): Promise<string>;
+}
+export type CellCompilerStatus = Readonly<{
+    loaded: boolean;
+    serversSpawned: number;
+    serversDisposed: number;
+    checks: number;
+    transpiles: number;
+}>;
+/** Real laziness probe for tests: the compiler child must stay unloaded on catalog-only cold paths. */
+export declare function cellCompilerStatus(): CellCompilerStatus;
+export declare function acquireCellTypeCompiler(host: ToolHost): Promise<CellTypeCompiler>;
+/** One actionable failure message; TS codes stay greppable (TS1234). */
+export declare function formatCellPreflightFailure(result: CellPreflightResult): string;