stable-harness 0.0.2 → 0.0.4

package/packages/core/dist/runtime/tool-gateway.d.ts

@@ -0,0 +1,40 @@
+export type RuntimeToolCallRequest = {
+    toolId: string;
+    args?: unknown;
+};
+export type RuntimeToolGatewayContext = {
+    workspaceRoot: string;
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+};
+export type RuntimeToolGatewayTool = {
+    id: string;
+    description?: string;
+    schema?: unknown;
+};
+export type RuntimeToolRepairModel = {
+    invoke(input: unknown): Promise<unknown> | unknown;
+};
+export type RuntimeToolGateway = {
+    get(toolId: string): RuntimeToolGatewayTool | undefined;
+    repairToolCall?(request: {
+        toolId: string;
+        args?: unknown;
+        allowedToolIds?: string[];
+        repairModel?: RuntimeToolRepairModel;
+        context: RuntimeToolGatewayContext;
+    }): Promise<{
+        toolId: string;
+        args: unknown;
+    } | undefined>;
+    invoke(request: {
+        toolId: string;
+        args?: unknown;
+        repairModel?: RuntimeToolRepairModel;
+        context: RuntimeToolGatewayContext;
+    }): Promise<{
+        toolId: string;
+        output: unknown;
+    }>;
+};

package/packages/core/dist/runtime/tool-gateway.js

@@ -0,0 +1 @@
+export{};

package/packages/core/dist/runtime/types.d.ts

@@ -0,0 +1,168 @@
+import type { MemoryCandidate } from "@stable-harness/memory";
+import type { RuntimeWorkflowRequest } from "../workflows/index.js";
+import type { RuntimeEvent } from "./events.js";
+import type { RuntimeToolCallRequest } from "./tool-gateway.js";
+export type RuntimeRecordState = "queued" | "running" | "completed" | "failed" | "cancelled";
+export type RuntimeOutput = {
+    text: string;
+    metadata?: Record<string, unknown>;
+    artifacts?: RuntimeArtifact[];
+};
+export type RuntimeArtifact = {
+    id: string;
+    kind: string;
+    uri?: string;
+    metadata?: Record<string, unknown>;
+};
+export type RuntimeArtifactRecord = RuntimeArtifact & {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    createdAt: string;
+    contentType?: string;
+    size?: number;
+};
+export type RuntimeArtifactInput = RuntimeArtifact & {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    content?: unknown;
+    contentType?: string;
+    createdAt?: string;
+};
+export type RuntimeArtifactStore = {
+    createArtifact(input: RuntimeArtifactInput): RuntimeArtifactRecord;
+    listArtifacts(filter?: RuntimeArtifactFilter): RuntimeArtifactRecord[];
+    readArtifact(id: string): unknown;
+};
+export type RuntimeArtifactFilter = {
+    requestId?: string;
+    sessionId?: string;
+    agentId?: string;
+};
+export type RuntimeRequest = {
+    input: string;
+    agentId?: string;
+    sessionId?: string;
+    requestId?: string;
+    parentRunId?: string;
+    toolCall?: RuntimeToolCallRequest;
+    workflow?: RuntimeWorkflowRequest;
+    memory?: RuntimeRequestMemory;
+    metadata?: Record<string, unknown>;
+};
+export type RuntimeRequestMemory = {
+    namespace?: string;
+    recall?: false | {
+        query?: string;
+        limit?: number;
+    };
+    candidates?: RuntimeMemoryCandidateInput[];
+};
+export type RuntimeMemoryCandidateInput = Omit<MemoryCandidate, "namespace"> & {
+    namespace?: string;
+};
+export type RuntimeResponse = {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    state: RuntimeRecordState;
+    output: string;
+    metadata?: Record<string, unknown>;
+    artifacts?: RuntimeArtifact[];
+};
+export type RuntimeRunRecord = {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    input: string;
+    state: RuntimeRecordState;
+    output?: string;
+    error?: string;
+    parentRunId?: string;
+    metadata?: Record<string, unknown>;
+    artifacts: RuntimeArtifact[];
+    startedAt: string;
+    completedAt?: string;
+    events: RuntimeEvent[];
+};
+export type RuntimeStoreRunPatch = Partial<Pick<RuntimeRunRecord, "state" | "output" | "error" | "metadata" | "artifacts" | "completedAt">>;
+export type RuntimeRunFilter = {
+    agentId?: string;
+    sessionId?: string;
+    state?: RuntimeRecordState;
+};
+export type RuntimeStore = {
+    createRun(record: RuntimeRunRecord): void;
+    updateRun(requestId: string, patch: RuntimeStoreRunPatch): RuntimeRunRecord | undefined;
+    appendEvent(event: RuntimeEvent): RuntimeRunRecord | undefined;
+    getRun(requestId: string): RuntimeRunRecord | undefined;
+    listRuns(filter?: RuntimeRunFilter): RuntimeRunRecord[];
+};
+export type RuntimeQueueRecord = {
+    requestId: string;
+    sessionId: string;
+    priority: number;
+    queueKey?: string;
+    enqueuedAt: string;
+    availableAt: string;
+    claimedBy?: string;
+    claimedAt?: string;
+    leaseExpiresAt?: string;
+    attemptCount: number;
+    lastError?: string;
+};
+export type RuntimeRequestControlRecord = {
+    requestId: string;
+    cancelRequested: boolean;
+    cancelReason?: string;
+    cancelRequestedAt?: string;
+    heartbeatAt?: string;
+    workerId?: string;
+    workerStartedAt?: string;
+};
+export type RuntimeRecoveryIntent = {
+    requestId: string;
+    sessionId: string;
+    kind: "approval-decision" | "restart-request";
+    savedAt: string;
+    checkpointRef?: string;
+    resumePayload?: unknown;
+    attempts: number;
+};
+export type RuntimeQueueStore = {
+    enqueue(record: Omit<RuntimeQueueRecord, "attemptCount" | "enqueuedAt"> & {
+        attemptCount?: number;
+        enqueuedAt?: string;
+    }): RuntimeQueueRecord;
+    listQueue(): RuntimeQueueRecord[];
+    getQueuedRequest(requestId: string): RuntimeQueueRecord | undefined;
+    claimNext(input: RuntimeQueueClaimInput): RuntimeQueueRecord | undefined;
+    heartbeat(input: RuntimeHeartbeatInput): RuntimeRequestControlRecord | undefined;
+    requestCancel(input: RuntimeCancelIntentInput): RuntimeRequestControlRecord;
+    getControl(requestId: string): RuntimeRequestControlRecord | undefined;
+    listStuck(input: RuntimeStuckRequestInput): RuntimeQueueRecord[];
+    saveRecoveryIntent(intent: RuntimeRecoveryIntent): RuntimeRecoveryIntent;
+    getRecoveryIntent(requestId: string): RuntimeRecoveryIntent | undefined;
+    clearRecoveryIntent(requestId: string): boolean;
+};
+export type RuntimeQueueClaimInput = {
+    workerId: string;
+    now?: string;
+    leaseMs: number;
+    queueKey?: string;
+};
+export type RuntimeHeartbeatInput = {
+    requestId: string;
+    workerId: string;
+    now?: string;
+};
+export type RuntimeCancelIntentInput = {
+    requestId: string;
+    reason?: string;
+    now?: string;
+};
+export type RuntimeStuckRequestInput = {
+    now?: string;
+    staleAfterMs: number;
+};

