@poncho-ai/harness 0.25.0 → 0.27.0

package/src/memory.ts

@@ -8,6 +8,7 @@ import {
   slugifyStorageComponent,
   STORAGE_SCHEMA_VERSION,
 } from "./agent-identity.js";
+import { createRawKVStore, type RawKVStore } from "./kv-store.js";
 
 export interface MainMemory {
   content: string;
@@ -168,25 +169,23 @@ class FileMainMemoryStore implements MemoryStore {
   }
 }
 
-abstract class KeyValueMainMemoryStoreBase implements MemoryStore {
-  protected readonly ttl?: number;
-  protected readonly memoryFallback: InMemoryMemoryStore;
+class KVBackedMemoryStore implements MemoryStore {
+  private readonly kv: RawKVStore;
+  private readonly storageKey: string;
+  private readonly ttl?: number;
+  private readonly memoryFallback: InMemoryMemoryStore;
 
-  constructor(ttl?: number) {
+  constructor(kv: RawKVStore, storageKey: string, ttl?: number) {
+    this.kv = kv;
+    this.storageKey = storageKey;
     this.ttl = ttl;
     this.memoryFallback = new InMemoryMemoryStore(ttl);
   }
 
-  protected abstract getRaw(key: string): Promise<string | undefined>;
-  protected abstract setRaw(key: string, value: string): Promise<void>;
-  protected abstract setRawWithTtl(key: string, value: string, ttl: number): Promise<void>;
-
-  protected async readPayload(key: string): Promise<MainMemoryPayload> {
+  private async readPayload(): Promise<MainMemoryPayload> {
     try {
-      const raw = await this.getRaw(key);
-      if (!raw) {
-        return { main: { ...DEFAULT_MAIN_MEMORY } };
-      }
+      const raw = await this.kv.get(this.storageKey);
+      if (!raw) return { main: { ...DEFAULT_MAIN_MEMORY } };
       const parsed = JSON.parse(raw) as MainMemoryPayload;
       const content = typeof parsed.main?.content === "string" ? parsed.main.content : "";
       const updatedAt = typeof parsed.main?.updatedAt === "number" ? parsed.main.updatedAt : 0;
@@ -197,259 +196,30 @@ abstract class KeyValueMainMemoryStoreBase implements MemoryStore {
     }
   }
 
-  protected async writePayload(key: string, payload: MainMemoryPayload): Promise<void> {
+  private async writePayload(payload: MainMemoryPayload): Promise<void> {
     try {
       const serialized = JSON.stringify(payload);
       if (typeof this.ttl === "number") {
-        await this.setRawWithTtl(key, serialized, Math.max(1, this.ttl));
+        await this.kv.setWithTtl(this.storageKey, serialized, Math.max(1, this.ttl));
       } else {
-        await this.setRaw(key, serialized);
+        await this.kv.set(this.storageKey, serialized);
       }
     } catch {
-      await this.memoryFallback.updateMainMemory({
-        content: payload.main.content,
-      });
+      await this.memoryFallback.updateMainMemory({ content: payload.main.content });
     }
   }
 
   async getMainMemory(): Promise<MainMemory> {
-    const payload = await this.readPayload(this.key());
+    const payload = await this.readPayload();
     return payload.main;
   }
 
   async updateMainMemory(input: { content: string }): Promise<MainMemory> {
-    const key = this.key();
-    const payload = await this.readPayload(key);
-    payload.main = {
-      content: input.content.trim(),
-      updatedAt: Date.now(),
-    };
-    await this.writePayload(key, payload);
+    const payload = await this.readPayload();
+    payload.main = { content: input.content.trim(), updatedAt: Date.now() };
+    await this.writePayload(payload);
     return payload.main;
   }
-
-  protected abstract key(): string;
-}
-
-class UpstashMemoryStore extends KeyValueMainMemoryStoreBase {
-  private readonly baseUrl: string;
-  private readonly token: string;
-  private readonly storageKey: string;
-
-  constructor(options: {
-    baseUrl: string;
-    token: string;
-    storageKey: string;
-    ttl?: number;
-  }) {
-    super(options.ttl);
-    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
-    this.token = options.token;
-    this.storageKey = options.storageKey;
-  }
-
-  protected key(): string {
-    return this.storageKey;
-  }
-
-  private headers(): HeadersInit {
-    return {
-      Authorization: `Bearer ${this.token}`,
-      "Content-Type": "application/json",
-    };
-  }
-
-  protected async getRaw(key: string): Promise<string | undefined> {
-    const response = await fetch(`${this.baseUrl}/get/${encodeURIComponent(key)}`, {
-      method: "POST",
-      headers: this.headers(),
-    });
-    if (!response.ok) {
-      return undefined;
-    }
-    const payload = (await response.json()) as { result?: string | null };
-    return payload.result ?? undefined;
-  }
-
-  protected async setRaw(key: string, value: string): Promise<void> {
-    await fetch(
-      `${this.baseUrl}/set/${encodeURIComponent(key)}/${encodeURIComponent(value)}`,
-      { method: "POST", headers: this.headers() },
-    );
-  }
-
-  protected async setRawWithTtl(key: string, value: string, ttl: number): Promise<void> {
-    await fetch(
-      `${this.baseUrl}/setex/${encodeURIComponent(key)}/${Math.max(1, ttl)}/${encodeURIComponent(
-        value,
-      )}`,
-      { method: "POST", headers: this.headers() },
-    );
-  }
-}
-
-class RedisMemoryStore extends KeyValueMainMemoryStoreBase {
-  private readonly storageKey: string;
-  private readonly clientPromise: Promise<
-    | {
-        get: (key: string) => Promise<string | null>;
-        set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
-      }
-    | undefined
-  >;
-
-  constructor(options: {
-    url: string;
-    storageKey: string;
-    ttl?: number;
-  }) {
-    super(options.ttl);
-    this.storageKey = options.storageKey;
-    this.clientPromise = (async () => {
-      try {
-        const redisModule = (await import("redis")) as unknown as {
-          createClient: (args: { url: string }) => {
-            connect: () => Promise<unknown>;
-            get: (key: string) => Promise<string | null>;
-            set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
-          };
-        };
-        const client = redisModule.createClient({ url: options.url });
-        await client.connect();
-        return client;
-      } catch {
-        return undefined;
-      }
-    })();
-  }
-
-  protected key(): string {
-    return this.storageKey;
-  }
-
-  protected async getRaw(key: string): Promise<string | undefined> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("Redis unavailable");
-    }
-    const value = await client.get(key);
-    return value ?? undefined;
-  }
-
-  protected async setRaw(key: string, value: string): Promise<void> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("Redis unavailable");
-    }
-    await client.set(key, value);
-  }
-
-  protected async setRawWithTtl(key: string, value: string, ttl: number): Promise<void> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("Redis unavailable");
-    }
-    await client.set(key, value, { EX: Math.max(1, ttl) });
-  }
-}
-
-class DynamoDbMemoryStore extends KeyValueMainMemoryStoreBase {
-  private readonly storageKey: string;
-  private readonly table: string;
-  private readonly clientPromise: Promise<
-    | {
-        send: (command: unknown) => Promise<unknown>;
-        GetItemCommand: new (input: unknown) => unknown;
-        PutItemCommand: new (input: unknown) => unknown;
-      }
-    | undefined
-  >;
-
-  constructor(options: {
-    table: string;
-    storageKey: string;
-    region?: string;
-    ttl?: number;
-  }) {
-    super(options.ttl);
-    this.storageKey = options.storageKey;
-    this.table = options.table;
-    this.clientPromise = (async () => {
-      try {
-        const module = (await import("@aws-sdk/client-dynamodb")) as {
-          DynamoDBClient: new (input: { region?: string }) => {
-            send: (command: unknown) => Promise<unknown>;
-          };
-          GetItemCommand: new (input: unknown) => unknown;
-          PutItemCommand: new (input: unknown) => unknown;
-        };
-        const client = new module.DynamoDBClient({ region: options.region });
-        return {
-          send: client.send.bind(client),
-          GetItemCommand: module.GetItemCommand,
-          PutItemCommand: module.PutItemCommand,
-        };
-      } catch {
-        return undefined;
-      }
-    })();
-  }
-
-  protected key(): string {
-    return this.storageKey;
-  }
-
-  protected async getRaw(key: string): Promise<string | undefined> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("DynamoDB unavailable");
-    }
-    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;
-  }
-
-  protected async setRaw(key: string, value: string): Promise<void> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("DynamoDB unavailable");
-    }
-    await client.send(
-      new client.PutItemCommand({
-        TableName: this.table,
-        Item: {
-          runId: { S: key },
-          value: { S: value },
-        },
-      }),
-    );
-  }
-
-  protected async setRawWithTtl(key: string, value: string, ttl: number): Promise<void> {
-    const client = await this.clientPromise;
-    if (!client) {
-      throw new Error("DynamoDB unavailable");
-    }
-    const ttlEpoch = Math.floor(Date.now() / 1000) + Math.max(1, ttl);
-    await client.send(
-      new client.PutItemCommand({
-        TableName: this.table,
-        Item: {
-          runId: { S: key },
-          value: { S: value },
-          ttl: { N: String(ttlEpoch) },
-        },
-      }),
-    );
-  }
 }
 
 export const createMemoryStore = (
@@ -459,54 +229,19 @@ export const createMemoryStore = (
 ): MemoryStore => {
   const provider = config?.provider ?? "local";
   const ttl = config?.ttl;
-  const storageKey = `poncho:${STORAGE_SCHEMA_VERSION}:${slugifyStorageComponent(
-    agentId,
-  )}:memory:main`;
   const workingDir = options?.workingDir ?? process.cwd();
+
   if (provider === "local") {
     return new FileMainMemoryStore(workingDir, ttl);
   }
   if (provider === "memory") {
     return new InMemoryMemoryStore(ttl);
   }
-  if (provider === "upstash") {
-    const urlEnv = config?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
-    const tokenEnv = config?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
-    const url = process.env[urlEnv] ?? "";
-    const token = process.env[tokenEnv] ?? "";
-    if (url && token) {
-      return new UpstashMemoryStore({
-        baseUrl: url,
-        token,
-        storageKey,
-        ttl,
-      });
-    }
-    return new InMemoryMemoryStore(ttl);
-  }
-  if (provider === "redis") {
-    const urlEnv = config?.urlEnv ?? "REDIS_URL";
-    const url = process.env[urlEnv] ?? "";
-    if (url) {
-      return new RedisMemoryStore({
-        url,
-        storageKey,
-        ttl,
-      });
-    }
-    return new InMemoryMemoryStore(ttl);
-  }
-  if (provider === "dynamodb") {
-    const table = config?.table ?? process.env.PONCHO_DYNAMODB_TABLE ?? "";
-    if (table) {
-      return new DynamoDbMemoryStore({
-        table,
-        storageKey,
-        region: config?.region,
-        ttl,
-      });
-    }
-    return new InMemoryMemoryStore(ttl);
+
+  const kv = createRawKVStore(config);
+  if (kv) {
+    const storageKey = `poncho:${STORAGE_SCHEMA_VERSION}:${slugifyStorageComponent(agentId)}:memory:main`;
+    return new KVBackedMemoryStore(kv, storageKey, ttl);
   }
   return new InMemoryMemoryStore(ttl);
 };

package/src/state.ts

@@ -21,6 +21,15 @@ export interface StateStore {
   delete(runId: string): Promise<void>;
 }
 
+export interface PendingSubagentResult {
+  subagentId: string;
+  task: string;
+  status: "completed" | "error" | "stopped";
+  result?: import("@poncho-ai/sdk").RunResult;
+  error?: import("@poncho-ai/sdk").AgentFailure;
+  timestamp: number;
+}
+
 export interface Conversation {
   conversationId: string;
   title: string;
@@ -55,6 +64,13 @@ export interface Conversation {
     channelId: string;
     platformThreadId: string;
   };
+  pendingSubagentResults?: PendingSubagentResult[];
+  subagentCallbackCount?: number;
+  runningCallbackSince?: number;
+  lastActivityAt?: number;
+  /** Harness-internal message chain preserved across continuation runs.
+   *  Cleared when a run completes without continuation. */
+  _continuationMessages?: Message[];
   createdAt: number;
   updatedAt: number;
 }
@@ -67,6 +83,7 @@ export interface ConversationStore {
   update(conversation: Conversation): Promise<void>;
   rename(conversationId: string, title: string): Promise<Conversation | undefined>;
   delete(conversationId: string): Promise<boolean>;
+  appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
 }
 
 export type StateProviderName =
@@ -300,6 +317,14 @@ export class InMemoryConversationStore implements ConversationStore {
   async delete(conversationId: string): Promise<boolean> {
     return this.conversations.delete(conversationId);
   }
+
+  async appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void> {
+    const conversation = this.conversations.get(conversationId);
+    if (!conversation) return;
+    if (!conversation.pendingSubagentResults) conversation.pendingSubagentResults = [];
+    conversation.pendingSubagentResults.push(result);
+    conversation.updatedAt = Date.now();
+  }
 }
 
 export type ConversationSummary = {
@@ -572,6 +597,16 @@ class FileConversationStore implements ConversationStore {
     }
     return removed;
   }
+
+  async appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void> {
+    await this.ensureLoaded();
+    const conversation = await this.get(conversationId);
+    if (!conversation) return;
+    if (!conversation.pendingSubagentResults) conversation.pendingSubagentResults = [];
+    conversation.pendingSubagentResults.push(result);
+    conversation.updatedAt = Date.now();
+    await this.update(conversation);
+  }
 }
 
 type LocalStateFile = {
@@ -689,6 +724,7 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
   protected readonly ttl?: number;
   private readonly agentIdPromise: Promise<string>;
   private readonly ownerLocks = new Map<string, Promise<void>>();
+  private readonly appendLocks = new Map<string, Promise<void>>();
   protected readonly memoryFallback: InMemoryConversationStore;
 
   constructor(ttl: number | undefined, workingDir: string, agentId?: string) {
@@ -712,6 +748,19 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
     }
   }
 
+  private async withAppendLock(conversationId: string, task: () => Promise<void>): Promise<void> {
+    const prev = this.appendLocks.get(conversationId) ?? Promise.resolve();
+    const next = prev.then(task, task);
+    this.appendLocks.set(conversationId, next);
+    try {
+      await next;
+    } finally {
+      if (this.appendLocks.get(conversationId) === next) {
+        this.appendLocks.delete(conversationId);
+      }
+    }
+  }
+
   private async namespace(): Promise<string> {
     const agentId = await this.agentIdPromise;
     return `poncho:${STORAGE_SCHEMA_VERSION}:${slugifyStorageComponent(agentId)}`;
@@ -945,6 +994,17 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
     });
     return true;
   }
