@deepstrike/sdk 0.2.27 → 0.2.30

package/README.md

@@ -76,6 +76,67 @@ const reply = await collectText(runner.run({ sessionId: "chat-1", goal: "What is
 
 Use `InMemorySessionLog` for process-local sessions or `FileSessionLog` when replay should survive restarts. `wake(sessionId)` resumes from the event log without inserting a duplicate `run_started` event.
 
+### Package layout (v0.2.30)
+
+The root export is the **intent layer** — what you reach for to run an agent, run a workflow, author a tool, or pick a provider (~30 symbols). Advanced machinery lives behind subpaths, so the common surface stays small and tree-shakeable:
+
+| Import | Contains |
+|--------|----------|
+| `@deepstrike/sdk` | `runAgent` · `runFanout` · `RuntimeRunner` · `tool` · `LocalExecutionPlane` · `InMemorySessionLog`/`FileSessionLog` · `AnthropicProvider`/`OpenAIProvider`/`OpenAIResponsesProvider` · `createProvider` · `Governance` · `AgentPool` · core types |
+| `@deepstrike/sdk/providers` | backend factories (`deepseek`, `kimi`, `qwen`, `glm`, `minimax`, `gemini`, `ollama`), profiles, `CircuitBreaker` |
+| `@deepstrike/sdk/workflow` | `SubAgentOrchestrator`, `spawnStandalone`, reducers, contracts, handoff/modes, agent + spec types |
+| `@deepstrike/sdk/planes` | `WorktreeExecutionPlane`, `ProcessSandboxPlane`, `McpProxyPlane`, `RemoteVpcPlane`, archive/credential stores |
+| `@deepstrike/sdk/memory` | `DreamStore`, `WorkingMemory`, `InMemoryDreamStore`, `KnowledgeSource` |
+| `@deepstrike/sdk/harness` | `SinglePassHarness`, `EvalLoopHarness`, `HarnessLoop`, `judge` |
+| `@deepstrike/sdk/os` | profiles, `KernelPrimitivesDashboard`, signals, `PermissionManager`, replay-testing utilities |
+
+> **Migration from 0.2.x:** the kernel-lowering converters (`*ToKernel`), low-level prompt/eval builders, and the `OpenAIChatProvider` alias are no longer exported from root; backend providers, planes, memory, harness, and OS utilities moved to the subpaths above. See [`MIGRATION-v0.2.300.md`](./MIGRATION-v0.2.300.md).
+
+### Recipes — the canonical entry points
+
+Most apps need one of three shapes. Start with the facades and drop down to `RuntimeRunner` only when you need streaming, signals, memory, or governance hooks.
+
+```typescript
+import { runAgent, runFanout } from "@deepstrike/sdk"
+
+// 1) Single agent — one prompt, one model, the text back.
+const answer = await runAgent({ provider, goal: "What is 17 + 28?", tools: [add] })
+
+// 2) Parallel fan-out → synthesize — N workers, then a synthesis pass, over the kernel-gated DAG.
+//    Bootstraps and tears down its own kernel, so it's safe from a stateless request handler.
+const { synthesis } = await runFanout({
+  provider,
+  tasks: [
+    "Summarize the security posture of the auth module",
+    "Summarize the data-retention posture",
+  ],
+  synthesize: "Combine the worker findings into one risk summary.",
+})
+
+// 3) Full control — sub-agents, governance, signals, streaming, resume → use RuntimeRunner directly.
+```
+
+`runFanout` is sugar over the **standalone `runWorkflow`** path: with no active `run()`, `runner.runWorkflow(spec)` auto-bootstraps a kernel that owns the DAG (governed · resumable), drives it, and tears it down — exactly what a Vercel/Lambda handler needs. See [Dynamic workflows](#dynamic-workflows). For parallel work you can also give each worker its own `RuntimeRunner`; `RuntimeRunner` carries per-run state, so **never share one instance across concurrent runs** — use a fresh instance per worker (or the `AgentPool` primitive).
+
+### Deploying to serverless / bundlers
+
+`@deepstrike/core` is a native N-API addon; its platform binary ships via `optionalDependencies`. Bundlers (Next.js/Vercel, webpack, esbuild) don't trace `.node` files by default, so the function fails at runtime with `Cannot find module '@deepstrike/core'`. Tell your bundler to treat the package as external and trace its files:
+
+```ts
+// next.config.ts (Next.js / Vercel)
+const nextConfig = {
+  serverExternalPackages: ["@deepstrike/sdk"],
+  outputFileTracingIncludes: {
+    "/api/**": ["./node_modules/@deepstrike/**/*"],
+  },
+}
+export default nextConfig
+```
+
+- **webpack:** add `@deepstrike/core` (and `@deepstrike/sdk`) to `externals`, or use `node-loader` for `.node` files.
+- **esbuild:** `--external:@deepstrike/core --external:@deepstrike/sdk` and ensure the platform binary is copied next to the bundle.
+- **Docker/standalone:** the build host's platform binary must match the runtime's (e.g. build on `linux-x64-gnu` for Vercel). Alpine images need the `-musl` binary.
+
 Streaming:
 
 ```typescript
@@ -161,9 +222,11 @@ const outcome = await runner.runWorkflow({
     { task: "Skeptic: which flags are real violations?",  role: "verify", dependsOn: [0, 1, 2] },
   ],
 })
-// → { completed: ["wf-node0", … ], failed: [] }
+// → { completed: ["wf-node0", … ], failed: [], outputs: { "wf-node3": "…" } }
 ```
 
+`runWorkflow` works **standalone** — call it on a freshly-constructed runner (e.g. inside a stateless HTTP handler) and it auto-bootstraps a kernel that owns the DAG, drives it under the same governance/quota/attention policies a full `run()` gets, and tears it down on completion. Called *during* a `run()`, it instead drives the workflow on the active kernel. Either way every node's final text comes back in `outputs`, keyed by node agent-id. To resume an interrupted standalone run, pass the prior session id: `runner.resumeWorkflow(spec, { sessionId })`.
+
 A node's `kind` selects the control-flow shape; the same executor drives them all, every spawn passing the syscall gate:
 
 | Node `kind` | Behavior |
@@ -185,23 +248,44 @@ A node's `kind` selects the control-flow shape; the same executor drives them al
 
 ## Providers
 
-| Class | Backend | Notes |
-|-------|---------|-------|
-| `OpenAIChatProvider` | OpenAI Chat Completions API | SSE tool-call accumulation |
-| `OpenAIProvider` | OpenAI Chat Completions API | Compatibility alias for `OpenAIChatProvider` |
-| `OpenAIResponsesProvider` | OpenAI Responses API | Native `previous_response_id` continuation |
-| `AnthropicProvider` | Anthropic API | Native SSE, `ThinkingDelta` support |
-| `QwenProvider` | DashScope | `enable_thinking` via extensions |
-| `DeepSeekProvider` | DeepSeek API | V4 thinking controls + reasoning replay across tool turns |
-| `MiniMaxProvider` | MiniMax API | Anthropic-compatible M2.7/M2.5 path |
-| `OllamaProvider` | Local Ollama | `http://localhost:11434` default |
-| `KimiProvider` | Moonshot API | K2.6 default; K2.5 also supported |
+The root package exports the three base providers — `AnthropicProvider`, `OpenAIProvider`,
+`OpenAIResponsesProvider` — plus `createProvider`. **Every other backend is a factory function** in
+`@deepstrike/sdk/providers`: one per backend, with a `protocol` option where a backend speaks both the
+OpenAI- and Anthropic-compatible wire.
 
-All providers accept `RetryConfig` for exponential backoff and share a `CircuitBreaker`.
+```typescript
+import { deepseek, kimi, minimax } from "@deepstrike/sdk/providers"
 
-`extensions` are forwarded by every provider in both `complete()` and `stream()` while SDK-owned structural fields such as `model`, `messages`, `tools`, and streaming flags remain protected.
+const ds = deepseek({ apiKey })                          // OpenAI-compatible wire (default)
+const dsA = deepseek({ apiKey, protocol: "anthropic" })  // Anthropic-compatible wire
+const mm = minimax({ apiKey })                           // MiniMax defaults to the Anthropic wire
+```
+
+| Entry | Import from | Backend |
+|-------|-------------|---------|
+| `OpenAIProvider` | root | OpenAI Chat Completions (and any OpenAI-compatible `/v1`) |
+| `OpenAIResponsesProvider` | root | OpenAI Responses API (`previous_response_id` continuation) |
+| `AnthropicProvider` | root | Anthropic Messages API (`ThinkingDelta` support) |
+| `deepseek` · `kimi` · `qwen` · `glm` · `minimax` · `gemini` · `ollama` | `@deepstrike/sdk/providers` | the respective vendor (factory functions) |
+
+Providers take an **options object** and share a `CircuitBreaker`. `extensions` are forwarded in both
+`complete()` and `stream()`; SDK-owned fields (`model`, `messages`, `tools`, streaming flags) stay protected.
+
+**Custom OpenAI-compatible endpoint** (MiMo, DeepSeek, Kimi, Qwen, GLM via their `/v1` base URL): construct
+`OpenAIProvider` with an options object — no more positional `baseURL` hole:
+
+```typescript
+import { OpenAIProvider } from "@deepstrike/sdk"
+
+const provider = new OpenAIProvider({
+  apiKey,
+  model: "mimo-v2.5-pro",
+  baseURL: "https://token-plan-cn.xiaomimimo.com/v1",
+})
+```
 
-OpenAI can also be selected through the provider catalog:
+Prefer a dedicated backend class from `@deepstrike/sdk/providers` when one exists — they default the base
+URL and add backend-specific reasoning handling. Any model can also be selected through the catalog: `createProvider` picks the protocol/endpoint for you:
 
 ```typescript
 import { createProvider } from "@deepstrike/sdk"

package/dist/harness/public.d.ts

@@ -0,0 +1,4 @@
+export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness.js";
+export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate, CriterionResult, HarnessEvent, VerdictFn, } from "./harness.js";
+export { judge } from "../runtime/eval.js";
+export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "../runtime/eval.js";

package/dist/harness/public.js

@@ -0,0 +1,3 @@
+// `@deepstrike/sdk/harness` — the evaluation framework: single-pass / eval-loop harnesses and the judge.
+export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness.js";
+export { judge } from "../runtime/eval.js";

package/dist/index.d.ts

@@ -1,90 +1,25 @@
+export { runAgent, runFanout } from "./runtime/facade.js";
+export type { RunAgentOptions, RunFanoutOptions } from "./runtime/facade.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
-export type { RuntimeOptions, SchedulerBudget } from "./runtime/runner.js";
-export { builtinReducers, resolveReducer } from "./runtime/reducers.js";
-export type { Reducer, ReducerRegistry, ReducerInput } from "./runtime/reducers.js";
-export { loopInstruction, classifyInstruction, judgeGoal, extractLoopContinue, extractClassifyBranch, extractJudgeWinner, } from "./runtime/workflow-control-flow.js";
-export { WorktreeExecutionPlane, GitWorktreeManager } from "./runtime/worktree-plane.js";
-export type { WorktreeManager } from "./runtime/worktree-plane.js";
-export { FileWorkflowStore } from "./runtime/workflow-store.js";
-export type { MemoryPolicy, MemoryWriteRateLimit, ResourceQuota } from "./kernel.js";
-export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
-export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
-export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
-export type { SubAgentRunContext } from "./runtime/sub-agent-orchestrator.js";
+export type { RuntimeOptions } from "./runtime/runner.js";
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export type { ExecutionPlane, RunContext } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
 export type { SessionLog, SessionEvent } from "./runtime/session-log.js";
-export { ReplayProvider } from "./runtime/replay-provider.js";
-export type { ReplayProviderOpts } from "./runtime/replay-provider.js";
-export { extractRecordedMessages } from "./runtime/replay-fixture.js";
-export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./runtime/eval.js";
-export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "./runtime/eval.js";
-export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
-export type { NativeOsProfile, OsProfileId } from "./runtime/os-profile.js";
-export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
-export type { OsSnapshot } from "./runtime/os-snapshot.js";
-export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";
-export type { KernelEventCategory } from "./runtime/kernel-event-log.js";
-export { NullArchiveStore, FileArchiveStore } from "./runtime/archive.js";
-export type { ArchiveStore } from "./runtime/archive.js";
-export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "./runtime/credential-vault.js";
-export type { CredentialVault } from "./runtime/credential-vault.js";
-export { ProcessSandboxPlane } from "./runtime/process-sandbox-plane.js";
-export type { SandboxOptions } from "./runtime/process-sandbox-plane.js";
-export { McpProxyPlane } from "./runtime/mcp-proxy-plane.js";
-export type { McpServerConfig } from "./runtime/mcp-proxy-plane.js";
-export { RemoteVpcPlane } from "./runtime/remote-vpc-plane.js";
-export type { RemoteVpcOptions } from "./runtime/remote-vpc-plane.js";
-export { AnthropicProvider } from "./providers/anthropic.js";
-export { OpenAIChatProvider, OpenAIProvider } from "./providers/openai.js";
-export { DeepSeekProvider, DeepSeekAnthropicProvider } from "./providers/deepseek.js";
-export { KimiProvider, KimiAnthropicProvider } from "./providers/kimi.js";
-export { QwenProvider, QwenAnthropicProvider } from "./providers/qwen.js";
-export { GLMProvider, GLMAnthropicProvider } from "./providers/glm.js";
-export { GeminiProvider } from "./providers/gemini.js";
-export { MiniMaxAnthropicProvider, MiniMaxOpenAIProvider } from "./providers/minimax.js";
-export { OllamaProvider } from "./providers/ollama.js";
-export { CircuitBreaker, normalizeToolCall } from "./providers/base.js";
-export { OpenAIChatAdapter } from "./providers/openai-chat.js";
-export { OpenAIResponsesAdapter, OpenAIResponsesProvider } from "./providers/openai-responses.js";
-export type { OpenAIResponsesRunState } from "./providers/openai-responses.js";
-export { endpointProfiles, modelProfiles, getModelProfile } from "./providers/profiles.js";
-export type { ModelProfileId, ProviderId } from "./providers/profiles.js";
-export { createProvider } from "./providers/catalog.js";
-export type { CreateProviderOptions, EndpointProfileId } from "./providers/catalog.js";
-export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "./providers/replay-validator.js";
-export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
-export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
+export { tool, streamingTool } from "./tools/index.js";
 export type { RegisteredTool, ToolExecContext } from "./tools/index.js";
 export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
 export type { ToolEnvelope, ToolEnvelopeOk, ToolEnvelopeFail } from "./tools/errors.js";
-export { scanSkillDir, readSkillFile } from "./skills/loader.js";
-export type { SkillMetadata } from "./skills/loader.js";
-export { WorkingMemory } from "./memory/working.js";
-export { InMemoryDreamStore } from "./memory/in-memory-store.js";
-export type { DreamStore, DreamResult, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, MemoryMetadata, MemoryKind, } from "./memory/protocols.js";
-export type { KnowledgeSource } from "./knowledge/source.js";
-export { ScheduledPrompt } from "./signals/scheduled.js";
-export { SignalGateway } from "./signals/gateway.js";
-export type { RuntimeSignal, SignalSource } from "./signals/types.js";
-export { PermissionManager, PermissionMode } from "./safety/permissions.js";
-export type { PermissionDecision, Permission } from "./safety/permissions.js";
-export { Governance, governancePolicyToKernelEvent } from "./governance.js";
+export { AnthropicProvider } from "./providers/anthropic.js";
+export type { AnthropicProviderConfig } from "./providers/anthropic.js";
+export { OpenAIProvider } from "./providers/openai.js";
+export type { OpenAIProviderOptions } from "./providers/openai.js";
+export { OpenAIResponsesProvider } from "./providers/openai-responses.js";
+export { createProvider } from "./providers/catalog.js";
+export type { CreateProviderOptions, EndpointProfileId } from "./providers/catalog.js";
+export { Governance } from "./governance.js";
 export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
-export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
-export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate, CriterionResult, HarnessEvent, VerdictFn } from "./harness/harness.js";
-export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, ReplayabilityAssessment, CacheBreakpointStrategy, } from "./types.js";
-export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpec, WorkflowNodeSpec, WorkflowTaskSpec, WorkflowSpawnInfo, } from "./types/agent.js";
-export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules, genEval, } from "./types/agent.js";
-export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";
-export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
 export { AgentPool } from "./collaboration/pool.js";
-export type { AgentRole, IsolatedVerifierContext, CoordinatorConfig } from "./collaboration/pool.js";
-export { KERNEL_ROLE_MAP } from "./collaboration/pool.js";
-export { ContractDrivenHarness } from "./collaboration/harness.js";
-export type { ContractOutcome, ContractHarnessOptions, Violation } from "./collaboration/harness.js";
-export { HandoffBus } from "./collaboration/handoff.js";
-export type { HandoffArtifact, ContractOutcomeInput } from "./collaboration/handoff.js";
-export { CreatorVerifierMode, OrchestrationMode } from "./collaboration/modes/creator-verifier.js";
-export type { CreatorVerifierMetrics } from "./collaboration/modes/creator-verifier.js";
+export type { RuntimeSignal, SignalSource } from "./signals/types.js";
+export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, } from "./types.js";
+export type { WorkflowSpec, WorkflowNodeSpec, } from "./types/agent.js";

package/dist/index.js

@@ -1,60 +1,33 @@
-// ── Runtime (Layer 1.5) ────────────────────────────────────────────────────
+// ╔══════════════════════════════════════════════════════════════════════════╗
+// ║ @deepstrike/sdk — root surface (v0.2.30).                                      ║
+// ║                                                                            ║
+// ║ This is the intent layer: run an agent, run a workflow, author a tool,     ║
+// ║ pick a provider. Advanced machinery lives behind subpaths:                 ║
+// ║   @deepstrike/sdk/providers  — backend provider classes + profiles         ║
+// ║   @deepstrike/sdk/workflow   — orchestration, reducers, contracts, specs   ║
+// ║   @deepstrike/sdk/planes     — worktree / sandbox / mcp / vpc planes        ║
+// ║   @deepstrike/sdk/memory     — dream + working memory, knowledge sources    ║
+// ║   @deepstrike/sdk/harness    — eval harnesses + judge                       ║
+// ║   @deepstrike/sdk/os         — profiles, diagnostics, signals, replay tests ║
+// ╚══════════════════════════════════════════════════════════════════════════╝
+// ── Start here: the canonical entry points ─────────────────────────────────
+export { runAgent, runFanout } from "./runtime/facade.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
-export { builtinReducers, resolveReducer } from "./runtime/reducers.js";
-export { loopInstruction, classifyInstruction, judgeGoal, extractLoopContinue, extractClassifyBranch, extractJudgeWinner, } from "./runtime/workflow-control-flow.js";
-export { WorktreeExecutionPlane, GitWorktreeManager } from "./runtime/worktree-plane.js";
-export { FileWorkflowStore } from "./runtime/workflow-store.js";
-export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
-export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
-export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
+// ── Execution plane + session log (the defaults) ────────────────────────────
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
-export { ReplayProvider } from "./runtime/replay-provider.js";
-export { extractRecordedMessages } from "./runtime/replay-fixture.js";
-export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./runtime/eval.js";
-export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
-export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
-export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";
-export { NullArchiveStore, FileArchiveStore } from "./runtime/archive.js";
-export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "./runtime/credential-vault.js";
-export { ProcessSandboxPlane } from "./runtime/process-sandbox-plane.js";
-export { McpProxyPlane } from "./runtime/mcp-proxy-plane.js";
-export { RemoteVpcPlane } from "./runtime/remote-vpc-plane.js";
-// ── Providers ─────────────────────────────────────────────────────────────
+// ── Tool authoring ──────────────────────────────────────────────────────────
+export { tool, streamingTool } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
+// ── Providers (base classes + the universal factory) ────────────────────────
+// Any backend — including a custom OpenAI-compatible endpoint — is reachable via `createProvider`.
+// Backend-specific classes (DeepSeek/Kimi/Qwen/GLM/Gemini/Ollama/MiniMax) live in `@deepstrike/sdk/providers`.
 export { AnthropicProvider } from "./providers/anthropic.js";
-export { OpenAIChatProvider, OpenAIProvider } from "./providers/openai.js";
-export { DeepSeekProvider, DeepSeekAnthropicProvider } from "./providers/deepseek.js";
-export { KimiProvider, KimiAnthropicProvider } from "./providers/kimi.js";
-export { QwenProvider, QwenAnthropicProvider } from "./providers/qwen.js";
-export { GLMProvider, GLMAnthropicProvider } from "./providers/glm.js";
-export { GeminiProvider } from "./providers/gemini.js";
-export { MiniMaxAnthropicProvider, MiniMaxOpenAIProvider } from "./providers/minimax.js";
-export { OllamaProvider } from "./providers/ollama.js";
-export { CircuitBreaker, normalizeToolCall } from "./providers/base.js";
-export { OpenAIChatAdapter } from "./providers/openai-chat.js";
-export { OpenAIResponsesAdapter, OpenAIResponsesProvider } from "./providers/openai-responses.js";
-export { endpointProfiles, modelProfiles, getModelProfile } from "./providers/profiles.js";
+export { OpenAIProvider } from "./providers/openai.js";
+export { OpenAIResponsesProvider } from "./providers/openai-responses.js";
 export { createProvider } from "./providers/catalog.js";
-export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "./providers/replay-validator.js";
-export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
-// ── Tools & Skills ─────────────────────────────────────────────────────────
-export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
-export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
-export { scanSkillDir, readSkillFile } from "./skills/loader.js";
-// ── Memory ─────────────────────────────────────────────────────────────────
-export { WorkingMemory } from "./memory/working.js";
-export { InMemoryDreamStore } from "./memory/in-memory-store.js";
-export { ScheduledPrompt } from "./signals/scheduled.js";
-export { SignalGateway } from "./signals/gateway.js";
-// ── Safety & Governance ────────────────────────────────────────────────────
-export { PermissionManager, PermissionMode } from "./safety/permissions.js";
-export { Governance, governancePolicyToKernelEvent } from "./governance.js";
-// ── Harness ────────────────────────────────────────────────────────────────
-export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
-export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules, genEval, } from "./types/agent.js";
-export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
+// ── Governance ──────────────────────────────────────────────────────────────
+export { Governance } from "./governance.js";
+// ── Multi-agent primitive ───────────────────────────────────────────────────
+// Parallel fan-out / sub-agent delegation. The full orchestration layer is in `@deepstrike/sdk/workflow`.
 export { AgentPool } from "./collaboration/pool.js";
-export { KERNEL_ROLE_MAP } from "./collaboration/pool.js";
-export { ContractDrivenHarness } from "./collaboration/harness.js";
-export { HandoffBus } from "./collaboration/handoff.js";
-export { CreatorVerifierMode, OrchestrationMode } from "./collaboration/modes/creator-verifier.js";

package/dist/memory/public.d.ts

@@ -0,0 +1,4 @@
+export { WorkingMemory } from "./working.js";
+export { InMemoryDreamStore } from "./in-memory-store.js";
+export type { DreamStore, DreamResult, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, MemoryMetadata, MemoryKind, } from "./protocols.js";
+export type { KnowledgeSource } from "../knowledge/source.js";

package/dist/memory/public.js

@@ -0,0 +1,3 @@
+// `@deepstrike/sdk/memory` — long-term (dream) and working memory, plus the knowledge-source interface.
+export { WorkingMemory } from "./working.js";
+export { InMemoryDreamStore } from "./in-memory-store.js";

package/dist/os/public.d.ts

@@ -0,0 +1,18 @@
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "../runtime/os-profile.js";
+export type { NativeOsProfile, OsProfileId } from "../runtime/os-profile.js";
+export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories } from "../runtime/os-snapshot.js";
+export type { OsSnapshot } from "../runtime/os-snapshot.js";
+export type { KernelEventCategory } from "../runtime/kernel-event-log.js";
+export { KernelPrimitivesDashboard } from "../runtime/kernel-primitives-dashboard.js";
+export type { MemoryPolicy, MemoryWriteRateLimit, ResourceQuota } from "../kernel.js";
+export type { SchedulerBudget } from "../runtime/runner.js";
+export { ScheduledPrompt } from "../signals/scheduled.js";
+export { SignalGateway } from "../signals/gateway.js";
+export { PermissionManager, PermissionMode } from "../safety/permissions.js";
+export type { PermissionDecision, Permission } from "../safety/permissions.js";
+export { ReplayProvider } from "../runtime/replay-provider.js";
+export type { ReplayProviderOpts } from "../runtime/replay-provider.js";
+export { extractRecordedMessages } from "../runtime/replay-fixture.js";
+export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "../providers/replay-validator.js";
+export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "../runtime/provider-replay.js";
+export type { ReplayabilityAssessment } from "../types.js";

package/dist/os/public.js

@@ -0,0 +1,14 @@
+// `@deepstrike/sdk/os` — Agent-OS diagnostics, profiles, signal/permission machinery, replay-testing,
+// and the scheduler/quota/policy types referenced by advanced `RuntimeOptions` fields.
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "../runtime/os-profile.js";
+export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories } from "../runtime/os-snapshot.js";
+export { KernelPrimitivesDashboard } from "../runtime/kernel-primitives-dashboard.js";
+// Signals + SDK-side permissions.
+export { ScheduledPrompt } from "../signals/scheduled.js";
+export { SignalGateway } from "../signals/gateway.js";
+export { PermissionManager, PermissionMode } from "../safety/permissions.js";
+// Replay-based testing utilities.
+export { ReplayProvider } from "../runtime/replay-provider.js";
+export { extractRecordedMessages } from "../runtime/replay-fixture.js";
+export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "../providers/replay-validator.js";
+export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "../runtime/provider-replay.js";

package/dist/planes/public.d.ts

@@ -0,0 +1,13 @@
+export { WorktreeExecutionPlane, GitWorktreeManager } from "../runtime/worktree-plane.js";
+export type { WorktreeManager } from "../runtime/worktree-plane.js";
+export { FilteredExecutionPlane } from "../runtime/filtered-plane.js";
+export { ProcessSandboxPlane } from "../runtime/process-sandbox-plane.js";
+export type { SandboxOptions } from "../runtime/process-sandbox-plane.js";
+export { McpProxyPlane } from "../runtime/mcp-proxy-plane.js";
+export type { McpServerConfig } from "../runtime/mcp-proxy-plane.js";
+export { RemoteVpcPlane } from "../runtime/remote-vpc-plane.js";
+export type { RemoteVpcOptions } from "../runtime/remote-vpc-plane.js";
+export { NullArchiveStore, FileArchiveStore } from "../runtime/archive.js";
+export type { ArchiveStore } from "../runtime/archive.js";
+export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "../runtime/credential-vault.js";
+export type { CredentialVault } from "../runtime/credential-vault.js";

package/dist/planes/public.js

@@ -0,0 +1,9 @@
+// `@deepstrike/sdk/planes` — advanced execution planes, archive stores, and credential vaults.
+// The root package exports `LocalExecutionPlane`; specialized planes live here.
+export { WorktreeExecutionPlane, GitWorktreeManager } from "../runtime/worktree-plane.js";
+export { FilteredExecutionPlane } from "../runtime/filtered-plane.js";
+export { ProcessSandboxPlane } from "../runtime/process-sandbox-plane.js";
+export { McpProxyPlane } from "../runtime/mcp-proxy-plane.js";
+export { RemoteVpcPlane } from "../runtime/remote-vpc-plane.js";
+export { NullArchiveStore, FileArchiveStore } from "../runtime/archive.js";
+export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "../runtime/credential-vault.js";

package/dist/providers/anthropic.d.ts

@@ -3,14 +3,23 @@ interface AnthropicProviderOptions {
     baseURL?: string;
     authMode?: "api-key" | "bearer";
 }
+/** Options-object form for `AnthropicProvider` — the recommended constructor shape. */
+export interface AnthropicProviderConfig extends AnthropicProviderOptions {
+    apiKey: string;
+    model?: string;
+    retry?: {
+        maxRetries: number;
+        baseDelay: number;
+    };
+}
 export declare class AnthropicProvider implements LLMProvider {
-    protected readonly model: string;
     private client;
     private circuit;
     private maxRetries;
     private baseDelay;
+    protected readonly model: string;
     private nativeAssistantBlocks;
-    constructor(apiKey: string, model?: string, retry?: {
+    constructor(apiKeyOrConfig: string | AnthropicProviderConfig, model?: string, retry?: {
         maxRetries: number;
         baseDelay: number;
     }, options?: AnthropicProviderOptions);

package/dist/providers/anthropic.js

@@ -13,23 +13,28 @@ const CLAUDE_POLICIES = {
     "claude-3-5-haiku-latest": { maxTurns: 15 },
 };
 export class AnthropicProvider {
-    model;
     client;
     circuit;
     maxRetries;
     baseDelay;
+    model;
     nativeAssistantBlocks = new Map();
-    constructor(apiKey, model = "claude-sonnet-4-6", retry = { maxRetries: 3, baseDelay: 1000 }, options = {}) {
-        this.model = model;
+    // Accepts the options object (`new AnthropicProvider({ apiKey, model, baseURL })`) or the legacy
+    // positional form (still used by the Anthropic-compatible backend subclasses' `super(...)` calls).
+    constructor(apiKeyOrConfig, model = "claude-sonnet-4-6", retry = { maxRetries: 3, baseDelay: 1000 }, options = {}) {
+        const c = typeof apiKeyOrConfig === "string"
+            ? { apiKey: apiKeyOrConfig, model, retry, ...options }
+            : { model: "claude-sonnet-4-6", retry: { maxRetries: 3, baseDelay: 1000 }, ...apiKeyOrConfig };
+        this.model = c.model ?? "claude-sonnet-4-6";
         this.client = withServerRuntimeGuard(() => new Anthropic({
-            ...(options.authMode === "bearer"
-                ? { authToken: apiKey, apiKey: null }
-                : { apiKey, authToken: null }),
-            ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+            ...(c.authMode === "bearer"
+                ? { authToken: c.apiKey, apiKey: null }
+                : { apiKey: c.apiKey, authToken: null }),
+            ...(c.baseURL ? { baseURL: c.baseURL } : {}),
         }));
         this.circuit = new CircuitBreaker();
-        this.maxRetries = retry.maxRetries;
-        this.baseDelay = retry.baseDelay;
+        this.maxRetries = c.retry?.maxRetries ?? 3;
+        this.baseDelay = c.retry?.baseDelay ?? 1000;
     }
     runtimePolicy() {
         return CLAUDE_POLICIES[this.model] ?? {};

package/dist/providers/factories.d.ts

@@ -0,0 +1,31 @@
+import type { LLMProvider } from "../types.js";
+/** Options for a backend provider factory. `protocol` only applies to backends with both wires. */
+export interface BackendProviderOptions {
+    apiKey: string;
+    model?: string;
+    /** Override the endpoint base URL (defaults to the backend's profile for the chosen protocol). */
+    baseURL?: string;
+    retry?: {
+        maxRetries: number;
+        baseDelay: number;
+    };
+    /** Wire protocol for dual-protocol backends. Defaults per backend (see each factory). */
+    protocol?: "openai" | "anthropic";
+}
+/** DeepSeek. Defaults to the OpenAI-compatible wire (richer reasoning-replay handling). */
+export declare function deepseek(o: BackendProviderOptions): LLMProvider;
+/** Moonshot Kimi. Defaults to the OpenAI-compatible wire. */
+export declare function kimi(o: BackendProviderOptions): LLMProvider;
+/** Alibaba Qwen / DashScope. Defaults to the OpenAI-compatible (DashScope) wire. */
+export declare function qwen(o: BackendProviderOptions): LLMProvider;
+/** Zhipu GLM. Defaults to the OpenAI-compatible wire. */
+export declare function glm(o: BackendProviderOptions): LLMProvider;
+/** MiniMax. Defaults to the Anthropic-compatible wire (the primary M2.x path). */
+export declare function minimax(o: BackendProviderOptions): LLMProvider;
+/** Google Gemini (single wire). */
+export declare function gemini(o: Omit<BackendProviderOptions, "protocol">): LLMProvider;
+/** Local Ollama (single wire, no API key). */
+export declare function ollama(o?: {
+    model?: string;
+    baseURL?: string;
+}): LLMProvider;

package/dist/providers/factories.js

@@ -0,0 +1,45 @@
+import { DeepSeekProvider, DeepSeekAnthropicProvider } from "./deepseek.js";
+import { KimiProvider, KimiAnthropicProvider } from "./kimi.js";
+import { QwenProvider, QwenAnthropicProvider } from "./qwen.js";
+import { GLMProvider, GLMAnthropicProvider } from "./glm.js";
+import { MiniMaxOpenAIProvider, MiniMaxAnthropicProvider } from "./minimax.js";
+import { GeminiProvider } from "./gemini.js";
+import { OllamaProvider } from "./ollama.js";
+/** DeepSeek. Defaults to the OpenAI-compatible wire (richer reasoning-replay handling). */
+export function deepseek(o) {
+    return o.protocol === "anthropic"
+        ? new DeepSeekAnthropicProvider(o.apiKey, o.model, o.retry, o.baseURL)
+        : new DeepSeekProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** Moonshot Kimi. Defaults to the OpenAI-compatible wire. */
+export function kimi(o) {
+    return o.protocol === "anthropic"
+        ? new KimiAnthropicProvider(o.apiKey, o.model, o.retry, o.baseURL)
+        : new KimiProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** Alibaba Qwen / DashScope. Defaults to the OpenAI-compatible (DashScope) wire. */
+export function qwen(o) {
+    return o.protocol === "anthropic"
+        ? new QwenAnthropicProvider(o.apiKey, o.model, o.retry, o.baseURL)
+        : new QwenProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** Zhipu GLM. Defaults to the OpenAI-compatible wire. */
+export function glm(o) {
+    return o.protocol === "anthropic"
+        ? new GLMAnthropicProvider(o.apiKey, o.model, o.retry, o.baseURL)
+        : new GLMProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** MiniMax. Defaults to the Anthropic-compatible wire (the primary M2.x path). */
+export function minimax(o) {
+    return o.protocol === "openai"
+        ? new MiniMaxOpenAIProvider(o.apiKey, o.model, o.retry, o.baseURL)
+        : new MiniMaxAnthropicProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** Google Gemini (single wire). */
+export function gemini(o) {
+    return new GeminiProvider(o.apiKey, o.model, o.retry, o.baseURL);
+}
+/** Local Ollama (single wire, no API key). */
+export function ollama(o = {}) {
+    return new OllamaProvider(o.model, o.baseURL);
+}

package/dist/providers/openai.d.ts

@@ -3,14 +3,26 @@ import type { Message, ProviderDescriptor, ProviderReplay, ProviderRunState, Ren
 import { CircuitBreaker } from "./base.js";
 import { OpenAIChatAdapter } from "./openai-chat.js";
 import type { ReplayabilityAssessment } from "./replay-validator.js";
+/** Options-object form for `OpenAIProvider` — the recommended way to construct an OpenAI-compatible
+ *  provider (custom `baseURL` no longer needs a positional hole). */
+export interface OpenAIProviderOptions {
+    apiKey: string;
+    model?: string;
+    retry?: {
+        maxRetries: number;
+        baseDelay: number;
+    };
+    /** Custom OpenAI-compatible endpoint (MiMo, DeepSeek, Kimi, …). Defaults to the OpenAI API. */
+    baseURL?: string;
+}
 export declare class OpenAIChatProvider implements LLMProvider {
-    protected readonly model: string;
     protected client: OpenAI;
     protected circuit: CircuitBreaker;
     protected maxRetries: number;
     protected baseDelay: number;
+    protected readonly model: string;
     protected readonly chat: OpenAIChatAdapter;
-    constructor(apiKey: string, model?: string, retry?: {
+    constructor(apiKeyOrOptions: string | OpenAIProviderOptions, model?: string, retry?: {
         maxRetries: number;
         baseDelay: number;
     }, baseURL?: string);

package/dist/providers/openai.js

@@ -26,18 +26,23 @@ const OPENAI_POLICIES = {
     "o4-mini": { maxTurns: 25 },
 };
 export class OpenAIChatProvider {
-    model;
     client;
     circuit;
     maxRetries;
     baseDelay;
+    model;
     chat = new OpenAIChatAdapter();
-    constructor(apiKey, model = "gpt-4o", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = "https://api.openai.com/v1") {
-        this.model = model;
-        this.client = withServerRuntimeGuard(() => new OpenAI({ apiKey, baseURL }));
+    // Accepts either the options object (`new OpenAIProvider({ apiKey, model, baseURL })`) or the legacy
+    // positional form (still used by the backend subclasses' `super(...)` calls).
+    constructor(apiKeyOrOptions, model = "gpt-4o", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = "https://api.openai.com/v1") {
+        const o = typeof apiKeyOrOptions === "string"
+            ? { apiKey: apiKeyOrOptions, model, retry, baseURL }
+            : { model: "gpt-4o", retry: { maxRetries: 3, baseDelay: 1000 }, baseURL: "https://api.openai.com/v1", ...apiKeyOrOptions };
+        this.model = o.model;
+        this.client = withServerRuntimeGuard(() => new OpenAI({ apiKey: o.apiKey, baseURL: o.baseURL }));
         this.circuit = new CircuitBreaker();
-        this.maxRetries = retry.maxRetries;
-        this.baseDelay = retry.baseDelay;
+        this.maxRetries = o.retry.maxRetries;
+        this.baseDelay = o.retry.baseDelay;
     }
     runtimePolicy() {
         return OPENAI_POLICIES[this.model] ?? {};

package/dist/providers/public.d.ts

@@ -0,0 +1,10 @@
+export { deepseek, kimi, qwen, glm, minimax, gemini, ollama } from "./factories.js";
+export type { BackendProviderOptions } from "./factories.js";
+export { OpenAIChatProvider } from "./openai.js";
+export { CircuitBreaker } from "./base.js";
+export { OpenAIResponsesAdapter } from "./openai-responses.js";
+export type { OpenAIResponsesRunState } from "./openai-responses.js";
+export { OpenAIChatAdapter } from "./openai-chat.js";
+export { endpointProfiles, modelProfiles, getModelProfile } from "./profiles.js";
+export type { ModelProfileId, ProviderId } from "./profiles.js";
+export type { ProviderRunState, ProviderToolSpec, ProviderReplay, RenderedContext, CacheBreakpointStrategy } from "../types.js";

package/dist/providers/public.js

@@ -0,0 +1,11 @@
+// `@deepstrike/sdk/providers` — backend provider factories, profiles, and provider-authoring types.
+// The root package exports `createProvider` + the 3 base providers (Anthropic / OpenAI / OpenAIResponses);
+// every other backend is a factory here. One function per backend (with a `protocol` option where a
+// backend speaks both wires) replaces the old dual `<Backend>Provider`/`<Backend>AnthropicProvider` classes.
+export { deepseek, kimi, qwen, glm, minimax, gemini, ollama } from "./factories.js";
+// `OpenAIChatProvider` is the base OpenAI-compatible class advanced users compose/extend directly.
+export { OpenAIChatProvider } from "./openai.js";
+export { CircuitBreaker } from "./base.js";
+export { OpenAIResponsesAdapter } from "./openai-responses.js";
+export { OpenAIChatAdapter } from "./openai-chat.js";
+export { endpointProfiles, modelProfiles, getModelProfile } from "./profiles.js";

package/dist/runtime/facade.d.ts

@@ -0,0 +1,49 @@
+import type { ExecutionPlane } from "./execution-plane.js";
+import type { SessionLog } from "./session-log.js";
+import type { LLMProvider } from "../types.js";
+import type { RegisteredTool } from "../tools/index.js";
+import type { WorkflowTaskSpec, KernelAgentRole } from "../types/agent.js";
+/** Shared knobs for the facade entry points. */
+export interface RunAgentOptions {
+    provider: LLMProvider;
+    goal: string;
+    systemPrompt?: string;
+    tools?: RegisteredTool[];
+    sessionId?: string;
+    maxTokens?: number;
+    maxTurns?: number;
+    /** Persist the run (resume / audit). Defaults to an in-memory, throwaway log. */
+    sessionLog?: SessionLog;
+    /** Custom execution plane (tools, sandboxing). Overrides `tools` when both are given. */
+    executionPlane?: ExecutionPlane;
+}
+/**
+ * Run a single agent to completion and return its final text — `RuntimeRunner` + `run` + `collectText`
+ * in one call. Register tools by passing `tools`; everything else has a working default.
+ */
+export declare function runAgent(opts: RunAgentOptions): Promise<string>;
+export interface RunFanoutOptions {
+    provider: LLMProvider;
+    /** One parallel worker per task. A string is shorthand for `{ goal }`. */
+    tasks: WorkflowTaskSpec[];
+    /** Final synthesis prompt; runs once after every worker completes, with their outputs in context. */
+    synthesize: string;
+    /** Role for the parallel workers (default `explore`) and the synthesis node (default `plan`). */
+    workerRole?: KernelAgentRole;
+    synthesisRole?: KernelAgentRole;
+    sessionId?: string;
+    maxTokens?: number;
+    maxTurns?: number;
+    sessionLog?: SessionLog;
+    executionPlane?: ExecutionPlane;
+}
+/**
+ * Parallel fan-out → synthesize, driven by the kernel-gated DAG (the standalone `runWorkflow` path):
+ * each task becomes a fresh-context worker node, and a final synthesis node depends on all of them.
+ * Returns the synthesis text plus every node's raw output. Safe to call from a stateless handler — it
+ * bootstraps and tears down its own kernel.
+ */
+export declare function runFanout(opts: RunFanoutOptions): Promise<{
+    synthesis: string;
+    outputs: Record<string, string>;
+}>;

package/dist/runtime/facade.js

@@ -0,0 +1,68 @@
+/**
+ * High-level facades for the two bread-and-butter cases, so a caller doesn't have to assemble
+ * `RuntimeRunner` + session log + execution plane + `collectText` by hand (integration feedback #4:
+ * the package exports ~150 symbols and the canonical entry point for common work wasn't discoverable).
+ *
+ * - `runAgent`   — one prompt, one model, the text back. The 90%-case single-agent call.
+ * - `runFanout`  — run N tasks in parallel, then synthesize, from a stateless request handler. Drives
+ *                  the kernel-gated DAG via the standalone `runWorkflow` path (governed · resumable),
+ *                  instead of hand-rolling a multi-runner fan-out.
+ *
+ * Both build a throwaway `RuntimeRunner` with sensible defaults; pass `sessionLog` / `executionPlane`
+ * to opt into persistence or custom tools. Reach for the underlying `RuntimeRunner` directly when you
+ * need streaming events, signals, memory, or governance hooks.
+ */
+import { RuntimeRunner, collectText } from "./runner.js";
+import { LocalExecutionPlane } from "./execution-plane.js";
+import { InMemorySessionLog } from "./session-log.js";
+/**
+ * Run a single agent to completion and return its final text — `RuntimeRunner` + `run` + `collectText`
+ * in one call. Register tools by passing `tools`; everything else has a working default.
+ */
+export async function runAgent(opts) {
+    const plane = opts.executionPlane ??
+        (opts.tools ?? []).reduce((p, t) => p.register(t), new LocalExecutionPlane());
+    const runner = new RuntimeRunner({
+        provider: opts.provider,
+        executionPlane: plane,
+        sessionLog: opts.sessionLog ?? new InMemorySessionLog(),
+        maxTokens: opts.maxTokens ?? 32_000,
+        ...(opts.maxTurns !== undefined ? { maxTurns: opts.maxTurns } : {}),
+        ...(opts.systemPrompt !== undefined ? { systemPrompt: opts.systemPrompt } : {}),
+    });
+    return collectText(runner.run({ sessionId: opts.sessionId ?? `agent-${crypto.randomUUID()}`, goal: opts.goal }));
+}
+/**
+ * Parallel fan-out → synthesize, driven by the kernel-gated DAG (the standalone `runWorkflow` path):
+ * each task becomes a fresh-context worker node, and a final synthesis node depends on all of them.
+ * Returns the synthesis text plus every node's raw output. Safe to call from a stateless handler — it
+ * bootstraps and tears down its own kernel.
+ */
+export async function runFanout(opts) {
+    const runner = new RuntimeRunner({
+        provider: opts.provider,
+        executionPlane: opts.executionPlane ?? new LocalExecutionPlane(),
+        sessionLog: opts.sessionLog ?? new InMemorySessionLog(),
+        maxTokens: opts.maxTokens ?? 32_000,
+        ...(opts.maxTurns !== undefined ? { maxTurns: opts.maxTurns } : {}),
+    });
+    const workerRole = opts.workerRole ?? "explore";
+    const spec = {
+        nodes: [
+            ...opts.tasks.map(task => ({ task, role: workerRole })),
+            {
+                task: opts.synthesize,
+                role: opts.synthesisRole ?? "plan",
+                dependsOn: opts.tasks.map((_, i) => i),
+            },
+        ],
+    };
+    const outcome = await runner.runWorkflow(spec, opts.sessionId ? { sessionId: opts.sessionId } : undefined);
+    // The synthesis node is the last spec node; the kernel ids nodes `wf-node{index}`. Prefer that id,
+    // but fall back to the last completed node's output so a kernel id-scheme change can't silently
+    // return an empty synthesis.
+    const synthesisId = `wf-node${opts.tasks.length}`;
+    const lastCompleted = outcome.completed[outcome.completed.length - 1];
+    const synthesis = outcome.outputs[synthesisId] ?? (lastCompleted ? outcome.outputs[lastCompleted] : undefined) ?? "";
+    return { synthesis, outputs: outcome.outputs };
+}

package/dist/runtime/runner.d.ts

@@ -230,6 +230,14 @@ export declare class RuntimeRunner {
     }): Promise<MemoryEntry[]>;
     private logMemoryRetrievalResult;
     private createSyscallRuntime;
+    /**
+     * Lower the declarative governance / attention / scheduler-budget / resource-quota policies into a
+     * freshly-created kernel. Shared by `execute()` (full agent run) and `bootstrapWorkflowKernel()`
+     * (standalone host-driven workflow) so a workflow's DAG-node spawns are gated, queued, and quota'd
+     * exactly as a mid-run spawn would be. Must run BEFORE `start_run` so the in-kernel gate enforces
+     * every policy from the first spawn. No config ⇒ the native-profile defaults (铁律: defaults only).
+     */
+    private applyKernelPolicies;
     private appendMemorySyscallObservations;
     /** Mount a tool capability on the currently-running kernel runtime. No-op if not running. */
     mountTool(schema: ToolSchema): void;
@@ -273,11 +281,21 @@ export declare class RuntimeRunner {
     runWorkflow(spec: WorkflowSpec, opts?: {
         resumedCompleted?: string[];
         resumedSubmissions?: Record<string, unknown>[][];
+        /** Standalone session id when bootstrapping (no active parent run). Defaults to a fresh uuid. */
+        sessionId?: string;
     }): Promise<{
         completed: string[];
         failed: string[];
         outputs: Record<string, string>;
     }>;
+    /**
+     * Bootstrap a standalone kernel for a host-driven workflow with NO active parent run — the path a
+     * stateless request handler takes when it calls `runWorkflow(spec)` directly. Mirrors `execute()`'s
+     * pre-run kernel setup (governance / attention / quota via `applyKernelPolicies`, then `start_run`)
+     * and records a `run_started` event so the standalone run is resumable from the session log. Sets
+     * `activeKernel` / `currentSessionId`; `runWorkflow` is responsible for tearing them down.
+     */
+    private bootstrapWorkflowKernel;
     /**
      * M5/G1: bootstrap an **agent-authored** workflow ("the model writes its own harness"). Unlike
      * `runWorkflow` (the host fires the privileged `load_workflow`), this routes the spec through the
@@ -325,7 +343,9 @@ export declare class RuntimeRunner {
      * Reads the session log, extracts completed workflow node agent_ids, and
      * calls runWorkflow with resumedCompleted so the kernel skips those nodes.
      */
-    resumeWorkflow(spec: WorkflowSpec): Promise<{
+    resumeWorkflow(spec: WorkflowSpec, opts?: {
+        sessionId?: string;
+    }): Promise<{
         completed: string[];
         failed: string[];
     }>;

package/dist/runtime/runner.js

@@ -139,6 +139,43 @@ export class RuntimeRunner {
             timeoutMs: this.opts.timeoutMs !== undefined ? BigInt(this.opts.timeoutMs) : undefined,
         });
     }
+    /**
+     * Lower the declarative governance / attention / scheduler-budget / resource-quota policies into a
+     * freshly-created kernel. Shared by `execute()` (full agent run) and `bootstrapWorkflowKernel()`
+     * (standalone host-driven workflow) so a workflow's DAG-node spawns are gated, queued, and quota'd
+     * exactly as a mid-run spawn would be. Must run BEFORE `start_run` so the in-kernel gate enforces
+     * every policy from the first spawn. No config ⇒ the native-profile defaults (铁律: defaults only).
+     */
+    applyKernelPolicies(runtime) {
+        // K2: lower governance / attention / scheduler / quota in ONE `configure_run` event instead of
+        // the previous 2–4 separate `set_*` / `load_governance_policy` events. The kernel applies each
+        // present field via the same path its granular event uses; absent fields are left untouched.
+        // (Requires the 0.2.30 core that ships `configure_run`.)
+        const osProfile = assertNativeProfile(this.opts.osProfile ?? "native");
+        const attentionPolicy = this.opts.attentionPolicy ?? osProfile.attentionPolicy;
+        const governancePolicy = this.opts.governancePolicy ?? osProfile.governancePolicy;
+        // Strip the event `kind` off the governance event — `configure_run.config.governance` carries the
+        // bare policy fields (default_action / rules / vetoed_tools / rate_limits / constraints).
+        const { kind: _govKind, ...governance } = governancePolicyToKernelEvent(governancePolicy);
+        const config = { governance };
+        if (attentionPolicy.maxQueueSize !== undefined) {
+            config.attention_max_queue_size = attentionPolicy.maxQueueSize;
+        }
+        if (this.opts.schedulerBudget?.maxWallMs !== undefined) {
+            config.scheduler_max_wall_ms = this.opts.schedulerBudget.maxWallMs;
+        }
+        if (this.opts.resourceQuota) {
+            const q = this.opts.resourceQuota;
+            config.resource_quota = {
+                ...(q.maxConcurrentSubagents !== undefined ? { max_concurrent_subagents: q.maxConcurrentSubagents } : {}),
+                ...(q.maxSpawnDepth !== undefined ? { max_spawn_depth: q.maxSpawnDepth } : {}),
+                ...(q.memoryWritesPerWindow !== undefined
+                    ? { memory_writes_per_window: [q.memoryWritesPerWindow.maxWrites, q.memoryWritesPerWindow.windowMs] }
+                    : {}),
+            };
+        }
+        kernelApply(runtime, this.pendingObservations, { kind: "configure_run", config });
+    }
     async appendMemorySyscallObservations(sessionId, observations) {
         if (!sessionId)
             return;
@@ -392,21 +429,66 @@ export class RuntimeRunner {
      * Returns the completed / failed node agent-ids.
      */
     async runWorkflow(spec, opts) {
-        if (!this.activeKernel || !this.currentSessionId) {
-            throw new Error("runWorkflow requires an active parent run");
+        // Standalone entry: with no active parent run (e.g. a stateless HTTP handler), auto-bootstrap a
+        // kernel that owns the DAG — start_run + the same governance/quota/attention policies a full run
+        // gets — then tear it down on completion so the runner is reusable. Mid-run callers (activeKernel
+        // already set by an in-flight `run()`) keep the original in-place behavior with no teardown.
+        const bootstrapped = !this.activeKernel || !this.currentSessionId;
+        if (bootstrapped) {
+            this.bootstrapWorkflowKernel(opts?.sessionId ?? `wf-${crypto.randomUUID()}`, spec);
         }
         const parentSessionId = this.currentSessionId;
         const runtime = this.activeKernel;
-        const observations = kernelApply(runtime, this.pendingObservations, {
-            kind: "load_workflow",
-            spec: workflowSpecToKernel(spec),
-            parent_session_id: parentSessionId,
-            // W0-ABI resume: skip nodes already completed before an interruption.
-            ...(opts?.resumedCompleted?.length ? { resumed_completed: opts.resumedCompleted } : {}),
-            // R3-1: re-apply recorded runtime submissions so dynamically-appended nodes are reconstructed.
-            ...(opts?.resumedSubmissions?.length ? { resumed_submissions: opts.resumedSubmissions } : {}),
-        });
-        return this.driveWorkflow(observations, parentSessionId, runtime);
+        try {
+            const observations = kernelApply(runtime, this.pendingObservations, {
+                kind: "load_workflow",
+                spec: workflowSpecToKernel(spec),
+                parent_session_id: parentSessionId,
+                // W0-ABI resume: skip nodes already completed before an interruption.
+                ...(opts?.resumedCompleted?.length ? { resumed_completed: opts.resumedCompleted } : {}),
+                // R3-1: re-apply recorded runtime submissions so dynamically-appended nodes are reconstructed.
+                ...(opts?.resumedSubmissions?.length ? { resumed_submissions: opts.resumedSubmissions } : {}),
+            });
+            return await this.driveWorkflow(observations, parentSessionId, runtime);
+        }
+        finally {
+            if (bootstrapped) {
+                this.activeKernel = null;
+                this.currentSessionId = null;
+                this.pendingObservations = [];
+            }
+        }
+    }
+    /**
+     * Bootstrap a standalone kernel for a host-driven workflow with NO active parent run — the path a
+     * stateless request handler takes when it calls `runWorkflow(spec)` directly. Mirrors `execute()`'s
+     * pre-run kernel setup (governance / attention / quota via `applyKernelPolicies`, then `start_run`)
+     * and records a `run_started` event so the standalone run is resumable from the session log. Sets
+     * `activeKernel` / `currentSessionId`; `runWorkflow` is responsible for tearing them down.
+     */
+    bootstrapWorkflowKernel(sessionId, spec) {
+        this.interrupted = false;
+        this.abortController = new AbortController();
+        this.pendingObservations = [];
+        this.pendingSpoolOutputs.clear();
+        this.currentSessionId = sessionId;
+        const runtime = this.createSyscallRuntime();
+        this.activeKernel = runtime;
+        const goal = `workflow:${spec.nodes.length} nodes`;
+        // Best-effort run_started log so a standalone workflow can be resumed via `resumeWorkflow`. The
+        // session log is fire-and-forget here (the kernel state, not the log, drives the DAG); a logless
+        // store simply means no resume.
+        void this.opts.sessionLog.append(sessionId, {
+            kind: "run_started",
+            run_id: crypto.randomUUID(),
+            goal,
+            criteria: [],
+            agent_id: this.opts.agentId,
+        }).catch(() => { });
+        this.applyKernelPolicies(runtime);
+        // K1: no explicit `start_run` — the host `load_workflow` (fired next by `runWorkflow`) self-bootstraps
+        // the run on the 0.2.30 core, matching the agent-reachable `submit_workflow` path.
+        return runtime;
     }
     /**
      * M5/G1: bootstrap an **agent-authored** workflow ("the model writes its own harness"). Unlike
@@ -575,14 +657,17 @@ export class RuntimeRunner {
      * Reads the session log, extracts completed workflow node agent_ids, and
      * calls runWorkflow with resumedCompleted so the kernel skips those nodes.
      */
-    async resumeWorkflow(spec) {
-        if (!this.currentSessionId) {
-            throw new Error("resumeWorkflow requires an active parent run");
+    async resumeWorkflow(spec, opts) {
+        // Standalone resume: a stateless handler passes the prior `sessionId` to pick up an interrupted
+        // workflow from the session log. Mid-run callers omit it and resume the active session.
+        const sessionId = opts?.sessionId ?? this.currentSessionId;
+        if (!sessionId) {
+            throw new Error("resumeWorkflow requires an active parent run or an explicit sessionId");
         }
-        const events = await this.opts.sessionLog.read(this.currentSessionId);
+        const events = await this.opts.sessionLog.read(sessionId);
         const resumedCompleted = recoverCompletedWorkflowNodes(events);
         const resumedSubmissions = recoverSubmittedWorkflowNodes(events);
-        return this.runWorkflow(spec, { resumedCompleted, resumedSubmissions });
+        return this.runWorkflow(spec, { resumedCompleted, resumedSubmissions, sessionId });
     }
     interrupt() { this.interrupted = true; this.abortController?.abort(); }
     async *run(req) {
@@ -919,51 +1004,7 @@ export class RuntimeRunner {
                 : baseSpec;
             startPayload.run_spec = agentRunSpecToKernel(spec);
         }
-        const osProfile = assertNativeProfile(this.opts.osProfile ?? "native");
-        const attentionPolicy = this.opts.attentionPolicy ?? osProfile.attentionPolicy;
-        const governancePolicy = this.opts.governancePolicy ?? osProfile.governancePolicy;
-        // Load the declarative governance policy into the kernel before the run starts,
-        // so the in-kernel gate enforces deny/veto/rate-limit/param before any tool runs.
-        kernelApply(runtime, this.pendingObservations, governancePolicyToKernelEvent(governancePolicy));
-        // Enable in-kernel signal routing so the kernel owns disposition + queuing.
-        kernelApply(runtime, this.pendingObservations, {
-            kind: "set_attention_policy",
-            ...(attentionPolicy.maxQueueSize !== undefined
-                ? { max_queue_size: attentionPolicy.maxQueueSize }
-                : {}),
-        });
-        // Set optional wall-clock budget override.
-        if (this.opts.schedulerBudget) {
-            kernelApply(runtime, this.pendingObservations, {
-                kind: "set_scheduler_budget",
-                ...(this.opts.schedulerBudget.maxWallMs !== undefined
-                    ? { max_wall_ms: this.opts.schedulerBudget.maxWallMs }
-                    : {}),
-            });
-        }
-        // Install optional resource quotas at the syscall trap (M2). Maps the ergonomic camelCase
-        // option onto the kernel's snake_case quota shape; the write-rate window is the serde tuple
-        // `[maxWrites, windowMs]`. Omitting the option leaves spawn / memory writes unbounded.
-        if (this.opts.resourceQuota) {
-            const q = this.opts.resourceQuota;
-            kernelApply(runtime, this.pendingObservations, {
-                kind: "set_resource_quota",
-                quota: {
-                    ...(q.maxConcurrentSubagents !== undefined
-                        ? { max_concurrent_subagents: q.maxConcurrentSubagents }
-                        : {}),
-                    ...(q.maxSpawnDepth !== undefined ? { max_spawn_depth: q.maxSpawnDepth } : {}),
-                    ...(q.memoryWritesPerWindow !== undefined
-                        ? {
-                            memory_writes_per_window: [
-                                q.memoryWritesPerWindow.maxWrites,
-                                q.memoryWritesPerWindow.windowMs,
-                            ],
-                        }
-                        : {}),
-                },
-            });
-        }
+        this.applyKernelPolicies(runtime);
         // Multimodal upload: seed the user's attachments (images/audio) as a history
         // message before start_run pushes the "[TASK STATE]" anchor. init_task does not
         // clear history, so order becomes [attachment user msg, "Proceed…"] — both land

package/dist/workflow/public.d.ts

@@ -0,0 +1,20 @@
+export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "../runtime/sub-agent-orchestrator.js";
+export type { SubAgentRunContext } from "../runtime/sub-agent-orchestrator.js";
+export { builtinReducers, resolveReducer } from "../runtime/reducers.js";
+export type { Reducer, ReducerRegistry, ReducerInput } from "../runtime/reducers.js";
+export { FileWorkflowStore } from "../runtime/workflow-store.js";
+export { submitWorkflowNodesTool, startWorkflowTool, generateAndFilter, verifyRules, genEval, milestoneCheckPass, milestoneCheckFail, } from "../types/agent.js";
+export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpawnInfo, WorkflowTaskSpec, } from "../types/agent.js";
+export type { AcceptanceCriterion, VerificationContract, ContractCheckResult } from "../collaboration/contract.js";
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings } from "../collaboration/contract.js";
+export type { AgentRole, IsolatedVerifierContext, CoordinatorConfig } from "../collaboration/pool.js";
+export { ContractDrivenHarness } from "../collaboration/harness.js";
+export type { ContractOutcome, ContractHarnessOptions, Violation } from "../collaboration/harness.js";
+export { HandoffBus } from "../collaboration/handoff.js";
+export type { HandoffArtifact, ContractOutcomeInput } from "../collaboration/handoff.js";
+export { CreatorVerifierMode, OrchestrationMode } from "../collaboration/modes/creator-verifier.js";
+export type { CreatorVerifierMetrics } from "../collaboration/modes/creator-verifier.js";
+export { scanSkillDir, readSkillFile } from "../skills/loader.js";
+export type { SkillMetadata } from "../skills/loader.js";
+export { executeTools, readFile, validateToolArguments } from "../tools/index.js";
+export type { ToolExecContext } from "../tools/index.js";

package/dist/workflow/public.js

@@ -0,0 +1,15 @@
+// `@deepstrike/sdk/workflow` — multi-agent orchestration: the sub-agent host, reducers, spec builders,
+// workflow node tools, agent/milestone types, and the collaboration (contract/handoff/mode) layer.
+// The root package exports `runFanout`, `AgentPool`, `WorkflowSpec`/`WorkflowNodeSpec`; the advanced
+// machinery lives here.
+export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "../runtime/sub-agent-orchestrator.js";
+export { builtinReducers, resolveReducer } from "../runtime/reducers.js";
+export { FileWorkflowStore } from "../runtime/workflow-store.js";
+export { submitWorkflowNodesTool, startWorkflowTool, generateAndFilter, verifyRules, genEval, milestoneCheckPass, milestoneCheckFail, } from "../types/agent.js";
+export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings } from "../collaboration/contract.js";
+export { ContractDrivenHarness } from "../collaboration/harness.js";
+export { HandoffBus } from "../collaboration/handoff.js";
+export { CreatorVerifierMode, OrchestrationMode } from "../collaboration/modes/creator-verifier.js";
+// Skills loader + lower-level tool execution helpers.
+export { scanSkillDir, readSkillFile } from "../skills/loader.js";
+export { executeTools, readFile, validateToolArguments } from "../tools/index.js";

package/package.json

@@ -1,10 +1,62 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.27",
+  "version": "0.2.30",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/public.d.ts",
+      "import": "./dist/providers/public.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow/public.d.ts",
+      "import": "./dist/workflow/public.js"
+    },
+    "./planes": {
+      "types": "./dist/planes/public.d.ts",
+      "import": "./dist/planes/public.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/public.d.ts",
+      "import": "./dist/memory/public.js"
+    },
+    "./harness": {
+      "types": "./dist/harness/public.d.ts",
+      "import": "./dist/harness/public.js"
+    },
+    "./os": {
+      "types": "./dist/os/public.d.ts",
+      "import": "./dist/os/public.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "providers": [
+        "./dist/providers/public.d.ts"
+      ],
+      "workflow": [
+        "./dist/workflow/public.d.ts"
+      ],
+      "planes": [
+        "./dist/planes/public.d.ts"
+      ],
+      "memory": [
+        "./dist/memory/public.d.ts"
+      ],
+      "harness": [
+        "./dist/harness/public.d.ts"
+      ],
+      "os": [
+        "./dist/os/public.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "README.md"
@@ -20,7 +72,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.27",
+    "@deepstrike/core": "0.2.30",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },