@poncho-ai/harness 0.22.0 → 0.22.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.22.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.22.1 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,8 +8,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 257.83 KB
-ESM ⚡️ Build success in 146ms
+ESM dist/index.js 260.03 KB
+ESM ⚡️ Build success in 131ms
 DTS Build start
-DTS ⚡️ Build success in 7680ms
-DTS dist/index.d.ts 27.07 KB
+DTS ⚡️ Build success in 6723ms
+DTS dist/index.d.ts 27.15 KB

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @poncho-ai/harness
 
+## 0.22.1
+
+### Patch Changes
+
+- [`096953d`](https://github.com/cesr/poncho-ai/commit/096953d5a64a785950ea0a7f09e2183e481afd29) Thanks [@cesr](https://github.com/cesr)! - Improve time-to-first-token by lazy-loading the recall corpus
+
+  The recall corpus (past conversation summaries) is now fetched on-demand only when the LLM invokes the `conversation_recall` tool, instead of blocking every message with ~1.3s of upfront I/O. Also adds batch `mget` support to Upstash/Redis/DynamoDB conversation stores, parallelizes memory fetch with skill refresh, debounces skill refresh in dev mode, and caches message conversions across multi-step runs.
+
 ## 0.22.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -562,6 +562,7 @@ declare class AgentHarness {
     private loadedConfig?;
     private loadedSkills;
     private skillFingerprint;
+    private lastSkillRefreshAt;
     private readonly activeSkillNames;
     private readonly registeredMcpToolNames;
     private latitudeTelemetry?;
@@ -601,6 +602,7 @@ declare class AgentHarness {
     private refreshMcpTools;
     private buildSkillFingerprint;
     private registerSkillTools;
+    private static readonly SKILL_REFRESH_DEBOUNCE_MS;
     private refreshSkillsIfChanged;
     initialize(): Promise<void>;
     private buildBrowserStoragePersistence;

package/dist/index.js

@@ -2771,10 +2771,9 @@ var createMemoryTools = (store, options) => {
           Math.min(5, typeof input.limit === "number" ? input.limit : 3)
         );
         const excludeConversationId = typeof input.excludeConversationId === "string" ? input.excludeConversationId : "";
-        const corpus = asRecallCorpus(context.parameters.__conversationRecallCorpus).slice(
-          0,
-          maxRecallConversations
-        );
+        const rawCorpus = context.parameters.__conversationRecallCorpus;
+        const resolvedCorpus = typeof rawCorpus === "function" ? await rawCorpus() : rawCorpus;
+        const corpus = asRecallCorpus(resolvedCorpus).slice(0, maxRecallConversations);
         const results = corpus.filter(
           (item) => excludeConversationId ? item.conversationId !== excludeConversationId : true
         ).map((item) => ({
@@ -4599,7 +4598,7 @@ function extractMediaFromToolOutput(output) {
   const strippedOutput = walk(output);
   return { mediaItems, strippedOutput };
 }
-var AgentHarness = class {
+var AgentHarness = class _AgentHarness {
   workingDir;
   environment;
   modelProvider;
@@ -4611,6 +4610,7 @@ var AgentHarness = class {
   loadedConfig;
   loadedSkills = [];
   skillFingerprint = "";
+  lastSkillRefreshAt = 0;
   activeSkillNames = /* @__PURE__ */ new Set();
   registeredMcpToolNames = /* @__PURE__ */ new Set();
   latitudeTelemetry;
@@ -4899,10 +4899,16 @@ var AgentHarness = class {
       })
     );
   }
+  static SKILL_REFRESH_DEBOUNCE_MS = 3e3;
   async refreshSkillsIfChanged() {
     if (this.environment !== "development") {
       return;
     }
+    const elapsed = Date.now() - this.lastSkillRefreshAt;
+    if (this.lastSkillRefreshAt > 0 && elapsed < _AgentHarness.SKILL_REFRESH_DEBOUNCE_MS) {
+      return;
+    }
+    this.lastSkillRefreshAt = Date.now();
     try {
       const latestSkills = await loadSkillMetadata(
         this.workingDir,
@@ -5228,6 +5234,7 @@ var AgentHarness = class {
     if (!this.parsedAgent) {
       await this.initialize();
     }
+    const memoryPromise = this.memoryStore ? this.memoryStore.getMainMemory() : void 0;
     await this.refreshSkillsIfChanged();
     this._currentRunConversationId = input.conversationId;
     const ownerParam = input.parameters?.__ownerId;
@@ -5280,7 +5287,7 @@ Each conversation gets its own browser tab sharing a single browser instance. Ca
     const promptWithSkills = this.skillContextWindow ? `${systemPrompt}${developmentContext}
 
 ${this.skillContextWindow}${browserContext}` : `${systemPrompt}${developmentContext}${browserContext}`;
-    const mainMemory = this.memoryStore ? await this.memoryStore.getMainMemory() : void 0;
+    const mainMemory = await memoryPromise;
     const boundedMainMemory = mainMemory && mainMemory.content.length > 4e3 ? `${mainMemory.content.slice(0, 4e3)}
 ...[truncated]` : mainMemory?.content;
     const memoryContext = boundedMainMemory && boundedMainMemory.trim().length > 0 ? `
@@ -5375,6 +5382,8 @@ ${boundedMainMemory.trim()}` : "";
     let totalOutputTokens = 0;
     let totalCachedTokens = 0;
     let transientStepRetryCount = 0;
+    let cachedCoreMessages = [];
+    let convertedUpTo = 0;
     for (let step = 1; step <= maxSteps; step += 1) {
       try {
         yield* drainBrowserEvents();
@@ -5651,7 +5660,15 @@ ${textContent}` };
             }
           }
         }
-        const coreMessages = (await Promise.all(messages.map(convertMessage))).flat();
+        if (convertedUpTo > messages.length) {
+          cachedCoreMessages = [];
+          convertedUpTo = 0;
+        }
+        const newMessages = messages.slice(convertedUpTo);
+        const newCoreMessages = newMessages.length > 0 ? (await Promise.all(newMessages.map(convertMessage))).flat() : [];
+        cachedCoreMessages = [...cachedCoreMessages, ...newCoreMessages];
+        convertedUpTo = messages.length;
+        const coreMessages = cachedCoreMessages;
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
         const maxTokens = agent.frontmatter.model?.maxTokens;
         const cachedMessages = addPromptCacheBreakpoints(coreMessages, modelInstance);
@@ -6750,12 +6767,12 @@ var KeyValueConversationStoreBase = class {
       return [];
     }
     const ids = await this.getOwnerConversationIds(ownerId);
+    if (ids.length === 0) return [];
+    const convKeys = await Promise.all(ids.map((id) => this.conversationKey(id)));
+    const rawValues = await kv.mget(convKeys);
     const conversations = [];
-    for (const id of ids) {
-      const raw = await kv.get(await this.conversationKey(id));
-      if (!raw) {
-        continue;
-      }
+    for (const raw of rawValues) {
+      if (!raw) continue;
       try {
         conversations.push(JSON.parse(raw));
       } catch {
@@ -6772,20 +6789,27 @@ var KeyValueConversationStoreBase = class {
       return [];
     }
     const ids = await this.getOwnerConversationIds(ownerId);
+    if (ids.length === 0) return [];
+    const metaKeys = await Promise.all(ids.map((id) => this.conversationMetaKey(id)));
+    const rawValues = await kv.mget(metaKeys);
     const summaries = [];
-    for (const id of ids) {
-      const meta = await this.getConversationMeta(id);
-      if (meta && meta.ownerId === ownerId) {
-        summaries.push({
-          conversationId: meta.conversationId,
-          title: meta.title,
-          updatedAt: meta.updatedAt,
-          createdAt: meta.createdAt,
-          ownerId: meta.ownerId,
-          parentConversationId: meta.parentConversationId,
-          messageCount: meta.messageCount,
-          hasPendingApprovals: meta.hasPendingApprovals
-        });
+    for (const raw of rawValues) {
+      if (!raw) continue;
+      try {
+        const meta = JSON.parse(raw);
+        if (meta.ownerId === ownerId) {
+          summaries.push({
+            conversationId: meta.conversationId,
+            title: meta.title,
+            updatedAt: meta.updatedAt,
+            createdAt: meta.createdAt,
+            ownerId: meta.ownerId,
+            parentConversationId: meta.parentConversationId,
+            messageCount: meta.messageCount,
+            hasPendingApprovals: meta.hasPendingApprovals
+          });
+        }
+      } catch {
       }
     }
     return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
@@ -6923,6 +6947,19 @@ var UpstashConversationStore = class extends KeyValueConversationStoreBase {
         const payload = await response.json();
         return payload.result ?? void 0;
       },
+      mget: async (keys) => {
+        if (keys.length === 0) return [];
+        const path = keys.map((k) => encodeURIComponent(k)).join("/");
+        const response = await fetch(`${this.baseUrl}/mget/${path}`, {
+          method: "POST",
+          headers: this.headers()
+        });
+        if (!response.ok) {
+          return keys.map(() => void 0);
+        }
+        const payload = await response.json();
+        return (payload.result ?? []).map((v) => v ?? void 0);
+      },
       set: async (key, value, ttl) => {
         const endpoint = typeof ttl === "number" ? `${this.baseUrl}/setex/${encodeURIComponent(key)}/${Math.max(
           1,
@@ -7015,6 +7052,11 @@ var RedisLikeConversationStore = class extends KeyValueConversationStoreBase {
         const value = await client.get(key);
         return value ?? void 0;
       },
+      mget: async (keys) => {
+        if (keys.length === 0) return [];
+        const values = await client.mGet(keys);
+        return values.map((v) => v ?? void 0);
+      },
       set: async (key, value, ttl) => {
         if (typeof ttl === "number") {
           await client.set(key, value, { EX: Math.max(1, ttl) });
@@ -7149,6 +7191,18 @@ var DynamoDbConversationStore = class extends KeyValueConversationStoreBase {
           })
         );
       },
+      mget: async (keys) => {
+        if (keys.length === 0) return [];
+        return Promise.all(keys.map(async (key) => {
+          const result = await client.send(
+            new client.GetItemCommand({
+              TableName: this.table,
+              Key: { runId: { S: key } }
+            })
+          );
+          return result.Item?.value?.S;
+        }));
+      },
       del: async (key) => {
         await client.send(
           new client.DeleteItemCommand({

package/package.json

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

package/src/harness.ts

@@ -545,6 +545,7 @@ export class AgentHarness {
   private loadedConfig?: PonchoConfig;
   private loadedSkills: SkillMetadata[] = [];
   private skillFingerprint = "";
+  private lastSkillRefreshAt = 0;
   private readonly activeSkillNames = new Set<string>();
   private readonly registeredMcpToolNames = new Set<string>();
   private latitudeTelemetry?: LatitudeTelemetry;
@@ -879,10 +880,17 @@ export class AgentHarness {
     );
   }
 
+  private static readonly SKILL_REFRESH_DEBOUNCE_MS = 3000;
+
   private async refreshSkillsIfChanged(): Promise<void> {
     if (this.environment !== "development") {
       return;
     }
+    const elapsed = Date.now() - this.lastSkillRefreshAt;
+    if (this.lastSkillRefreshAt > 0 && elapsed < AgentHarness.SKILL_REFRESH_DEBOUNCE_MS) {
+      return;
+    }
+    this.lastSkillRefreshAt = Date.now();
     try {
       const latestSkills = await loadSkillMetadata(
         this.workingDir,
@@ -1269,6 +1277,10 @@ export class AgentHarness {
     if (!this.parsedAgent) {
       await this.initialize();
     }
+    // Start memory fetch early so it overlaps with skill refresh I/O
+    const memoryPromise = this.memoryStore
+      ? this.memoryStore.getMainMemory()
+      : undefined;
     await this.refreshSkillsIfChanged();
 
     // Track which conversation/owner this run belongs to so browser & subagent tools resolve correctly
@@ -1328,9 +1340,7 @@ Each conversation gets its own browser tab sharing a single browser instance. Ca
     const promptWithSkills = this.skillContextWindow
       ? `${systemPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}`
       : `${systemPrompt}${developmentContext}${browserContext}`;
-    const mainMemory = this.memoryStore
-      ? await this.memoryStore.getMainMemory()
-      : undefined;
+    const mainMemory = await memoryPromise;
     const boundedMainMemory =
       mainMemory && mainMemory.content.length > 4000
         ? `${mainMemory.content.slice(0, 4000)}\n...[truncated]`
@@ -1445,6 +1455,8 @@ ${boundedMainMemory.trim()}`
     let totalOutputTokens = 0;
     let totalCachedTokens = 0;
     let transientStepRetryCount = 0;
+    let cachedCoreMessages: ModelMessage[] = [];
+    let convertedUpTo = 0;
 
     for (let step = 1; step <= maxSteps; step += 1) {
       try {
@@ -1784,9 +1796,19 @@ ${boundedMainMemory.trim()}`
           }
         }
 
-        const coreMessages: ModelMessage[] = (
-          await Promise.all(messages.map(convertMessage))
-        ).flat();
+        // Only convert messages added since the last step
+        if (convertedUpTo > messages.length) {
+          // Compaction replaced the array — invalidate cache
+          cachedCoreMessages = [];
+          convertedUpTo = 0;
+        }
+        const newMessages = messages.slice(convertedUpTo);
+        const newCoreMessages: ModelMessage[] = newMessages.length > 0
+          ? (await Promise.all(newMessages.map(convertMessage))).flat()
+          : [];
+        cachedCoreMessages = [...cachedCoreMessages, ...newCoreMessages];
+        convertedUpTo = messages.length;
+        const coreMessages = cachedCoreMessages;
 
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
         const maxTokens = agent.frontmatter.model?.maxTokens;
@@ -1794,6 +1816,7 @@ ${boundedMainMemory.trim()}`
 
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
 
+
         const result = await streamText({
           model: modelInstance,
           system: integrityPrompt,

package/src/memory.ts

@@ -658,10 +658,10 @@ export const createMemoryTools = (
           typeof input.excludeConversationId === "string"
             ? input.excludeConversationId
             : "";
-        const corpus = asRecallCorpus(context.parameters.__conversationRecallCorpus).slice(
-          0,
-          maxRecallConversations,
-        );
+        const rawCorpus = context.parameters.__conversationRecallCorpus;
+        const resolvedCorpus =
+          typeof rawCorpus === "function" ? await (rawCorpus as () => Promise<unknown>)() : rawCorpus;
+        const corpus = asRecallCorpus(resolvedCorpus).slice(0, maxRecallConversations);
         const results = corpus
           .filter((item) =>
             excludeConversationId ? item.conversationId !== excludeConversationId : true,

package/src/state.ts

@@ -646,6 +646,7 @@ class FileStateStore implements StateStore {
 
 interface RawKeyValueClient {
   get(key: string): Promise<string | undefined>;
+  mget(keys: string[]): Promise<(string | undefined)[]>;
   set(key: string, value: string, ttl?: number): Promise<void>;
   del(key: string): Promise<void>;
 }
@@ -760,21 +761,18 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
       return await this.memoryFallback.list(ownerId);
     }
     if (!ownerId) {
-      // KV stores index per-owner; cross-owner listing not supported
       return [];
     }
     const ids = await this.getOwnerConversationIds(ownerId);
+    if (ids.length === 0) return [];
+    const convKeys = await Promise.all(ids.map((id) => this.conversationKey(id)));
+    const rawValues = await kv.mget(convKeys);
     const conversations: Conversation[] = [];
-    for (const id of ids) {
-      const raw = await kv.get(await this.conversationKey(id));
-      if (!raw) {
-        continue;
-      }
+    for (const raw of rawValues) {
+      if (!raw) continue;
       try {
         conversations.push(JSON.parse(raw) as Conversation);
-      } catch {
-        // Skip invalid records.
-      }
+      } catch { /* skip invalid records */ }
     }
     return conversations.sort((a, b) => b.updatedAt - a.updatedAt);
   }
@@ -788,21 +786,27 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
       return [];
     }
     const ids = await this.getOwnerConversationIds(ownerId);
+    if (ids.length === 0) return [];
+    const metaKeys = await Promise.all(ids.map((id) => this.conversationMetaKey(id)));
+    const rawValues = await kv.mget(metaKeys);
     const summaries: ConversationSummary[] = [];
-    for (const id of ids) {
-      const meta = await this.getConversationMeta(id);
-      if (meta && meta.ownerId === ownerId) {
-        summaries.push({
-          conversationId: meta.conversationId,
-          title: meta.title,
-          updatedAt: meta.updatedAt,
-          createdAt: meta.createdAt,
-          ownerId: meta.ownerId,
-          parentConversationId: meta.parentConversationId,
-          messageCount: meta.messageCount,
-          hasPendingApprovals: meta.hasPendingApprovals,
-        });
-      }
+    for (const raw of rawValues) {
+      if (!raw) continue;
+      try {
+        const meta = JSON.parse(raw) as ConversationMeta;
+        if (meta.ownerId === ownerId) {
+          summaries.push({
+            conversationId: meta.conversationId,
+            title: meta.title,
+            updatedAt: meta.updatedAt,
+            createdAt: meta.createdAt,
+            ownerId: meta.ownerId,
+            parentConversationId: meta.parentConversationId,
+            messageCount: meta.messageCount,
+            hasPendingApprovals: meta.hasPendingApprovals,
+          });
+        }
+      } catch { /* skip invalid records */ }
     }
     return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
   }
@@ -948,6 +952,19 @@ class UpstashConversationStore extends KeyValueConversationStoreBase {
         const payload = (await response.json()) as { result?: string | null };
         return payload.result ?? undefined;
       },
+      mget: async (keys: string[]) => {
+        if (keys.length === 0) return [];
+        const path = keys.map((k) => encodeURIComponent(k)).join("/");
+        const response = await fetch(`${this.baseUrl}/mget/${path}`, {
+          method: "POST",
+          headers: this.headers(),
+        });
+        if (!response.ok) {
+          return keys.map(() => undefined);
+        }
+        const payload = (await response.json()) as { result?: (string | null)[] };
+        return (payload.result ?? []).map((v) => v ?? undefined);
+      },
       set: async (key: string, value: string, ttl?: number) => {
         const endpoint =
           typeof ttl === "number"
@@ -1042,6 +1059,7 @@ class RedisLikeConversationStore extends KeyValueConversationStoreBase {
   private readonly clientPromise: Promise<
     | {
         get: (key: string) => Promise<string | null>;
+        mGet: (keys: readonly string[]) => Promise<(string | null)[]>;
         set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
         del: (key: string) => Promise<unknown>;
       }
@@ -1056,6 +1074,7 @@ class RedisLikeConversationStore extends KeyValueConversationStoreBase {
           createClient: (options: { url: string }) => {
             connect: () => Promise<unknown>;
             get: (key: string) => Promise<string | null>;
+            mGet: (keys: readonly string[]) => Promise<(string | null)[]>;
             set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
             del: (key: string) => Promise<unknown>;
           };
@@ -1079,6 +1098,11 @@ class RedisLikeConversationStore extends KeyValueConversationStoreBase {
         const value = await client.get(key);
         return value ?? undefined;
       },
+      mget: async (keys: string[]) => {
+        if (keys.length === 0) return [];
+        const values = await client.mGet(keys);
+        return values.map((v: string | null) => v ?? undefined);
+      },
       set: async (key: string, value: string, ttl?: number) => {
         if (typeof ttl === "number") {
           await client.set(key, value, { EX: Math.max(1, ttl) });
@@ -1261,6 +1285,18 @@ class DynamoDbConversationStore extends KeyValueConversationStoreBase {
           }),
         );
       },
+      mget: async (keys: string[]) => {
+        if (keys.length === 0) return [];
+        return Promise.all(keys.map(async (key) => {
+          const result = (await client.send(
+            new client.GetItemCommand({
+              TableName: this.table,
+              Key: { runId: { S: key } },
+            }),
+          )) as { Item?: { value?: { S?: string } } };
+          return result.Item?.value?.S;
+        }));
+      },
       del: async (key: string) => {
         await client.send(
           new client.DeleteItemCommand({