stable-harness 0.0.8 → 0.0.9

package/docs/adapter-contract.md

@@ -0,0 +1,199 @@
+# Backend Adapter Contract
+
+Backend adapters connect `stable-harness` to an upstream agent framework.
+
+They are internal integration layers. They are not the public product boundary.
+
+Adapters are passthrough-first. They translate stable runtime requests into
+upstream calls, preserve upstream execution semantics, and avoid creating
+stable-owned replicas of backend concepts.
+
+## Adapter Inputs
+
+Every adapter receives:
+
+- compiled workspace
+- selected agent
+- runtime request
+- request ID
+- session ID
+- event emitter
+
+Adapters should use the selected agent's structured config to call the upstream framework.
+
+Before adding adapter behavior, inspect the current upstream backend capability. If the upstream framework already owns the behavior, the adapter should expose it through passthrough config instead of rebuilding it.
+
+Adapter config may include backend-native sections. Those sections are not a
+license to leak backend concepts into core runtime; they are an escape hatch for
+typed upstream passthrough.
+
+## Adapter Outputs
+
+Adapters may return either a string or a structured runtime output:
+
+```ts
+type RuntimeOutput = {
+  text: string;
+  metadata?: Record<string, unknown>;
+  artifacts?: RuntimeArtifact[];
+};
+```
+
+Artifacts must remain stable runtime records rather than backend-specific public types.
+
+## Runtime Interface
+
+The core runtime interface is split into focused surfaces:
+
+- `RuntimeClient`: submit a request and receive a response
+- `RuntimeEventSource`: subscribe to normalized runtime events
+- `RuntimeInspector`: inspect run records
+- `RuntimeLifecycle`: cancel running work and stop the runtime
+
+The runtime owns request IDs, session IDs, parent run links, metadata, artifact records, lifecycle state, and event recording. Backend adapters own only the upstream execution handoff.
+
+## Workflow Adapter Interface
+
+The native product surface is still an `Agent` definition. Graph-capable
+backends such as LangGraph can run an Agent whose normal inventory fields are
+connected by optional `edges`; DeepAgents agent definitions remain unchanged.
+
+Workflow adapters are separate from agent backend adapters. They receive an
+explicit workflow request plus a validated workflow definition and decide how to
+compile or execute it with an upstream workflow system.
+
+Core runtime owns:
+
+- resolving `workflowId`, `routeId`, and default workflow routing from typed config
+- validating that the workflow exists in workspace inventory
+- recording request lifecycle and normalized events
+- exposing workflow inspection and plan surfaces
+
+Workflow adapters own:
+
+- compiling the workflow to LangGraph, Microsoft Agent Framework, or another backend
+- preserving that backend's execution semantics
+- mapping backend progress into stable runtime events
+- returning stable runtime output and artifacts
+
+The core runtime must not execute workflow nodes itself unless a future native
+workflow adapter is intentionally added as a replaceable plugin.
+
+## LangGraph Workflow Adapter
+
+`@stable-harness/adapter-langgraph` is the first graph-capable adapter. It can
+compile either an explicit workflow definition or a `backend: langgraph` Agent
+with appended `edges` into an upstream LangGraph `StateGraph`.
+
+For the Agent path, nodes are derived from existing Agent inventory:
+
+- `tools` become `tools.<id>` nodes
+- `skills` become `skills.<id>` nodes
+- `subagents` become `agents.<id>` nodes
+- `edges` connect those node IDs
+
+No DeepAgents field changes are required for this path.
+
+The adapter intentionally does not define stable-owned agent or tool execution
+semantics. Each workflow node must resolve to an injected node handler, keyed by
+node ID or inventory reference such as `agents.orchestra` or `tools.shell`.
+For generic inventory integration, callers can inject node resolvers keyed by
+inventory kind such as `agents`, `tools`, `skills`, or `workflows`.
+
+This keeps responsibilities separated:
+
+- workflow YAML defines topology and inventory references
+- LangGraph owns graph execution semantics
+- node handlers decide how a referenced agent, tool, skill, or sub-workflow runs
+- node resolvers provide reusable handling for inventory reference families
+- core runtime owns request lifecycle, events, metadata, artifacts, and protocol access
+
+Conditional edges and cyclic graphs require explicit adapter plugins or options.
+They must not be inferred from prompt text.
+
+Conditional LangGraph edges are enabled through injected `conditionalRouters`.
+The YAML `condition` value is a route label, not business logic. A router keyed
+by source node ID reads typed runtime state and returns one of those labels.
+
+Sub-workflow nodes are also opt-in adapter behavior. A node that references
+`workflows.<id>` is executed only when the LangGraph adapter is configured with
+sub-workflow support. The adapter re-enters LangGraph with the referenced
+workflow and enforces a depth limit. Core runtime still treats this as one
+pluggable workflow adapter call; it does not interpret the child workflow's node
+semantics.
+
+The root runtime factory may assemble known workflow adapters from workflow YAML.
+For example, a workflow with `adapter: langgraph` can be paired with injected
+LangGraph node handlers. Unknown workflow adapter names are left for explicit
+injection and must not block ordinary runtime startup.
+
+Embedded callers may provide adapter factories keyed by adapter name. This is
+the native extension point for customer-owned runtime or workflow backends; it
+keeps workspace config generic while avoiding hardcoded backend aliases.
+
+## Required Behavior
+
+Adapters should:
+
+- preserve upstream execution semantics
+- pass through upstream-native config when possible
+- expose upstream primitives through typed config rather than harness-owned replicas
+- normalize upstream events into stable runtime events
+- put backend-specific recovery hints in typed runtime config, not core code
+- keep backend-specific details behind the adapter boundary
+- use typed config and metadata for runtime decisions
+- keep each stable wrapper capability independently enableable, disableable, replaceable, and testable
+
+## Forbidden Behavior
+
+Adapters must not:
+
+- route by matching user prose
+- hardcode downstream business domains
+- infer tools from TODO text
+- synthesize tool calls the upstream model did not select
+- locally replay upstream custom tool calls
+- recreate an upstream framework's default stack when a native constructor exists
+- add bundled behavior that cannot be enabled, disabled, or replaced independently
+- invent a stable-owned concept when upstream passthrough or typed backend config is sufficient
+- shape generic runtime interfaces around one backend's internal model
+
+## DeepAgents Direction
+
+The DeepAgents adapter should use the upstream `createDeepAgent` path as the primary integration point.
+
+DeepAgents-native features such as subagents, task tool behavior, filesystem middleware, skills, memory middleware, and sandbox primitives should be passed through or configured through upstream-native options.
+
+The adapter must not duplicate any current DeepAgents feature. If a DeepAgents feature needs stable product treatment, add only a narrow optional runtime capability around it, such as events, approvals, persistence, replay, artifact capture, protocol access, or operator inspection.
+
+DeepAgents-native memory passthrough belongs in the DeepAgents adapter package.
+Core memory lifecycle may expose generic provider and maintenance contracts, but
+it must not export DeepAgents-named helpers.
+
+`stable-harness` should expose only the stable runtime layer around that execution:
+
+- workspace loading
+- request lifecycle
+- approvals
+- events
+- traces
+- recovery
+- memory lifecycle
+- protocol access
+
+Each item should remain an independent capability with its own interface, config, tests, and replacement point.
+
+## Future Adapters
+
+OpenAI Agents SDK, Gemini SDK, LangGraph, and customer-owned frameworks should use the same adapter contract.
+
+If a backend requires a capability that does not fit this contract, first decide whether it is:
+
+- backend execution semantics, which should stay inside the adapter
+- product runtime semantics, which may extend the core contract
+- downstream application logic, which belongs in the workspace
+
+Microsoft Agent Framework should follow the same rule if added later: its typed
+workflows, checkpoints, middleware, sessions, and human-in-the-loop primitives
+should be passed through or wrapped for runtime lifecycle and observability, not
+rebuilt as a second stable-owned workflow engine.

