@tagma/sdk 0.7.1 → 0.7.4

package/README.md

@@ -64,6 +64,8 @@ console.log(result.success ? 'Done' : 'Failed');
 
 The package root is intentionally small. Use explicit subpaths for YAML,
 config editing, plugin registry helpers, and low-level dataflow utilities.
+The SDK composes `@tagma/core` with `@tagma/runtime-bun`; import those packages
+directly only when you need lower-level package boundaries.
 
 ## Features
 
@@ -75,8 +77,7 @@ config editing, plugin registry helpers, and low-level dataflow utilities.
 - **Middleware** -- enrich prompts before execution (e.g. inject static context)
 - **Completion checks** -- validate task output with `exit_code`, `file_exists`, or `output_check` plugins
 - **Plugin schemas** -- triggers/completions/middlewares can declare a `PluginSchema` so visual editors render typed forms for their config
-- **Lightweight task bindings** -- pass dynamic values with task-level `inputs` / `outputs` without declaring a typed contract
-- **Typed task ports** -- declare named, typed `ports.inputs` / `ports.outputs` when a task needs a strict, validated I/O contract
+- **Unified task bindings** -- pass dynamic values with task-level `inputs` / `outputs`; add optional `type` metadata when a binding needs validation
 
 ## Pipeline YAML Reference
 
@@ -205,9 +206,8 @@ Each hook value can be a single command string or an array of commands.
 | `middlewares`   | `MiddlewareConfig[]` | No       | Inherited from track | Middleware override. Set `[]` to disable inherited middlewares                                         |
 | `trigger`       | `TriggerConfig`      | No       | —                    | Gate that must resolve before the task runs (see Triggers)                                             |
 | `completion`    | `CompletionConfig`   | No       | —                    | Post-execution check to validate task output (see Completions)                                         |
-| `inputs`        | `TaskInputBindings`  | No       | —                    | Lightweight parameter bindings for `{{inputs.<name>}}`                                                 |
-| `outputs`       | `TaskOutputBindings` | No       | —                    | Lightweight named outputs published after success                                                      |
-| `ports`         | `TaskPorts`          | No       | —                    | Typed input/output ports — see Typed Ports below                                                       |
+| `inputs`        | `TaskInputBindings`  | No       | —                    | Task input bindings for `{{inputs.<name>}}`; optional `type` enables coercion/validation                |
+| `outputs`       | `TaskOutputBindings` | No       | —                    | Named outputs published after success; optional `type` enables coercion/validation                      |
 
 ### Permissions
 
@@ -227,15 +227,17 @@ Track-level `middlewares` apply to all tasks in the track. Setting task-level `m
 
 ---
 
-### Lightweight Bindings
+### Unified Task Bindings
 
-Use task-level `inputs` / `outputs` for ordinary parameter passing. They are task-level only, do not inherit, and do not add prompt schema blocks or type coercion.
+Use task-level `inputs` / `outputs` for parameter passing. They are task-level only, do not inherit, and can stay lightweight by omitting `type`. Add `type`, `required`, `enum`, and `description` when a binding should be strict and editor-visible.
 
 ```yaml
 - id: build
   command: bun run build
   outputs:
-    bundlePath: { from: json.bundlePath }
+    bundlePath:
+      from: json.bundlePath
+      type: string
 
 - id: test
   depends_on: [build]
@@ -244,17 +246,18 @@ Use task-level `inputs` / `outputs` for ordinary parameter passing. They are tas
     bundlePath:
       from: t.build.outputs.bundlePath
       required: true