package/packages/core/dist/runtime/types.js

@@ -0,0 +1 @@
+export{};

package/packages/core/dist/runtime.d.ts

@@ -1,12 +1,16 @@
 import type { ApprovalQueue } from "@stable-harness/governance";
 import type { MemoryProvider, RuntimeMemoryStore } from "@stable-harness/memory";
-import type { CompiledWorkspace, RuntimeToolGateway, RuntimeAdapter, RuntimeStore, StableHarnessRuntime } from "./types.js";
-export declare function createStableHarnessRuntime(input: {
+import type { CompiledWorkspace, RuntimeToolGateway, RuntimeAdapter, RuntimeStore, RuntimeProgressNarrationOptions, RuntimeWorkflowAdapter, StableHarnessRuntime } from "./types.js";
+type RuntimeFactoryInput = {
     workspace: CompiledWorkspace;
     adapters: RuntimeAdapter[];
+    workflowAdapters?: RuntimeWorkflowAdapter[];
     memory?: RuntimeMemoryStore;
     memoryProviders?: MemoryProvider[];
     approvals?: ApprovalQueue;
     toolGateway?: RuntimeToolGateway;
     store?: RuntimeStore;
-}): StableHarnessRuntime;
+    progressNarration?: RuntimeProgressNarrationOptions | false;
+};
+export declare function createStableHarnessRuntime(input: RuntimeFactoryInput): StableHarnessRuntime;
+export {};

package/packages/core/dist/runtime.js

