@poncho-ai/harness 0.40.1 → 0.41.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.40.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.41.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            489.88 KB
+ESM dist/index.js            493.42 KB
 ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 205ms
+ESM ⚡️ Build success in 238ms
 DTS Build start
-DTS ⚡️ Build success in 7664ms
-DTS dist/index.d.ts 75.12 KB
+DTS ⚡️ Build success in 7385ms
+DTS dist/index.d.ts 77.00 KB

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @poncho-ai/harness
 
+## 0.41.0
+
+### Minor Changes
+
+- [#110](https://github.com/cesr/poncho-ai/pull/110) [`7d57a88`](https://github.com/cesr/poncho-ai/commit/7d57a88e55a49ec04de3dbd415b2440bb727e31f) Thanks [@cesr](https://github.com/cesr)! - harness: allow programmatic agent + storage injection (no AGENT.md required)
+
+  `HarnessOptions` gains two optional fields that let callers construct a
+  `Harness` without an `AGENT.md` on disk and without the
+  `ensureAgentIdentity` filesystem dance:
+  - `agentDefinition?: string | ParsedAgent` — raw markdown or a pre-parsed
+    agent. When provided, `initialize()` skips the `AGENT.md` read.
+  - `storageEngine?: StorageEngine` — pre-constructed engine; required
+    whenever `agentDefinition` is provided. The engine's `agentId` (now a
+    public readonly field on the `StorageEngine` interface) becomes the
+    source of truth for partitioning, and is mirrored onto
+    `parsedAgent.frontmatter.id` so existing downstream readers continue
+    to resolve correctly.
+
+  When neither field is provided, behaviour is unchanged: the harness
+  reads `AGENT.md` from `workingDir`, calls `ensureAgentIdentity`, and
+  constructs the `StorageEngine` internally.
+
+  `refreshAgentIfChanged()` short-circuits when an agent definition was
+  injected — callers who update an agent re-instantiate the harness
+  rather than relying on disk file watching.
+
+  This is the first of a small set of changes that lets `@poncho-ai/harness`
+  be embedded as a library by consumer SaaS apps where each user has
+  their own per-tenant agent state in a database, no filesystem layout.
+
+- [#111](https://github.com/cesr/poncho-ai/pull/111) [`ac18616`](https://github.com/cesr/poncho-ai/commit/ac18616b864189c91d0957c72c537933497505f4) Thanks [@cesr](https://github.com/cesr)! - harness: allow programmatic `PonchoConfig` injection
+
+  `HarnessOptions` gains an optional `config?: PonchoConfig` field. When
+  provided, `initialize()` skips `loadPonchoConfig` (which imports
+  `poncho.config.js` from `workingDir`) and uses the supplied object
+  directly. Downstream resolvers (`resolveMemoryConfig`,
+  `resolveStateConfig`, etc.) run as today, so any validation/normalization
+  they perform applies to injected configs identically.
+
+  Behaviour is unchanged when the field is absent: the disk loader runs
+  as before.
+
+  This is part of a small series of changes that enables
+  `@poncho-ai/harness` to be embedded as a library by a consumer SaaS
+  where each user's agent configuration comes from a database row, not a
+  `poncho.config.js` on disk.
+
+- [#112](https://github.com/cesr/poncho-ai/pull/112) [`c22416b`](https://github.com/cesr/poncho-ai/commit/c22416b3d4c4557277aeabf53e70877be6436e85) Thanks [@cesr](https://github.com/cesr)! - harness: cache MCP clients per `(serverName, tenantId)` instead of rebuilding per call
+
+  When a tenant resolves a different bearer token than the host's
+  `process.env` default for an MCP server, the per-call handler used to
+  construct a brand-new `StreamableHttpMcpRpcClient` on every tool call.
+  For builders this rarely triggered. For consumer/SaaS deployments where
+  **every** call resolves a different per-user token, every tool call
+  forced a fresh `initialize` round-trip — no session reuse, high
+  latency, and a behaviour the recently-added 404 session-retry can't
+  help with because there was nothing to retry.
+
+  `LocalMcpBridge` now keeps a `Map<key, { client, token, lastUsed }>`
+  keyed by `(serverName, tenantId)`. Lookups reuse the cached client when
+  the token is unchanged and the entry is within the configured idle TTL
+  (default 15 minutes). On token rotation or TTL expiry the entry is
+  evicted lazily and rebuilt. `stopLocalServers()` closes all cached
+  tenant clients alongside the server-default ones.
+
+  The TTL is configurable via a constructor option (`tenantClientTtlMs`)
+  for tests and tuning.
+
+### Patch Changes
+
+- [#109](https://github.com/cesr/poncho-ai/pull/109) [`4b5d974`](https://github.com/cesr/poncho-ai/commit/4b5d974345733ac9e68f36201dff7e7d8a8f0327) Thanks [@cesr](https://github.com/cesr)! - harness: re-initialize MCP session on 404 instead of staying wedged
+
+  Streamable-HTTP MCP clients with session state (e.g. Arcade's gateway
+  for Gmail / Google Calendar) issue an `Mcp-Session-Id` on initialize
+  and expire it after some idle window. The bridge cached `sessionId`
+  and `initialized` in process memory and never reset them, so once the
+  server returned 404 for a stale session every subsequent tool call
+  also 404'd until the host process restarted. Long-lived deployments
+  (e.g. Railway) hit this; serverless platforms masked it because each
+  invocation re-initialized.
+
+  The client now treats `404` with a stored `sessionId` as a session
+  expiry signal: it clears the session, re-runs `initialize`, and
+  retries the request once. A 404 from initialize itself (no session
+  yet) is still treated as a hard endpoint failure with no retry.
+
 ## 0.40.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -370,12 +370,26 @@ declare class LocalMcpBridge {
     private readonly unavailableServers;
     private readonly authFailedServers;
     private envResolver?;
+    /**
+     * Per-tenant MCP client cache. For consumer/SaaS deployments where every
+     * call resolves a different bearer token, building a fresh
+     * `StreamableHttpMcpRpcClient` per call would force a fresh `initialize`
+     * round-trip every time. We keep one client per `(serverName, tenantId)`
+     * with TTL-based idle eviction; on token rotation we evict the entry
+     * lazily and rebuild.
+     */
+    private readonly tenantClients;
+    /** Test/observability hook: bumped every time a new tenant client is constructed. */
+    tenantClientConstructions: number;
+    private readonly tenantClientTtlMs;
     /**
      * Set a resolver for per-tenant env vars (e.g. MCP auth tokens).
      * Called by the harness after creating the secrets store.
      */
     setEnvResolver(resolver: (tenantId: string | undefined, envName: string) => Promise<string | undefined>): void;
-    constructor(config: McpConfig | undefined);
+    constructor(config: McpConfig | undefined, options?: {
+        tenantClientTtlMs?: number;
+    });
     private getServerName;
     private log;
     /** Set of servers where discovery was deferred (no default token, has env resolver). */
@@ -389,6 +403,7 @@ declare class LocalMcpBridge {
     private tryDeferredDiscovery;
     startLocalServers(): Promise<void>;
     stopLocalServers(): Promise<void>;
+    private getOrCreateTenantClient;
     listServers(): RemoteMcpServerConfig[];
     listRemoteServers(): RemoteMcpServerConfig[];
     checkRemoteConnectivity(): Promise<Array<{
@@ -806,6 +821,8 @@ interface VfsDirEntry {
     type: "file" | "directory" | "symlink";
 }
 interface StorageEngine {
+    /** Partition key: every read/write is scoped to this agent id. */
+    readonly agentId: string;
     /** Run migrations and prepare the storage backend. */
     initialize(): Promise<void>;
     /** Gracefully release resources. */
@@ -1007,6 +1024,27 @@ interface HarnessOptions {
     toolDefinitions?: ToolDefinition[];
     modelProvider?: ModelProviderFactory;
     uploadStore?: UploadStore;
+    /**
+     * Inject the agent definition directly instead of reading AGENT.md from
+     * `workingDir`. Pass raw markdown (string) or a pre-parsed `ParsedAgent`.
+     * When provided, `storageEngine` is also required — the engine's
+     * `agentId` becomes the source of truth for partitioning, and the
+     * filesystem identity dance (`ensureAgentIdentity`) is skipped.
+     */
+    agentDefinition?: string | ParsedAgent;
+    /**
+     * Pre-constructed storage engine. When provided, the harness will not
+     * create one internally. The engine's `agentId` is used wherever the
+     * harness today reads `parsedAgent.frontmatter.id`.
+     */
+    storageEngine?: StorageEngine;
+    /**
+     * Inject a `PonchoConfig` object directly instead of importing
+     * `poncho.config.js` from `workingDir`. When provided, the disk-based
+     * loader is skipped. Downstream resolvers (`resolveMemoryConfig`,
+     * `resolveStateConfig`, etc.) run as today regardless of source.
+     */
+    config?: PonchoConfig;
 }
 interface HarnessRunOutput {
     runId: string;
@@ -1037,6 +1075,7 @@ declare class AgentHarness {
     reminderStore?: ReminderStore;
     secretsStore?: SecretsStore;
     private loadedConfig?;
+    private readonly injectedConfig?;
     private loadedSkills;
     private skillFingerprint;
     private lastSkillRefreshAt;
@@ -1051,6 +1090,8 @@ declare class AgentHarness {
     private _browserMod?;
     private parsedAgent?;
     private agentFileFingerprint;
+    private injectedAgentDefinition?;
+    private injectedStorageEngine;
     private mcpBridge?;
     private subagentManager?;
     private readonly archivedToolResultsByConversation;
@@ -1279,7 +1320,7 @@ declare class TelemetryEmitter {
 }
 
 declare class InMemoryEngine implements StorageEngine {
-    private readonly agentId;
+    readonly agentId: string;
     private convs;
     private mem;
     private todoData;
@@ -1394,7 +1435,7 @@ declare class ConversationEgressMeter {
 }
 declare abstract class SqlStorageEngine implements StorageEngine {
     protected readonly dialect: Dialect;
-    protected readonly agentId: string;
+    readonly agentId: string;
     protected abstract readonly executor: QueryExecutor;
     protected readonly egressMeter: ConversationEgressMeter;
     constructor(dialect: Dialect, agentId: string);

package/dist/index.js

@@ -5911,6 +5911,11 @@ var McpHttpError = class extends Error {
     this.status = status;
   }
 };
+var McpSessionExpiredError = class extends Error {
+  constructor() {
+    super("MCP session expired");
+  }
+};
 var StreamableHttpMcpRpcClient = class {
   endpoint;
   timeoutMs;
@@ -5962,6 +5967,9 @@ var StreamableHttpMcpRpcClient = class {
       if (response.status === 403) {
         throw new McpHttpError(403, "MCP server forbidden");
       }
+      if (response.status === 404 && this.sessionId) {
+        throw new McpSessionExpiredError();
+      }
       if (!response.ok) {
         throw new Error(`MCP HTTP request failed with status ${response.status}`);
       }
@@ -6036,20 +6044,32 @@ var StreamableHttpMcpRpcClient = class {
     throw new Error(`MCP response missing JSON-RPC payload for id ${id}`);
   }
   async request(method, params) {
-    await this.ensureInitialized();
-    const id = this.idCounter++;
-    const payload = {
-      jsonrpc: "2.0",
-      id,
-      method,
-      params: params ?? {}
-    };
-    const payloads = await this.postMessage(payload);
-    const result = this.extractResult(payloads, id);
-    if (result.error) {
-      throw new Error(result.error.message ?? `MCP error on ${method}`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        await this.ensureInitialized();
+        const id = this.idCounter++;
+        const payload = {
+          jsonrpc: "2.0",
+          id,
+          method,
+          params: params ?? {}
+        };
+        const payloads = await this.postMessage(payload);
+        const result = this.extractResult(payloads, id);
+        if (result.error) {
+          throw new Error(result.error.message ?? `MCP error on ${method}`);
+        }
+        return result.result;
+      } catch (error) {
+        if (error instanceof McpSessionExpiredError && attempt === 0) {
+          this.sessionId = void 0;
+          this.initialized = false;
+          continue;
+        }
+        throw error;
+      }
     }
-    return result.result;
+    throw new Error(`MCP request to ${method} failed after session retry`);
   }
   async ensureInitialized() {
     if (this.initialized) {
@@ -6105,6 +6125,8 @@ var StreamableHttpMcpRpcClient = class {
     }
   }
 };
+var TENANT_CLIENT_TTL_MS = 15 * 60 * 1e3;
+var tenantClientKey = (serverName, tenantId) => `${serverName}\0${tenantId}`;
 var LocalMcpBridge = class {
   remoteServers;
   rpcClients = /* @__PURE__ */ new Map();
@@ -6112,6 +6134,18 @@ var LocalMcpBridge = class {
   unavailableServers = /* @__PURE__ */ new Map();
   authFailedServers = /* @__PURE__ */ new Set();
   envResolver;
+  /**
+   * Per-tenant MCP client cache. For consumer/SaaS deployments where every
+   * call resolves a different bearer token, building a fresh
+   * `StreamableHttpMcpRpcClient` per call would force a fresh `initialize`
+   * round-trip every time. We keep one client per `(serverName, tenantId)`
+   * with TTL-based idle eviction; on token rotation we evict the entry
+   * lazily and rebuild.
+   */
+  tenantClients = /* @__PURE__ */ new Map();
+  /** Test/observability hook: bumped every time a new tenant client is constructed. */
+  tenantClientConstructions = 0;
+  tenantClientTtlMs;
   /**
    * Set a resolver for per-tenant env vars (e.g. MCP auth tokens).
    * Called by the harness after creating the secrets store.
@@ -6119,7 +6153,8 @@ var LocalMcpBridge = class {
   setEnvResolver(resolver) {
     this.envResolver = resolver;
   }
-  constructor(config) {
+  constructor(config, options) {
+    this.tenantClientTtlMs = options?.tenantClientTtlMs ?? TENANT_CLIENT_TTL_MS;
     this.remoteServers = (config?.mcp ?? []).filter(
       (entry) => typeof entry.url === "string"
     );
@@ -6290,6 +6325,35 @@ var LocalMcpBridge = class {
       await client.close();
     }
     this.rpcClients.clear();
+    for (const [, entry] of this.tenantClients) {
+      await entry.client.close();
+    }
+    this.tenantClients.clear();
+  }
+  getOrCreateTenantClient(serverName, tenantId, token, server) {
+    const key = tenantClientKey(serverName, tenantId);
+    const now2 = Date.now();
+    const existing = this.tenantClients.get(key);
+    if (existing) {
+      const idle = now2 - existing.lastUsed > this.tenantClientTtlMs;
+      const tokenChanged = existing.token !== token;
+      if (idle || tokenChanged) {
+        void existing.client.close();
+        this.tenantClients.delete(key);
+      } else {
+        existing.lastUsed = now2;
+        return existing.client;
+      }
+    }
+    const client = new StreamableHttpMcpRpcClient(
+      server.url,
+      server.timeoutMs ?? 1e4,
+      token,
+      server.headers
+    );
+    this.tenantClients.set(key, { client, token, lastUsed: now2 });
+    this.tenantClientConstructions += 1;
+    return client;
   }
   listServers() {
     return [...this.remoteServers];
@@ -6411,15 +6475,15 @@ var LocalMcpBridge = class {
         try {
           const tokenEnv = server?.auth?.tokenEnv;
           let callClient = client;
-          if (tokenEnv && this.envResolver && context?.tenantId) {
+          if (tokenEnv && this.envResolver && context?.tenantId && server) {
             const tenantToken = await this.envResolver(context.tenantId, tokenEnv);
             const defaultToken = process.env[tokenEnv];
             if (tenantToken && tenantToken !== defaultToken) {
-              callClient = new StreamableHttpMcpRpcClient(
-                server.url,
-                server.timeoutMs ?? 1e4,
+              callClient = this.getOrCreateTenantClient(
+                serverName,
+                context.tenantId,
                 tenantToken,
-                server.headers
+                server
               );
             }
           }
@@ -8640,6 +8704,7 @@ var AgentHarness = class _AgentHarness {
   reminderStore;
   secretsStore;
   loadedConfig;
+  injectedConfig;
   loadedSkills = [];
   skillFingerprint = "";
   lastSkillRefreshAt = 0;
@@ -8654,6 +8719,8 @@ var AgentHarness = class _AgentHarness {
   _browserMod;
   parsedAgent;
   agentFileFingerprint = "";
+  injectedAgentDefinition;
+  injectedStorageEngine = false;
   mcpBridge;
   subagentManager;
   archivedToolResultsByConversation = /* @__PURE__ */ new Map();
@@ -8821,6 +8888,17 @@ var AgentHarness = class _AgentHarness {
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.uploadStore = options.uploadStore;
+    this.injectedConfig = options.config;
+    if (options.agentDefinition !== void 0 && options.storageEngine === void 0) {
+      throw new Error(
+        "HarnessOptions.agentDefinition requires HarnessOptions.storageEngine \u2014 construct a StorageEngine with the desired agentId and pass both."
+      );
+    }
+    this.injectedAgentDefinition = options.agentDefinition;
+    if (options.storageEngine) {
+      this.storageEngine = options.storageEngine;
+      this.injectedStorageEngine = true;
+    }
     if (options.toolDefinitions?.length) {
       this.dispatcher.registerMany(options.toolDefinitions);
     }
@@ -9237,6 +9315,9 @@ var AgentHarness = class _AgentHarness {
     if (this.environment !== "development") {
       return false;
     }
+    if (this.injectedAgentDefinition !== void 0) {
+      return false;
+    }
     try {
       const agentFilePath = resolve11(this.workingDir, "AGENT.md");
       const rawContent = await readFile8(agentFilePath, "utf8");
@@ -9304,15 +9385,23 @@ var AgentHarness = class _AgentHarness {
     }
   }
   async initialize() {
-    const agentFilePath = resolve11(this.workingDir, "AGENT.md");
-    const agentRawContent = await readFile8(agentFilePath, "utf8");
-    this.parsedAgent = parseAgentMarkdown(agentRawContent);
-    this.agentFileFingerprint = agentRawContent;
-    const identity = await ensureAgentIdentity(this.workingDir);
-    if (!this.parsedAgent.frontmatter.id) {
-      this.parsedAgent.frontmatter.id = identity.id;
+    if (this.injectedAgentDefinition !== void 0) {
+      this.parsedAgent = typeof this.injectedAgentDefinition === "string" ? parseAgentMarkdown(this.injectedAgentDefinition) : this.injectedAgentDefinition;
+      this.agentFileFingerprint = "";
+      if (this.storageEngine) {
+        this.parsedAgent.frontmatter.id = this.storageEngine.agentId;
+      }
+    } else {
+      const agentFilePath = resolve11(this.workingDir, "AGENT.md");
+      const agentRawContent = await readFile8(agentFilePath, "utf8");
+      this.parsedAgent = parseAgentMarkdown(agentRawContent);
+      this.agentFileFingerprint = agentRawContent;
+      const identity = await ensureAgentIdentity(this.workingDir);
+      if (!this.parsedAgent.frontmatter.id) {
+        this.parsedAgent.frontmatter.id = identity.id;
+      }
     }
-    const config = await loadPonchoConfig(this.workingDir);
+    const config = this.injectedConfig ?? await loadPonchoConfig(this.workingDir);
     this.loadedConfig = config;
     this.registerConfiguredBuiltInTools(config);
     const provider = this.parsedAgent.frontmatter.model?.provider ?? "anthropic";
@@ -9328,15 +9417,21 @@ var AgentHarness = class _AgentHarness {
     this.skillFingerprint = this.buildSkillFingerprint(skillMetadata);
     this.registerSkillTools();
     const agentId = this.parsedAgent.frontmatter.id ?? this.parsedAgent.frontmatter.name;
-    const storageProvider = config?.storage?.provider ?? "sqlite";
-    const engine = createStorageEngine({
-      provider: storageProvider,
-      workingDir: this.workingDir,
-      agentId,
-      urlEnv: config?.storage?.urlEnv
-    });
-    await engine.initialize();
-    this.storageEngine = engine;
+    let engine;
+    if (this.injectedStorageEngine && this.storageEngine) {
+      engine = this.storageEngine;
+      await engine.initialize();
+    } else {
+      const storageProvider = config?.storage?.provider ?? "sqlite";
+      engine = createStorageEngine({
+        provider: storageProvider,
+        workingDir: this.workingDir,
+        agentId,
+        urlEnv: config?.storage?.urlEnv
+      });
+      await engine.initialize();
+      this.storageEngine = engine;
+    }
     const maxFileSize = config?.storage?.limits?.maxFileSize ?? 100 * 1024 * 1024;
     const maxTotalStorage = config?.storage?.limits?.maxTotalStorage ?? 1024 * 1024 * 1024;
     const bashWorkingDir = this.environment === "production" ? null : this.workingDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.40.1",
+  "version": "0.41.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/harness.ts

@@ -102,6 +102,27 @@ export interface HarnessOptions {
   toolDefinitions?: ToolDefinition[];
   modelProvider?: ModelProviderFactory;
   uploadStore?: UploadStore;
+  /**
+   * Inject the agent definition directly instead of reading AGENT.md from
+   * `workingDir`. Pass raw markdown (string) or a pre-parsed `ParsedAgent`.
+   * When provided, `storageEngine` is also required — the engine's
+   * `agentId` becomes the source of truth for partitioning, and the
+   * filesystem identity dance (`ensureAgentIdentity`) is skipped.
+   */
+  agentDefinition?: string | ParsedAgent;
+  /**
+   * Pre-constructed storage engine. When provided, the harness will not
+   * create one internally. The engine's `agentId` is used wherever the
+   * harness today reads `parsedAgent.frontmatter.id`.
+   */
+  storageEngine?: StorageEngine;
+  /**
+   * Inject a `PonchoConfig` object directly instead of importing
+   * `poncho.config.js` from `workingDir`. When provided, the disk-based
+   * loader is skipped. Downstream resolvers (`resolveMemoryConfig`,
+   * `resolveStateConfig`, etc.) run as today regardless of source.
+   */
+  config?: PonchoConfig;
 }
 
 export interface HarnessRunOutput {
@@ -805,6 +826,7 @@ export class AgentHarness {
   reminderStore?: ReminderStore;
   secretsStore?: SecretsStore;
   private loadedConfig?: PonchoConfig;
+  private readonly injectedConfig?: PonchoConfig;
   private loadedSkills: SkillMetadata[] = [];
   private skillFingerprint = "";
   private lastSkillRefreshAt = 0;
@@ -823,6 +845,8 @@ export class AgentHarness {
 
   private parsedAgent?: ParsedAgent;
   private agentFileFingerprint = "";
+  private injectedAgentDefinition?: string | ParsedAgent;
+  private injectedStorageEngine = false;
   private mcpBridge?: LocalMcpBridge;
   private subagentManager?: SubagentManager;
   private readonly archivedToolResultsByConversation = new Map<string, Record<string, ArchivedToolResult>>();
@@ -1011,6 +1035,19 @@ export class AgentHarness {
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.uploadStore = options.uploadStore;
+    this.injectedConfig = options.config;
+
+    if (options.agentDefinition !== undefined && options.storageEngine === undefined) {
+      throw new Error(
+        "HarnessOptions.agentDefinition requires HarnessOptions.storageEngine — " +
+        "construct a StorageEngine with the desired agentId and pass both.",
+      );
+    }
+    this.injectedAgentDefinition = options.agentDefinition;
+    if (options.storageEngine) {
+      this.storageEngine = options.storageEngine;
+      this.injectedStorageEngine = true;
+    }
 
     if (options.toolDefinitions?.length) {
       this.dispatcher.registerMany(options.toolDefinitions);
@@ -1508,6 +1545,11 @@ export class AgentHarness {
     if (this.environment !== "development") {
       return false;
     }
+    if (this.injectedAgentDefinition !== undefined) {
+      // Caller owns the agent definition — re-instantiate the harness to
+      // pick up changes rather than re-reading from disk.
+      return false;
+    }
     try {
       const agentFilePath = resolve(this.workingDir, "AGENT.md");
       const rawContent = await readFile(agentFilePath, "utf8");
@@ -1586,15 +1628,28 @@ export class AgentHarness {
   }
 
   async initialize(): Promise<void> {
-    const agentFilePath = resolve(this.workingDir, "AGENT.md");
-    const agentRawContent = await readFile(agentFilePath, "utf8");
-    this.parsedAgent = parseAgentMarkdown(agentRawContent);
-    this.agentFileFingerprint = agentRawContent;
-    const identity = await ensureAgentIdentity(this.workingDir);
-    if (!this.parsedAgent.frontmatter.id) {
-      this.parsedAgent.frontmatter.id = identity.id;
-    }
-    const config = await loadPonchoConfig(this.workingDir);
+    if (this.injectedAgentDefinition !== undefined) {
+      this.parsedAgent = typeof this.injectedAgentDefinition === "string"
+        ? parseAgentMarkdown(this.injectedAgentDefinition)
+        : this.injectedAgentDefinition;
+      this.agentFileFingerprint = "";
+      // The injected StorageEngine is the source of truth for agentId.
+      // Mirror it onto frontmatter.id so existing downstream readers
+      // (`frontmatter.id ?? frontmatter.name`) keep resolving correctly.
+      if (this.storageEngine) {
+        this.parsedAgent.frontmatter.id = this.storageEngine.agentId;
+      }
+    } else {
+      const agentFilePath = resolve(this.workingDir, "AGENT.md");
+      const agentRawContent = await readFile(agentFilePath, "utf8");
+      this.parsedAgent = parseAgentMarkdown(agentRawContent);
+      this.agentFileFingerprint = agentRawContent;
+      const identity = await ensureAgentIdentity(this.workingDir);
+      if (!this.parsedAgent.frontmatter.id) {
+        this.parsedAgent.frontmatter.id = identity.id;
+      }
+    }
+    const config = this.injectedConfig ?? await loadPonchoConfig(this.workingDir);
     this.loadedConfig = config;
     this.registerConfiguredBuiltInTools(config);
     const provider = this.parsedAgent.frontmatter.model?.provider ?? "anthropic";
@@ -1612,15 +1667,23 @@ export class AgentHarness {
     const agentId = this.parsedAgent.frontmatter.id ?? this.parsedAgent.frontmatter.name;
 
     // --- Unified Storage Engine ---
-    const storageProvider = (config?.storage?.provider ?? "sqlite") as StorageProvider;
-    const engine = createStorageEngine({
-      provider: storageProvider,
-      workingDir: this.workingDir,
-      agentId,
-      urlEnv: config?.storage?.urlEnv,
-    });
-    await engine.initialize();
-    this.storageEngine = engine;
+    let engine: StorageEngine;
+    if (this.injectedStorageEngine && this.storageEngine) {
+      // Caller-constructed engine; assume already initialized or will be
+      // initialized by them (initialize() is idempotent in current impls).
+      engine = this.storageEngine;
+      await engine.initialize();
+    } else {
+      const storageProvider = (config?.storage?.provider ?? "sqlite") as StorageProvider;
+      engine = createStorageEngine({
+        provider: storageProvider,
+        workingDir: this.workingDir,
+        agentId,
+        urlEnv: config?.storage?.urlEnv,
+      });
+      await engine.initialize();
+      this.storageEngine = engine;
+    }
 
     // --- Bash Environment Manager ---
     const maxFileSize = config?.storage?.limits?.maxFileSize ?? 100 * 1024 * 1024; // 100MB