+      type: string
 ```
 
-Input bindings support `value`, `from`, `default`, and `required`. `from` accepts `taskId.outputs.name`, `taskId.stdout`, `taskId.stderr`, `taskId.normalizedOutput`, `taskId.exitCode`, or `outputs.name` to name-match direct upstream outputs.
+Input bindings support `value`, `from`, `default`, `required`, optional `type`, `enum`, and `description`. `from` accepts `taskId.outputs.name`, `taskId.stdout`, `taskId.stderr`, `taskId.normalizedOutput`, `taskId.exitCode`, or `outputs.name` to name-match direct upstream outputs.
 
-Output bindings support `value`, `from`, and `default`. `from` defaults to `json.<outputName>` and also accepts `stdout`, `stderr`, or `normalizedOutput`.
+Output bindings support `value`, `from`, `default`, optional `type`, `enum`, and `description`. `from` defaults to `json.<outputName>` and also accepts `stdout`, `stderr`, or `normalizedOutput`.
 
-Use `ports` instead when downstream tasks need required typed values, the editor should present a stable I/O contract, or prompt tasks should receive `[Inputs]` / `[Output Format]` blocks.
+Prompt tasks infer their structured input/output contract from neighboring command tasks that use typed `outputs` / `inputs`. The engine renders `[Inputs]` and `[Output Format]` blocks from that inferred contract.
 
 ---
 
-### Typed Ports
+### Typed Binding Example
 
 Tasks can declare named, typed `inputs` / `outputs`. Inputs flow in from upstream task outputs; outputs are extracted from a task's stdout (or the AI driver's `normalizedOutput`) on success.
 
@@ -262,40 +265,50 @@ Tasks can declare named, typed `inputs` / `outputs`. Inputs flow in from upstrea
 - id: lookup-weather
   name: Lookup weather
   command: weather.sh --city "{{inputs.city}}"
-  ports:
-    inputs:
-      - { name: city, type: string, required: true, description: Target city }
-    outputs:
-      - { name: temperature, type: number, description: Current temperature in Celsius }
-      - { name: conditions, type: enum, enum: [sunny, cloudy, rain, snow] }
+  inputs:
+    city:
+      type: string
+      required: true
+      description: Target city
+  outputs:
+    temperature:
+      type: number
+      description: Current temperature in Celsius
+    conditions:
+      type: enum
+      enum: [sunny, cloudy, rain, snow]
 
 - id: write-report
   depends_on: [lookup-weather]
   prompt: 'Write a brief weather report for {{inputs.city}}.'
-  ports:
-    inputs:
-      - { name: city, type: string, required: true }
-      - { name: temperature, type: number, required: true }
-      - { name: conditions, type: enum, enum: [sunny, cloudy, rain, snow] }
+  inputs:
+    city: { from: t.lookup-weather.outputs.city, type: string, required: true }
+    temperature: { from: t.lookup-weather.outputs.temperature, type: number, required: true }
+    conditions:
+      from: t.lookup-weather.outputs.conditions
+      type: enum
+      enum: [sunny, cloudy, rain, snow]
 ```
 