@@ -1 +1 @@
-import{randomUUID as e}from"node:crypto";import{assertExecutionContract as t}from"./execution-contract.js";import{projectRequestInspection as s,projectRequestSummary as r,projectSessionSummaries as o}from"./inspection.js";import{recallMemoryPlugins as n,runMemoryPlugins as a}from"./memory-plugins.js";import{createInMemoryRuntimeStore as d}from"./stores.js";export function createStableHarnessRuntime(I){const m=new Set,l=I.store??d(),p=e=>{l.appendEvent(e);for(const t of m)t(e)};return{async request(s){const{agent:r,adapter:o}=function(e,t){const s=t.agentId??e.workspace.runtime.defaultAgentId,r=e.workspace.agents.get(s);if(!r)throw new Error(`Agent ${s} is not defined in the workspace`);if(t.toolCall)return{agent:r,adapter:void 0};const o=e.adapters.find(e=>e.canRun(r));if(!o)throw new Error(`No runtime adapter can run backend ${r.backend} for agent ${r.id}`);return{agent:r,adapter:o}}(I,s),d=s.requestId??e(),m=s.sessionId??e();l.createRun(function(e,t,s,r){return{requestId:t,sessionId:s,agentId:r.id,input:e.input,state:"running",parentRunId:e.parentRunId,metadata:e.metadata,artifacts:[],startedAt:(new Date).toISOString(),events:[]}}(s,d,m,r)),p({type:"request.started",requestId:d,sessionId:m,agentId:r.id});try{if(s.toolCall){const e=await async function(e){const t=e.request.toolCall;if(!t)throw new Error("Direct tool call request is missing");if(!e.gateway)throw new Error("Runtime tool gateway is not configured");const s=await async function(e){if(e.agent.tools.includes(e.toolId)&&e.gateway.get(e.toolId))return{toolId:e.toolId,args:e.args};const t=await(e.gateway.repairToolCall?.({toolId:e.toolId,args:e.args,allowedToolIds:e.agent.tools,context:{workspaceRoot:e.workspace.root,requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id}}));if(t&&e.agent.tools.includes(t.toolId)&&e.gateway.get(t.toolId))return t;if(!e.agent.tools.includes(e.toolId))throw new Error(`Tool ${e.toolId} is not assigned to agent ${e.agent.id}`);throw new Error(`Tool is not registered: ${e.toolId}`)}({gateway:e.gateway,workspace:e.workspace,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,toolId:t.toolId,args:t.args});e.emit({type:"tool.started",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,toolId:s.toolId});const r=await e.gateway.invoke({toolId:s.toolId,args:s.args,context:{workspaceRoot:e.workspace.root,requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id}});return e.emit({type:"tool.completed",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,toolId:r.toolId,output:r.output}),{text:(o=r.output,"string"==typeof o?o:JSON.stringify(o)),metadata:{toolCall:{toolId:r.toolId}}};var o}({gateway:I.toolGateway,workspace:I.workspace,emit:p,request:s,requestId:d,sessionId:m,agent:r});return c({store:l,emit:p,requestId:d,sessionId:m,agent:r,result:e})}return await async function(e){if(!e.adapter)throw new Error(`No runtime adapter can run backend ${e.agent.backend} for agent ${e.agent.id}`);const s=await async function(e){if(!e.memory)return;if(i(e.memory,e.emit,e.requestId,e.sessionId,e.agent.id,"read-before-plan"),!1===e.request.memory?.recall)return;const t=u(e.workspace,e.agent,e.request),s=e.request.memory?.recall?.query??e.request.input,r=await e.memory.recall({namespace:t,query:s,limit:e.request.memory?.recall?.limit});return e.emit({type:"memory.recall.completed",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,namespace:t,recordIds:r.records.map(e=>e.id),context:r.context}),{namespace:t,records:r.records,context:r.context}}({memory:e.input.memory,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace}),r=await n({providers:e.input.memoryProviders,request:e.request,agent:e.agent,workspace:e.input.workspace}),o=function(e){return"string"==typeof e?{text:e}:e}(await e.adapter.run({workspace:e.input.workspace,agent:e.agent,request:e.request,requestId:e.requestId,sessionId:e.sessionId,memory:s,pluginMemories:r,toolGateway:e.input.toolGateway,emit:e.emit}));i(e.input.memory,e.emit,e.requestId,e.sessionId,e.agent.id,"read-before-finalize"),await async function(e){if(!e.memory||!e.request.memory?.candidates?.length)return;i(e.memory,e.emit,e.requestId,e.sessionId,e.agent.id,"write-after-run");const t=u(e.workspace,e.agent,e.request);for(const s of e.request.memory.candidates){const r={...s,namespace:s.namespace??t},o=await e.memory.submitCandidate(r);if(e.emit({type:"memory.candidate.submitted",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,candidate:o.candidate,decision:o.decision,record:o.record}),"review"===o.decision.action&&e.approvals){const t=await e.approvals.create({kind:"memory_write",reason:o.decision.reason,requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,subject:{candidate:o.candidate,decision:o.decision}});e.emit({type:"memory.approval.requested",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,approval:t})}}}({memory:e.input.memory,approvals:e.input.approvals,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace}),t({store:e.store,emit:e.emit,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent});const d=c({store:e.store,emit:e.emit,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,result:o});return await a({providers:e.input.memoryProviders,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace,result:o}),d}({input:I,store:l,emit:p,adapter:o,request:s,requestId:d,sessionId:m,agent:r})}catch(e){return function(e){const t=e.error instanceof Error?e.error.message:String(e.error);return e.store.getRun(e.requestId)&&e.store.updateRun(e.requestId,{state:"failed",error:t,completedAt:(new Date).toISOString()}),e.emit({type:"request.failed",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,error:t}),{requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,state:"failed",output:t}}({store:l,emit:p,requestId:d,sessionId:m,agent:r,error:e})}},subscribe:e=>(m.add(e),()=>m.delete(e)),inspect:()=>({workspaceRoot:I.workspace.root,agents:[...I.workspace.agents.keys()].sort(),models:[...I.workspace.models.keys()].sort(),tools:[...I.workspace.tools.keys()].sort(),runs:l.listRuns()}),getRun:e=>l.getRun(e),listRequests:e=>l.listRuns(e).map(r),listSessions:()=>o(l.listRuns()),inspectRequest(e){const t=l.getRun(e);return t?s(I.workspace,t):void 0},cancel(e,t){const s=l.getRun(e);s&&"running"===s.state&&(l.updateRun(e,{state:"cancelled",completedAt:(new Date).toISOString()}),p({type:"request.cancelled",requestId:e,sessionId:s.sessionId,agentId:s.agentId,reason:t}))},async stop(){m.clear()}}}function i(e,t,s,r,o,n){e&&t({type:"memory.lifecycle",requestId:s,sessionId:r,agentId:o,hook:n})}function u(e,t,s){return s.memory?.namespace??`${e.root}:${t.id}`}function c(e){const t=e.store.getRun(e.requestId);if("cancelled"===t?.state)return I(e,"cancelled");t&&e.store.updateRun(e.requestId,{state:"completed",output:e.result.text,metadata:{...t.metadata,...e.result.metadata},artifacts:[...t.artifacts,...e.result.artifacts??[]],completedAt:(new Date).toISOString()});for(const t of e.result.artifacts??[])e.emit({type:"artifact.created",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,artifact:t});return e.emit({type:"request.completed",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,output:e.result.text}),I(e,"completed")}function I(e,t){return{requestId:e.requestId,sessionId:e.sessionId,agentId:e.agent.id,state:t,output:e.result.text,metadata:e.result.metadata,artifacts:e.result.artifacts}}
+import{randomUUID as e}from"node:crypto";import{assertExecutionContract as t}from"./execution-contract.js";import{projectRequestInspection as r,projectRequestSummary as s,projectSessionSummaries as o}from"./runtime/persistence/inspection.js";import{recallMemoryPlugins as a,runMemoryPlugins as n}from"./memory-plugins.js";import{assertNoRawToolCallOutput as i,assertNoToolExecutionErrorOutput as u,buildAdapterErrorRecoveryPrompt as c,buildEvidenceSynthesisOutput as l,buildExecutionContractRecoveryRequest as p,buildResultRecoveryRequest as d,containsRawToolCallOutput as m,isRecoverableAdapterError as w,rawToolCallFailureMessage as f,toolCallRecoveryEnabled as y}from"./recovery/tool-call.js";import{completeRun as g,failRun as q}from"./runtime/completion.js";import{runDirectToolCall as I}from"./runtime/direct-tool-call.js";import{emitMemoryLifecycle as k,runMemoryRecall as R,submitMemoryCandidates as v}from"./runtime/memory.js";import{createInMemoryRuntimeStore as A}from"./runtime/persistence/stores.js";import{createProgressNarrationEvent as b,resolveProgressNarrator as C}from"./runtime/progress-narration.js";import{runWorkflowRequest as h}from"./workflows/runtime.js";export function createStableHarnessRuntime(t){const i=new Set,u=t.store??A(),l=C({options:t.progressNarration,policy:t.workspace.runtime}),emit=e=>{u.appendEvent(e);for(const t of i)t(e);!function tryEmitProgressNarration(e){try{const t=b({source:e.event,narrator:e.narrator,options:e.options,policy:e.policy});!function isPromiseLike(e){return"object"==typeof e&&null!==e&&"then"in e&&"function"==typeof e.then}(t)?t&&e.emitNarration(t):t.then(t=>{t&&e.emitNarration(t)}).catch(()=>{})}catch{return}}({event:e,narrator:l,options:t.progressNarration,policy:t.workspace.runtime,emitNarration:e=>{u.appendEvent(e);for(const t of i)t(e)}})};return{request:async r=>async function runRuntimeRequest(t){const{agent:r,adapter:s}=function resolveExecution(e,t){const r=t.agentId??e.workspace.runtime.defaultAgentId,s=e.workspace.agents.get(r);if(!s)throw new Error(`Agent ${r} is not defined in the workspace`);if(t.toolCall||t.workflow)return{agent:s,adapter:void 0};const o=e.adapters.find(e=>e.canRun(s));if(!o)throw new Error(`No runtime adapter can run backend ${s.backend} for agent ${s.id}`);return{agent:s,adapter:o}}(t.input,t.request),o=t.request.requestId??e(),i=t.request.sessionId??e();t.store.createRun(function createRunRecord(e,t,r,s){return{requestId:t,sessionId:r,agentId:s.id,input:e.input,state:"running",parentRunId:e.parentRunId,metadata:e.metadata,artifacts:[],startedAt:(new Date).toISOString(),events:[]}}(t.request,o,i,r)),t.emit({type:"runtime.request.started",requestId:o,sessionId:i,agentId:r.id,input:t.request.input});try{if(t.request.workflow){const e=await h({workspace:t.input.workspace,adapters:t.input.workflowAdapters??[],toolGateway:t.input.toolGateway,request:{input:t.request.input,...t.request.workflow},requestId:o,sessionId:i,agentId:r.id,emit:t.emit});return g({store:t.store,emit:t.emit,requestId:o,sessionId:i,agent:r,result:e})}if(t.request.toolCall){const e=await I({gateway:t.input.toolGateway,workspace:t.input.workspace,emit:t.emit,request:t.request,requestId:o,sessionId:i,agent:r});return g({store:t.store,emit:t.emit,requestId:o,sessionId:i,agent:r,result:e})}return await async function runAdapterRequest(e){if(!e.adapter)throw new Error(`No runtime adapter can run backend ${e.agent.backend} for agent ${e.agent.id}`);const t=e.adapter,r=await R({memory:e.input.memory,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace}),s=await a({providers:e.input.memoryProviders,request:e.request,agent:e.agent,workspace:e.input.workspace}),o=e.input.workspace.runtime,i=new Map;let u;try{u=await runAdapterOnce(e,t,e.request,r,s,i)}catch(a){if(!w(a,o))throw a;u=await runAdapterOnce(e,t,c(e.request,a,o),r,s,i)}u=await recoverAdapterResultOutput(e,t,e.request,u,r,s,o,i),k(e.input.memory,e.emit,e.requestId,e.sessionId,e.agent.id,"read-before-finalize"),await v({memory:e.input.memory,approvals:e.input.approvals,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace});try{assertRequestExecutionContract(e)}catch(a){const n=p({request:e.request,events:e.store.getRun(e.requestId)?.events??[],policy:o});if(!n)throw a;u=await runAdapterOnce(e,t,n,r,s,i),u=await recoverAdapterResultOutput(e,t,n,u,r,s,o,i),assertRequestExecutionContract(e)}const l=g({store:e.store,emit:e.emit,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,result:u});return await n({providers:e.input.memoryProviders,emit:e.emit,request:e.request,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,workspace:e.input.workspace,result:u}),l}({...t,adapter:s,requestId:o,sessionId:i,agent:r})}catch(e){return q({store:t.store,emit:t.emit,requestId:o,sessionId:i,agent:r,error:e})}}({input:t,store:u,emit:emit,request:r}),subscribe:e=>(i.add(e),()=>i.delete(e)),inspect(){return{workspaceRoot:t.workspace.root,agents:[...t.workspace.agents.keys()].sort(),workflows:[...t.workspace.workflows.keys()].sort(),...t.workspace.runtime.specDrivenWorkflow?{specDrivenWorkflow:(e=t.workspace.runtime.specDrivenWorkflow,{enabled:e.enabled,artifactsDir:e.artifactsDir,...e.constitution?{constitution:e.constitution}:{},phases:e.phases.map(e=>e.id)})}:{},evaluations:[...t.workspace.evaluations?.keys()??[]].sort(),...t.workspace.runtime.workflowRouting?.defaultWorkflowId?{defaultWorkflowId:t.workspace.runtime.workflowRouting.defaultWorkflowId}:{},workflowRoutes:(t.workspace.runtime.workflowRouting?.routes??[]).map(e=>e.id).sort(),models:[...t.workspace.models.keys()].sort(),tools:[...t.workspace.tools.keys()].sort(),runs:u.listRuns()};var e},getRuntimePolicy:()=>t.workspace.runtime,getWorkflow:e=>t.workspace.workflows.get(e),getRun:e=>u.getRun(e),listRequests:e=>u.listRuns(e).map(s),listSessions:()=>o(u.listRuns()),inspectRequest(e){const s=u.getRun(e);return s?r(t.workspace,s):void 0},cancel(e,t){const r=u.getRun(e);r&&"running"===r.state&&(u.updateRun(e,{state:"cancelled",completedAt:(new Date).toISOString()}),emit({type:"runtime.request.cancelled",requestId:e,sessionId:r.sessionId,agentId:r.agentId,reason:t}))},async stop(){i.clear()}}}async function recoverAdapterResultOutput(e,t,r,s,o,a,n,c){let p=r;const w=function resultRecoveryAttempts(e){const t="object"!=typeof e||null===e||Array.isArray(e)?void 0:e.recovery,r="object"!=typeof t||null===t||Array.isArray(t)?void 0:t.toolCall,s="object"!=typeof r||null===r||Array.isArray(r)?void 0:r.maxResultRecoveryAttempts;return"number"==typeof s&&Number.isInteger(s)&&s>0?s:3}(n);let g=0;for(let r=0;r<w;r+=1){const r=e.store.getRun(e.requestId)?.events??[],i=d({request:p,output:s.text,events:r.slice(g),availableToolIds:e.agent.tools,policy:n});if(!i)break;p=i,g=e.store.getRun(e.requestId)?.events.length??0,s=await runAdapterOnce(e,t,i,o,a,c)}if(y(n)){let t=!1;m(s.text,n)&&function rawToolCallFailureReturnsMessage(e){return"message"===("object"!=typeof e?.toolCallRecovery||null===e.toolCallRecovery||Array.isArray(e.toolCallRecovery)?{}:e.toolCallRecovery).onFailure}(r.metadata)&&(s={...s,text:f(),metadata:{...s.metadata,toolCallRecovery:{failed:!0,reason:"raw_tool_call_output"}}});const o=l({request:r,output:s.text,events:e.store.getRun(e.requestId)?.events??[],policy:n});o&&(t=!0,s={...s,text:o,metadata:{...s.metadata,toolCallRecovery:{synthesized:!0,reason:"raw_tool_call_output_with_evidence"}}}),t||(i(s.text,n),u(s.text,n))}return s}function assertRequestExecutionContract(e){t({store:e.store,emit:e.emit,requestId:e.requestId,sessionId:e.sessionId,agent:e.agent,metadata:e.request.metadata})}async function runAdapterOnce(e,t,r,s,o,a){return function normalizeAdapterResult(e){return"string"==typeof e?{text:e}:e}(await t.run({workspace:e.input.workspace,agent:e.agent,request:r,requestId:e.requestId,sessionId:e.sessionId,memory:s,pluginMemories:o,toolGateway:e.input.toolGateway,requestState:a,emit:e.emit}))}

