@bastani/atomic 0.5.11 → 0.5.12-0

package/.agents/skills/workflow-creator/references/getting-started.md

@@ -0,0 +1,289 @@
+# Workflow Authors: Getting Started
+
+This guide covers the basics of creating workflows with the `defineWorkflow().run().compile()` API.
+
+## Quick-start example
+
+Use `defineWorkflow<"agent">().run(callback).compile()` to define your workflow. Inside the `.run()` callback, use `ctx.stage()` to spawn agent sessions dynamically. Each session gets its own tmux window and graph node. Use native TypeScript control flow (`for`, `if`, `Promise.all()`) for orchestration.
+
+The runtime manages the full session lifecycle automatically — it creates the client, creates the session, runs your callback, then cleans up. You never need to manually disconnect or stop anything.
+
+### Claude
+
+```ts
+// .atomic/workflows/my-workflow/claude/index.ts
+import { defineWorkflow } from "@bastani/atomic/workflows";
+
+export default defineWorkflow<"claude">({
+    name: "my-workflow",
+    description: "A two-session pipeline",
+  })
+  .run(async (ctx) => {
+    // Free-form workflow: the positional CLI prompt lands under
+    // `inputs.prompt`. Destructure once and close over it in stages.
+    const prompt = ctx.inputs.prompt ?? "";
+
+    const describe = await ctx.stage(
+      { name: "describe", description: "Ask Claude to describe the project" },
+      {},
+      {},
+      async (s) => {
+        await s.session.query(prompt);
+        s.save(s.sessionId);
+      },
+    );
+
+    await ctx.stage(
+      { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      {},
+      async (s) => {
+        const research = await s.transcript(describe);
+        await s.session.query(
+          `Read ${research.path} and summarize it in 2-3 bullet points.`,
+        );
+        s.save(s.sessionId);
+      },
+    );
+  })
+  .compile();
+```
+
+### Copilot
+
+```ts
+// .atomic/workflows/my-workflow/copilot/index.ts
+import { defineWorkflow } from "@bastani/atomic/workflows";
+
+export default defineWorkflow<"copilot">({
+    name: "my-workflow",
+    description: "A two-session pipeline",
+  })
+  .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+
+    const describe = await ctx.stage(
+      { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      {},
+      async (s) => {
+        await s.session.send({ prompt });
+        s.save(await s.session.getMessages());
+      },
+    );
+
+    await ctx.stage(
+      { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      {},
+      async (s) => {
+        const research = await s.transcript(describe);
+        await s.session.send({
+          prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
+        });
+        s.save(await s.session.getMessages());
+      },
+    );
+  })
+  .compile();
+```
+
+### OpenCode
+
+```ts
+// .atomic/workflows/my-workflow/opencode/index.ts
+import { defineWorkflow } from "@bastani/atomic/workflows";
+
+export default defineWorkflow<"opencode">({
+    name: "my-workflow",
+    description: "A two-session pipeline",
+  })
+  .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+
+    const describe = await ctx.stage(
+      { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      { title: "describe" },
+      async (s) => {
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
+          parts: [{ type: "text", text: prompt }],
+        });
+        s.save(result.data!);
+      },
+    );
+
+    await ctx.stage(
+      { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      { title: "summarize" },
+      async (s) => {
+        const research = await s.transcript(describe);
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
+          parts: [{ type: "text", text: `Summarize the following in 2-3 bullet points:\n\n${research.content}` }],
+        });
+        s.save(result.data!);
+      },
+    );
+  })
+  .compile();
+```
+
+Reading top-to-bottom: `describe → summarize`. Each session spawns a graph node and tmux window.
+
+## Native TypeScript control flow
+
+Sessions are spawned dynamically, so you can use loops, conditionals, and `Promise.all()`:
+
+```ts
+// Parallel sessions
+const [a, b] = await Promise.all([
+  ctx.stage({ name: "task-a" }, {}, {}, async (s) => { /* ... */ }),
+  ctx.stage({ name: "task-b" }, {}, {}, async (s) => { /* ... */ }),
+]);
+
+// Loop with dynamic sessions
+for (let i = 1; i <= maxIterations; i++) {
+  const result = await ctx.stage({ name: `step-${i}` }, {}, {}, async (s) => {
+    // ... do work ...
+    return someValue; // available as result.result
+  });
+  if (result.result === "done") break;
+}
+
+// Conditional sessions
+if (needsReview) {
+  await ctx.stage({ name: "review" }, {}, {}, async (s) => { /* ... */ });
+}
+```
+
+## Headless (background) stages
+
+Stages can run in headless mode by setting `headless: true` in the first argument to `ctx.stage()`. Headless stages execute the provider SDK in-process instead of spawning a tmux window — they are invisible in the workflow graph but tracked via a background task counter in the statusline.
+
+```ts
+// Headless stage — identical callback API, no tmux window
+const result = await ctx.stage(
+  { name: "background-task", headless: true },
+  {}, {},
+  async (s) => {
+    // s.client, s.session, s.save(), s.transcript() all work identically
+    const result = await s.session.query("Analyze the codebase.");
+    s.save(s.sessionId);
+    return result.output;
+  },
+);
+// result.result contains the returned value
+```
+
+The callback interface is identical to interactive stages. The only differences:
+- No tmux window is created
+- The stage does not appear as a node in the workflow graph
+- The `paneId` is a virtual identifier: `headless-<name>-<sessionId>`
+- Background stages are tracked by a counter in the orchestrator statusline
+
+**Common pattern — visible seed, parallel headless gather, visible merge:**
+
+```ts
+const seed = await ctx.stage({ name: "seed" }, {}, {}, async (s) => { /* ... */ });
+
+const [a, b, c] = await Promise.all([
+  ctx.stage({ name: "gather-a", headless: true }, {}, {}, async (s) => { /* ... */ }),
+  ctx.stage({ name: "gather-b", headless: true }, {}, {}, async (s) => { /* ... */ }),
+  ctx.stage({ name: "gather-c", headless: true }, {}, {}, async (s) => { /* ... */ }),
+]);
+
+await ctx.stage({ name: "merge" }, {}, {}, async (s) => {
+  await s.session.query(`Merge:\n${a.result}\n${b.result}\n${c.result}`);
+  s.save(s.sessionId);
+});
+```
+
+Headless stages are transparent to graph topology — `seed → [3 headless] → merge` renders as `seed → merge` in the graph.
+
+## SDK exports
+
+The `@bastani/atomic/workflows` package exports the workflow authoring primitives. For native SDK types and utilities, install and import from the provider packages directly.
+
+**Builder:**
+- `defineWorkflow` — entry point, accepts an optional type parameter (`"claude"`, `"copilot"`, `"opencode"`) for type narrowing; returns a chainable `WorkflowBuilder`
+- `WorkflowBuilder` — the builder class (rarely needed directly)
+
+**Types** (import with `import type`):
+- `AgentType` — `"copilot" | "opencode" | "claude"`
+- `Transcript` — `{ path: string, content: string }` from `ctx.transcript()`
+- `SavedMessage` — union of provider-specific message types
+- `SaveTranscript` — overloaded save function type
+- `SessionContext` — the context object passed to `ctx.stage()` callbacks
+- `SessionHandle<T>` — returned by `ctx.stage()`, carries `{ name, id, result }`
+- `SessionRunOptions` — `{ name, description?, headless? }` for `ctx.stage()` first argument
+- `StageClientOptions<A>` — provider-specific client init options for `ctx.stage()` second argument
+- `StageSessionOptions<A>` — provider-specific session create options for `ctx.stage()` third argument
+- `ProviderClient<A>` — the `s.client` type, resolved by agent type
+- `ProviderSession<A>` — the `s.session` type, resolved by agent type
+- `ClaudeSessionWrapper` — Atomic wrapper for Claude sessions (exposes `s.session.query()`)
+- `ClaudeQueryDefaults` — per-stage query defaults (timeouts, poll interval) for Claude sessions
+- `SessionRef` — `string | SessionHandle<unknown>` for transcript/message lookups
+- `WorkflowContext` — top-level context passed to `.run()` callback
+- `WorkflowOptions` — `{ name, description? }` workflow metadata
+- `WorkflowDefinition` — sealed output of `.compile()`
+
+**Validation helpers:**
+- `validateClaudeWorkflow` — static validation for Claude workflow source files; warns on direct `createClaudeSession` or `claudeQuery` usage
+- `validateCopilotWorkflow` — static validation for Copilot workflow source files; warns on manual `new CopilotClient` or `client.createSession()` usage
+- `validateOpenCodeWorkflow` — static validation for OpenCode workflow source files; warns on manual `createOpencodeClient()` or `client.session.create()` usage
+
+**Native SDK dependencies:**
+
+The Atomic runtime provides `s.client` and `s.session` with types resolved from the native SDKs. If you need to name those types in your own code, or use SDK utilities and advanced APIs, import them directly from the provider packages:
+
+| Provider | Package | Key imports |
+|----------|---------|-------------|
+| Copilot | `@github/copilot-sdk` | `SessionEvent`, `CopilotClient`, `CopilotSession`, `approveAll`, `defineTool` |
+| Claude | `@anthropic-ai/claude-agent-sdk` | `SessionMessage`, `query` |
+| OpenCode | `@opencode-ai/sdk/v2` | `SessionPromptResponse`, `OpencodeClient`, `Session` |
+
+## `SessionContext` reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `client` | `ProviderClient<A>` | Pre-created SDK client (auto-managed by runtime) |
+| `session` | `ProviderSession<A>` | Pre-created provider session (auto-managed by runtime) |
+| `inputs` | `Record<string, string>` | Structured inputs for this run. Free-form workflows read `s.inputs.prompt`; structured workflows read their declared field names. See `workflow-inputs.md`. |
+| `agent` | `AgentType` | Which agent is running |
+| `transcript(ref)` | `(ref: SessionRef) => Promise<Transcript>` | Get prior session's transcript as `{ path, content }` |
+| `getMessages(ref)` | `(ref: SessionRef) => Promise<SavedMessage[]>` | Get prior session's raw native messages |
+| `save` | `SaveTranscript` | Save this session's output for downstream sessions |
+| `sessionDir` | `string` | Path to session storage directory |
+| `paneId` | `string` | tmux pane ID (or `headless-<name>-<id>` for headless stages) |
+| `sessionId` | `string` | Session UUID |
+| `stage(opts, clientOpts, sessionOpts, fn)` | `<T>(...) => Promise<SessionHandle<T>>` | Spawn a nested sub-session (child of this session in the graph) |
+
+## Reference files
+
+| File | Topic |
+|---|---|
+| `workflow-inputs.md` | Declaring the `inputs: WorkflowInput[]` schema, the free-form vs structured decision, CLI flag + picker invocation surfaces, builtin protection |
+| `agent-sessions.md` | Creating agent sessions with SDK calls per provider |
+| `computation-and-validation.md` | Deterministic computation, parsing, validation inside `run()` |
+| `user-input.md` | Collecting user input **mid-workflow** (for invocation-time inputs, see `workflow-inputs.md`) |
+| `control-flow.md` | Loops, conditionals, early termination in plain TypeScript |
+| `state-and-data-flow.md` | Data flow between sessions, transcripts, persistence |
+| `session-config.md` | Per-SDK session configuration: model, tools, permissions, hooks |
+| `discovery-and-verification.md` | Workflow file discovery, validation, TypeScript config |
+
+## Builtin reference implementations
+
+The SDK ships two builtin workflows that demonstrate production patterns for all three SDKs:
+
+- **`ralph`** (`src/sdk/workflows/builtin/ralph/`) — iterative plan → orchestrate → review → debug loop with consecutive clean-pass detection, shared helpers for prompts/parsing/git, and cross-SDK adaptation
+- **`deep-research-codebase`** (`src/sdk/workflows/builtin/deep-research-codebase/`) — deterministic codebase scout → LOC-based heuristic explorer partitioning → parallel explorers → aggregator with file-based handoffs and context-aware prompt engineering
+- **`headless-test`** (`.atomic/workflows/headless-test/`) — demonstrates the visible → [parallel headless] → visible merge pattern (all 3 SDKs)
+
+Both include `helpers/` directories with SDK-agnostic logic (prompt builders, parsers, heuristics) and per-agent `index.ts` files showing how the same workflow topology adapts to Claude, Copilot, and OpenCode.
+
+## Type safety
+
+The SDK is typed with **no `unknown` or `any`**. `SessionContext` fields are precisely typed, and native provider types may appear inside Atomic generic aliases and runtime values — if you need to name those types in your own code, import them from the provider SDK directly. Use `import type` for type-only imports. Use the `defineWorkflow<"agent">()` type parameter to narrow `s.client` and `s.session` to the correct provider types.

