stable-harness 0.0.139 → 0.0.143

package/README.md

@@ -92,25 +92,34 @@ stable-harness console -w ./examples/minimal-deepagents
 Start the runtime daemon and protocol facades:
 
 ```bash
-stable-harness start -w ./examples/minimal-deepagents --port 8642
+stable-harness start -w ./examples/minimal-deepagents
+stable-harness serve -w ./examples/minimal-deepagents
 ```
 
-Then point first-party clients at the Stable Runtime control plane and
-OpenAI-compatible clients at `/v1`:
+Then point clients at the single Stable Harness gateway. The gateway exposes
+system metadata, first-party runtime APIs, and protocol-compatible surfaces under
+stable path groups:
 
 ```text
-http://127.0.0.1:8641
-http://127.0.0.1:8642/v1
+http://127.0.0.1:56789/manifest
+http://127.0.0.1:56789/protocols
+http://127.0.0.1:56789/runtime/v1
+http://127.0.0.1:56789/protocols/openai/v1
+http://127.0.0.1:56789/protocols/langgraph
+http://127.0.0.1:56789/protocols/mcp
+http://127.0.0.1:56789/protocols/a2a
+http://127.0.0.1:56789/protocols/acp
+http://127.0.0.1:56789/protocols/ag-ui
 ```
 
-ACP, A2A, and AG-UI facades are available when enabled in runtime YAML through
-the combined `agentProtocols` server.
+Runtime YAML can disable protocol groups or bind the gateway to an
+environment-managed port.
 
 For request commands and console mode, the CLI can choose how it connects:
 
 ```bash
 stable-harness -w ./examples/minimal-deepagents --runtime auto "Review this workspace."
-stable-harness -w ./examples/minimal-deepagents --runtime daemon --daemon-url http://127.0.0.1:8641 "Review this workspace."
+stable-harness -w ./examples/minimal-deepagents --runtime daemon --daemon-url http://127.0.0.1:56789/runtime/v1 "Review this workspace."
 stable-harness -w ./examples/minimal-deepagents --runtime local "Review this workspace."
 stable-harness console -w ./examples/minimal-deepagents --runtime daemon
 ```
@@ -124,15 +133,19 @@ When a protocol facade is enabled, the same CLI can also choose the client
 protocol:
 
 ```bash
-stable-harness -w ./examples/minimal-deepagents --protocol stable-runtime --tool echo_tool --tool-args-json '{"value":"native"}'
-stable-harness -w ./examples/minimal-deepagents --protocol a2a --protocol-url http://127.0.0.1:8650 --tool echo_tool --tool-args-json '{"value":"a2a"}'
-stable-harness -w ./examples/minimal-deepagents --protocol agui --protocol-url http://127.0.0.1:8650 --tool echo_tool --tool-args-json '{"value":"agui"}'
-stable-harness -w ./examples/minimal-deepagents --protocol acp --protocol-url http://127.0.0.1:8650 --tool echo_tool --tool-args-json '{"value":"acp"}'
+stable-harness -w ./examples/minimal-deepagents --protocol runtime --tool echo_tool --tool-args-json '{"value":"native"}'
+stable-harness -w ./examples/minimal-deepagents --protocol a2a --protocol-url http://127.0.0.1:56789/protocols --tool echo_tool --tool-args-json '{"value":"a2a"}'
+stable-harness -w ./examples/minimal-deepagents --protocol agui --protocol-url http://127.0.0.1:56789/protocols --tool echo_tool --tool-args-json '{"value":"agui"}'
+stable-harness -w ./examples/minimal-deepagents --protocol acp --protocol-url http://127.0.0.1:56789/protocols --tool echo_tool --tool-args-json '{"value":"acp"}'
 ```
 
-`stable-runtime` exposes the full operator control plane. A2A, AG-UI, and ACP
-map request turns through their protocol facades; use Stable Runtime HTTP + SSE
-for traces, approvals, memory administration, and full session inspection.
+`runtime` exposes the full operator control plane directly through
+`/runtime/v1`. OpenAI, A2A, AG-UI, ACP, MCP, and LangGraph-compatible protocol
+routes live under `/protocols/*`.
+
+See the [protocol feature coverage matrix](docs/protocols/coverage-matrix.md)
+for the side-by-side list of features, API families, protocol support, and
+unsupported areas.
 
 Build a portable Docker runtime artifact for the workspace:
 