package/packages/core/dist/spec-driven/config.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceSpecDrivenPhase, WorkspaceSpecDrivenWorkflowPolicy } from "./types.js";
+export declare const DEFAULT_SPEC_DRIVEN_PHASES: WorkspaceSpecDrivenPhase[];
+export declare function createSpecDrivenWorkflowPolicy(input?: Partial<WorkspaceSpecDrivenWorkflowPolicy>): WorkspaceSpecDrivenWorkflowPolicy;
+export declare function assertSpecDrivenWorkflowPolicy(policy: WorkspaceSpecDrivenWorkflowPolicy): void;

package/packages/core/dist/spec-driven/config.js

@@ -0,0 +1 @@
+export const DEFAULT_SPEC_DRIVEN_PHASES=[{id:"constitution",artifactKind:"constitution",required:!0},{id:"specify",artifactKind:"spec",required:!0},{id:"plan",artifactKind:"plan",required:!0},{id:"contracts",artifactKind:"contract"},{id:"research",artifactKind:"research"},{id:"tasks",artifactKind:"tasks",required:!0},{id:"implement",artifactKind:"execution"},{id:"verify",artifactKind:"evidence",required:!0}];export function createSpecDrivenWorkflowPolicy(i){return{enabled:i?.enabled??!1,...i?.constitution?{constitution:i.constitution}:{},artifactsDir:i?.artifactsDir??"specs",phases:(t=i?.phases,(t&&t.length>0?t:DEFAULT_SPEC_DRIVEN_PHASES).map(i=>({id:i.id,...i.artifactKind?{artifactKind:i.artifactKind}:{},...void 0!==i.required?{required:i.required}:{},...i.gate?{gate:i.gate}:{},...i.config?{config:i.config}:{}}))),...i?.gates?{gates:i.gates}:{},...i?.config?{config:i.config}:{}};var t}export function assertSpecDrivenWorkflowPolicy(i){const t=new Set;for(const e of i.phases){if(!e.id.trim())throw new Error("specDrivenWorkflow phases require non-empty id");if(t.has(e.id))throw new Error(`specDrivenWorkflow phase is duplicated: ${e.id}`);t.add(e.id)}}

