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

package/README.md

@@ -11,9 +11,10 @@ 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.
+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.
 
 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
@@ -147,9 +148,146 @@ 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.
+Keep ordinary mode for work that does not need these checkpoints. Ordinary
+execution shares its configured invocation deadline across guest code and tool
+waits (120 seconds by default); durable mode is the long-running path.
+Registered agent runs are available below; the old Flow DSL is not imported.
+
+
+## Registered agents in ordinary or durable cells
+
+`@oh-my-ai-sdk/omakase/agents` exports `mountAgents(host, options)` and
+`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.
+
+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
+access; `bun add --global pnpm@10.32.1` installs the tested prerequisite. Adapters
+and their pinned bootstrap recipes ship inside Omakase. The native CLI/SDK
+dependencies are downloaded on first use, not bundled into the MCP executable.
+Flow's content-addressed `~/.cache/ai-sdk-harness` store shares those downloads;
+`AI_SDK_HARNESS_STORE` selects a different cache. Parallel runs still have
+separate sessions and processes, not shared model credentials.
+
+For Claude with GLM, create `.omakase/agents/reviewer/agent.yaml` in your project:
+
+```yaml
+name: reviewer
+harness: glm
+permissionMode: allow-reads
+activeTools: [read]
+harnesses:
+  glm:
+    harness: claude-code
+    options:
+      auth: direct
+      model: glm-5.3
+      env:
+        ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic
+        ANTHROPIC_AUTH_TOKEN: ${ZHIPU_API_KEY}
+    sandbox:
+      type: local-persistent
+```
+
+Supply `ZHIPU_API_KEY` to the MCP server environment; alternatively use a
+`${file:/absolute/private/key-file}` reference. Do not commit credential values.
+An adjacent `instructions.md` supplies the agent's standing instructions.
+Other existing Flow names, directory references and `name#profile` references
+resolve the same way; callers cannot choose manifests, models or environment
+variables through tool arguments.
+
+`activeTools` is the native SDK's optional capability allowlist, not a prompt.
+This reviewer exposes only file reads. Omit it for the harness's usual tool set,
+or list the built-in/custom tools the role actually needs. Approval policy is
+separate; restricting capabilities does not grant approval or sandbox the agent.
+
+Create `host.config.mjs` at that project's root:
+
+```js
+import { fileURLToPath } from 'node:url';
+
+export default async ({ createAgentHost }) => createAgentHost({
+  workspaceDir: fileURLToPath(new URL('.', import.meta.url)),
+  agents: {
+    reviewer: { ref: 'reviewer#glm' },
+  },
+});
+```
+
+Connect the same MCP server as before, now using this config:
+
+```sh
+claude mcp add --scope project --transport stdio omakase -- \
+  npx -y @oh-my-ai-sdk/omakase@beta --config "$PWD/host.config.mjs"
+```
+
+Long agent sessions also need a suitable **caller's MCP request deadline**.
+For example, start Claude Code with `MCP_TOOL_TIMEOUT=900000 claude` for a
+15-minute deadline. Set this on the caller process, not in the MCP server's
+environment; other harnesses have their own request limits.
+
+Ask the caller to execute this body with `execution: "durable"`:
+
+```ts
+const reviews = await Promise.all(
+  ['README.md', 'package.json'].map(path =>
+    agents.reviewer({ prompt: `Inspect ${path}; report concrete issues.` }),
+  ),
+);
+const synthesis = await agents.reviewer({
+  prompt: `Combine these actual findings: ${JSON.stringify(reviews)}`,
+});
+return { reviews, synthesis };
+```
 
+Without `outputSchema`, a registered tool returns `{ sessionId, text }`. Set a
+registration's `outputSchema` to a concrete JSON Schema to get that structured
+value **directly** instead; its exact schema appears in the catalog and cell
+type checker. Native/answer-tool schema support depends on the selected harness;
+unsupported schemas fail rather than falling back to unvalidated prose.
+
+Omit `workspaceDir` to use the registered workspace. A per-call override must
+resolve inside that root, including symlink resolution. This selects the working
+directory; it is not filesystem confinement or a hostile-code security boundary.
+Child capabilities and permissions remain those of the trusted manifest.
+Workers inherit the MCP server's environment; a manifest's `env` is not a
+credential allowlist. Use a suitably restricted server environment.
+
+To retain skills or other tools, call `mountAgents` on your existing host. CLI
+factories receive both helpers alongside `createSkillsHost`; native applications
+import them from `/agents` and use the same host snapshots/cell frontends. Direct
+snapshot callers should provide stable `sessionId`/`harnessId` labels: repeated
+tool IDs within that context denote the same intent, and changed input conflicts.
+
+**Recovery and limits:** WDK-worker replacement reattaches still-live agent runs
+and reuses completed agent results. It does not restart an interrupted native
+agent or recover after whole-MCP-server death. Failed/unknown intents are not
+silently rerun. Runs retain private state under `~/.local/share/omakase/agents`
+(`stateDir` or `OMAKASE_AGENT_STATE_DIR` overrides it). Cancellation stops owned
+processes. A separate parent-liveness pipe also makes host death stop the worker
+and its owned native processes; it does not recover them or undo effects.
+Retained state may need reconciliation.
+`execution.json` records last-observed diagnostics, not liveness or a complete
+effect journal: abrupt cancellation can leave it marked `running`. Host receipts
+record the invocation outcome. Retention is explicit; no automatic pruning runs.
+The live host also retains invocation inputs and full settled results in memory
+for its lifetime, including ordinary calls. This beta has no bounded replay
+cache. Evicting identities blindly could repeat effects; memory grows with the
+number and size of calls. Retire only drained hosts, since host replacement
+does not recover active work.
+The default executable is `bun`; `OMAKASE_AGENT_RUNTIME_EXECUTABLE` can select an
+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
+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.
 
 ## Skill reads through Code Mode
 
@@ -210,9 +348,10 @@ 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.
+`/agents` for registered native agent runs, and `/workflow` plus `/workflow-host`
+for Workflow-backed cells. Custom ESM CLI factories can use the injected
+`createSkillsHost`, `createAgentHost` and `mountAgents` helpers without resolving
+Omakase imports from the npx cache.
 
 ## Bounds and release status