@@ -264,10 +277,10 @@ This is constrained repair, not silent magic:
 
 ## Protocols
 
-- Stable Runtime HTTP + SSE: [docs/protocols/http-runtime.md](docs/protocols/http-runtime.md)
+- native runtime HTTP + SSE: [docs/protocols/http-runtime.md](docs/protocols/http-runtime.md)
 - 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)
-- ACP, A2A, and AG-UI facades: [docs/protocols/agent-protocols.md](docs/protocols/agent-protocols.md)
+- ACP, A2A, and AG-UI facades: [docs/protocols/protocol-facades.md](docs/protocols/protocol-facades.md)
 
 ## Documentation
 

package/dist/index.js

@@ -1 +1 @@
-import{createBackendModel as e,createDeepAgentsAdapter as r}from"@stable-harness/adapter-deepagents";import{createLangGraphRuntimeAdapter as a,createLangGraphWorkflowAdapter as t,createRegistrySkillResolverProvider as o}from"@stable-harness/adapter-langgraph";import{createStableHarnessRuntime as n}from"@stable-harness/core";import{createModuleToolGateway as i}from"@stable-harness/tool-gateway";import{loadWorkspaceFromYaml as s}from"@stable-harness/workspace-yaml";export{createDeepAgentsAdapter,createDeepAgentsMemoryMaintenanceTarget}from"@stable-harness/adapter-deepagents";export{createDeepAgentsMiddlewareSkillProvider,createLangGraphRuntimeAdapter,createLangGraphWorkflowAdapter,createRegistrySkillResolverProvider}from"@stable-harness/adapter-langgraph";export{createLangMemServiceProvider}from"@stable-harness/memory";export{createInMemoryRuntimeMemoryStore,createJsonFileRuntimeMemoryStore}from"@stable-harness/memory";export{applySpecDrivenPhaseTransition,containsRecoverableResultOutput,createSpecDrivenArtifact,createSpecDrivenArtifactEvent,createSpecDrivenPhaseEvent,createSpecDrivenWorkflowPolicy,createSpecDrivenWorkflowState,defaultExecutionEvaluatorRules,defaultToolGuardrails,evaluateExecutionRules,evaluateToolGuardrails,collectStableHarnessPrometheusSamples,projectRuntimeTrace,repeatToolGuardrail,renderStableHarnessPrometheusMetrics,resolveEnabledMemories,STABLE_HARNESS_PROMETHEUS_LABELS,requiredPlanToolGuardrail,reviewExecutionEvidence,toolDependencyGuardrail}from"@stable-harness/core";export{loadWorkspaceFromYaml}from"@stable-harness/workspace-yaml";export{createInMemoryToolGateway,createModuleToolGateway}from"@stable-harness/tool-gateway";export function createStableHarnessRuntime(e){return"string"==typeof e?createStableRuntime({workspaceRoot:e}):"workspaceRoot"in e?createStableRuntime(e):n(e)}export async function createStableRuntime(e){const r=await s(e.workspaceRoot),a=e.toolGateway??await i({tools:r.tools.values()});return n({workspace:r,toolGateway:a,memory:e.memory,qualityReviewModel:createQualityReviewModel(r),toolGuardrails:e.toolGuardrails,executionEvaluatorRules:e.executionEvaluatorRules,adapters:e.adapters??createRuntimeAdapters(r,e),workflowAdapters:e.workflowAdapters??createWorkflowAdapters(r,e)})}function createQualityReviewModel(r){const a=function readQualityModelRef(e){const r=isRecord(e)?e:{};return readString((isRecord(r.reviewer)?r.reviewer:r).modelRef)}(r.runtime.quality),t=a?r.models.get(a):void 0,o=t?e(t):void 0;return function isQualityReviewModel(e){return isRecord(e)&&"function"==typeof e.invoke}(o)?o:void 0}export async function requestStableRuntime(e,r){return e.request(r)}function createRuntimeAdapters(e,t){const o={deepagents:({policy:e})=>r(e.config?{config:e.config}:{}),langgraph:({policy:e})=>a({...readLangGraphOptions(e.config),name:e.name}),...t.adapterFactories},n=function runtimeAdapterPolicies(e){const r=e.runtime.adapters?.filter(e=>!1!==e.enabled);return r&&r.length>0?r:[...new Set([...e.agents.values()].map(e=>e.backend))].map(e=>({name:e}))}(e);return n.map(r=>{const a=o[r.name];if(a)return a({policy:r,workspace:e});throw new Error(`Unsupported runtime adapter: ${r.name}`)})}function createWorkflowAdapters(e,r){const a={langgraph:({name:e,options:r})=>t({...readLangGraphOptions(r),name:e}),...r.workflowAdapterFactories};return[...new Set([...e.workflows.values()].map(e=>e.adapter??"").filter(Boolean))].map(t=>{const o=a[t];return o?.({name:t,workspace:e,options:readWorkflowAdapterOptions(r,t)})}).filter(e=>Boolean(e))}function readWorkflowAdapterOptions(e,r){return e.workflowAdapterOptions?.[r]??{}}function readLangGraphOptions(e){return isRecord(e)?{...e,...void 0!==readLangGraphSkillProvider(e)?{skillProvider:readLangGraphSkillProvider(e)}:{}}:{}}function readLangGraphSkillProvider(e){if(!1===e.skillProvider)return!1;const r=function readSkillProviderConfig(e){return isRecord(e.skills)?e.skills:isRecord(e.skillProvider)?e.skillProvider:void 0}(e);if(!r)return;const a=readString(r.provider)??readString(r.name)??"registry-resolver";if(["none","disabled","false"].includes(a))return!1;if("registry-resolver"!==a)throw new Error(`Unsupported LangGraph skill provider: ${a}`);return o({..."boolean"==typeof r.includeContent?{includeContent:r.includeContent}:{},..."number"==typeof r.maxBytes&&Number.isFinite(r.maxBytes)?{maxBytes:r.maxBytes}:{}})}function readString(e){return"string"==typeof e&&e.trim()?e.trim():void 0}function isRecord(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}
+import{createBackendModel as e,createDeepAgentsAdapter as r}from"@stable-harness/adapter-deepagents";import{createLangGraphRuntimeAdapter as t,createLangGraphWorkflowAdapter as a,createRegistrySkillResolverProvider as o}from"@stable-harness/adapter-langgraph";import{createStableHarnessRuntime as n}from"@stable-harness/core";import{createModuleToolGateway as i}from"@stable-harness/tool-gateway";import{loadWorkspaceFromYaml as s}from"@stable-harness/workspace-yaml";export{createDeepAgentsAdapter,createDeepAgentsMemoryMaintenanceTarget}from"@stable-harness/adapter-deepagents";export{createDeepAgentsMiddlewareSkillProvider,createLangGraphRuntimeAdapter,createLangGraphWorkflowAdapter,createRegistrySkillResolverProvider}from"@stable-harness/adapter-langgraph";export{createLangMemServiceProvider}from"@stable-harness/memory";export{createInMemoryRuntimeMemoryStore,createJsonFileRuntimeMemoryStore}from"@stable-harness/memory";export{applySpecDrivenPhaseTransition,containsRecoverableResultOutput,createSpecDrivenArtifact,createSpecDrivenArtifactEvent,createSpecDrivenPhaseEvent,createSpecDrivenWorkflowPolicy,createSpecDrivenWorkflowState,defaultExecutionEvaluatorRules,defaultToolGuardrails,evaluateExecutionRules,evaluateToolGuardrails,collectStableHarnessPrometheusSamples,projectRuntimeTrace,repeatToolGuardrail,renderStableHarnessPrometheusMetrics,resolveEnabledMemories,STABLE_HARNESS_PROMETHEUS_LABELS,requiredPlanToolGuardrail,reviewExecutionEvidence,toolDependencyGuardrail}from"@stable-harness/core";export{loadWorkspaceFromYaml}from"@stable-harness/workspace-yaml";export{createInMemoryToolGateway,createModuleToolGateway}from"@stable-harness/tool-gateway";export function createStableHarnessRuntime(e){return"string"==typeof e?createStableRuntime({workspaceRoot:e}):"workspaceRoot"in e?createStableRuntime(e):n(e)}export async function createStableRuntime(e){const r=await s(e.workspaceRoot),t=e.toolGateway??await i({tools:r.tools.values()});return n({workspace:r,toolGateway:t,memory:e.memory,qualityReviewModel:createQualityReviewModel(r),toolGuardrails:e.toolGuardrails,executionEvaluatorRules:e.executionEvaluatorRules,adapters:e.adapters??createRuntimeAdapters(r,e),workflowAdapters:e.workflowAdapters??createWorkflowAdapters(r,e)})}function createQualityReviewModel(r){const t=function readQualityModelRef(e){const r=isRecord(e)?e:{};return readString((isRecord(r.reviewer)?r.reviewer:r).modelRef)}(r.runtime.quality),a=t?r.models.get(t):void 0,o=a?e(a):void 0;return function isQualityReviewModel(e){return isRecord(e)&&"function"==typeof e.invoke}(o)?o:void 0}export async function requestStableRuntime(e,r){return e.request(r)}function createRuntimeAdapters(e,a){const o={deepagents:({policy:e})=>r(e.config?{config:e.config}:{}),langgraph:({policy:e})=>t({...readLangGraphOptions(e.config),name:e.name}),...a.adapterFactories},n=function runtimeAdapterPolicies(e){const r=e.runtime.adapters?.filter(e=>!1!==e.enabled);return r&&r.length>0?r:[...new Set([...e.agents.values()].map(e=>e.backend))].map(e=>({name:e}))}(e);return n.map(r=>{const t=o[r.name];if(t)return t({policy:r,workspace:e});throw new Error(`Unsupported runtime adapter: ${r.name}`)})}function createWorkflowAdapters(e,r){const t={langgraph:({name:e,options:r})=>a({...readLangGraphOptions(r),name:e}),...r.workflowAdapterFactories};return[...new Set([...e.workflows.values()].map(e=>e.adapter??"").filter(Boolean))].map(a=>{const o=t[a];return o?.({name:a,workspace:e,options:readWorkflowAdapterOptions(r,a)})}).filter(e=>Boolean(e))}function readWorkflowAdapterOptions(e,r){return e.workflowAdapterOptions?.[r]??{}}function readLangGraphOptions(e){return isRecord(e)?{...e,...void 0!==readLangGraphSkillProvider(e)?{skillProvider:readLangGraphSkillProvider(e)}:{}}:{}}function readLangGraphSkillProvider(e){if(!1===e.skillProvider)return!1;const r=function readSkillProviderConfig(e){return isRecord(e.skills)?e.skills:isRecord(e.skillProvider)?e.skillProvider:void 0}(e);if(!r)return;const t=readString(r.provider)??readString(r.name)??"registry-resolver";if(["none","disabled","false"].includes(t))return!1;if("registry-resolver"!==t)throw new Error(`Unsupported LangGraph skill provider: ${t}`);return o({..."boolean"==typeof r.includeContent?{includeContent:r.includeContent}:{},..."number"==typeof r.maxBytes&&Number.isFinite(r.maxBytes)?{maxBytes:r.maxBytes}:{}})}function readString(e){return"string"==typeof e&&e.trim()?e.trim():void 0}function isRecord(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}