package/packages/core/dist/spec-driven/events.d.ts

@@ -0,0 +1,11 @@
+import type { RuntimeEvent } from "../runtime/events.js";
+import type { RuntimeArtifact } from "../runtime/types.js";
+import type { SpecDrivenPhaseTransition } from "./types.js";
+export type SpecDrivenEventContext = {
+    requestId: string;
+    sessionId: string;
+    agentId: string;
+    workflowId?: string;
+};
+export declare function createSpecDrivenPhaseEvent(context: SpecDrivenEventContext, transition: SpecDrivenPhaseTransition): RuntimeEvent;
+export declare function createSpecDrivenArtifactEvent(context: SpecDrivenEventContext, phaseId: string, artifact: RuntimeArtifact): RuntimeEvent;

package/packages/core/dist/spec-driven/events.js

@@ -0,0 +1 @@
+export function createSpecDrivenPhaseEvent(e,t){const r={requestId:e.requestId,sessionId:e.sessionId,agentId:e.agentId,phaseId:t.phaseId,...e.workflowId?{workflowId:e.workflowId}:{}};return"started"===t.status?{type:"runtime.specDriven.phase.started",...r}:"completed"===t.status?{type:"runtime.specDriven.phase.completed",...r,artifact:t.artifact}:"verified"===t.status?{type:"runtime.specDriven.phase.verified",...r,artifact:t.artifact}:{type:"runtime.specDriven.phase.blocked",...r,reason:t.reason??"unspecified"}}export function createSpecDrivenArtifactEvent(e,t,r){return{type:"runtime.artifact.created",requestId:e.requestId,sessionId:e.sessionId,agentId:e.agentId,artifact:{...r,metadata:{...r.metadata,phaseId:t,workflowKind:"spec-driven"}}}}

