@botbotgo/agent-harness 0.0.44 → 0.0.46

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
@@ -207,6 +219,8 @@ Core workspace files:
 - `config/workspace.yaml`
 - `config/agent-context.md`
 - `config/models.yaml`
+- `config/embedding-models.yaml`
+- `config/vector-stores.yaml`
 - `config/stores.yaml`
 - `config/tools.yaml`
 - `config/mcp.yaml`
@@ -216,29 +230,281 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
-### `config/workspace.yaml`
+Use Kubernetes-style YAML:
+
+- collection files use `apiVersion`, plural `kind`, and `spec: []`
+- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+
+Use distinct names for named objects such as models, stores, checkpointers, tools, and MCP servers.
+
+### 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.
 
-Use this file for runtime-level policy:
+There are three layers of client configuration:
 
-- `runRoot`
-- `routing.rules`
-- `routing.defaultAgentId`
-- `routing.systemPrompt`
-- `routing.modelRouting`
-- `concurrency.maxConcurrentRuns`
-- `recovery.enabled`
-- `recovery.resumeOnStartup`
-- `recovery.maxRecoveryAttempts`
-- `maintenance.checkpoints.*`
+- runtime-level policy in `config/workspace.yaml`
+- reusable object catalogs in `config/*.yaml`
+- agent assembly in `config/agents/*.yaml`
+
+### `config/workspace.yaml`
+
+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:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Models
+spec:
+  - name: default
+    provider: openai
+    model: gpt-4.1
+    temperature: 0.2
+  - name: planner
+    provider: openai
+    model: gpt-4.1-mini
+```
+
+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:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Stores
+spec:
+  - kind: Store
+    name: default
+    storeKind: FileStore
+    path: store.json
+  - kind: Checkpointer
+    name: default
+    checkpointerKind: MemorySaver
+```
+
+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:
@@ -257,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/`
 
@@ -283,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
@@ -291,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/config/embedding-models.yaml

@@ -0,0 +1,28 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for named embedding-model presets.
+kind: EmbeddingModels
+spec:
+  # agent-harness feature: named embedding model entry used by refs such as `embedding-model/default`.
+  - name: default
+    # ====================
+    # LangChain v1 Features
+    # ====================
+    # LangChain aligned feature: provider family or integration namespace for an embeddings implementation.
+    provider: ollama
+    # LangChain aligned feature: concrete embedding model identifier passed to the provider integration.
+    model: nomic-embed-text
+    # LangChain aligned feature: provider-specific initialization options for embeddings.
+    baseUrl: https://ollama-rtx-4070.easynet.world/
+
+    # ===================
+    # DeepAgents Features
+    # ===================
+    # DeepAgents does not define a separate embeddings abstraction. Embedding models are consumed indirectly
+    # by retrieval tools that a DeepAgent may call.
+
+    # ======================
+    # agent-harness Features
+    # ======================
+    # This object is packaged and referenced through retrieval-oriented workspace tools such as the RAG index builder
+    # and query tool, not through `agent.modelRef`.

package/dist/config/mcp.yaml

@@ -1,20 +1,5 @@
 # agent-harness feature: schema version for reusable MCP server objects.
 apiVersion: agent-harness/v1alpha1
-# This first-layer catalog is the default place to register reusable McpServer objects and MCP-backed Tool objects.
-# Examples:
-# items:
-#   - kind: McpServer
-#     metadata:
-#       name: browser
-#     spec:
-#       command: node
-#       args: ["./mcp-browser-server.mjs"]
-#
-#   - kind: Tool
-#     metadata:
-#       name: browser_navigate
-#     spec:
-#       mcp:
-#         serverRef: mcp/browser
-#         tool: navigate
-items: []
+# agent-harness feature: object type for named reusable MCP server and MCP-backed tool presets.
+kind: McpServers
+spec: []

package/dist/config/models.yaml

@@ -4,26 +4,26 @@ apiVersion: agent-harness/v1alpha1
 kind: Models
 spec:
   - name: default
-    # ====================
-    # LangChain v1 Features
-    # ====================
-    # LangChain aligned feature: provider family or integration namespace.
-    # Common options in this harness today include:
-    # - `ollama`
-    # - `openai`
-    # - `openai-compatible`
-    # - `anthropic`
-    # - `google` / `google-genai` / `gemini`
-    # The runtime adapter uses this to select the concrete LangChain chat model implementation.
+  # ====================
+  # LangChain v1 Features
+  # ====================
+  # LangChain aligned feature: provider family or integration namespace.
+  # Common options in this harness today include:
+  # - `ollama`
+  # - `openai`
+  # - `openai-compatible`
+  # - `anthropic`
+  # - `google` / `google-genai` / `gemini`
+  # The runtime adapter uses this to select the concrete LangChain chat model implementation.
     provider: ollama
-    # LangChain aligned feature: concrete model identifier passed to the selected provider integration.
-    # Example values depend on `provider`, such as `gpt-oss:latest` for `ollama`.
+  # LangChain aligned feature: concrete model identifier passed to the selected provider integration.
+  # Example values depend on `provider`, such as `gpt-oss:latest` for `ollama`.
     model: gpt-oss:latest
-    # LangChain aligned feature: provider-specific initialization options.
-    # Write these fields directly on the model object.
-    # Common examples include `baseUrl`, `temperature`, and auth/client settings.
-    # `baseUrl` configures the Ollama-compatible endpoint used by the model client.
-    # For `openai-compatible`, `baseUrl` is normalized into the ChatOpenAI `configuration.baseURL` field.
+  # LangChain aligned feature: provider-specific initialization options.
+  # Write these fields directly on the model object.
+  # Common examples include `baseUrl`, `temperature`, and auth/client settings.
+  # `baseUrl` configures the Ollama-compatible endpoint used by the model client.
+  # For `openai-compatible`, `baseUrl` is normalized into the ChatOpenAI `configuration.baseURL` field.
     baseUrl: https://ollama-rtx-4070.easynet.world/
-    # LangChain aligned feature: provider/model initialization option controlling sampling temperature.
+  # LangChain aligned feature: provider/model initialization option controlling sampling temperature.
     temperature: 0.2

package/dist/config/stores.yaml

@@ -1,19 +1,17 @@
 # agent-harness feature: schema version for reusable persistence presets.
 apiVersion: agent-harness/v1alpha1
-items:
+# agent-harness feature: object type for named persistence presets.
+kind: Stores
+spec:
   # agent-harness feature: reusable store preset for agent backends that need a durable key-value store.
   - kind: Store
-    metadata:
-      name: default
-      description: Default file-backed store preset for runtime-managed agent state.
-    spec:
-      storeKind: FileStore
-      path: store.json
+    name: default
+    description: Default file-backed store preset for runtime-managed agent state.
+    storeKind: FileStore
+    path: store.json
 
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer
-    metadata:
-      name: default
-      description: Default in-memory checkpointer preset for lightweight local development.
-    spec:
-      checkpointerKind: MemorySaver
+    name: default
+    description: Default in-memory checkpointer preset for lightweight local development.
+    checkpointerKind: MemorySaver

package/dist/config/tools.yaml

@@ -1,13 +1,5 @@
 # agent-harness feature: schema version for reusable tool objects.
 apiVersion: agent-harness/v1alpha1
-# This first-layer catalog is the default place to register reusable Tool objects that agents can reference.
-# Examples:
-# items:
-#   - kind: Tool
-#     metadata:
-#       name: repo_search
-#       description: Workspace-local repo search tool.
-#     spec:
-#       backend:
-#         operation: repo_search
-items: []
+# agent-harness feature: object type for named reusable tool presets.
+kind: Tools
+spec: []

package/dist/config/vector-stores.yaml

@@ -0,0 +1,25 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for named vector-store presets.
+kind: VectorStores
+spec:
+  # agent-harness feature: named vector store entry used by refs such as `vector-store/default`.
+  - name: default
+    # ====================
+    # LangChain v1 Features
+    # ====================
+    # LangChain aligned feature: concrete vector store implementation.
+    # The built-in runtime currently supports `LibSQLVectorStore` for SQLite/libSQL-backed vector retrieval.
+    storeKind: LibSQLVectorStore
+    # LangChain aligned feature: libSQL connection URL.
+    # Local SQLite files use the `file:` prefix.
+    url: file:.agent/vector-store.db
+    # LangChain aligned feature: target table and embedding column.
+    table: rag_chunks
+    column: embedding
+
+    # ======================
+    # agent-harness Features
+    # ======================
+    # Retrieval tools use this to resolve their default embeddings when indexing or querying this vector store.
+    embeddingModelRef: embedding-model/default