@botbotgo/agent-harness 0.0.45 → 0.0.47

package/README.md

@@ -17,7 +17,7 @@ What it provides:
 - YAML-defined runtime assembly for hosts, models, routing, recovery, concurrency, MCP, and maintenance policy
 - backend-adapted execution with a generic runtime contract and current LangChain v1 / DeepAgents adapters
 - local `resources/tools/` and `resources/skills/` loading
-- persisted runs, threads, approvals, events, and resumable checkpoints
+- persisted runs, threads, approvals, events, queued tasks, and resumable checkpoints
 
 ## Quick Start
 
@@ -35,6 +35,8 @@ your-workspace/
     agent-context.md
     workspace.yaml
     models.yaml
+    embedding-models.yaml
+    vector-stores.yaml
     stores.yaml
     tools.yaml
     mcp.yaml
@@ -77,7 +79,7 @@ try {
 - Persisted threads, runs, approvals, and lifecycle events
 - Recovery policy and resumable checkpoints
 - Background checkpoint maintenance
-- Runtime-level concurrency control
+- Runtime-level concurrency control and queued-run persistence
 
 ## How To Use
 
@@ -150,6 +152,16 @@ const result = await run(runtime, {
 
 `subscribe(...)` is a read-only observer surface over stored lifecycle events.
 
+The event stream includes:
+
+- `run.created`
+- `run.queued`
+- `run.dequeued`
+- `run.state.changed`
+- `approval.requested`
+- `approval.resolved`
+- `output.delta`
+
 ### Inspect Threads And Approvals
 
 ```ts
@@ -225,29 +237,105 @@ Use Kubernetes-style YAML:
 
 Use distinct names for named objects such as models, stores, checkpointers, tools, and MCP servers.
 
-### `config/workspace.yaml`
+### Client-Configurable YAML Reference
+
+This section is the client-facing explanation of what can be configured in YAML today and what each field changes at runtime.
+
+There are three layers of client configuration:
+
+- runtime-level policy in `config/workspace.yaml`
+- reusable object catalogs in `config/*.yaml`
+- agent assembly in `config/agents/*.yaml`
 
-Use this file for runtime-level policy:
+### `config/workspace.yaml`
 
-- `runRoot`
-- `routing.rules`
-- `routing.defaultAgentId`
-- `routing.systemPrompt`
-- `routing.modelRouting`
-- `concurrency.maxConcurrentRuns`
-- `recovery.enabled`
-- `recovery.resumeOnStartup`
-- `recovery.maxRecoveryAttempts`
-- `maintenance.checkpoints.*`
+Use this file for runtime-level policy shared by the whole workspace.
+
+Primary fields:
+
+- `runRoot`: root directory where the runtime stores thread indexes, runs, approvals, artifacts, queued requests, and default local persistence
+- `routing.defaultAgentId`: default host selected when no explicit routing rule matches
+- `routing.rules`: ordered YAML routing rules evaluated before backend routing
+- `routing.systemPrompt`: optional model-classifier prompt used only when model routing is enabled
+- `routing.modelRouting`: opt in to model-driven host classification fallback
+- `concurrency.maxConcurrentRuns`: maximum number of active runs; extra runs enter the persistent queue
+- `recovery.enabled`: enables runtime-managed startup recovery
+- `recovery.resumeOnStartup`: compatibility alias for resuming interrupted approval-driven runs on startup
+- `recovery.resumeResumingRunsOnStartup`: explicit control for resuming interrupted approval-driven runs on startup
+- `recovery.maxRecoveryAttempts`: upper bound for startup recovery retries
+- `maintenance.checkpoints.enabled`: turns on background checkpoint cleanup
+- `maintenance.checkpoints.schedule.intervalSeconds`: maintenance loop interval
+- `maintenance.checkpoints.schedule.runOnStartup`: run checkpoint cleanup during startup
+- `maintenance.checkpoints.policies.maxAgeSeconds`: age-based checkpoint cleanup
+- `maintenance.checkpoints.policies.maxBytes`: size-based checkpoint cleanup
+- `maintenance.checkpoints.sqlite.sweepBatchSize`: batch size for SQLite cleanup scans
+- `maintenance.checkpoints.sqlite.vacuum`: vacuum SQLite after deletions
 
 If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
 
+Example:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+  concurrency:
+    maxConcurrentRuns: 3
+  routing:
+    defaultAgentId: orchestra
+    modelRouting: false
+    rules:
+      - agentId: orchestra
+        contains: ["latest", "recent", "today", "news"]
+      - agentId: orchestra
+        regex:
+          - "\\b(create|build|implement|fix|debug|review|inspect)\\b"
+  maintenance:
+    checkpoints:
+      enabled: true
+      schedule:
+        intervalSeconds: 3600
+        runOnStartup: true
+      policies:
+        maxAgeSeconds: 604800
+      sqlite:
+        sweepBatchSize: 200
+        vacuum: false
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3
+```
+
+Notes:
+
+- `routing.rules` only choose the starting host agent; they do not replace backend planning semantics
+- queued runs are persisted under `runRoot` and continue after process restart
+- `running` runs are only replayed on startup when the bound tools are retryable
+
 ### `config/agent-context.md`
 
 Use this file for shared startup context loaded into agents at construction time.
 
 Put stable project context here. Do not use it as mutable long-term memory.
 
+Good uses:
+
+- product positioning
+- codebase conventions
+- stable domain vocabulary
+- organization-specific rules
+
+Bad uses:
+
+- transient scratch notes
+- per-run execution state
+- approval packets
+- long-term memory that should live in the store
+
 ### `config/models.yaml`
 
 Use one file for multiple named models:
@@ -259,6 +347,7 @@ spec:
   - name: default
     provider: openai
     model: gpt-4.1
+    temperature: 0.2
   - name: planner
     provider: openai
     model: gpt-4.1-mini
@@ -266,6 +355,70 @@ spec:
 
 These load as `model/default` and `model/planner`.
 
+Client-configurable model fields:
+
+- `name`: catalog name referenced by `model/<name>`
+- `provider`: provider family such as `openai`, `openai-compatible`, `ollama`, `anthropic`, or `google`
+- `model`: provider model id
+- top-level provider init fields such as `temperature`, `baseUrl`, API-specific settings, and client options
+- `clientRef`: optional external client reference
+- `fallbacks`: optional fallback model refs
+- `metadata`: optional model metadata
+
+### `config/embedding-models.yaml`
+
+Use this file for named embedding model presets used by retrieval-oriented tools.
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: EmbeddingModels
+spec:
+  - name: default
+    provider: ollama
+    model: nomic-embed-text
+    baseUrl: http://localhost:11434
+```
+
+Client-configurable embedding fields:
+
+- `name`
+- `provider`
+- `model`
+- top-level provider init fields such as `baseUrl`
+- `clientRef`
+- `metadata`
+
+These load as `embedding-model/default`.
+
+### `config/vector-stores.yaml`
+
+Use this file for named vector store presets referenced by retrieval tools.
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: VectorStores
+spec:
+  - name: default
+    storeKind: LibSQLVectorStore
+    url: file:.agent/vector-store.db
+    table: rag_chunks
+    column: embedding
+    embeddingModelRef: embedding-model/default
+```
+
+Client-configurable vector store fields:
+
+- `name`
+- `storeKind`
+- `url`
+- `authToken`
+- `table`
+- `column`
+- `embeddingModelRef`
+- `metadata`
+
+These load as `vector-store/default`.
+
 ### `config/stores.yaml`
 
 Use one file for named persistence presets:
@@ -285,6 +438,73 @@ spec:
 
 These load as `store/default` and `checkpointer/default`.
 
+Client-configurable store fields:
+
+- `kind: Store` for backend stores
+- `kind: Checkpointer` for resumable execution state
+- `name` for refs
+- `storeKind` such as `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`
+- `checkpointerKind` such as `MemorySaver`, `FileCheckpointer`, `SqliteSaver`
+- storage-specific fields such as `path`, connection strings, auth, and provider options
+
+### `config/tools.yaml`
+
+Use this file for reusable tool presets and tool bundles.
+
+Minimal collection form:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Tools
+spec:
+  - kind: Tool
+    name: fetch_docs
+    type: function
+    description: Fetch a documentation page.
+```
+
+Client-configurable tool fields:
+
+- `name`
+- `type`: `function`, `backend`, `mcp`, or `bundle`
+- `description`
+- `implementationName` for local JS tool modules
+- `inputSchema.ref`
+- `backend.operation`
+- `mcp.ref` or `mcp.tool`
+- `refs` for bundle composition
+- `hitl.enabled` and `hitl.allow` for approval-gated tools
+- `retryable: true` for tools that are safe to replay during startup recovery
+- `config` for tool-specific options
+
+Use `retryable` carefully. Mark a tool retryable only when repeated execution is safe or intentionally idempotent.
+
+### `config/mcp.yaml`
+
+Use this file for reusable MCP server definitions and MCP-backed tool presets.
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: McpServers
+spec:
+  - name: docs
+    transport: http
+    url: https://example.com/mcp
+  - name: local-browser
+    transport: stdio
+    command: node
+    args: ["./mcp-browser-server.mjs"]
+```
+
+Client-configurable MCP fields:
+
+- `name`
+- `transport`: `stdio`, `http`, `sse`, or `websocket`
+- `command`, `args`, `env`, `cwd` for stdio servers
+- `url`, `token`, `headers` for network servers
+
+These load as `mcp/<name>`.
+
 ### `config/agents/*.yaml`
 
 Prefer the generic agent form and declare the current execution backend explicitly:
@@ -303,20 +523,75 @@ spec:
 
 `kind: DeepAgent` and `kind: LangChainAgent` remain supported as compatibility forms, but `kind: Agent` is the recommended product-facing entry point.
 
-Common fields include:
-
-- `modelRef`
-- `execution.backend`
-- `systemPrompt`
-- `tools`
-- `skills`
-- `memory`
-- `checkpointer`
-- `store`
-- `backend`
-- `middleware`
-- `subagents`
-- `mcpServers`
+Common client-configurable agent fields:
+
+- `metadata.name`
+- `metadata.description`
+- `spec.execution.backend`
+- `spec.modelRef`
+- `spec.systemPrompt`
+- `spec.tools`
+- `spec.skills`
+- `spec.memory`
+- `spec.checkpointer`
+- `spec.store`
+- `spec.backend`
+- `spec.middleware`
+- `spec.subagents`
+- `spec.mcpServers`
+- `spec.responseFormat`
+- `spec.contextSchema`
+
+Typical patterns:
+
+- use `direct` as a lightweight host for simple one-turn requests
+- use `orchestra` as the main execution host for tools, multi-step work, and delegation
+- keep routing policy in `config/workspace.yaml`, not buried in prompts
+
+Example direct agent:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: direct
+spec:
+  execution:
+    backend: langchain-v1
+  modelRef: model/default
+  checkpointer:
+    ref: checkpointer/default
+  systemPrompt: |-
+    You are the direct agent.
+    Answer simple requests directly.
+```
+
+Example orchestra agent:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
+spec:
+  execution:
+    backend: deepagent
+  modelRef: model/default
+  memory:
+    - path: config/agent-context.md
+  store:
+    ref: store/default
+  checkpointer:
+    ref: checkpointer/default
+  backend:
+    kind: CompositeBackend
+    state:
+      kind: VfsSandbox
+      timeout: 600
+    routes:
+      /memories/:
+        kind: StoreBackend
+```
 
 ### `resources/`
 
@@ -329,6 +604,24 @@ Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`
 
 The preferred tool module format is exporting `tool({...})`.
 
+Example:
+
+```js
+import { z } from "zod";
+import { tool } from "@botbotgo/agent-harness/tools";
+
+export const local_lookup = tool({
+  description: "Lookup a ticker from a local tool module.",
+  retryable: true,
+  schema: {
+    ticker: z.string().min(1),
+  },
+  async invoke(input) {
+    return input.ticker.toUpperCase();
+  },
+});
+```
+
 Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under repository `test/`.
 
 ## Design Notes
@@ -337,11 +630,12 @@ Keep runtime extension source under `resources/`. Keep tests outside the publish
 - agent-level execution behavior stays upstream
 - application-level orchestration and lifecycle management stays in the harness
 - checkpoint resume is treated as a system-managed runtime behavior, not a primary public abstraction
+- public runtime contract generic does not mean backend-agnostic implementation internals; it means client-facing semantics stay stable even when adapters change
 
 ## API Summary
 
 - `createAgentHarness(...)`
-- `run(...)`
+- `run(runtime, {...})`
 - `subscribe(...)`
 - `listThreads(...)`
 - `getThread(...)`

package/dist/api.d.ts

@@ -13,6 +13,7 @@ export declare function run(runtime: AgentHarnessRuntime, options: RunOptions):
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listThreads(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<ThreadSummary[]>;
 export declare function getThread(runtime: AgentHarnessRuntime, threadId: string): Promise<ThreadRecord | null>;
+export declare function deleteThread(runtime: AgentHarnessRuntime, threadId: string): Promise<boolean>;
 export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listApprovals"]>[0]): Promise<ApprovalRecord[]>;
 export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<ApprovalRecord | null>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;

package/dist/api.js

@@ -21,6 +21,9 @@ export async function listThreads(runtime, filter) {
 export async function getThread(runtime, threadId) {
     return runtime.getThread(threadId);
 }
+export async function deleteThread(runtime, threadId) {
+    return runtime.deleteThread(threadId);
+}
 export async function listApprovals(runtime, filter) {
     return runtime.listApprovals(filter);
 }

package/dist/config/workspace.yaml

@@ -22,6 +22,11 @@ spec:
   # Value options: relative workspace path like `./.agent`, or an absolute filesystem path.
   runRoot: ./.agent
 
+  # agent-harness feature: runtime-level task queue and maximum number of concurrent runs.
+  # Additional runs wait in the harness queue until a slot becomes available.
+  concurrency:
+    maxConcurrentRuns: 3
+
   # agent-harness feature: optional host-router prompt override used when the runtime chooses between
   # top-level host agents such as a main execution host and an optional low-latency side host.
   # Use placeholders so the same prompt can survive host renames:
@@ -90,19 +95,17 @@ spec:
   # - oldest-first deletion by time policy and/or size policy
   # - background scheduling inside the harness lifecycle
   #
-  # Example:
-  # maintenance:
-  #   checkpoints:
-  #     enabled: true
-  #     schedule:
-  #       intervalSeconds: 3600
-  #       runOnStartup: true
-  #     policies:
-  #       maxAgeSeconds: 604800
-  #       maxBytes: 1073741824
-  #     sqlite:
-  #       sweepBatchSize: 200
-  #       vacuum: false
+  maintenance:
+    checkpoints:
+      enabled: true
+      schedule:
+        intervalSeconds: 3600
+        runOnStartup: true
+      policies:
+        maxAgeSeconds: 604800
+      sqlite:
+        sweepBatchSize: 200
+        vacuum: false
 
   # agent-harness feature: runtime-managed recovery policy for interrupted runs.
   # This keeps checkpoint resume as an internal lifecycle concern instead of a primary user-facing API concept.
@@ -112,8 +115,7 @@ spec:
   # - persisted approval-decision intent for cross-restart resume continuation
   # - bounded retry attempts to avoid infinite restart loops
   #
-  # Example:
-  # recovery:
-  #   enabled: true
-  #   resumeResumingRunsOnStartup: true
-  #   maxRecoveryAttempts: 3
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3

package/dist/contracts/types.d.ts

@@ -4,7 +4,7 @@ export type RuntimeCapabilities = {
     delegation?: boolean;
     memory?: boolean;
 };
-export type RunState = "running" | "waiting_for_approval" | "resuming" | "completed" | "failed";
+export type RunState = "queued" | "running" | "waiting_for_approval" | "resuming" | "completed" | "failed";
 export type ParsedAgentObject = {
     id: string;
     executionMode: ExecutionMode;
@@ -85,6 +85,7 @@ export type ParsedToolObject = {
         enabled: boolean;
         allow?: Array<"approve" | "edit" | "reject">;
     };
+    retryable?: boolean;
     sourcePath: string;
 };
 export type LangChainAgentParams = {
@@ -172,6 +173,7 @@ export type CompiledTool = {
         enabled: boolean;
         allow: Array<"approve" | "edit" | "reject">;
     };
+    retryable?: boolean;
     runtimeValue: {
         name: string;
         description: string;
@@ -221,7 +223,7 @@ export type ThreadSummary = {
     status: RunState;
 };
 export type SessionRecord = ThreadSummary;
-export type KnownHarnessEventType = "run.created" | "run.state.changed" | "run.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "reasoning.delta" | "runtime.synthetic_fallback";
+export type KnownHarnessEventType = "run.created" | "run.queued" | "run.dequeued" | "run.state.changed" | "run.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "reasoning.delta" | "runtime.synthetic_fallback";
 export type HarnessEventType = KnownHarnessEventType | (string & {});
 export type HarnessEvent = {
     eventId: string;

package/dist/extensions.js

@@ -126,6 +126,7 @@ registerToolKind({
                         allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
                     }
                     : undefined,
+                retryable: tool.retryable,
                 runtimeValue: { name: tool.name, description: tool.description, type: "function" },
             },
         ];
@@ -158,6 +159,7 @@ registerToolKind({
                         allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
                     }
                     : undefined,
+                retryable: tool.retryable,
                 runtimeValue: { name: tool.name, description: tool.description, type: "backend" },
             },
         ];
@@ -190,6 +192,7 @@ registerToolKind({
                         allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
                     }
                     : undefined,
+                retryable: tool.retryable,
                 runtimeValue: { name: tool.name, description: tool.description, type: "mcp" },
             },
         ];

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.44";
+export declare const AGENT_HARNESS_VERSION = "0.0.46";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.44";
+export const AGENT_HARNESS_VERSION = "0.0.46";

package/dist/persistence/file-store.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
+import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, InvocationEnvelope, MessageContent, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
 type ThreadMeta = {
     threadId: string;
     workspaceId: string;
@@ -39,9 +39,18 @@ type RecoveryIntent = {
     resumePayload: unknown;
     attempts: number;
 };
+type PersistedRunRequest = {
+    input: MessageContent;
+    invocation?: InvocationEnvelope;
+    savedAt: string;
+};
 export declare class FilePersistence {
     private readonly runRoot;
     constructor(runRoot: string);
+    private threadIndexPath;
+    private runIndexPath;
+    private approvalIndexPath;
+    private delegationIndexPath;
     initialize(): Promise<void>;
     threadDir(threadId: string): string;
     runDir(threadId: string, runId: string): string;
@@ -73,6 +82,10 @@ export declare class FilePersistence {
     getRunApprovals(threadId: string, runId: string): Promise<InternalApprovalRecord[]>;
     getRunMeta(threadId: string, runId: string): Promise<RunMeta>;
     getRunLifecycle(threadId: string, runId: string): Promise<Lifecycle>;
+    deleteThread(threadId: string): Promise<boolean>;
+    saveRunRequest(threadId: string, runId: string, request: PersistedRunRequest): Promise<void>;
+    getRunRequest(threadId: string, runId: string): Promise<PersistedRunRequest | null>;
+    clearRunRequest(threadId: string, runId: string): Promise<void>;
     listDelegations(): Promise<DelegationRecord[]>;
     createApproval(record: InternalApprovalRecord): Promise<void>;
     resolveApproval(threadId: string, runId: string, approvalId: string, status: InternalApprovalRecord["status"]): Promise<InternalApprovalRecord>;