package/docs/architecture/backend-comparison.md

@@ -0,0 +1,41 @@
+# Backend Comparison
+
+`stable-harness` compares backend adapters through the stable runtime boundary,
+not by reimplementing backend execution semantics.
+
+The comparison test in `test/adapter/backend-comparison.test.ts` runs the same
+workspace inventory through:
+
+- `deepagents`: upstream agent loop receives stable tool gateway tools and skill
+  source paths.
+- `langgraph`: graph nodes receive the same stable tool gateway and resolve
+  `skills.*` through the registry resolver.
+
+The test validates:
+
+- both backends can run from the same `WorkspaceAgent` inventory shape;
+- both backends invoke the same stable tool gateway with the same arguments;
+- each backend keeps its own runtime context and agent id;
+- DeepAgents receives skill paths as upstream passthrough;
+- LangGraph resolves skill metadata and `SKILL.md` content through the stable
+  registry resolver;
+- LangGraph graph trace preserves node order.
+
+Observed adapter difference:
+
+- DeepAgents tool output is normalized through the upstream tool wrapper and is
+  stringified before reaching the mocked agent result.
+- LangGraph node resolver output remains structured inside graph state.
+
+This difference is backend-specific and should remain visible in adapter tests
+instead of being hidden by core runtime behavior.
+
+Run the deterministic benchmark:
+
+```bash
+npm run benchmark:backend-comparison
+```
+
+The benchmark emits JSON with per-backend success rate, tool argument match rate,
+skill resolution rate, average duration, output shape, and LangGraph trace nodes.
+Use `BACKEND_COMPARE_REPEAT=20` to increase the repeat count.