package/dist/runtime/skills/skill-metadata.js

@@ -1 +1 @@
-import{readFileSync as r,statSync as t}from"node:fs";import*as e from"node:path";import{parse as n}from"yaml";export function validateSkillMetadata(o){const i=t(o).isDirectory()?e.join(o,"SKILL.md"):o,a=r(i,"utf8").match(/^---\n([\s\S]*?)\n---/u);if(!a)throw new Error(`${i} is missing YAML front matter`);const s=n(a[1]),m=readString(s.name,"name",i),l=readString(s.description,"description",i),d=function readStringList(r){return Array.isArray(r)?r.filter(r=>"string"==typeof r&&r.trim().length>0):[]}(s["allowed-tools"]);if(0===d.length)throw new Error(`${e.basename(o)} must declare allowed-tools`);return{name:m,description:l,allowedTools:d,path:i}}function readString(r,t,e){if("string"!=typeof r||!r.trim())throw new Error(`${e} front matter requires ${t}`);return r.trim()}
+import{readFileSync as r,statSync as t}from"node:fs";import*as e from"node:path";import{parse as o}from"yaml";export function validateSkillMetadata(n){const i=t(n).isDirectory()?e.join(n,"SKILL.md"):n,a=r(i,"utf8").match(/^---\n([\s\S]*?)\n---/u);if(!a)throw new Error(`${i} is missing YAML front matter`);const s=o(a[1]),m=readString(s.name,"name",i),l=readString(s.description,"description",i),d=function readStringList(r){return Array.isArray(r)?r.filter(r=>"string"==typeof r&&r.trim().length>0):[]}(s["allowed-tools"]);if(0===d.length)throw new Error(`${e.basename(n)} must declare allowed-tools`);return{name:m,description:l,allowedTools:d,path:i}}function readString(r,t,e){if("string"!=typeof r||!r.trim())throw new Error(`${e} front matter requires ${t}`);return r.trim()}