package/packages/core/dist/spec-driven/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./config.js";
+export * from "./events.js";
+export * from "./lifecycle.js";
+export * from "./types.js";

package/packages/core/dist/spec-driven/index.js

@@ -0,0 +1 @@
+export*from"./config.js";export*from"./events.js";export*from"./lifecycle.js";export*from"./types.js";

package/packages/core/dist/spec-driven/lifecycle.d.ts

@@ -0,0 +1,11 @@
+import type { RuntimeArtifact } from "../runtime/types.js";
+import type { SpecDrivenPhaseTransition, SpecDrivenWorkflowState, WorkspaceSpecDrivenWorkflowPolicy } from "./types.js";
+export declare function createSpecDrivenWorkflowState(policy: WorkspaceSpecDrivenWorkflowPolicy): SpecDrivenWorkflowState;
+export declare function applySpecDrivenPhaseTransition(state: SpecDrivenWorkflowState, transition: SpecDrivenPhaseTransition): SpecDrivenWorkflowState;
+export declare function createSpecDrivenArtifact(input: {
+    id: string;
+    phaseId: string;
+    artifactKind: string;
+    uri?: string;
+    metadata?: Record<string, unknown>;
+}): RuntimeArtifact;

package/packages/core/dist/spec-driven/lifecycle.js