-#### `PortDef` fields
+#### Binding fields
 
 | Field         | Type                                                  | Required | Description                                                                                                                                                                       |
 | ------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`        | `string`                                              | Yes      | Port name; also the substitution key (`{{inputs.<name>}}`)                                                                                                                        |
-| `type`        | `'string' \| 'number' \| 'boolean' \| 'enum' \| 'json'` | Yes      | Coercion type. Mismatched values block the task with a typed-error diagnostic                                                                                                     |
+| `value`       | `unknown`                                             | No       | Literal value. For inputs, this wins over `from`                                                                                                                                  |
+| `from`        | `string`                                              | No       | Inputs: upstream source such as `taskId.outputs.name`, `taskId.stdout`, or `outputs.name`. Outputs: `json.<key>`, `stdout`, `stderr`, or `normalizedOutput`                      |
+| `default`     | `unknown`                                             | No       | Fallback value when the source is missing                                                                                                                                         |
+| `required`    | `boolean`                                             | Inputs only | When `true`, missing upstream value and no `default` blocks the task                                                                                                           |
+| `type`        | `'string' \| 'number' \| 'boolean' \| 'enum' \| 'json'` | No       | Optional coercion type. Omit it for pass-through values                                                                                                                           |
 | `description` | `string`                                              | No       | Free-text description; rendered into the `[Inputs]` / `[Output Format]` blocks                                                                                                    |
-| `required`    | `boolean`                                             | No       | Inputs only. When `true`, missing upstream value (and no `default`) blocks the task                                                                                               |
-| `default`     | `unknown`                                             | No       | Inputs only. Fallback value when no upstream produces the port                                                                                                                    |
 | `enum`        | `string[]`                                            | When `type: enum` | Allowed values                                                                                                                                                                    |
-| `from`        | `string`                                              | No       | Inputs only. Explicit upstream binding — bare `portName` (match by name) or `taskId.portName` (fully qualified). Unset = match by name across all direct upstreams; ambiguous matches block |
 
 #### Substitution and AI prompt blocks
 
 - `{{inputs.<name>}}` is expanded verbatim in `command` and `prompt` strings before execution. Quote your placeholders in command lines (`--city "{{inputs.city}}"`) — the engine does not shell-escape.
-- AI tasks additionally get two prepended `PromptContextBlock`s: `[Output Format]` (instructs the model to emit a final-line JSON object matching the declared outputs) and `[Inputs]` (renders the resolved inputs as `name: value  # description`). Tasks without ports get no extra blocks.
-- Output extraction strategy: prefer `normalizedOutput` (AI tasks), fall back to stdout (command tasks). Find the last non-empty line that parses as a JSON object, then read each declared output key. Failures append a diagnostic to stderr; the port is absent from `outputs` and downstream tasks see it as missing.
+- AI tasks get `[Output Format]` and `[Inputs]` blocks when typed bindings can be inferred from neighboring command tasks.
+- Output extraction strategy: prefer `normalizedOutput` (AI tasks), fall back to stdout (command tasks). Find the last non-empty line that parses as a JSON object, then read each declared output key. Failures append a diagnostic to stderr; the binding is absent from `outputs` and downstream tasks see it as missing.
+
+YAML `ports` has been replaced by typed `inputs` / `outputs`. `validateRaw` reports any `ports` field as a migration error.
 
 ---
 
@@ -363,9 +376,10 @@ Tasks can declare named, typed `inputs` / `outputs`. Inputs flow in from upstrea
 ### Root: `@tagma/sdk`
 
 - `createTagma(options?)`
+- `bunRuntime()`
 - `definePipeline(pipeline)`
 - `PluginRegistry`
-- stable pipeline/result/event types
+- stable pipeline/result/event/plugin/runtime types, including `TagmaPlugin` and `TagmaRuntime`
 - trigger error classes
 
 ### YAML: `@tagma/sdk/yaml`
@@ -391,10 +405,22 @@ Tasks can declare named, typed `inputs` / `outputs`. Inputs flow in from upstrea
 - raw validation helpers
 - task reference helpers
 
-### Ports: `@tagma/sdk/ports`
+### Dataflow helpers: `@tagma/sdk/ports`
 
-- current dataflow helpers for placeholder substitution, binding resolution,
-  output extraction, and prompt-port inference
+- placeholder substitution, binding resolution, output extraction, and internal prompt-contract inference
+- the subpath name is historical; YAML `ports` is rejected by validation
+
+### Runtime approval adapters
+
+- `@tagma/sdk/runtime/adapters/stdin-approval`
+- `@tagma/sdk/runtime/adapters/websocket-approval`
+- the older `@tagma/sdk/adapters/*` subpaths remain thin compatibility re-exports
+
+### Split packages
+
+- `@tagma/core` -- runtime-independent orchestration, registry, approval, logging, event/result types, and the `TagmaRuntime` interface
+- `@tagma/runtime-bun` -- Bun process execution, file watching, log storage, `bunRuntime()`, and runtime approval adapters
+- `@tagma/sdk` -- convenience package that composes core + Bun runtime + built-in plugins
 
 ### `bootstrapBuiltins(registry)`
 