package/dist/workspace/compile.js

@@ -1 +1 @@
-import{readdir as e,readFile as t}from"node:fs/promises";import*as s from"node:path";import{parseAllDocuments as o}from"yaml";import{validateSkillMetadata as r}from"../runtime/skills/skill-metadata.js";export async function loadWorkspace(n){const i=s.resolve(n),a=await async function readConfigDocuments(e){const s=await listYamlFiles(e),r=[];for(const e of s){const s=await t(e,"utf8");for(const e of o(s)){const t=e.toJSON();t?.kind&&r.push({...t,metadata:t.metadata??{},spec:t.spec??{}})}}return r}(s.join(i,"config")),c=function compileModels(e){const t=new Map;for(const s of e){if("Models"===s.kind&&Array.isArray(s.spec))for(const e of s.spec){const s=compileModel(e);t.set(String(s.name),s)}if("Model"===s.kind&&isRecord(s.spec)){const e=compileModel({name:s.metadata?.name,...s.spec});t.set(String(e.name),e)}}return t}(a),l=function compileAgents(e,t){const o=new Map;for(const r of t.filter(e=>"Agent"===e.kind)){if(!isRecord(r.spec))continue;const t=String(r.metadata?.name),n=isRecord(r.spec.config)?r.spec.config:{},i=readSystemPrompt(r.spec,n);o.set(t,{id:t,name:t,description:r.metadata?.description??"",sourcePath:s.join(e,"config","agents",`${t}.yaml`),modelRef:normalizeRef(r.spec.modelRef),toolRefs:readStringList(r.spec.tools),skillPathRefs:readStringList(r.spec.skills).map(t=>s.join(e,"resources","skills",t)),subagentRefs:readStringList(r.spec.subagents),memorySources:readMemorySources(r.spec.memory),deepAgentConfig:{...n,responseFormat:normalizeResponseFormat(n.responseFormat),systemPrompt:i}})}return o}(i,a),m=await async function compileTools(e,t){const o=new Map;for(const e of t.filter(e=>"Tool"===e.kind)){const t=e.metadata?.name;t&&o.set(t,{name:t,id:t,spec:e.spec})}return await loadToolExports(s.join(e,"resources","tools"),o),o}(i,a),p=await async function compileSkills(t){const o=new Map,n=s.join(t,"resources","skills");for(const t of await e(n,{withFileTypes:!0})){if(!t.isDirectory())continue;const e=s.join(n,t.name),i=r(e);o.set(i.name,{name:i.name,path:e,description:i.description,allowedTools:i.allowedTools})}return o}(i);return function resolveAgentSkillNames(e,t){for(const o of e.values())o.skillPathRefs=o.skillPathRefs.map(e=>{const o=s.basename(e);return t.get(o)?.path??e})}(l,p),function ensureDirectAgent(e,t){e.has("direct")||e.set("direct",{id:"direct",name:"direct",description:"Direct execution agent.",sourcePath:s.join(t,"config","runtime","workspace.yaml"),toolRefs:[],skillPathRefs:[],subagentRefs:[],memorySources:[],deepAgentConfig:{}})}(l,i),{workspaceRoot:i,models:c,agents:l,tools:m,skills:p,bindings:compileBindings(l)}}async function listYamlFiles(t){const o=await e(t,{withFileTypes:!0});return(await Promise.all(o.map(async e=>{const o=s.join(t,e.name);return e.isDirectory()?listYamlFiles(o):e.isFile()&&/\.ya?ml$/iu.test(e.name)?[o]:[]}))).flat().sort()}function compileModel(e){const t=String(e.name),s={...e};return delete s.name,delete s.provider,delete s.model,{name:t,provider:String(resolveValue(e.provider)),model:String(resolveValue(e.model)),init:(o=s,Object.fromEntries(Object.entries(o).map(([e,t])=>[e,resolveValue(t)])))};var o}async function loadToolExports(o,r){const n=await e(o,{withFileTypes:!0});for(const e of n){if(e.name.startsWith("_"))continue;const n=s.join(o,e.name);if(e.isDirectory()){await loadToolExports(n,r);continue}if(!e.isFile()||!e.name.endsWith(".mjs"))continue;const i=(await t(n,"utf8")).match(/export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*tool/u),a=i?.[1]??s.basename(e.name,".mjs");r.set(a,{name:a,id:a,sourcePath:n})}}function compileBindings(e){const t=new Map;for(const[s,o]of e){const e=o.deepAgentConfig;t.set(s,{agentId:s,deepAgentParams:{responseFormat:e.responseFormat,systemPrompt:e.systemPrompt}})}return t}function readSystemPrompt(e,t){return"string"==typeof e.systemPrompt?e.systemPrompt:"string"==typeof t.systemPrompt?t.systemPrompt:""}function normalizeResponseFormat(e){const t={type:"object",properties:{status:{type:"string",enum:["completed","blocked","failed","refused"]},summary:{type:"array",items:{type:"string"}},findings:{type:"array",items:{type:"string"}},blockers:{type:"array",items:{type:"string"}},nextActions:{type:"array",items:{type:"string"}},report:{type:"string"}},required:["status","summary","findings","blockers","nextActions","report"]};if(!isRecord(e))return t;const s=isRecord(e.properties)?e.properties:{},o=Array.isArray(e.required)?e.required:[];return{...t,...e,properties:{...t.properties,...s},required:[...new Set([...t.required,...o].filter(e=>"string"==typeof e))]}}function readMemorySources(e){return Array.isArray(e)?e.flatMap(e=>isRecord(e)&&"string"==typeof e.path?[e.path]:[]):[]}function readStringList(e){return Array.isArray(e)?e.filter(e=>"string"==typeof e&&e.trim().length>0):[]}function normalizeRef(e){return"string"==typeof e?e.replace(/^[^/]+\//u,""):void 0}function resolveValue(e){if("string"!=typeof e)return e;const t=e.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/gu,(e,t,s)=>process.env[t]??s??"");return/^(true|false)$/iu.test(t)?"true"===t.toLowerCase():/^-?\d+$/u.test(t)?Number(t):t}function isRecord(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}
+import{readdir as e,readFile as t}from"node:fs/promises";import*as o from"node:path";import{parseAllDocuments as s}from"yaml";import{validateSkillMetadata as r}from"../runtime/skills/skill-metadata.js";export async function loadWorkspace(n){const i=o.resolve(n),a=await async function readConfigDocuments(e){const o=await listYamlFiles(e),r=[];for(const e of o){const o=await t(e,"utf8");for(const e of s(o)){const t=e.toJSON();t?.kind&&r.push({...t,metadata:t.metadata??{},spec:t.spec??{}})}}return r}(o.join(i,"config")),c=function compileModels(e){const t=new Map;for(const o of e){if("Models"===o.kind&&Array.isArray(o.spec))for(const e of o.spec){const o=compileModel(e);t.set(String(o.name),o)}if("Model"===o.kind&&isRecord(o.spec)){const e=compileModel({name:o.metadata?.name,...o.spec});t.set(String(e.name),e)}}return t}(a),m=function compileAgents(e,t){const s=new Map;for(const r of t.filter(e=>"Agent"===e.kind)){if(!isRecord(r.spec))continue;const t=String(r.metadata?.name),n=isRecord(r.spec.config)?r.spec.config:{},i=readSystemPrompt(r.spec,n);s.set(t,{id:t,name:t,description:r.metadata?.description??"",sourcePath:o.join(e,"config","agents",`${t}.yaml`),modelRef:normalizeRef(r.spec.modelRef),toolRefs:readStringList(r.spec.tools),skillPathRefs:readStringList(r.spec.skills).map(t=>o.join(e,"resources","skills",t)),subagentRefs:readStringList(r.spec.subagents),memorySources:readMemorySources(r.spec.memory),deepAgentConfig:{...n,responseFormat:normalizeResponseFormat(n.responseFormat),systemPrompt:i}})}return s}(i,a),l=await async function compileTools(e,t){const s=new Map;for(const e of t.filter(e=>"Tool"===e.kind)){const t=e.metadata?.name;t&&s.set(t,{name:t,id:t,spec:e.spec})}return await loadToolExports(o.join(e,"resources","tools"),s),s}(i,a),p=await async function compileSkills(t){const s=new Map,n=o.join(t,"resources","skills");for(const t of await e(n,{withFileTypes:!0})){if(!t.isDirectory())continue;const e=o.join(n,t.name),i=r(e);s.set(i.name,{name:i.name,path:e,description:i.description,allowedTools:i.allowedTools})}return s}(i);return function resolveAgentSkillNames(e,t){for(const s of e.values())s.skillPathRefs=s.skillPathRefs.map(e=>{const s=o.basename(e);return t.get(s)?.path??e})}(m,p),function ensureDirectAgent(e,t){e.has("direct")||e.set("direct",{id:"direct",name:"direct",description:"Direct execution agent.",sourcePath:o.join(t,"config","runtime","workspace.yaml"),toolRefs:[],skillPathRefs:[],subagentRefs:[],memorySources:[],deepAgentConfig:{}})}(m,i),{workspaceRoot:i,models:c,agents:m,tools:l,skills:p,bindings:compileBindings(m)}}async function listYamlFiles(t){const s=await e(t,{withFileTypes:!0});return(await Promise.all(s.map(async e=>{const s=o.join(t,e.name);return e.isDirectory()?listYamlFiles(s):e.isFile()&&/\.ya?ml$/iu.test(e.name)?[s]:[]}))).flat().sort()}function compileModel(e){const t=String(e.name),o={...e};return delete o.name,delete o.provider,delete o.model,{name:t,provider:String(resolveValue(e.provider)),model:String(resolveValue(e.model)),init:(s=o,Object.fromEntries(Object.entries(s).map(([e,t])=>[e,resolveValue(t)])))};var s}async function loadToolExports(s,r){const n=await e(s,{withFileTypes:!0});for(const e of n){if(e.name.startsWith("_"))continue;const n=o.join(s,e.name);if(e.isDirectory()){await loadToolExports(n,r);continue}if(!e.isFile()||!e.name.endsWith(".mjs"))continue;const i=(await t(n,"utf8")).match(/export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*tool/u),a=i?.[1]??o.basename(e.name,".mjs");r.set(a,{name:a,id:a,sourcePath:n})}}function compileBindings(e){const t=new Map;for(const[o,s]of e){const e=s.deepAgentConfig;t.set(o,{agentId:o,deepAgentParams:{responseFormat:e.responseFormat,systemPrompt:e.systemPrompt}})}return t}function readSystemPrompt(e,t){return"string"==typeof e.systemPrompt?e.systemPrompt:"string"==typeof t.systemPrompt?t.systemPrompt:""}function normalizeResponseFormat(e){const t={type:"object",properties:{status:{type:"string",enum:["completed","blocked","failed","refused"]},summary:{type:"array",items:{type:"string"}},findings:{type:"array",items:{type:"string"}},blockers:{type:"array",items:{type:"string"}},nextActions:{type:"array",items:{type:"string"}},report:{type:"string"}},required:["status","summary","findings","blockers","nextActions","report"]};if(!isRecord(e))return t;const o=isRecord(e.properties)?e.properties:{},s=Array.isArray(e.required)?e.required:[];return{...t,...e,properties:{...t.properties,...o},required:[...new Set([...t.required,...s].filter(e=>"string"==typeof e))]}}function readMemorySources(e){return Array.isArray(e)?e.flatMap(e=>isRecord(e)&&"string"==typeof e.path?[e.path]:[]):[]}function readStringList(e){return Array.isArray(e)?e.filter(e=>"string"==typeof e&&e.trim().length>0):[]}function normalizeRef(e){return"string"==typeof e?e.replace(/^[^/]+\//u,""):void 0}function resolveValue(e){if("string"!=typeof e)return e;const t=e.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/gu,(e,t,o)=>process.env[t]??o??"");return/^(true|false)$/iu.test(t)?"true"===t.toLowerCase():/^-?\d+$/u.test(t)?Number(t):t}function isRecord(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}

package/docs/0.1.0-tool-guard-benchmark.zh.md

@@ -4,7 +4,7 @@
 
 ## 测试设置
 
-- 远端 Ollama：`https://ollama-rtx-4070.easynet.world`
+- 远端 Ollama：`https://ollama-rtx-4070.easynet.world/v1`
 - 每个模型自然用例轮数：`10`，总自然用例数为 `50`
 - 注入错误矩阵覆盖：未知工具、错误工具名、缺必填、类型错、enum 错、extra arg、绝对路径、语义 ticker 错、不可解析参数
 - 该 benchmark 是产品级 fault-injection 与本地 BFCL-style 子集，不是 BFCL 官方成绩。
@@ -19,8 +19,8 @@
 | qwen3.5:0.8b | on | 50 | 100% | 100% | 0% | 0% | 100% |
 | qwen3.5:2b | off | 50 | 100% | 100% | 0% | 0% | 100% |
 | qwen3.5:2b | on | 50 | 100% | 100% | 0% | 0% | 100% |
-| granite4.1:3b | off | 50 | 100% | 100% | 0% | 0% | 100% |
-| granite4.1:3b | on | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:4b | off | 50 | 100% | 100% | 0% | 0% | 100% |
+| qwen3.5:4b | on | 50 | 100% | 100% | 0% | 0% | 100% |
 | qwen3.5:4b | off | 50 | 100% | 100% | 0% | 0% | 100% |
 | qwen3.5:4b | on | 50 | 100% | 100% | 0% | 0% | 100% |
 
@@ -31,12 +31,12 @@
 | qwen3:0.6b | 100% | 66.7% | name, schema, type, semantic |
 | qwen3.5:0.8b | 100% | 66.7% | name, schema, type, semantic |
 | qwen3.5:2b | 100% | 100% | name, schema, type, semantic |
-| granite4.1:3b | 100% | 100% | name, schema, type, semantic |
+| qwen3.5:4b | 100% | 100% | name, schema, type, semantic |
 | qwen3.5:4b | 100% | 100% | name, schema, type, semantic |
 
 ## 结论
 
 - Guard 的核心收益是阻止错误 tool call 进入真实执行层；在本轮测试里，所有注入错误都被 100% 拦截。
 - `qwen3:0.6b` 的自然输出存在 20% 原本会错误执行的 registered tool call，开启 Guard 后 bad execution 从 20% 降到 0%。
-- `qwen3.5:2b`、`granite4.1:3b`、`qwen3.5:4b` 对注入错误的一轮 repair 成功率为 100%。这个结论只适用于本 benchmark 的注入错误矩阵。
+- `qwen3.5:2b`、`qwen3.5:4b`、`qwen3.5:4b` 对注入错误的一轮 repair 成功率为 100%。这个结论只适用于本 benchmark 的注入错误矩阵。
 - `qwen3.5:0.8b` 及以上在本轮自然用例里 baseline 已经是 100%，所以自然场景没有可观察的 accepted-rate uplift。

package/docs/architecture/system-architecture.zh.md

@@ -366,7 +366,7 @@ flowchart LR
   end
 
   subgraph Service["Standalone service"]
-    CLI["stable-harness start -w workspace --port 8642"] --> Server["HTTP / OpenAI-compatible server"]
+    CLI["stable-harness start -w workspace"] --> Server["HTTP / protocol servers"]
     Server --> RuntimeB["Runtime instance"]
   end
 
@@ -383,8 +383,8 @@ flowchart LR
 推荐启动路径：
 
 - 嵌入式应用：`createStableHarnessRuntime(workspaceRoot)`，由 workspace YAML 决定 adapter、protocol 和 policy 默认值。
-- 本地或服务化入口：`stable-harness start -w "$PWD" --port 8642 --api-key ...`。
-- OpenAI-compatible 客户端：连接 `http://host:port/v1`，把 `model` 映射为 workspace agent id。
+- 本地或服务化入口：`stable-harness start -w "$PWD"` 或 `stable-harness serve -w "$PWD"`。
+- OpenAI-compatible 客户端：默认连接 `http://127.0.0.1:56789/protocols/openai/v1`，把 `model` 映射为 workspace agent id。
 
 ## 扩展点