@poncho-ai/harness 0.40.0 → 0.41.0

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

package/src/mcp.ts

@@ -46,6 +46,12 @@ class McpHttpError extends Error {
   }
 }
 
+class McpSessionExpiredError extends Error {
+  constructor() {
+    super("MCP session expired");
+  }
+}
+
 class StreamableHttpMcpRpcClient implements McpRpcClient {
   private readonly endpoint: string;
   private readonly timeoutMs: number;
@@ -106,6 +112,9 @@ class StreamableHttpMcpRpcClient implements McpRpcClient {
       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}`);
       }
@@ -192,20 +201,32 @@ class StreamableHttpMcpRpcClient implements McpRpcClient {
   }
 
   private async request(method: string, params?: Record<string, unknown>): Promise<unknown> {
-    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 = undefined;
+          this.initialized = false;
+          continue;
+        }
+        throw error;
+      }
     }
-    return result.result;
+    throw new Error(`MCP request to ${method} failed after session retry`);
   }
 
   private async ensureInitialized(): Promise<void> {
@@ -270,6 +291,16 @@ class StreamableHttpMcpRpcClient implements McpRpcClient {
   }
 }
 
+interface CachedTenantClient {
+  client: StreamableHttpMcpRpcClient;
+  token: string;
+  lastUsed: number;
+}
+
+const TENANT_CLIENT_TTL_MS = 15 * 60 * 1000;
+const tenantClientKey = (serverName: string, tenantId: string): string =>
+  `${serverName}\0${tenantId}`;
+
 export class LocalMcpBridge {
   private readonly remoteServers: RemoteMcpServerConfig[];
   private readonly rpcClients = new Map<string, McpRpcClient>();
@@ -277,6 +308,18 @@ export class LocalMcpBridge {
   private readonly unavailableServers = new Map<string, string>();
   private readonly authFailedServers = new Set<string>();
   private envResolver?: (tenantId: string | undefined, envName: string) => Promise<string | undefined>;
+  /**
+   * 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 = new Map<string, CachedTenantClient>();
+  /** Test/observability hook: bumped every time a new tenant client is constructed. */
+  tenantClientConstructions = 0;
+  private readonly tenantClientTtlMs: number;
 
   /**
    * Set a resolver for per-tenant env vars (e.g. MCP auth tokens).
@@ -286,7 +329,8 @@ export class LocalMcpBridge {
     this.envResolver = resolver;
   }
 
-  constructor(config: McpConfig | undefined) {
+  constructor(config: McpConfig | undefined, options?: { tenantClientTtlMs?: number }) {
+    this.tenantClientTtlMs = options?.tenantClientTtlMs ?? TENANT_CLIENT_TTL_MS;
     this.remoteServers = (config?.mcp ?? []).filter((entry): entry is RemoteMcpServerConfig =>
       typeof entry.url === "string",
     );
@@ -477,6 +521,43 @@ export class LocalMcpBridge {
       await client.close();
     }
     this.rpcClients.clear();
+    for (const [, entry] of this.tenantClients) {
+      await entry.client.close();
+    }
+    this.tenantClients.clear();
+  }
+
+  private getOrCreateTenantClient(
+    serverName: string,
+    tenantId: string,
+    token: string,
+    server: RemoteMcpServerConfig,
+  ): StreamableHttpMcpRpcClient {
+    const key = tenantClientKey(serverName, tenantId);
+    const now = Date.now();
+    // Lazily evict idle entries on access — no background timer needed.
+    const existing = this.tenantClients.get(key);
+    if (existing) {
+      const idle = now - existing.lastUsed > this.tenantClientTtlMs;
+      const tokenChanged = existing.token !== token;
+      if (idle || tokenChanged) {
+        // Best-effort close; the new client supersedes it.
+        void existing.client.close();
+        this.tenantClients.delete(key);
+      } else {
+        existing.lastUsed = now;
+        return existing.client;
+      }
+    }
+    const client = new StreamableHttpMcpRpcClient(
+      server.url,
+      server.timeoutMs ?? 10_000,
+      token,
+      server.headers,
+    );
+    this.tenantClients.set(key, { client, token, lastUsed: now });
+    this.tenantClientConstructions += 1;
+    return client;
   }
 
   listServers(): RemoteMcpServerConfig[] {
@@ -617,20 +698,18 @@ export class LocalMcpBridge {
       handler: async (input, context) => {
         try {
           // Per-tenant token resolution: if we have a resolver and the server uses tokenEnv,
-          // create a per-request client with the tenant-specific token
+          // resolve the tenant token and reuse a cached per-tenant client when present.
           const tokenEnv = server?.auth?.tokenEnv;
-          let callClient = client;
-          if (tokenEnv && this.envResolver && context?.tenantId) {
+          let callClient: McpRpcClient = client;
+          if (tokenEnv && this.envResolver && context?.tenantId && server) {
             const tenantToken = await this.envResolver(context.tenantId, tokenEnv);
             const defaultToken = process.env[tokenEnv];
-            // Only create a per-request client when the tenant has a different token.
-            // Using the original client preserves the established MCP session.
             if (tenantToken && tenantToken !== defaultToken) {
-              callClient = new StreamableHttpMcpRpcClient(
-                server.url,
-                server.timeoutMs ?? 10_000,
+              callClient = this.getOrCreateTenantClient(
+                serverName,
+                context.tenantId,
                 tenantToken,
-                server.headers,
+                server,
               );
             }
           }

package/src/storage/engine.ts

@@ -33,6 +33,8 @@ export interface VfsDirEntry {
 // ---------------------------------------------------------------------------
 
 export 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. */

package/src/storage/memory-engine.ts

@@ -55,7 +55,7 @@ const vfsKey = (tenantId: string, path: string) => `${tenantId}\0${path}`;
 // ---------------------------------------------------------------------------
 
 export class InMemoryEngine implements StorageEngine {
-  private readonly agentId: string;
+  readonly agentId: string;
 
   // Conversation data
   private convs = new Map<string, Conversation>();

package/src/storage/sql-dialect.ts

@@ -191,7 +191,7 @@ const colBytes = (v: unknown): number => {
 
 export abstract class SqlStorageEngine implements StorageEngine {
   protected readonly dialect: Dialect;
-  protected readonly agentId: string;
+  readonly agentId: string;
   protected abstract readonly executor: QueryExecutor;
   protected readonly egressMeter = new ConversationEgressMeter();
 

package/test/agent-parser.test.ts

@@ -166,6 +166,24 @@ cron:
       expect(parsed.frontmatter.cron!["job"]!.timezone).toBe("Europe/London");
     });
 
+    it.each(["UTC", "GMT", "Etc/UTC"])(
+      "accepts %s as a timezone",
+      (tz) => {
+        const parsed = parseAgentMarkdown(`---
+name: test-agent
+cron:
+  job:
+    schedule: "0 9 * * *"
+    timezone: "${tz}"
+    task: "Do something"
+---
+
+# Agent
+`);
+        expect(parsed.frontmatter.cron!["job"]!.timezone).toBe(tz);
+      },
+    );
+
     it("parses maxRuns when present", () => {
       const parsed = parseAgentMarkdown(`---
 name: test-agent

package/test/harness-config-injection.test.ts

@@ -0,0 +1,63 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { AgentHarness } from "../src/harness.js";
+import type { PonchoConfig } from "../src/config.js";
+
+const AGENT_MD = `---
+name: config-inject-agent
+model:
+  provider: anthropic
+  name: claude-opus-4-5
+---
+
+# Config injection test
+`;
+
+describe("HarnessOptions.config injection (PR 2)", () => {
+  it("uses an injected PonchoConfig instead of reading poncho.config.js from disk", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-cfg-injected-"));
+    try {
+      await writeFile(join(dir, "AGENT.md"), AGENT_MD, "utf8");
+      // Deliberately do NOT write a poncho.config.js — the injected
+      // config should be used end-to-end.
+      const config: PonchoConfig = {
+        tools: { web_search: false },
+        storage: { provider: "memory" },
+      };
+
+      const harness = new AgentHarness({ workingDir: dir, config });
+      await harness.initialize();
+
+      const names = harness.listTools().map((t) => t.name);
+      // web_search was disabled in the injected config; bash is a default
+      // built-in that should still be registered.
+      expect(names).not.toContain("web_search");
+      expect(names).toContain("bash");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("disk-loaded behaviour is unchanged when no config option is provided", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-cfg-disk-"));
+    try {
+      await writeFile(join(dir, "AGENT.md"), AGENT_MD, "utf8");
+      // Write a poncho.config.js that disables a tool — proves loadPonchoConfig
+      // ran (otherwise web_search would be present).
+      await writeFile(
+        join(dir, "poncho.config.js"),
+        "export default { tools: { web_search: false }, storage: { provider: 'memory' } };\n",
+        "utf8",
+      );
+      const harness = new AgentHarness({ workingDir: dir });
+      await harness.initialize();
+      const names = harness.listTools().map((t) => t.name);
+      expect(names).not.toContain("web_search");
+      expect(names).toContain("bash");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/test/harness-injection.test.ts

@@ -0,0 +1,93 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { AgentHarness } from "../src/harness.js";
+import { InMemoryEngine } from "../src/storage/memory-engine.js";
+
+const AGENT_MD = `---
+name: injected-agent
+model:
+  provider: anthropic
+  name: claude-opus-4-5
+---
+
+# Injected agent
+
+You are a test agent.
+`;
+
+describe("HarnessOptions injection (PR 1)", () => {
+  it("initializes without an AGENT.md on disk when agentDefinition + storageEngine are provided", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-injection-"));
+    try {
+      const engine = new InMemoryEngine("user-123");
+      const harness = new AgentHarness({
+        workingDir: dir,
+        agentDefinition: AGENT_MD,
+        storageEngine: engine,
+      });
+      await expect(harness.initialize()).resolves.toBeUndefined();
+      // No AGENT.md was written into `dir` — confirm initialize ran from
+      // injected content alone.
+      expect(harness.frontmatter?.name).toBe("injected-agent");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("mirrors storageEngine.agentId onto frontmatter.id on the injected path", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-injection-id-"));
+    try {
+      const engine = new InMemoryEngine("user-456");
+      const harness = new AgentHarness({
+        workingDir: dir,
+        agentDefinition: AGENT_MD,
+        storageEngine: engine,
+      });
+      await harness.initialize();
+      expect(harness.frontmatter?.id).toBe("user-456");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("accepts a pre-parsed ParsedAgent as agentDefinition", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-injection-parsed-"));
+    try {
+      const engine = new InMemoryEngine("user-789");
+      const parsed = {
+        frontmatter: {
+          name: "preparsed-agent",
+          model: { provider: "anthropic" as const, name: "claude-opus-4-5" },
+        },
+        body: "# Pre-parsed agent\n",
+      };
+      const harness = new AgentHarness({
+        workingDir: dir,
+        agentDefinition: parsed,
+        storageEngine: engine,
+      });
+      await harness.initialize();
+      expect(harness.frontmatter?.name).toBe("preparsed-agent");
+      expect(harness.frontmatter?.id).toBe("user-789");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when agentDefinition is provided without storageEngine", () => {
+    expect(
+      () =>
+        new AgentHarness({
+          agentDefinition: AGENT_MD,
+        }),
+    ).toThrow(/agentDefinition requires HarnessOptions\.storageEngine/);
+  });
+
+  it("falls back to disk path when neither agentDefinition nor storageEngine is provided (existing behaviour unchanged)", async () => {
+    // This is implicitly covered by every other test in harness.test.ts —
+    // we simply assert that the constructor accepts no injection options.
+    expect(() => new AgentHarness({ workingDir: tmpdir() })).not.toThrow();
+  });
+});