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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,351 @@
-# Temporary Holding Version
+# Omakase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+configured URI sources. No model-facing registry-management tools.
+
+## CLI setup
+
+Requires Node.js22.13 or newer. No model key is needed by the host: your existing
+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`):
+
+```js
+export default async ({ createSkillsHost }) => createSkillsHost({
+  collections: [
+    { id: 'try', directory: '/absolute/path/to/your/skills' },
+    // { id: 'public', github: 'https://github.com/owner/repo', path: 'skills' },
+  ],
+  cwd: '/absolute/path/to/workspace',
+});
+```
+
+The CLI supplies `createSkillsHost` to your factory, so the config needs no package
+imports and works when launched from the npx cache. Local collections are scanned
+atomically and refreshed every second. GitHub sources are public HTTPS repositories;
+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@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
+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@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 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 `cell({})` to inspect the current full leaf catalog. Submit the following
+body as `cell({ code: "..." })`:
+
+```ts
+const listed = await skills.list({server: 'self'});
+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});
+```
+
+`skills.list({})` selects own plus configured peers. `server: 'self'` selects
+registered collections; another server ID selects a configured peer. Peer discovery
+never registers peer skills locally. MCP tool results retain their envelopes.
+Supporting files have readable addresses in `entry.readResources`. Remote gateway
+reads verify manifest membership, size and digest. Scripts are read as data.
+
+`tools.read({path})` also accepts real local paths, `file:` URIs and configured
+resolver schemes. It returns UTF-8 text or a base64 blob. Mounted MCP addresses
+select a configured connection and use `resources/read`; unknown schemes fail.
+The reader is trusted filesystem access, not confinement.
+
+Avoid shadowing namespace aliases: use `const listed = await skills.list(...)`,
+not `const skills = await skills.list(...)`. Canonical
+`await tools['skills.list']({...})` access also works. Await every tool call.
+
+## Native use and custom hosts
+
+```ts
+import { ToolLoopAgent } from 'ai';
+import { createCodeModeCaller } from '@oh-my-ai-sdk/omakase';
+import { createSkillsHost } from '@oh-my-ai-sdk/omakase/skills-host';
+
+const host = await createSkillsHost({collections: [{id: 'try', directory: '/absolute/skills'}]});
+try {
+  const agent = new ToolLoopAgent({model, tools: {code_mode: createCodeModeCaller(host)}});
+  await agent.generate({prompt: 'Use Omakase to read ELI5 and follow its instructions.'});
+} finally { await host.close(); }
+```
+
+`model` is supplied by your application. `createToolHost()` accepts ordinary
+AI SDK ToolSet values; `host.register('local', tools)` creates qualified names such
+as `local.add`. Snapshots expose only mediated wrappers. The core also supports
+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. 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, `/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.
+
+## Bounds and release status
+
+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.
+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

@@ -0,0 +1,60 @@
+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;
+    readonly bindingId?: string;
+    readonly toolCallId: string;
+    readonly parentToolCallId?: string;
+    readonly caller: string;
+    readonly toolName: string;
+    readonly input: JSONValue;
+}
+export type HostApprovalPolicy = (invocation: HostInvocation) => HostApprovalStatus | Promise<HostApprovalStatus>;
+export interface ApprovalRequest extends HostInvocation {
+    readonly approvalId: string;
+}
+export interface ApprovalDecision {
+    readonly approvalId: string;
+    readonly approved: boolean;
+    readonly reason?: string;
+}
+export type RequestApproval = (request: ApprovalRequest, options: {
+    signal: AbortSignal;
+}) => Promise<ApprovalDecision>;
+export interface HostExecution {
+    executionId: string;
+    signal: AbortSignal;
+    run<T>(action: () => Promise<T>, resumeApprovalId?: string): Promise<T>;
+    request(approvalId: string): ApprovalRequest;
+    settle(decision: ApprovalDecision): void;
+    finish(): void;
+}
+export interface HostControl {
+    beginExecution(options: {
+        parentToolCallId?: string;
+        caller: string;
+        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;
+export declare class HostApprovalRequired extends Error {
+    readonly request: ApprovalRequest;
+    constructor(request: ApprovalRequest);
+}
+export declare function isHostApprovalRequired(value: unknown): value is HostApprovalRequired;

package/dist/approval.js

@@ -0,0 +1,22 @@
+const controls = new WeakMap();
+export function registerHostControl(host, control) { controls.set(host, control); }
+export function getHostControl(host) {
+    const control = controls.get(host);
+    if (!control)
+        throw new Error('Unknown tool host');
+    return control;
+}
+// Identity, rather than a structural payload, identifies host control flow.
+const required = new WeakSet();
+export class HostApprovalRequired extends Error {
+    request;
+    constructor(request) {
+        super(`Approval required for ${request.toolName}`);
+        this.request = request;
+        this.name = 'HostApprovalRequired';
+        required.add(this);
+    }
+}
+export function isHostApprovalRequired(value) {
+    return typeof value === 'object' && value !== null && required.has(value);
+}