@@ -0,0 +1 @@
+export function createSpecDrivenWorkflowState(t){return{enabled:t.enabled,artifactsDir:t.artifactsDir,...t.constitution?{constitution:t.constitution}:{},phases:t.phases.map(t=>({id:t.id,status:"pending",updatedAt:new Date(0).toISOString()}))}}export function applySpecDrivenPhaseTransition(t,a){if(!new Set(t.phases.map(t=>t.id)).has(a.phaseId))throw new Error(`Spec-driven workflow phase is not configured: ${a.phaseId}`);return{...t,phases:t.phases.map(t=>function updatePhase(t,a){return t.id!==a.phaseId?t:{id:t.id,status:a.status,...a.artifact?{artifact:a.artifact}:t.artifact?{artifact:t.artifact}:{},...a.reason?{reason:a.reason}:{},updatedAt:a.timestamp??(new Date).toISOString()}}(t,a))}}export function createSpecDrivenArtifact(t){return{id:t.id,kind:`spec-driven.${t.artifactKind}`,...t.uri?{uri:t.uri}:{},metadata:{phaseId:t.phaseId,...t.metadata}}}

package/packages/core/dist/spec-driven/types.d.ts

@@ -0,0 +1,38 @@
+import type { RuntimeArtifact } from "../runtime/types.js";
+export type SpecDrivenPhaseId = string;
+export type SpecDrivenPhaseStatus = "pending" | "started" | "blocked" | "completed" | "verified";
+export type WorkspaceSpecDrivenPhase = {
+    id: string;
+    artifactKind?: string;
+    required?: boolean;
+    gate?: string;
+    config?: Record<string, unknown>;
+};
+export type WorkspaceSpecDrivenWorkflowPolicy = {
+    enabled: boolean;
+    constitution?: string;
+    artifactsDir: string;
+    phases: WorkspaceSpecDrivenPhase[];
+    gates?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+};
+export type SpecDrivenPhaseRecord = {
+    id: string;
+    status: SpecDrivenPhaseStatus;
+    artifact?: RuntimeArtifact;
+    reason?: string;
+    updatedAt: string;
+};
+export type SpecDrivenWorkflowState = {
+    enabled: boolean;
+    artifactsDir: string;
+    constitution?: string;
+    phases: SpecDrivenPhaseRecord[];
+};
+export type SpecDrivenPhaseTransition = {
+    phaseId: string;
+    status: Exclude<SpecDrivenPhaseStatus, "pending">;
+    artifact?: RuntimeArtifact;
+    reason?: string;
+    timestamp?: string;
+};

package/packages/core/dist/spec-driven/types.js

@@ -0,0 +1 @@
+export{};

package/packages/core/dist/trace.d.ts