package/docs/architecture/runtime-events.md

@@ -0,0 +1,263 @@
+# Runtime Event Model
+
+This document defines the stable-harness event model. The names listed here are
+the current physical event schema; old event names are not kept as a compatible
+surface.
+
+Chapter structure:
+
+- Top level: owner, starting with `agent`.
+- Middle level: category, such as Signal, Fact, Envelope, or View.
+- Lower level: concrete event group, such as `agent.tool.*` or `runtime.request.*`.
+
+The `runtime.*` and `agent.*` names in this document are stable namespaces.
+`event type` means a top-level runtime event; `payload phase` means
+`runtime.adapter.event.event.phase`.
+
+Source of truth:
+
+- Top-level runtime events: `packages/core/src/runtime/events.ts`
+- Trace projection: `packages/core/src/trace.ts`
+- OpenAI-compatible SSE projection: `packages/protocols/src/openai-stream.ts`
+
+## 1. Owner: Agent Runtime / Backend Adapter
+
+Agent owner means the upstream agent runtime or backend adapter, such as
+DeepAgents, the LangGraph workflow adapter, or future OpenAI Agents SDK and
+Gemini SDK adapters.
+
+stable-harness does not own this layer's execution semantics. It observes,
+records, persists, and projects these signals through the
+`runtime.adapter.event` envelope.
+
+### 1.1 Category: Agent Signals
+
+Agent signals are observable signals from upstream/backend execution.
+
+#### 1.1.1 Event Group: `agent.lifecycle.*`
+
+| Event | Payload phase | Owner | Common fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `agent.handoff` | `agent.handoff` | backend adapter | `adapter`, `phase`, `modelRef`, `tools`, `subagents` | Adapter took over execution. |
+
+#### 1.1.2 Event Group: `agent.output.*`
+
+| Event | Payload phase | Owner | Common fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `agent.output.delta` | `agent.output.delta` | upstream agent runtime | `adapter`, `phase`, `text` | Assistant stream delta. |
+
+#### 1.1.3 Event Group: `agent.tool.*`
+
+| Event | Payload phase | Owner | Common fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `agent.tool.start` | `agent.tool.start` | upstream / adapter | `adapter`, `phase`, `toolId`, `args` | Upstream/adapter tool call started. |
+| `agent.tool.result` | `agent.tool.result` | upstream / adapter | `adapter`, `phase`, `toolId`, `output`, `error` | Upstream/adapter tool call completed or failed. |
+
+#### 1.1.4 Event Group: `agent.workflow.*`
+
+| Event | Payload phase | Owner | Common fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `agent.langgraph.invoke` | `agent.langgraph.invoke` | upstream workflow runtime | `adapter`, `phase`, `workflowId` | LangGraph workflow invocation started. |
+| `agent.node.completed` | `agent.node.completed` | upstream workflow runtime | `adapter`, `phase`, `workflowId`, `nodeId` | Workflow node completed. |
+
+## 2. Owner: Stable Harness Runtime / Control Plane
+
+Stable Harness runtime/control-plane owner means facts, runtime contracts,
+memory lifecycle, artifacts, tool gateway events, and adapter envelopes owned by
+stable-harness itself.
+
+These events are the source of truth for store, audit, replay, and tests.
+
+### 2.1 Category: Runtime Facts
+
+Runtime facts are stable, typed, auditable facts stored on the run record.
+
+#### 2.1.1 Event Group: `runtime.request.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.request.started` | `runtime.request.started` | `requestId`, `sessionId`, `agentId` | | Request started. |
+| `runtime.request.completed` | `runtime.request.completed` | `requestId`, `sessionId`, `agentId`, `output` | | Request completed successfully. |
+| `runtime.request.failed` | `runtime.request.failed` | `requestId`, `sessionId`, `agentId`, `error` | | Request failed. |
+| `runtime.request.cancelled` | `runtime.request.cancelled` | `requestId`, `sessionId`, `agentId` | `reason` | Request was cancelled. |
+
+#### 2.1.2 Event Group: `runtime.execution.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.execution.contract.failed` | `runtime.execution.contract.failed` | `requestId`, `sessionId`, `agentId`, `reason` | `missingEvidenceTools` | Execution evidence contract failed. |
+
+#### 2.1.3 Event Group: `runtime.tool.direct.*`
+
+These events only describe stable-harness direct tool requests executed through
+the runtime tool gateway. They do not mean the agent/upstream selected a tool
+during execution; agent-internal tool calls belong to `agent.tool.*` signals.
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.tool.direct.started` | `runtime.tool.direct.started` | `requestId`, `sessionId`, `agentId`, `toolId` | | Direct tool request started. |
+| `runtime.tool.direct.completed` | `runtime.tool.direct.completed` | `requestId`, `sessionId`, `agentId`, `toolId`, `output` | | Direct tool request completed. |
+
+#### 2.1.4 Event Group: `runtime.workflow.*`
+
+These events are owned by the stable-harness workflow runtime. They are emitted
+as top-level `runtime.workflow.*` facts, not adapter payloads; adapter payloads
+only carry upstream/backend-owned workflow signals such as
+`agent.langgraph.invoke`.
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.workflow.started` | `runtime.workflow.started` | `requestId`, `sessionId`, `agentId`, `workflowId`, `adapter` | | stable-harness workflow execution started. |
+| `runtime.workflow.completed` | `runtime.workflow.completed` | `requestId`, `sessionId`, `agentId`, `workflowId`, `adapter` | | stable-harness workflow execution completed. |
+
+#### 2.1.5 Event Group: `runtime.artifact.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.artifact.created` | `runtime.artifact.created` | `requestId`, `sessionId`, `agentId`, `artifact` | | Artifact was created. |
+
+#### 2.1.6 Event Group: `runtime.specDriven.*`
+
+These events are owned by the stable-harness spec-driven workflow capability.
+They record control-plane phase facts and artifacts; they do not replace backend
+agent execution semantics.
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.specDriven.phase.started` | `runtime.specDriven.phase.started` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId` | Spec-driven phase started. |
+| `runtime.specDriven.phase.blocked` | `runtime.specDriven.phase.blocked` | `requestId`, `sessionId`, `agentId`, `phaseId`, `reason` | `workflowId` | Spec-driven phase was blocked by a gate or policy. |
+| `runtime.specDriven.phase.completed` | `runtime.specDriven.phase.completed` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId`, `artifact` | Spec-driven phase completed. |
+| `runtime.specDriven.phase.verified` | `runtime.specDriven.phase.verified` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId`, `artifact` | Spec-driven phase was verified. |
+
+#### 2.1.7 Event Group: `runtime.skill.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.skill.candidate.created` | `runtime.skill.candidate.created` | `requestId`, `sessionId`, `agentId`, `candidateId`, `name`, `confidence`, `evidenceCount`, `status` | `proposedPath` | Skill candidate was discovered. |
+
+### 2.2 Category: Runtime Memory Facts
+
+Memory is a stable-harness runtime/control-plane capability, so it belongs under
+`runtime.memory.*`.
+
+#### 2.2.1 Event Group: `runtime.memory.lifecycle`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.lifecycle` | `runtime.memory.lifecycle` | `requestId`, `sessionId`, `agentId`, `hook` | | Memory lifecycle hook ran. |
+
+Current hooks:
+
+| Hook | Meaning |
+| --- | --- |
+| `read-before-plan` | Read memory before planning. |
+| `read-before-finalize` | Read memory before final output finalization. |
+| `write-after-run` | Write memory after the run. |
+
+#### 2.2.2 Event Group: `runtime.memory.recall.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.recall.completed` | `runtime.memory.recall.completed` | `requestId`, `sessionId`, `agentId`, `namespace`, `recordIds`, `context` | | Memory recall completed. |
+
+#### 2.2.3 Event Group: `runtime.memory.write.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.candidate.submitted` | `runtime.memory.candidate.submitted` | `requestId`, `sessionId`, `agentId`, `candidate`, `decision` | `record` | Memory write candidate was submitted. |
+| `runtime.memory.approval.requested` | `runtime.memory.approval.requested` | `requestId`, `sessionId`, `agentId`, `approval` | | Memory operation requested approval. |
+
+#### 2.2.4 Event Group: `runtime.memory.plugin.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.plugin.started` | `runtime.memory.plugin.started` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace` | | Memory plugin started. |
+| `runtime.memory.plugin.completed` | `runtime.memory.plugin.completed` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace`, `candidateCount` | | Memory plugin completed. |
+| `runtime.memory.plugin.failed` | `runtime.memory.plugin.failed` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace`, `error` | | Memory plugin failed. |
+
+#### 2.2.5 Event Group: `runtime.memory.maintenance.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.maintenance.started` | `runtime.memory.maintenance.started` | `requestId`, `sessionId`, `agentId`, `target` | | Memory maintenance started. |
+| `runtime.memory.maintenance.completed` | `runtime.memory.maintenance.completed` | `requestId`, `sessionId`, `agentId`, `target`, `operationCount` | | Memory maintenance completed. |
+| `runtime.memory.maintenance.failed` | `runtime.memory.maintenance.failed` | `requestId`, `sessionId`, `agentId`, `target`, `error` | | Memory maintenance failed. |
+
+### 2.3 Category: Runtime Envelope
+
+Envelope is the stable container owned by stable-harness. The nested payload is
+owned by the agent/backend.
+
+#### 2.3.1 Event Group: `runtime.adapter.*`
+
+| Event | Event type | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.adapter.event` | `runtime.adapter.event` | `requestId`, `sessionId`, `agentId`, `event` | | Stable envelope for backend/agent signals. |
+
+## 3. Owner: Stable Harness Views / Protocol
+
+Views/protocol owner means the presentation, projection, transport, and
+narration layers stable-harness derives from facts and signals. These layers do
+not replace original facts or create execution semantics.
+
+### 3.1 Category: Runtime Trace Views
+
+#### 3.1.1 Event Group: `runtime.trace.*`
+
+| Logical view | Current implementation | Source | Purpose |
+| --- | --- | --- | --- |
+| `runtime.trace.request` | Trace category `request` | `runtime.request.*`, `runtime.execution.contract.failed` | Request timeline. |
+| `runtime.trace.tool.direct` | Trace category `tool` | `runtime.tool.direct.started`, `runtime.tool.direct.completed` | Direct/gateway tool timeline. |
+| `runtime.trace.agent.tool` | Trace category `adapter` | `runtime.adapter.event` payload `agent.tool.start` / `agent.tool.result` | Agent/upstream tool timeline. |
+| `runtime.trace.adapter` | Trace category `adapter` | `runtime.adapter.event` | Backend signal timeline. |
+| `runtime.trace.memory` | Trace category `memory` | `runtime.memory.*` | Memory timeline. |
+| `runtime.trace.artifact` | Trace category `artifact` | `runtime.artifact.created` | Artifact timeline. |
+| `runtime.trace.spec` | Trace category `spec` | `runtime.specDriven.phase.*` | Spec-driven phase timeline. |
+| `runtime.trace.plan` | Trace category `plan` | `runtime.adapter.event.traceType: "plan"` | Plan/TODO presentation. |
+| `runtime.trace.delegation` | Trace category `delegation` | `runtime.adapter.event.traceType: "delegation"` | Delegation presentation. |
+
+### 3.2 Category: Runtime Stream Views
+
+#### 3.2.1 Event Group: `runtime.stream.*`
+
+| Logical view | Current implementation | Source | Purpose |
+| --- | --- | --- | --- |
+| `runtime.stream.tool.progress` | SSE `stable_harness.tool.progress` | `runtime.tool.direct.*` or `agent.tool.*` signal | OpenAI-compatible tool progress stream. |
+| `runtime.stream.progress.narration` | SSE `stable_harness.progress.narration` | `runtime.progress.narration` | OpenAI-compatible narration stream. |
+
+### 3.3 Category: Runtime Progress Views
+
+#### 3.3.1 Event Group: `runtime.progress.*`
+
+| Logical event | Current implementation | Required fields | Optional fields | Meaning |
+| --- | --- | --- | --- | --- |
+| `runtime.progress.narration` | Runtime event | `requestId`, `sessionId`, `agentId`, `message`, `provider`, `sourceEventTypes` | `sourceEventIds`, `model`, `style` | Human-readable progress generated from runtime facts and agent signals. |
+
+Constraints:
+
+- The narrator only consumes events. It must not mutate execution, runtime
+  state, tool results, approvals, or memory decisions.
+- Narrator output must be traceable to source events.
+- The narrator provider is a pluggable runtime view provider with sync or async
+  implementations; built-in `template` narration is available.
+- Enable narration with `createStableHarnessRuntime({ progressNarration })` or
+  workspace `runtime.progress.narration.enabled`.
+- CLI presentation policy is a separate runtime setting: `runtime.cli.events`.
+  It only controls CLI display, not whether runtime events are produced.
+- The CLI default only shows `runtime.progress.narration`; use `include: ["*"]`
+  to show every event.
+
+Workspace YAML:
+
+```yaml
+spec:
+  progress:
+    narration:
+      enabled: true
+      style: concise
+  cli:
+    events:
+      include:
+        - runtime.progress.narration
+        - runtime.tool.direct.*
+```