stable-harness 0.0.4 → 0.0.5

package/README.md

@@ -1,32 +1,212 @@
 # stable-harness
 
+[![npm](https://img.shields.io/npm/v/stable-harness)](https://www.npmjs.com/package/stable-harness)
+[![license](https://img.shields.io/npm/l/stable-harness)](https://www.npmjs.com/package/stable-harness)
+
 Stable runtime and operator control plane for agent applications.
 
-`stable-harness` is not an agent execution framework. It loads a YAML-defined
-workspace, maps that workspace onto an upstream agent framework, and owns the
-production runtime surfaces around execution: requests, sessions, approvals,
-events, artifacts, memory lifecycle, recovery, governance, and protocol access.
+`stable-harness` lets a team keep its chosen agent framework while adding the
+production surfaces that real workspaces need: YAML inventory, runtime requests,
+sessions, event traces, artifacts, memory lifecycle, governance hooks, recovery,
+tool repair, and protocol access.
+
+It is not another agent execution framework. Upstream frameworks own execution
+semantics. Stable Harness owns the runtime boundary around them.
+
+## Why Use It
+
+Agent frameworks are good at deciding what an agent should do next. Production
+applications also need a stable layer that can be inspected, governed, resumed,
+replayed, and called through predictable APIs.
 
-The first backend target is DeepAgents. The adapter contract is intentionally
-thin: upstream frameworks own execution semantics; stable-harness owns runtime
-assembly and lifecycle.
+Stable Harness gives you that layer without rewriting the backend:
+
+- define agents, tools, models, memory, workflows, and protocol exposure in YAML
+- run the same workspace through CLI, SDK, HTTP, and OpenAI-compatible clients
+- keep DeepAgents and LangGraph behavior upstream-native through thin adapters
+- validate and repair tool calls at the runtime gateway before execution
+- observe upstream tool, planning, delegation, progress, memory, and artifact events
+- keep downstream product logic in the workspace, not inside the framework
+
+## Install
+
+```bash
+npm install stable-harness
+```
+
+Stable Harness currently targets Node.js `>=24 <25`.
 
 ## First Run
 
+Clone the repo when developing the framework itself:
+
 ```bash
+git clone git@github.com:botbotgo/stable-harness.git
+cd stable-harness
 npm install
 npm run build
 npm run check:rules
-npm run test
+npm test
 npm run example:minimal
 ```
 
+Run an existing Stable Harness workspace:
+
+```bash
+stable-harness -w ./examples/minimal-deepagents "hello stable harness"
+```
+
+Inspect the workspace without running an agent:
+
+```bash
+stable-harness -w ./examples/minimal-deepagents
+stable-harness agent render orchestra -w ./examples/minimal-deepagents
+stable-harness workflow render review-shell -w ./examples/minimal-deepagents
+```
+
+Start the OpenAI-compatible facade:
+
+```bash
+stable-harness start -w ./examples/minimal-deepagents --port 8642
+```
+
+Then point compatible clients at:
+
+```text
+http://127.0.0.1:8642/v1
+```
+
+## Embed In An App
+
+```ts
+import { createStableHarnessRuntime } from "stable-harness";
+
+const runtime = await createStableHarnessRuntime("/path/to/workspace");
+
+const response = await runtime.request({
+  input: "Review the current release evidence.",
+  agentId: "orchestra",
+});
+
+console.log(response.output);
+```
+
+The runtime also exposes `subscribe`, `inspect`, `getRun`, `listRequests`,
+`listSessions`, `inspectRequest`, `cancel`, and `stop` so applications can build
+operator workflows around the same execution surface.
+
+## Workspace Shape
+
+A workspace is a folder with Kubernetes-style YAML documents:
+
+```text
+config/
+  runtime/workspace.yaml
+  agents/orchestra.yaml
+  catalogs/models.yaml
+  catalogs/tools.yaml
+  workflows/review-shell.yaml
+resources/
+  tools/
+  skills/
+```
+
+Minimal runtime:
+
+```yaml
+apiVersion: stable-harness.dev/v1
+kind: Runtime
+metadata:
+  name: app-runtime
+spec:
+  routing:
+    defaultAgentId: orchestra
+  protocols:
+    inProcess: true
+    openaiCompatible:
+      bearerToken: ${env:STABLE_HARNESS_API_KEY}
+```
+
+Minimal agent:
+
+```yaml
+apiVersion: stable-harness.dev/v1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  backend: deepagents
+  modelRef: local-dev
+  systemPrompt: You are a concise workspace agent.
+  tools:
+    - shell
+  subagents:
+    - reviewer
+```
+
+## Runtime Boundary
+
+```mermaid
+flowchart LR
+  Client["CLI / SDK / HTTP / OpenAI-compatible client"]
+  Runtime["Stable Harness runtime"]
+  Inventory["YAML workspace inventory"]
+  Gateway["Tool gateway + repair policy"]
+  Adapter["Thin backend adapter"]
+  Backend["DeepAgents / LangGraph / future backend"]
+  Ops["Events / runs / memory / approvals / artifacts"]
+
+  Client --> Runtime
+  Inventory --> Runtime
+  Runtime --> Gateway
+  Runtime --> Adapter
+  Adapter --> Backend
+  Runtime --> Ops
+```
+
+Stable Harness owns lifecycle, governance, observability, persistence, recovery,
+protocol access, and tool-gateway policy. It does not infer routing from user
+keywords, synthesize upstream planning calls, or rebuild backend-native agent
+semantics.
+
+## Current Backends
+
+| Backend | Status | Boundary |
+| --- | --- | --- |
+| DeepAgents | Primary adapter | Upstream execution, skills, planning, delegation, and built-ins are passed through; Stable Harness observes and governs the runtime edge. |
+| LangGraph | Runtime and workflow adapter | Stable Harness can compile explicit workflow topology and expose LangGraph-compatible protocol surfaces. |
+| Custom adapters | Supported through SDK | Implement `RuntimeAdapter` and declare the backend in workspace YAML. |
+
+## Tool Reliability
+
+Stable Harness uses `@botbotgo/better-call` at the tool-gateway boundary. The
+default CLI path configures repair mode for registered tools, so malformed or
+near-miss tool calls can be repaired before execution while agent inventory,
+schema validation, semantic validators, and governance policy still define what
+is allowed.
+
+This is constrained repair, not silent magic:
+
+- unknown or unauthorized tools stay blocked
+- semantic validators remain authoritative
+- upstream built-ins stay upstream-owned
+- repaired calls are observable through runtime events and traces
+
+## Protocols
+
+- OpenAI-compatible facade: [docs/protocols/openai-compatible.md](docs/protocols/openai-compatible.md)
+- LangGraph-compatible facade: [docs/protocols/langgraph-compatible.md](docs/protocols/langgraph-compatible.md)
+- HTTP runtime protocol: [docs/protocols/http-runtime.md](docs/protocols/http-runtime.md)
+
 ## Product Boundary
 
-See:
+Read these before adding public runtime behavior:
 
 - [Product boundary](docs/product-boundary.md)
 - [Compatibility matrix](docs/compatibility-matrix.md)
 - [Implementation blueprint](docs/implementation-blueprint.md)
 - [Engineering rules](docs/engineering-rules.md)
 - [Adapter contract](docs/adapter-contract.md)
+
+The short rule: pass through upstream execution semantics first, then add only
+small, typed, replaceable runtime capabilities around them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stable-harness",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "Stable application runtime and operator control plane for agent workspaces.",
   "license": "MIT",