+
+  async appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void> {
+    await this.withAppendLock(conversationId, async () => {
+      const conversation = await this.get(conversationId);
+      if (!conversation) return;
+      if (!conversation.pendingSubagentResults) conversation.pendingSubagentResults = [];
+      conversation.pendingSubagentResults.push(result);
+      conversation.updatedAt = Date.now();
+      await this.update(conversation);
+    });
+  }
 }
 
 class UpstashConversationStore extends KeyValueConversationStoreBase {
@@ -991,23 +1051,28 @@ class UpstashConversationStore extends KeyValueConversationStoreBase {
         return (payload.result ?? []).map((v) => v ?? undefined);
       },
       set: async (key: string, value: string, ttl?: number) => {
-        const endpoint =
-          typeof ttl === "number"
-            ? `${this.baseUrl}/setex/${encodeURIComponent(key)}/${Math.max(
-                1,
-                ttl,
-              )}/${encodeURIComponent(value)}`
-            : `${this.baseUrl}/set/${encodeURIComponent(key)}/${encodeURIComponent(value)}`;
-        await fetch(endpoint, {
+        const command = typeof ttl === "number"
+          ? ["SETEX", key, Math.max(1, ttl), value]
+          : ["SET", key, value];
+        const response = await fetch(this.baseUrl, {
           method: "POST",
           headers: this.headers(),
+          body: JSON.stringify(command),
         });
+        if (!response.ok) {
+          const text = await response.text().catch(() => "");
+          console.error(`[store][upstash] SET failed (${response.status}): ${text.slice(0, 200)}`);
+        }
       },
       del: async (key: string) => {
-        await fetch(`${this.baseUrl}/del/${encodeURIComponent(key)}`, {
+        const response = await fetch(`${this.baseUrl}/del/${encodeURIComponent(key)}`, {
           method: "POST",
           headers: this.headers(),
         });
+        if (!response.ok) {
+          const text = await response.text().catch(() => "");
+          console.error(`[store][upstash] DEL failed (${response.status}): ${text.slice(0, 200)}`);
+        }
       },
     };
   }

package/src/subagent-manager.ts

@@ -15,14 +15,18 @@ export interface SubagentSummary {
   messageCount: number;
 }
 
+export interface SubagentSpawnResult {
+  subagentId: string;
+}
+
 export interface SubagentManager {
   spawn(opts: {
     task: string;
     parentConversationId: string;
     ownerId: string;
-  }): Promise<SubagentResult>;
+  }): Promise<SubagentSpawnResult>;
 
-  sendMessage(subagentId: string, message: string): Promise<SubagentResult>;
+  sendMessage(subagentId: string, message: string): Promise<SubagentSpawnResult>;
 
   stop(subagentId: string): Promise<void>;
 

package/src/subagent-tools.ts

@@ -1,48 +1,18 @@
-import { defineTool, type Message, type ToolDefinition, getTextContent } from "@poncho-ai/sdk";
-import type { SubagentManager, SubagentResult } from "./subagent-manager.js";
-
-const LAST_MESSAGES_TO_RETURN = 10;
-
-const summarizeResult = (r: SubagentResult): Record<string, unknown> => {
-  const summary: Record<string, unknown> = {
-    subagentId: r.subagentId,
-    status: r.status,
-  };
-  if (r.result) {
-    summary.result = {
-      status: r.result.status,
-      response: r.result.response,
-      steps: r.result.steps,
-      duration: r.result.duration,
-    };
-  }
-  if (r.error) {
-    summary.error = r.error;
-  }
-  if (r.latestMessages && r.latestMessages.length > 0) {
-    summary.latestMessages = r.latestMessages
-      .slice(-LAST_MESSAGES_TO_RETURN)
-      .map((m: Message) => ({
-        role: m.role,
-        content: getTextContent(m).slice(0, 2000),
-      }));
-  }
-  return summary;
-};
+import { defineTool, type ToolContext, type ToolDefinition } from "@poncho-ai/sdk";
+import type { SubagentManager } from "./subagent-manager.js";
 
 export const createSubagentTools = (
   manager: SubagentManager,
-  getConversationId: () => string | undefined,
-  getOwnerId: () => string,
 ): ToolDefinition[] => [
   defineTool({
     name: "spawn_subagent",
     description:
-      "Spawn a subagent to work on a task and wait for it to finish. The subagent is a full copy of " +
-      "yourself running in its own conversation context with access to the same tools (except memory writes). " +
-      "This call blocks until the subagent completes and returns its result.\n\n" +
+      "Spawn a subagent to work on a task in the background. Returns immediately with a subagent ID. " +
+      "The subagent runs independently and its result will be delivered to you as a message in the " +
+      "conversation when it completes.\n\n" +
       "Guidelines:\n" +
-      "- Use subagents to parallelize work: call spawn_subagent multiple times in one response for independent sub-tasks -- they run concurrently.\n" +
+      "- Spawn all needed subagents in a SINGLE response (they run concurrently), then end your turn with a brief message to the user.\n" +
+      "- Do NOT spawn more subagents in follow-up steps. Wait for results to be delivered before deciding if more work is needed.\n" +
       "- Prefer doing work yourself for simple or quick tasks. Spawn subagents for substantial, self-contained work.\n" +
       "- The subagent has no memory of your conversation -- write thorough, self-contained instructions in the task.",
     inputSchema: {
@@ -58,29 +28,32 @@ export const createSubagentTools = (
       required: ["task"],
       additionalProperties: false,
     },
-    handler: async (input) => {
+    handler: async (input: Record<string, unknown>, context: ToolContext) => {
       const task = typeof input.task === "string" ? input.task : "";
       if (!task.trim()) {
         return { error: "task is required" };
       }
-      const conversationId = getConversationId();
+      const conversationId = context.conversationId;
       if (!conversationId) {
         return { error: "no active conversation to spawn subagent from" };
       }
-      const result = await manager.spawn({
+      const ownerId = typeof context.parameters.__ownerId === "string"
+        ? context.parameters.__ownerId
+        : "anonymous";
+      const { subagentId } = await manager.spawn({
         task: task.trim(),
         parentConversationId: conversationId,
-        ownerId: getOwnerId(),
+        ownerId,
       });
-      return summarizeResult(result);
+      return { subagentId, status: "running" };
     },
   }),
 
   defineTool({
     name: "message_subagent",
     description:
-      "Send a follow-up message to a completed or stopped subagent and wait for it to finish. " +
-      "This restarts the subagent with the new message and blocks until it completes. " +
+      "Send a follow-up message to a completed or stopped subagent. The subagent restarts in the " +
+      "background and its result will be delivered to you as a message when it completes. " +
       "Only works when the subagent is not currently running.",
     inputSchema: {
       type: "object",
@@ -103,8 +76,8 @@ export const createSubagentTools = (
       if (!subagentId || !message.trim()) {
         return { error: "subagent_id and message are required" };
       }
-      const result = await manager.sendMessage(subagentId, message.trim());
-      return summarizeResult(result);
+      const { subagentId: id } = await manager.sendMessage(subagentId, message.trim());
+      return { subagentId: id, status: "running" };
     },
   }),
 
@@ -145,8 +118,8 @@ export const createSubagentTools = (
       properties: {},
       additionalProperties: false,
     },
-    handler: async () => {
-      const conversationId = getConversationId();
+    handler: async (_input: Record<string, unknown>, context: ToolContext) => {
+      const conversationId = context.conversationId;
       if (!conversationId) {
         return { error: "no active conversation" };
       }