@@ -4,7 +4,7 @@ export type PlanTodoItem = {
     status: string;
 };
 export type RuntimeTraceEntry = {
-    type: "request" | "tool" | "adapter" | "memory" | "artifact" | "plan" | "delegation";
+    type: "request" | "tool" | "workflow" | "spec" | "adapter" | "memory" | "artifact" | "progress" | "plan" | "delegation";
     label: string;
     agentId: string;
     requestId: string;

package/packages/core/dist/trace.js

@@ -1 +1 @@
-export function projectRuntimeTrace(t){return t.events.map(projectEvent).filter(r)}export function projectEvent(t){return"request.started"===t.type||"request.completed"===t.type||"request.failed"===t.type?o(t,"request",t.type):"request.cancelled"===t.type?o(t,"request",t.type,{reason:t.reason}):"execution.contract.failed"===t.type?o(t,"request",t.type,{reason:t.reason,missingEvidenceTools:t.missingEvidenceTools}):"tool.started"===t.type?o(t,"tool","tool.started",{toolId:t.toolId}):"tool.completed"===t.type?"write_todos"===t.toolId?o(t,"plan","plan.updated",{toolId:t.toolId,todos:readPlanTodos(t.output)}):o(t,"tool","tool.completed",{toolId:t.toolId}):"adapter.event"===t.type?function(t){const e=t.event;if(n(e)&&"string"==typeof e.phase){if("tool.result"===e.phase&&"write_todos"===e.toolId)return o(t,"plan","plan.updated",e);const r=function(t,e){if("task"!==e.toolId)return;const r=function(t){const e=n(t.args)?t.args:void 0,o=n(t.output)?t.output:void 0;return a(e?.subagent_type)??a(e?.subagentType)??a(o?.subagent_type)??a(o?.subagentType)}(e);return"tool.start"===e.phase?o(t,"delegation","delegation.start",{...e,subagentType:r}):"tool.result"===e.phase?o(t,"delegation","delegation.completed",{...e,subagentType:r}):void 0}(t,e);return r||o(t,"adapter",`adapter.${e.phase}`,e)}return o(t,"adapter","adapter.event",{event:e})}(t):"artifact.created"===t.type?o(t,"artifact","artifact.created",{artifact:t.artifact}):t.type.startsWith("memory.")?o(t,"memory",t.type):void 0}export function readPlanTodos(o){const r=function(t){if(n(t))return t;if("string"==typeof t)try{const e=JSON.parse(t);return n(e)?e:void 0}catch{return}}(o),a=function(t){const e=n(t?.args)?t.args:void 0;return Array.isArray(t?.todos)?t.todos:Array.isArray(e?.todos)?e.todos:[]}(r);return a.map(t).filter(e)}function t(t){if(n(t)&&"string"==typeof t.content)return{content:t.content,status:"string"==typeof t.status?t.status:"pending"}}function e(t){return void 0!==t}function o(t,e,o,r){return{type:e,label:o,agentId:t.agentId,requestId:t.requestId,detail:r}}function r(t){return void 0!==t}function n(t){return"object"==typeof t&&null!==t&&!Array.isArray(t)}function a(t){return"string"==typeof t&&t.trim()?t:void 0}
+export function projectRuntimeTrace(e){return e.events.map(projectEvent).filter(isTraceEntry)}export function projectEvent(e){return"runtime.request.started"===e.type||"runtime.request.completed"===e.type||"runtime.request.failed"===e.type?base(e,"request",e.type):"runtime.request.cancelled"===e.type?base(e,"request",e.type,{reason:e.reason}):"runtime.execution.contract.failed"===e.type?base(e,"request",e.type,{reason:e.reason,missingEvidenceTools:e.missingEvidenceTools}):"runtime.tool.direct.started"===e.type?base(e,"tool","runtime.tool.direct.started",{toolId:e.toolId}):"runtime.tool.direct.completed"===e.type?base(e,"tool","runtime.tool.direct.completed",{toolId:e.toolId}):"runtime.workflow.started"===e.type||"runtime.workflow.completed"===e.type?base(e,"workflow",e.type,{workflowId:e.workflowId,adapter:e.adapter}):function isSpecDrivenPhaseEvent(e){return e.type.startsWith("runtime.specDriven.phase.")}(e)?base(e,"spec",e.type,{phaseId:e.phaseId,..."workflowId"in e&&e.workflowId?{workflowId:e.workflowId}:{},..."reason"in e?{reason:e.reason}:{},..."artifact"in e&&e.artifact?{artifact:e.artifact}:{}}):"runtime.adapter.event"===e.type?function adapterTrace(e){const t=e.event;if(isRecord(t)&&"string"==typeof t.phase){const r=function semanticAdapterTrace(e,t){const r=function readTraceType(e){const t=readString(e);return"request"===t||"tool"===t||"workflow"===t||"spec"===t||"adapter"===t||"memory"===t||"artifact"===t||"progress"===t||"plan"===t||"delegation"===t?t:void 0}(t.traceType),o=readString(t.traceLabel);if(r&&o)return base(e,r,o,t)}(e,t);return r||base(e,"adapter",t.phase.startsWith("agent.")?t.phase:`adapter.${t.phase}`,t)}return base(e,"adapter","runtime.adapter.event",{event:t})}(e):"runtime.artifact.created"===e.type?base(e,"artifact","runtime.artifact.created",{artifact:e.artifact}):e.type.startsWith("runtime.memory.")?base(e,"memory",e.type):"runtime.progress.narration"===e.type?base(e,"progress",e.type,{message:e.message,provider:e.provider,sourceEventTypes:e.sourceEventTypes}):void 0}export function readPlanTodos(e){const t=function readPlanRecord(e){if(isRecord(e))return e;if("string"==typeof e)try{const t=JSON.parse(e);return isRecord(t)?t:void 0}catch{return}}(e),r=function readTodosArray(e){const t=isRecord(e?.args)?e.args:void 0;return Array.isArray(e?.todos)?e.todos:Array.isArray(t?.todos)?t.todos:[]}(t);return r.map(readTodo).filter(isPlanTodoItem)}function readTodo(e){if(isRecord(e)&&"string"==typeof e.content)return{content:e.content,status:"string"==typeof e.status?e.status:"pending"}}function isPlanTodoItem(e){return void 0!==e}function base(e,t,r,o){return{type:t,label:r,agentId:e.agentId,requestId:e.requestId,detail:o}}function isTraceEntry(e){return void 0!==e}function isRecord(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}function readString(e){return"string"==typeof e&&e.trim()?e:void 0}