@botbotgo/agent-harness 0.0.1

package/dist/api.d.ts

@@ -0,0 +1,22 @@
+import type { ArtifactListing, RestartConversationOptions, ResumeOptions, RunOptions, RuntimeAdapterOptions, SessionRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
+import { AgentHarness } from "./runtime/harness.js";
+export declare function loadWorkspaceBundle(workspaceRoot: string, options?: WorkspaceLoadOptions): Promise<WorkspaceBundle>;
+export declare function createHarness(workspace: WorkspaceBundle, adapterOptions?: RuntimeAdapterOptions): AgentHarness;
+export declare function listHarnessSessions(harness: AgentHarness, filter?: {
+    agentId?: string;
+}): Promise<SessionRecord[]>;
+export declare function getHarnessApproval(harness: AgentHarness, approvalId: string): Promise<import("./contracts/types.js").ApprovalRecord | null>;
+export declare function runHarness(harness: AgentHarness, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function streamHarness(harness: AgentHarness, options: RunOptions): Promise<AsyncGenerator<string, any, any>>;
+export declare function streamHarnessEvents(harness: AgentHarness, options: RunOptions): Promise<AsyncGenerator<import("./contracts/types.js").HarnessStreamItem, any, any>>;
+export declare function resumeHarness(harness: AgentHarness, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function submitHarnessDecision(harness: AgentHarness, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function approveHarnessRun(harness: AgentHarness, threadId: string, runId?: string): Promise<import("./contracts/types.js").RunResult>;
+export declare function rejectHarnessRun(harness: AgentHarness, threadId: string, runId?: string): Promise<import("./contracts/types.js").RunResult>;
+export declare function restartHarnessConversation(harness: AgentHarness, options: RestartConversationOptions): Promise<import("./contracts/types.js").RunResult & {
+    restart: Record<string, string>;
+}>;
+export declare function listHarnessArtifacts(harness: AgentHarness, threadId: string, runId?: string): Promise<ArtifactListing>;
+export declare function subscribeHarness(harness: AgentHarness, listener: Parameters<AgentHarness["subscribe"]>[0]): () => void;
+export declare function closeHarness(harness: AgentHarness): Promise<void>;
+export { loadWorkspaceBundle as loadWorkspaceFacade, listHarnessSessions as listSessionsFacade, getHarnessApproval as getApprovalFacade, runHarness as runFacade, streamHarness as streamFacade, streamHarnessEvents as streamEventsFacade, resumeHarness as resumeFacade, submitHarnessDecision as submitDecisionFacade, approveHarnessRun as approveFacade, rejectHarnessRun as rejectFacade, restartHarnessConversation as restartConversationFacade, listHarnessArtifacts as artifactsFacade, subscribeHarness as subscribeFacade, closeHarness as closeFacade, };

package/dist/api.js

@@ -0,0 +1,48 @@
+import { AgentHarness } from "./runtime/harness.js";
+import { loadWorkspace } from "./workspace/compile.js";
+export async function loadWorkspaceBundle(workspaceRoot, options = {}) {
+    return loadWorkspace(workspaceRoot, options);
+}
+export function createHarness(workspace, adapterOptions = {}) {
+    return new AgentHarness(workspace, adapterOptions);
+}
+export async function listHarnessSessions(harness, filter) {
+    return harness.listSessions(filter);
+}
+export async function getHarnessApproval(harness, approvalId) {
+    return harness.getApproval(approvalId);
+}
+export async function runHarness(harness, options) {
+    return harness.run(options);
+}
+export async function streamHarness(harness, options) {
+    return harness.stream(options);
+}
+export async function streamHarnessEvents(harness, options) {
+    return harness.streamEvents(options);
+}
+export async function resumeHarness(harness, options) {
+    return harness.resume(options);
+}
+export async function submitHarnessDecision(harness, options) {
+    return harness.submitDecision(options);
+}
+export async function approveHarnessRun(harness, threadId, runId) {
+    return harness.approve(threadId, runId);
+}
+export async function rejectHarnessRun(harness, threadId, runId) {
+    return harness.reject(threadId, runId);
+}
+export async function restartHarnessConversation(harness, options) {
+    return harness.restartConversation(options);
+}
+export async function listHarnessArtifacts(harness, threadId, runId) {
+    return harness.artifacts(threadId, runId);
+}
+export function subscribeHarness(harness, listener) {
+    return harness.subscribe(listener);
+}
+export async function closeHarness(harness) {
+    return harness.close();
+}
+export { loadWorkspaceBundle as loadWorkspaceFacade, listHarnessSessions as listSessionsFacade, getHarnessApproval as getApprovalFacade, runHarness as runFacade, streamHarness as streamFacade, streamHarnessEvents as streamEventsFacade, resumeHarness as resumeFacade, submitHarnessDecision as submitDecisionFacade, approveHarnessRun as approveFacade, rejectHarnessRun as rejectFacade, restartHarnessConversation as restartConversationFacade, listHarnessArtifacts as artifactsFacade, subscribeHarness as subscribeFacade, closeHarness as closeFacade, };

package/dist/config/direct.yaml

@@ -0,0 +1,48 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type discriminator.
+# Available options today: `DeepAgent`, `LangChainAgent`.
+# `LangChainAgent` means this file compiles to the lightweight LangChain v1 execution path
+# rather than the upstream `createDeepAgent(...)` runtime.
+kind: LangChainAgent
+metadata:
+  # agent-harness feature: stable object id used for refs and host-agent selection.
+  name: direct
+  # agent-harness feature: human-readable summary for inventory and UI.
+  description: Manual low-latency host for direct answers and lightweight inventory lookup. Do not use it as the default executor for tool-heavy or specialist-shaped tasks.
+spec:
+  # ======================
+  # LangChainAgent Features
+  # ======================
+  # Shared LangChain v1 / DeepAgents feature: model ref for the underlying LLM used by the
+  # direct-response agent. This should point at a cheap, fast, general-purpose chat model,
+  # because `direct` is intended to be the low-latency path for simple requests.
+  modelRef: model/default
+  # Shared LangChain v1 / DeepAgents feature: checkpointer config passed into the runtime.
+  # Even the lightweight direct path can benefit from resumable state during interactive use.
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+  checkpointer:
+    kind: MemorySaver
+  # LangChainAgent aligned feature: system prompt for the lightweight direct-response host.
+  # This prompt should keep the agent focused on:
+  # - answering simple requests in one turn
+  # - staying lightweight instead of planning or orchestrating
+  # - avoiding specialist-style decomposition unless the caller explicitly switches agents
+  #
+  # The direct host is intentionally narrower than the orchestra host:
+  # - `direct` is optimized for latency and straightforward completion
+  # - `orchestra` is optimized for multi-step work, tools, delegation, and specialist use
+  #
+  # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
+  # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
+  # rather than overloading the direct host prompt with classifier behavior.
+  systemPrompt: |-
+    You are the direct agent.
+
+    This is a manual low-latency host.
+    Answer simple requests directly.
+    Keep the path lightweight.
+    Do not delegate.
+    Do not perform broad multi-step execution.
+    Do not behave like the default execution host.

package/dist/config/embedding-model.yaml

@@ -0,0 +1,30 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for a named embedding-model preset.
+kind: EmbeddingModel
+metadata:
+  # agent-harness feature: stable embedding model object id used by refs such as `embedding-model/default`.
+  name: default
+spec:
+  # ====================
+  # 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
+  init:
+    # 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 builtin tools such as `builtin.build_rag_index`
+  # and `builtin.query_rag_index`, not through `agent.modelRef`.

package/dist/config/model.yaml

@@ -0,0 +1,44 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for a named model preset.
+# Available options today: `Model`.
+# The harness resolves this object into LangChain model construction parameters.
+kind: Model
+metadata:
+  # agent-harness feature: stable model object id used by refs such as `model/default`.
+  name: default
+spec:
+  # ====================
+  # 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`.
+  model: gpt-oss:latest
+  init:
+    # LangChain aligned feature: provider-specific initialization options.
+    # Available keys are provider-specific; 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.
+    temperature: 0.2
+  # ===================
+  # DeepAgents Features
+  # ===================
+  # DeepAgents uses the same model object shape indirectly through `createDeepAgent({ model })`.
+  # There is no separate DeepAgents-only field here; DeepAgent bindings consume the same compiled model.
+
+  # ======================
+  # agent-harness Features
+  # ======================
+  # This object is packaged and referenced through `modelRef` fields in harness config, but the actual
+  # model arguments above map directly onto the upstream LangChain model layer.

package/dist/config/orchestra.yaml

@@ -0,0 +1,92 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type discriminator.
+# Available options today: `DeepAgent`, `LangChainAgent`.
+# `DeepAgent` means this file compiles to `createDeepAgent(...)` rather than the LangChain v1 agent path.
+kind: DeepAgent
+metadata:
+  # agent-harness feature: stable object id used for refs and default DeepAgents name inference.
+  name: orchestra
+  # agent-harness feature: human-readable summary for inventory and UI.
+  description: Default execution host. Answer directly when possible, use local tools and skills first, and delegate only when a specialist is a better fit. Not a reflex delegation-only planner.
+spec:
+  # ===================
+  # DeepAgents Features
+  # ===================
+  # DeepAgents aligned feature: model ref for the underlying LLM used by `createDeepAgent(...)`.
+  modelRef: model/default
+  # Shared LangChain v1 / DeepAgents feature: checkpointer config passed into the upstream runtime.
+  # This persists resumable graph state for this agent.
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+  checkpointer:
+    # kind: FileCheckpointer
+    kind: MemorySaver
+  memory:
+    # DeepAgents aligned feature: bootstrap memory sources supplied to the deep agent at construction time.
+    # These source paths resolve to static files that prime the agent before tool execution begins.
+    # This is distinct from long-term memory:
+    # - `memory:` here provides startup context files to `createDeepAgent(...)`
+    # - `store` below provides the LangGraph store consumed by `StoreBackend`
+    # - `backend` below controls `/memories/*` routing and other filesystem backend behavior
+    # - the harness checkpointer persists resumable graph state separately under the run root
+    - path: AGENTS.md
+  # DeepAgents aligned feature: store config passed into `createDeepAgent({ store })`.
+  # This is the LangGraph store used by `StoreBackend` routes inside the DeepAgents backend.
+  # Available `kind` options in this harness: `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`.
+  store:
+    kind: FileStore
+    path: store.json
+  # DeepAgents aligned feature: backend config passed into `createDeepAgent({ backend })`.
+  # This directly defines the backend topology for this agent:
+  # - runtime graph state uses `StateBackend`
+  # - long-term memory under `/memories/*` uses `StoreBackend`
+  # - `CompositeBackend` composes those backend instances together
+  # The harness also injects a persistent file-backed store and a file-backed checkpointer so that
+  # `/memories/*` and resumable run state survive restarts in the default setup.
+  # Available top-level `kind` options in this harness: `CompositeBackend`, `StateBackend`, `StoreBackend`.
+  backend:
+    kind: CompositeBackend
+    state:
+      # Available state backend `kind` options today: `StateBackend`, `LocalShellBackend`.
+      kind: LocalShellBackend
+      inheritEnv: true
+      timeout: 600
+      maxOutputBytes: 200000
+    routes:
+      /memories/:
+        # Available route backend `kind` options today: `StoreBackend`.
+        kind: StoreBackend
+  # DeepAgents aligned feature: system prompt for the orchestration deep agent.
+  # This becomes the top-level instruction block for the upstream DeepAgents runtime.
+  systemPrompt: |-
+    You are the orchestra agent.
+
+    You are the default execution host.
+    Try to finish the request yourself before delegating.
+    Use your own tools first when they are sufficient.
+    Use your own skills first when they are sufficient.
+    Delegate only when a specialist is a clearly better fit or when your own tools and skills are not enough.
+    If neither you nor any suitable specialist can do the work, say so plainly.
+
+    Do not delegate by reflex.
+    Do not delegate just because a task has multiple steps.
+    Do not delegate when a direct answer or a short local tool pass is enough.
+    Keep the critical path local when immediate progress depends on it; otherwise delegate bounded sidecar work to
+    the most appropriate specialist.
+
+    Use your own tools for lightweight discovery, inventory, and context gathering.
+    Prefer the structured checkout, indexing, retrieval, and inventory tools that are already attached to you over
+    ad hoc shell work when those tools are sufficient.
+    Use the attached specialist descriptions as the source of truth for what each specialist is for.
+    Do not delegate to a specialist whose description does not clearly match the task.
+    Integrate specialist results into one coherent answer and do not claim checks or evidence you did not obtain.
+
+    When the user asks about available tools, skills, or agents, use the attached inventory tools instead of
+    inferring from memory.
+
+    Write to `/memories/*` only when the information is durable, reusable across future runs or threads, and likely
+    to matter again: user preferences, project conventions, confirmed decisions, reusable summaries, and stable
+    ownership facts are good candidates.
+    Do not store transient reasoning, temporary plans, scratch work, one-off search results, or intermediate
+    outputs that can be cheaply recomputed.

package/dist/config/runtime.yaml

@@ -0,0 +1,47 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: workspace-global runtime defaults.
+# This object is harness-owned and acts like a global variables document for the workspace.
+# It is loaded automatically and does not use `ref` indirection from agents.
+# Available options today: `Runtime`.
+kind: Runtime
+metadata:
+  # agent-harness feature: stable singleton name for the default runtime variables object.
+  name: default
+spec:
+  # ======================
+  # agent-harness Features
+  # ======================
+  # agent-harness feature: filesystem root where the harness stores local run artifacts by default.
+  # This affects file-backed persistence such as:
+  # - session / thread / run indexes
+  # - approval and delegation records
+  # - default file-backed store paths
+  # - default file-backed checkpointer paths
+  # Agents inherit this value unless they override `spec.runRoot` locally.
+  # Value options: relative workspace path like `./.agent`, or an absolute filesystem path.
+  runRoot: ./.agent
+
+  # agent-harness feature: optional host-router prompt override used when the framework chooses between
+  # top-level host agents such as `direct` and `orchestra`.
+  # Use placeholders so the same prompt can survive host renames:
+  # - {{primaryAgentId}}
+  # - {{primaryDescription}}
+  # - {{secondaryAgentId}}
+  # - {{secondaryDescription}}
+  routing:
+    systemPrompt: |-
+      You are a routing classifier for an agent harness. Reply with exactly one agent id:
+      {{primaryAgentId}} or {{secondaryAgentId}}.
+
+      Choose {{primaryAgentId}} only for lightweight conversational turns that can be answered directly in one step
+      without tool use, repository inspection, file lookup, external checkout, or orchestration.
+
+      Choose {{secondaryAgentId}} for requests that need tools, multi-step execution, external research, repository or
+      file analysis, downloading or cloning content, codebase exploration, verification, or any task where the agent
+      should inspect the workspace or another repository before answering.
+
+      If the request asks to download, clone, fetch, inspect, analyze, trace, or locate implementation in a repo or
+      codebase, choose {{secondaryAgentId}}.
+
+      When uncertain, prefer {{secondaryAgentId}}.

package/dist/config/vector-store.yaml

@@ -0,0 +1,26 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for a named vector-store preset.
+kind: VectorStore
+metadata:
+  # agent-harness feature: stable vector store object id used by refs such as `vector-store/default`.
+  name: default
+spec:
+  # ====================
+  # 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