@@ -404,6 +430,17 @@ Registers all built-in plugins (opencode driver, file/manual triggers, completio
 
 Parses YAML, resolves inheritance, and validates the configuration.
 
+### `createTagma(options?)`
+
+Creates an isolated SDK instance with its own plugin registry.
+
+Options:
+
+- `registry` -- use an existing `PluginRegistry` instance
+- `builtins` -- register built-in plugins into the instance registry; defaults to `true`
+- `plugins` -- register package-level `TagmaPlugin` capability objects into the instance registry
+- `runtime` -- override process execution, file watching, file existence checks, log storage, time, and sleep; defaults to `bunRuntime()`
+
 ### `createTagma().run(config, options): Promise<EngineResult>`
 
 Executes the pipeline. Returns `{ success, runId, logPath, summary, states }`.
@@ -414,7 +451,7 @@ Options:
 - `signal` -- `AbortSignal` to cancel the run externally
 - `onEvent` -- callback for real-time `RunEventPayload` updates. Every payload carries `runId`. The editor server stamps a per-run `seq` on top of this payload before broadcasting over SSE (producing a `WireRunEvent`); the SDK itself does not stamp `seq`. Event variants:
   - `run_start` — pipeline approved and all tasks transitioned to `waiting`; includes `tasks: RunTaskState[]` (wire-shape snapshot of every task). Fires only when the `pipeline_start` hook allows the run — blocked pipelines emit no wire events at all.
-  - `task_update` — a task's status or result changed; flat fields (`status`, `startedAt?`, `finishedAt?`, `durationMs?`, `exitCode?`, `stdout?`, `stderr?`, `stdoutPath?`, `stderrPath?`, `stdoutBytes?`, `stderrBytes?`, `sessionId?`, `normalizedOutput?`, `outputs?`, `inputs?`, `resolvedDriver?`, `resolvedModel?`, `resolvedPermissions?`) so clients can fold partial updates with `??` semantics. `inputs` carries the resolved port input map (set once just before the task transitions to `running`); `outputs` carries the extracted port output map after a successful terminal transition. `startedAt` is populated before the `running` transition; `finishedAt` and result fields are populated before any terminal-status transition. Terminal-state locking in the engine guarantees at most one terminal event per task.
+  - `task_update` — a task's status or result changed; flat fields (`status`, `startedAt?`, `finishedAt?`, `durationMs?`, `exitCode?`, `stdout?`, `stderr?`, `stdoutPath?`, `stderrPath?`, `stdoutBytes?`, `stderrBytes?`, `sessionId?`, `normalizedOutput?`, `outputs?`, `inputs?`, `resolvedDriver?`, `resolvedModel?`, `resolvedPermissions?`) so clients can fold partial updates with `??` semantics. `inputs` carries the resolved task input map (set once just before the task transitions to `running`); `outputs` carries the extracted binding output map after a successful terminal transition. `startedAt` is populated before the `running` transition; `finishedAt` and result fields are populated before any terminal-status transition. Terminal-state locking in the engine guarantees at most one terminal event per task.
   - `task_log` — a structured log line was written to `pipeline.log`. Mirrors every `Logger` call (info/warn/error/debug/section/quiet) and carries `{ taskId: string | null, level, timestamp, text }`. `taskId` is non-null for lines tagged with a `[task:<id>]` prefix (or passed explicitly to `section`/`quiet`) and `null` for pipeline-wide messages such as the configuration dump and DAG topology. Use this to stream the full run process into UIs without tailing the log file.
   - `run_end` — pipeline finished; includes `success: boolean` and `abortReason: 'timeout' | 'stop_all' | 'external' | null`. `null` means the run completed on its own steam (success may still be `false` if tasks failed).
   - `run_error` — reserved for fatal engine errors surfaced over the wire.
@@ -423,7 +460,7 @@ Options:
 - `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
 - `skipPluginLoading` -- skip the engine's built-in `loadPlugins(config.plugins)` call. Set this when the host has already pre-loaded plugins from a custom resolution path (e.g. the editor loading from the user's workspace `node_modules`) so the engine doesn't re-resolve them via Node's default cwd-based import.
 
-> **stdout / stderr persistence.** The engine streams every task's stdout and stderr to disk under `<workDir>/.tagma/logs/<runId>/<taskId>.stdout` and `.stderr`. The `TaskResult.stdout` / `stderr` strings are bounded tails (8 MB / 4 MB by default) — long outputs are truncated from the head with a marker, and consumers that need the full bytes should read `TaskResult.stdoutPath` / `stderrPath`. Use `TaskResult.stdoutBytes` / `stderrBytes` to display "32 MB (truncated)" without re-stat'ing the file.
+> **stdout / stderr persistence.** With the default Bun runtime, the engine streams every task's stdout and stderr to disk under `<workDir>/.tagma/logs/<runId>/<taskId>.stdout` and `.stderr`. Custom runtimes can relocate those artifacts by implementing `runtime.logStore.taskOutputPath()`. The `TaskResult.stdout` / `stderr` strings are bounded tails (8 MB / 4 MB by default) — long outputs are truncated from the head with a marker, and consumers that need the full bytes should read `TaskResult.stdoutPath` / `stderrPath`. Use `TaskResult.stdoutBytes` / `stderrBytes` to display "32 MB (truncated)" without re-stat'ing the file.
 
 ### `PipelineRunner`
 
@@ -460,7 +497,7 @@ Properties:
 
 Typed error classes for trigger plugin error classification. The engine uses `instanceof` checks on these to set the correct task status (`blocked` or `timeout`) instead of matching on error message substrings.
 
-Built-in triggers (`manual`, `file`) throw these automatically. Third-party trigger plugins should throw `TriggerBlockedError` for user/policy rejections and `TriggerTimeoutError` for genuine wait timeouts. Plugins that throw plain `Error` still work — the engine falls back to string matching for backward compatibility, but typed errors are preferred to avoid misclassification from coincidental substrings.
+Built-in triggers (`manual`, `file`) throw these automatically. Trigger plugins should throw `TriggerBlockedError` for user/policy rejections and `TriggerTimeoutError` for genuine wait timeouts.
 
 ```ts
 import { TriggerBlockedError, TriggerTimeoutError } from '@tagma/sdk';
@@ -470,13 +507,30 @@ throw new TriggerBlockedError('Access denied by policy');
 throw new TriggerTimeoutError('File did not appear within 30s');
 ```
 
-### `PluginRegistry.loadPlugins(names): Promise<void>`
+### `PluginRegistry.loadPlugins(names, resolveFrom?): Promise<void>`
+
+Dynamically loads and registers external plugin packages. Each package must default-export a `TagmaPlugin` with capability maps.
+
+```ts
+export default {
+  name: '@tagma/trigger-http',
+  capabilities: {
+    triggers: {
+      http: HttpTrigger,
+    },
+  },
+} satisfies TagmaPlugin;
+```
+
+Pass `resolveFrom` when plugins are installed in a workspace-local `node_modules`.
+
+### `PluginRegistry.registerTagmaPlugin(plugin): RegisteredCapability[]`
 
-Dynamically loads and registers external plugin packages.
+Registers every supported capability from a `TagmaPlugin` default export.
 
 ### `PluginRegistry.registerPlugin(category, type, handler): void`
 
-Registers a plugin handler manually. Idempotent — duplicate registrations are silently ignored.
+Registers one capability handler manually. Prefer `registerTagmaPlugin()` for package-level plugins.
 
 Plugin handlers (`TriggerPlugin`, `CompletionPlugin`, `MiddlewarePlugin`) may optionally expose a declarative `schema: PluginSchema` field so visual editors can render a typed form for the plugin's config instead of a raw key/value editor:
 
@@ -494,6 +548,8 @@ export const HttpTrigger: TriggerPlugin = {
     },
   },
   async watch(config, ctx) {
+    // Trigger plugins should use ctx.runtime for file IO, watching, and
+    // timing so they can run under non-Bun test/runtime implementations.
     /* ... */
   },
 };
@@ -612,9 +668,9 @@ Validates a resolved pipeline config without executing it. Checks DAG structure
 
 Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `resolveConfig` for a final pre-run check.
 
-### Bindings And Ports API
+### Bindings API
 
-Pure helpers backing lightweight bindings and `task.ports`. Safe to use in editors, simulators, and custom drivers — no I/O, no side effects.
+Pure helpers backing typed task bindings and internal prompt-contract inference. Safe to use in editors, simulators, and custom drivers — no I/O, no side effects.
 
 | Function                                                | Description                                                                                                                                                                                                                          |
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -623,7 +679,7 @@ Pure helpers backing lightweight bindings and `task.ports`. Safe to use in edito
 | `resolveTaskBindingInputs(task, upstreamData, dependsOn)` | Resolve lightweight task-level `inputs` from literal values, upstream outputs, stdout/stderr, normalized output, defaults, and required flags                                                                                         |
 | `resolveTaskInputs(task, upstreamOutputs, dependsOn)`   | Gather the input values a task will consume from its direct upstreams. Applies `from` bindings, defaults, and type coercion. Returns `{ kind: 'ready', inputs, missingOptional }` or `{ kind: 'blocked', missingRequired, ambiguous, typeErrors, reason }` |
 | `extractTaskBindingOutputs(outputs, stdout, stderr, normalizedOutput)` | Publish lightweight task-level `outputs` from final-line JSON, stdout/stderr, normalized output, literal values, or defaults                                                                                              |
-| `extractTaskOutputs(ports, stdout, normalizedOutput)`   | Pull declared output values from a terminated task's output. Strategy: prefer `normalizedOutput`; find the last non-empty line that parses as a JSON object; coerce each declared key. Returns `{ outputs, diagnostic }`             |
+| `extractTaskOutputs(ports, stdout, normalizedOutput)`   | Internal helper for inferred prompt contracts. Strategy: prefer `normalizedOutput`; find the last non-empty line that parses as a JSON object; coerce each declared key. Returns `{ outputs, diagnostic }`             |
 | `prependContext(doc, block)`                            | Same shape as `appendContext` but prepends; the engine uses this to place `[Output Format]` and `[Inputs]` blocks before middleware-added context                                                                                    |
 | `renderInputsBlock(inputsDecl, values)`                 | Build the `[Inputs]` `PromptContextBlock` rendered into AI prompts (`name: value  # description` lines). Returns `null` when no inputs to render                                                                                     |
 | `renderOutputSchemaBlock(outputsDecl)`                  | Build the `[Output Format]` `PromptContextBlock` instructing the model to emit a final-line JSON object matching the declared outputs. Returns `null` when no outputs declared                                                       |
@@ -634,7 +690,7 @@ Custom drivers that wrap the prompt in their own envelope can read `DriverContex
 
 Validates a raw pipeline config without resolving inheritance or executing anything. Returns a flat list of `{ path, message, severity? }` objects — empty array means valid. `severity` is `'error'` (default, fatal) or `'warning'` (soft hint; non-blocking).
 
-Checks: required fields, `prompt`/`command` exclusivity, duplicate task IDs within a track, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection, port shape (name format, valid `type`, duplicate names, `enum` requires non-empty `enum` array, `required`/`from` ignored on outputs), `{{inputs.<name>}}` references resolving to a declared input port, and `permissions` shape (must be an object with boolean `read`/`write`/`execute`). Tolerant of half-built configs — non-array `tracks` or `tasks` produce a structured error instead of throwing.
+Checks: required fields, `prompt`/`command` exclusivity, duplicate task IDs within a track, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection, binding shape (name format, valid `type`, duplicate names, `enum` requires non-empty `enum` array), `ports` migration errors, `{{inputs.<name>}}` references resolving to a declared or inferred input binding, and `permissions` shape (must be an object with boolean `read`/`write`/`execute`). Tolerant of half-built configs — non-array `tracks` or `tasks` produce a structured error instead of throwing.
 
 Plugin-type checks are opt-in via `knownTypes`: when provided, references to trigger/completion/middleware/driver types that are neither built-in nor in the supplied set produce a **warning** (`severity: 'warning'`) so editors can light up uninstalled plugins without blocking save / run. Omit `knownTypes` for offline / pre-load validation — no plugin warnings are emitted in that case.
 
@@ -694,7 +750,9 @@ Use `buildDag` instead when you have a fully resolved `PipelineConfig` and need
 Dual-channel logger — console + file. Creates a per-run log file at `<workDir>/.tagma/logs/<runId>/pipeline.log`.
 
 ```ts
-const logger = new Logger(workDir, runId);
+import { bunRuntime } from '@tagma/sdk';
+
+const logger = new Logger(workDir, runId, bunRuntime().logStore);
 logger.info('[track]', 'message'); // console + file
 logger.warn('[track]', 'message'); // console + file
 logger.error('[track]', 'message'); // console + file
@@ -706,13 +764,14 @@ logger.dir; // run artifact directory
 logger.close(); // close the persistent file handle (called automatically when Tagma.run completes)
 ```
 
-Pass an optional third argument to stream every appended line out as a
+Pass an optional fourth argument to stream every appended line out as a
 structured `LogRecord`; the engine uses this to emit `task_log` events:
 
 ```ts
+import { bunRuntime } from '@tagma/sdk';
 import { Logger, type LogRecord } from '@tagma/sdk/logger';
 
-const logger = new Logger(workDir, runId, (record: LogRecord) => {
+const logger = new Logger(workDir, runId, bunRuntime().logStore, (record: LogRecord) => {
   // record = { level, taskId, timestamp, text }
   // level  = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet'
   // taskId is extracted from a '[task:<id>]' prefix, or null for untagged lines
@@ -751,6 +810,8 @@ Truncates `text` to at most `maxBytes` UTF-8 bytes (default 16 KB), appending a
 | Package                                                                                  | Description                                   |
 | ---------------------------------------------------------------------------------------- | --------------------------------------------- |
 | [@tagma/types](https://www.npmjs.com/package/@tagma/types)                               | Shared TypeScript types                       |
+| [@tagma/core](https://www.npmjs.com/package/@tagma/core)                                 | Runtime-independent orchestration core        |
+| [@tagma/runtime-bun](https://www.npmjs.com/package/@tagma/runtime-bun)                   | Bun runtime implementation                    |
 | [@tagma/driver-codex](https://www.npmjs.com/package/@tagma/driver-codex)                 | Codex CLI driver plugin                       |
 | [@tagma/driver-claude-code](https://www.npmjs.com/package/@tagma/driver-claude-code)     | Claude Code CLI driver plugin                 |
 | [@tagma/middleware-lightrag](https://www.npmjs.com/package/@tagma/middleware-lightrag)   | LightRAG knowledge-graph retrieval middleware |

package/dist/adapters/stdin-approval.d.ts

@@ -1,6 +1,2 @@
-import type { ApprovalGateway } from '../approval';
-export interface StdinApprovalAdapter {
-    readonly detach: () => void;
-}
-export declare function attachStdinApprovalAdapter(gateway: ApprovalGateway): StdinApprovalAdapter;
+export * from '../runtime/adapters/stdin-approval';
 //# sourceMappingURL=stdin-approval.d.ts.map

package/dist/adapters/stdin-approval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdin-approval.d.ts","sourceRoot":"","sources":["../../src/adapters/stdin-approval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAQpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,eAAe,GAAG,oBAAoB,CA4FzF"}
+{"version":3,"file":"stdin-approval.d.ts","sourceRoot":"","sources":["../../src/adapters/stdin-approval.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC"}

package/dist/adapters/stdin-approval.js

@@ -1,90 +1,2 @@
-import * as readline from 'readline';
-export function attachStdinApprovalAdapter(gateway) {
-    const queue = [];
-    let processing = false;
-    let rl = null;
-    function ensureReadline() {
-        if (!rl) {
-            rl = readline.createInterface({ input: process.stdin, terminal: false });
-        }
-        return rl;
-    }
-    function readOneLine() {
-        return new Promise((resolvePromise) => {
-            const reader = ensureReadline();
-            const handler = (line) => {
-                reader.off('line', handler);
-                resolvePromise(line);
-            };
-            reader.on('line', handler);
-        });
-    }
-    async function processNext() {
-        if (processing)
-            return;
-        processing = true;
-        try {
-            while (queue.length > 0) {
-                const req = queue.shift();
-                // If the request was already resolved by another path while queued, skip it.
-                if (!gateway.pending().some((p) => p.id === req.id))
-                    continue;
-                process.stdout.write(`\n[APPROVAL REQUIRED] ${req.message}\n` +
-                    `  id:      ${req.id}\n` +
-                    `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
-                    `  approve / reject > `);
-                const input = (await readOneLine()).trim().toLowerCase();
-                const approveAliases = new Set(['approve', 'yes', 'y', 'ok', 'true', '1']);
-                const rejectAliases = new Set(['reject', 'no', 'n', 'deny', 'false', '0']);
-                if (approveAliases.has(input)) {
-                    gateway.resolve(req.id, { outcome: 'approved', actor: 'cli' });
-                }
-                else if (rejectAliases.has(input)) {
-                    gateway.resolve(req.id, {
-                        outcome: 'rejected',
-                        actor: 'cli',
-                        reason: 'user rejected via CLI',
-                    });
-                }
-                else {
-                    process.stdout.write(`  unrecognized input "${input}" — treating as rejection\n`);
-                    gateway.resolve(req.id, {
-                        outcome: 'rejected',
-                        actor: 'cli',
-                        reason: `unrecognized CLI input: ${input}`,
-                    });
-                }
-            }
-        }
-        finally {
-            processing = false;
-        }
-    }
-    const unsubscribe = gateway.subscribe((event) => {
-        switch (event.type) {
-            case 'requested':
-                queue.push(event.request);
-                void processNext();
-                return;
-            case 'resolved':
-            case 'expired':
-            case 'aborted': {
-                // Drop from queue if it's still waiting its turn.
-                const idx = queue.findIndex((r) => r.id === event.request.id);
-                if (idx >= 0)
-                    queue.splice(idx, 1);
-                return;
-            }
-        }
-    });
-    return {
-        detach: () => {
-            unsubscribe();
-            if (rl) {
-                rl.close();
-                rl = null;
-            }
-        },
-    };
-}
+export * from '../runtime/adapters/stdin-approval';
 //# sourceMappingURL=stdin-approval.js.map

package/dist/adapters/stdin-approval.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdin-approval.js","sourceRoot":"","sources":["../../src/adapters/stdin-approval.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stdin-approval.js","sourceRoot":"","sources":["../../src/adapters/stdin-approval.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC"}

package/dist/adapters/websocket-approval.d.ts

@@ -1,28 +1,2 @@
-import type { ApprovalGateway } from '../approval';
-export interface WebSocketApprovalAdapterOptions {
-    port?: number;
-    hostname?: string;
-    /**
-     * M11: shared secret required from the client during the WebSocket
-     * upgrade. The token can be supplied either as the `?token=` query
-     * parameter or in the `x-tagma-token` request header. When set, any
-     * upgrade request that fails the check is rejected with HTTP 401 and
-     * never reaches the WebSocket layer (so a misconfigured client cannot
-     * exhaust rate-limit slots either). Leave undefined for backward
-     * compatibility with localhost-only deployments.
-     */
-    token?: string;
-    /**
-     * M11: opt-out of origin checking. Defaults to false, meaning Origin
-     * headers are restricted to loopback hosts (localhost / 127.0.0.1 / ::1).
-     * Requests without an Origin header are still allowed so non-browser local
-     * clients can connect. Set true only for trusted reverse-proxy setups.
-     */
-    allowAnyOrigin?: boolean;
-}
-export interface WebSocketApprovalAdapter {
-    readonly port: number;
-    readonly detach: () => void;
-}
-export declare function attachWebSocketApprovalAdapter(gateway: ApprovalGateway, options?: WebSocketApprovalAdapterOptions): WebSocketApprovalAdapter;
+export * from '../runtime/adapters/websocket-approval';
 //# sourceMappingURL=websocket-approval.d.ts.map

package/dist/adapters/websocket-approval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket-approval.d.ts","sourceRoot":"","sources":["../../src/adapters/websocket-approval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAoBlE,MAAM,WAAW,+BAA+B;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAQD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,+BAAoC,GAC5C,wBAAwB,CAmJ1B"}
+{"version":3,"file":"websocket-approval.d.ts","sourceRoot":"","sources":["../../src/adapters/websocket-approval.ts"],"names":[],"mappings":"AAAA,cAAc,wCAAwC,CAAC"}