package/.agents/skills/workflow-creator/references/session-config.md

@@ -0,0 +1,355 @@
+# Session Configuration
+
+Each SDK has its own configuration options for controlling model selection, tools, permissions, hooks, and structured output. Pass these via `clientOpts` (2nd arg to `ctx.stage()`) and `sessionOpts` (3rd arg to `ctx.stage()`). The runtime uses them to create the client and session automatically — no manual client or session creation needed.
+
+## Claude Agent SDK
+
+### Client options (`clientOpts` — 2nd arg to `ctx.stage()`)
+
+These control how the Claude TUI pane is started:
+
+```ts
+await ctx.stage({ name: "..." }, {
+  chatFlags: ["--model", "opus", "--dangerously-skip-permissions"],
+  readyTimeoutMs: 60_000,  // Wait up to 60s for TUI (default: 30s)
+}, {}, async (s) => {
+  // s.client and s.session are ready
+});
+```
+
+### Session options (`sessionOpts` — 3rd arg to `ctx.stage()`)
+
+These are `ClaudeQueryDefaults` and set defaults for every `s.session.query()`
+call inside the callback (`timeoutMs`, `pollIntervalMs`, etc.):
+
+```ts
+await ctx.stage({ name: "..." }, {}, {
+  timeoutMs: 5 * 60 * 1000,     // 5 minutes per query (default)
+  pollIntervalMs: 1_000,         // Poll interval for output
+}, async (s) => {
+  await s.session.query((ctx.inputs.prompt ?? ""));
+  s.save(s.sessionId);
+});
+```
+
+### `query()` options
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const result = query({
+  prompt: (ctx.inputs.prompt ?? ""),
+  options: {
+    // Model selection
+    model: "claude-opus-4-6",         // Full model ID or alias ("opus", "sonnet", "haiku")
+    effort: "high",                   // "low", "medium", "high", "max" (max is Opus 4.6 only)
+    thinking: { type: "adaptive" },   // Default for supported models; or { type: "enabled", budgetTokens: N }
+    maxTurns: 50,                     // Maximum conversation turns
+    maxBudgetUsd: 5.0,                // Spending cap in USD
+
+    // Permissions
+    permissionMode: "acceptEdits",    // "default", "dontAsk", "acceptEdits", "bypassPermissions", "plan"
+
+    // Tools — base set of available built-in tools
+    tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],  // or { type: "preset", preset: "claude_code" } for all defaults
+    allowedTools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],  // auto-allowed without prompting
+    disallowedTools: ["AskUserQuestion"],  // removed from model's context
+
+    // System prompt — string or preset with additions
+    systemPrompt: "You are a senior security auditor...",
+    // Or: { type: "preset", preset: "claude_code", append: "Always explain your reasoning." }
+
+    // Structured output
+    outputFormat: {
+      type: "json_schema",
+      schema: {
+        type: "object",
+        properties: {
+          tasks: { type: "array", items: { type: "string" } },
+        },
+      },
+    },
+
+    // Subagents — Record<string, AgentDefinition> keyed by name
+    agents: {
+      worker: { description: "Implement tasks", prompt: "You are a task implementer...", tools: ["Read", "Write", "Edit", "Bash"] },
+    },
+    agent: "worker",                  // Main thread agent name (optional)
+
+    // MCP servers
+    mcpServers: {
+      "my-server": { command: "node", args: ["server.js"] },
+    },
+
+    // Session continuity
+    resume: previousSessionId,         // Resume a prior session
+    forkSession: true,                 // When true with resume, forks to new session
+    persistSession: true,              // Persist session to disk (default: true)
+
+    // Sandbox — isolated command execution
+    sandbox: { enabled: true, autoAllowBashIfSandboxed: true },
+
+    // Beta features
+    betas: ["context-1m-2025-08-07"], // 1M context window (Sonnet 4/4.5 only)
+  },
+});
+```
+
+### `s.session.query()` usage
+
+`s.session.query()` sends text to the Claude pane, verifies delivery, and waits for output stabilization. It uses
+the pane ID from `s.paneId` automatically. Call it inside the stage callback:
+
+```ts
+await ctx.stage({ name: "..." }, {}, {}, async (s) => {
+  const result = await s.session.query("Your prompt");
+  // result.output — captured response text
+  s.save(s.sessionId);
+});
+```
+
+The query defaults (timeout, poll interval) can be configured via `sessionOpts`
+as shown above.
+
+### Claude hooks
+
+Hooks intercept tool usage, session events, and context management. The `hooks` option is `Partial<Record<HookEvent, HookCallbackMatcher[]>>` — each event maps to an array of matchers with callback arrays:
+
+```ts
+const result = query({
+  prompt: (ctx.inputs.prompt ?? ""),
+  options: {
+    hooks: {
+      PreToolUse: [{
+        matcher: (input) => input.tool_name === "Bash",  // Optional — filter which events trigger this hook
+        hooks: [async (input, toolUseID, { signal }) => {
+          // input.tool_name, input.tool_input available
+          if (input.tool_input?.command?.includes("rm -rf")) {
+            return { decision: "deny", reason: "Dangerous command" };
+          }
+          return { decision: "allow" };
+          // Return values: { decision: "allow" | "deny" | "ask" | "defer" }
+        }],
+      }],
+      PostToolUse: [{
+        hooks: [async (input) => {
+          // React after a tool completes
+          console.log(`Tool ${input.tool_name} completed`);
+        }],
+      }],
+      Stop: [{
+        hooks: [async (input) => {
+          // Called when the agent wants to stop
+        }],
+      }],
+      PreCompact: [{
+        hooks: [async (input) => {
+          // Before context compaction — inject durable context
+          return { additionalContext: "Remember: always run tests after edits." };
+        }],
+      }],
+    },
+  },
+});
+```
+
+**Hook events** (most commonly used): `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SessionStart`, `SessionEnd`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `Notification`, `PermissionRequest`, `PermissionDenied`, `Elicitation`, `ElicitationResult`, `ConfigChange`, `FileChanged`, `CwdChanged`.
+
+## Copilot SDK
+
+### Session options (`sessionOpts` — 3rd arg to `ctx.stage()`)
+
+All `client.createSession()` options are passed as `sessionOpts`. The runtime
+forwards them to `client.createSession()`. `onPermissionRequest` defaults to
+`approveAll` when not specified.
+
+```ts
+import { approveAll, defineTool } from "@github/copilot-sdk";
+
+await ctx.stage({ name: "plan" }, {}, {
+  // Model selection
+  model: "claude-sonnet-4.6",
+  reasoningEffort: "high",
+
+  // System prompt
+  systemMessage: "You are a security auditor...",
+
+  // Custom tools
+  tools: [
+    defineTool({
+      name: "check-coverage",
+      description: "Check test coverage",
+      parameters: { type: "object", properties: { path: { type: "string" } } },
+      execute: async (params) => ({ content: "Coverage: 85%" }),
+    }),
+  ],
+
+  // Permissions (defaults to approveAll if omitted)
+  onPermissionRequest: approveAll,
+
+  // User input
+  onUserInputRequest: async (request) => {
+    return "User's response";
+  },
+  onElicitationRequest: async (request) => {
+    return { action: "submit", values: { choice: "option-a" } };
+  },
+
+  // Hooks
+  hooks: {
+    onPreToolUse: (event) => { /* before tool */ },
+    onPostToolUse: (event) => { /* after tool */ },
+    onSessionStart: (event) => { /* session started */ },
+    onSessionEnd: (event) => { /* session ended */ },
+    onErrorOccurred: (event) => { /* error handling */ },
+  },
+
+  // Advanced
+  infiniteSessions: true,             // Auto-manage context via compaction
+}, async (s) => {
+  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  s.save(await s.session.getMessages());
+});
+```
+
+### Copilot permission modes
+
+```ts
+// Approve everything (autonomous) — this is the default
+await ctx.stage({ name: "plan" }, {}, { onPermissionRequest: approveAll }, async (s) => {
+  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  s.save(await s.session.getMessages());
+});
+
+// Custom permission handler
+await ctx.stage({ name: "plan" }, {}, {
+  onPermissionRequest: async (request) => {
+    // request.kind: "shell" | "write" | "read" | "mcp" | "custom-tool" | "url" | "memory" | "hook"
+    switch (request.kind) {
+      case "shell":
+        return request.command?.includes("rm")
+          ? { kind: "denied-permanently", reason: "Dangerous" }
+          : { kind: "approved" };
+      case "write":
+        return { kind: "approved" };
+      default:
+        return { kind: "approved" };
+    }
+  },
+}, async (s) => {
+  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  s.save(await s.session.getMessages());
+});
+```
+
+## OpenCode SDK
+
+### Client options (`clientOpts` — 2nd arg to `ctx.stage()`)
+
+The `baseUrl` is auto-injected by the runtime. Pass any additional client
+options (such as `directory`) via `clientOpts`:
+
+```ts
+await ctx.stage({ name: "..." }, {
+  directory: "/path/to/project",   // Override working directory
+}, {}, async (s) => {
+  // s.client is the OpencodeClient, already connected
+});
+```
+
+### Session options (`sessionOpts` — 3rd arg to `ctx.stage()`)
+
+These are forwarded to `client.session.create()`. Use them to set a title,
+parentID, or workspaceID for the session:
+
+```ts
+await ctx.stage({ name: "..." }, {}, {
+  title: "Feature implementation",
+  parentID: "parent-session-id",
+  workspaceID: "workspace-id",
+}, async (s) => {
+  // s.session is the created OpencodeSession, s.session.id is the session ID
+});
+```
+
+### Session prompting
+
+Use `s.client` and `s.session.id` inside the callback:
+
+```ts
+await ctx.stage({ name: "implement" }, {}, {}, async (s) => {
+  // Basic prompt
+  const result = await s.client.session.prompt({
+    sessionID: s.session.id,
+    parts: [{ type: "text", text: (ctx.inputs.prompt ?? "") }],
+  });
+
+  // Structured output
+  const structured = await s.client.session.prompt({
+    sessionID: s.session.id,
+    parts: [{ type: "text", text: "List endpoints as JSON" }],
+    format: {
+      type: "json_schema",
+      schema: { type: "object", properties: { endpoints: { type: "array" } } },
+      retryCount: 3,
+    },
+  });
+
+  // No-reply context injection
+  await s.client.session.prompt({
+    sessionID: s.session.id,
+    parts: [{ type: "text", text: "Background context..." }],
+    noReply: true,
+  });
+
+  s.save(result.data!);
+});
+```
+
+### OpenCode session management
+
+```ts
+await ctx.stage({ name: "..." }, {}, {}, async (s) => {
+  // Select session in TUI (auto-called by runtime, but can be called again)
+  await s.client.tui.selectSession({ sessionID: s.session.id });
+
+  // Fork session
+  await s.client.session.fork({ sessionID: s.session.id, messageID: "..." });
+
+  // Abort
+  await s.client.session.abort({ sessionID: s.session.id });
+
+  // Session messages
+  const messages = await s.client.session.messages({ sessionID: s.session.id });
+});
+```
+
+### OpenCode event streaming
+
+```ts
+await ctx.stage({ name: "..." }, {}, {}, async (s) => {
+  const unsubscribe = await s.client.event.subscribe((event) => {
+    switch (event.type) {
+      case "session.updated":
+        console.log("Session updated");
+        break;
+      case "message.created":
+        console.log("New message");
+        break;
+    }
+  });
+});
+```
+
+### OpenCode permissions
+
+```ts
+await ctx.stage({ name: "..." }, {}, {}, async (s) => {
+  // Handle permission requests
+  await s.client.session.permission({
+    sessionID: s.session.id,
+    permissionID: "...",
+    approved: true,
+  });
+});
+```