@poncho-ai/harness 0.50.4 → 0.50.5

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.50.4 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.50.5 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            533.24 KB
+ESM dist/index.js            535.57 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM ⚡️ Build success in 250ms
+ESM ⚡️ Build success in 240ms
 DTS Build start
-DTS ⚡️ Build success in 9179ms
-DTS dist/index.d.ts 89.97 KB
+DTS ⚡️ Build success in 7598ms
+DTS dist/index.d.ts 91.35 KB

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @poncho-ai/harness
 
+## 0.50.5
+
+### Patch Changes
+
+- [`991a4b9`](https://github.com/cesr/poncho-ai/commit/991a4b98d6683c105c7aae50551d30b16080d618) Thanks [@cesr](https://github.com/cesr)! - harness: subagents survive the wall-clock timeout, and can be given a longer budget than the foreground turn.
+
+  Previously a subagent that hit its hard `timeout` (vs. `maxSteps`) emitted `run:error` with no `runResult`, so the orchestrator dropped everything it had gathered: the parent received a bare `(no result)`, the subagent was falsely marked `completed`, and the work — often dozens of completed searches, just short of the write step — was lost.
+  - **Graceful timeout/error delivery.** When a subagent run ends abnormally (timeout or model error) with no `runResult`, the orchestrator now recovers its real output (run response → streamed draft → transcript walk-back, discarding the synthetic `[Error: …]` placeholder), and delivers it tagged so the parent knows it didn't finish — it may not have written its files — with a concrete recovery hint (use the partial work, send a write-only `message_subagent` follow-up, or `read_subagent(…, mode:"full")`). The subagent is marked `status: "error"` (not a fake `completed`) and carries the failure in its `error` field. Applied to both the spawn and continuation paths.
+  - **`runTimeoutSecOverride` (HarnessOptions).** A constructor-level override for the per-run hard wall-clock timeout, taking precedence over the agent definition's `limits.timeout`. Lets a platform give background subagents a longer budget (e.g. 1h) than a foreground turn (5 min) without forking the agent definition. `0` disables the hard timeout.
+
 ## 0.50.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1261,6 +1261,14 @@ interface HarnessOptions {
      * should also be browsable in the VFS. Empty by default.
      */
     systemSkillPaths?: string[];
+    /**
+     * Override the per-run hard wall-clock timeout, in seconds, taking
+     * precedence over the agent definition's `limits.timeout`. Platforms use
+     * this to give background subagents a longer budget than the foreground
+     * agent without forking the agent definition (e.g. a 1h research subagent
+     * vs. a 5-min foreground turn). `0` disables the hard timeout.
+     */
+    runTimeoutSecOverride?: number;
 }
 interface HarnessRunOutput {
     runId: string;
@@ -1280,6 +1288,7 @@ interface ArchivedToolResult {
 declare class AgentHarness {
     private readonly workingDir;
     private readonly environment;
+    private readonly runTimeoutSecOverride?;
     private modelProvider;
     private readonly modelProviderInjected;
     private readonly dispatcher;
@@ -1988,6 +1997,28 @@ declare const STALE_SUBAGENT_THRESHOLD_MS: number;
  * before — instead of surfacing to the parent as an empty result.
  */
 declare const lastAssistantText: (messages: Message[]) => string;
+/**
+ * The run loop stuffs a synthetic `[Error: ...]` placeholder into the draft /
+ * persisted assistant text when a run ends on `run:error` (e.g. a timeout).
+ * That placeholder is not real model output — strip it so we don't surface it
+ * to the parent as the subagent's "response".
+ */
+declare const realResponseText: (text: string | undefined) => string;
+/**
+ * Build the result text delivered to the parent when a subagent ended
+ * abnormally (timeout / error) with no RunResult. We never drop the work it
+ * gathered, and the parent is told it didn't finish — e.g. it may not have
+ * written its output files — plus how to recover (use what's here, send a
+ * write-only follow-up, or read the full transcript).
+ */
+declare const abnormalEndResponse: (opts: {
+    subagentId: string;
+    gathered: string;
+    runError?: {
+        code?: string;
+        message?: string;
+    };
+}) => string;
 type ActiveConversationRun = {
     ownerId: string;
     abortController: AbortController;
@@ -2150,4 +2181,4 @@ interface RunConversationTurnResult {
 }
 declare const runConversationTurn: (opts: RunConversationTurnOpts) => Promise<RunConversationTurnResult>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -9170,6 +9170,7 @@ function extractMediaFromToolOutput(output) {
 var AgentHarness = class _AgentHarness {
   workingDir;
   environment;
+  runTimeoutSecOverride;
   modelProvider;
   modelProviderInjected;
   dispatcher = new ToolDispatcher();
@@ -9375,6 +9376,7 @@ var AgentHarness = class _AgentHarness {
   constructor(options = {}) {
     this.workingDir = options.workingDir ?? process.cwd();
     this.environment = options.environment ?? "development";
+    this.runTimeoutSecOverride = options.runTimeoutSecOverride;
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.uploadStore = options.uploadStore;
@@ -10237,7 +10239,7 @@ var AgentHarness = class _AgentHarness {
     const runId = `run_${randomUUID5()}`;
     const start = now();
     const maxSteps = agent.frontmatter.limits?.maxSteps ?? 20;
-    const configuredTimeout = agent.frontmatter.limits?.timeout;
+    const configuredTimeout = this.runTimeoutSecOverride ?? agent.frontmatter.limits?.timeout;
     const timeoutMs = this.environment === "development" && configuredTimeout == null ? 0 : (configuredTimeout ?? 300) * 1e3;
     const platformMaxDurationSec = Number(process.env.PONCHO_MAX_DURATION) || 0;
     const softDeadlineMs = input.disableSoftDeadline || platformMaxDurationSec <= 0 ? 0 : platformMaxDurationSec * 800;
@@ -12340,6 +12342,18 @@ var lastAssistantText = (messages) => {
   }
   return "";
 };
+var realResponseText = (text) => {
+  const t = (text ?? "").trim();
+  return t.startsWith("[Error:") ? "" : t;
+};
+var abnormalEndResponse = (opts) => {
+  const timedOut = opts.runError?.code === "TIMEOUT";
+  const head = timedOut ? "[Subagent hit its time limit before finishing \u2014 it may not have written its output files.]" : `[Subagent ended before finishing${opts.runError?.message ? `: ${opts.runError.message}` : ""}.]`;
+  const recover = opts.gathered ? "Partial work it gathered is below \u2014 write the files yourself from it, or send a tight write-only follow-up with message_subagent." : `Use read_subagent("${opts.subagentId}", mode:"full") to recover what it gathered.`;
+  return opts.gathered ? `${head} ${recover}
+
+${opts.gathered}` : `${head} ${recover}`;
+};
 var AgentOrchestrator = class {
   harness;
   conversationStore;
@@ -12865,6 +12879,7 @@ var AgentOrchestrator = class {
     const draft = createTurnDraftState();
     let latestRunId = "";
     let runResult;
+    let runError;
     try {
       const conversation = await this.conversationStore.getWithArchive(childConversationId);
       if (!conversation) throw new Error("Subagent conversation not found");
@@ -13001,6 +13016,7 @@ var AgentOrchestrator = class {
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(childConversationId, event);
@@ -13048,7 +13064,12 @@ var AgentOrchestrator = class {
           }
           return;
         }
-        conv.subagentMeta = { ...conv.subagentMeta, status: "completed" };
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta,
+          status: abnormalEnd ? "error" : "completed",
+          ...abnormalEnd ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } } : {}
+        };
         await this.conversationStore.update(conv);
       }
       this.hooks?.onStreamEnd?.(childConversationId);
@@ -13057,18 +13078,25 @@ var AgentOrchestrator = class {
         subagentId: childConversationId,
         conversationId: childConversationId
       });
-      let subagentResponse = (runResult?.response ?? draft.assistantResponse ?? "").trim();
-      if (!subagentResponse) {
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(childConversationId);
-        if (freshSubConv) {
-          subagentResponse = lastAssistantText(freshSubConv.messages);
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+      const abnormal = !runResult;
+      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: childConversationId, gathered, runError }) : gathered;
       const pendingResult = {
         subagentId: childConversationId,
         task,
-        status: "completed",
-        result: runResult ? { status: runResult.status, response: subagentResponse, steps: runResult.steps, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult.duration } : void 0,
+        status: abnormal ? "error" : "completed",
+        result: {
+          status: runResult?.status ?? "error",
+          response: subagentResponse,
+          steps: runResult?.steps ?? 0,
+          tokens: { input: 0, output: 0, cached: 0 },
+          duration: runResult?.duration ?? 0
+        },
+        ...abnormal ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } } : {},
         timestamp: Date.now()
       };
       await this.conversationStore.appendSubagentResult(parentConversationId, pendingResult);
@@ -13316,6 +13344,7 @@ ${resultBody}`,
     this.activeSubagentRuns.set(conversationId, { abortController: childAbortController, harness: childHarness, parentConversationId });
     const draft = createTurnDraftState();
     let runResult;
+    let runError;
     try {
       const recallParams = this.hooks?.buildRecallParams?.({ ownerId, tenantId: conversation.tenantId, excludeConversationId: conversationId }) ?? {};
       for await (const event of childHarness.runWithTelemetry({
@@ -13348,6 +13377,7 @@ ${resultBody}`,
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(conversationId, event);
@@ -13396,7 +13426,12 @@ ${resultBody}`,
           }
           return;
         }
-        conv.subagentMeta = { ...conv.subagentMeta, status: "completed" };
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta,
+          status: abnormalEnd ? "error" : "completed",
+          ...abnormalEnd ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } } : {}
+        };
         await this.conversationStore.update(conv);
       }
       this.activeSubagentRuns.delete(conversationId);
@@ -13405,20 +13440,21 @@ ${resultBody}`,
         subagentId: conversationId,
         conversationId
       });
-      let subagentResponse = (runResult?.response ?? draft.assistantResponse ?? "").trim();
-      if (!subagentResponse) {
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(conversationId);
-        if (freshSubConv) {
-          subagentResponse = lastAssistantText(freshSubConv.messages);
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+      const abnormal = !runResult;
+      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: conversationId, gathered, runError }) : gathered;
       const parentConv = await this.conversationStore.get(parentConversationId);
       if (parentConv) {
         const result = {
           subagentId: conversationId,
           task,
-          status: "completed",
-          result: { status: "completed", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          status: abnormal ? "error" : "completed",
+          result: { status: runResult?.status ?? "error", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          ...abnormal ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } } : {},
           timestamp: Date.now()
         };
         await this.conversationStore.appendSubagentResult(parentConversationId, result);
@@ -14048,6 +14084,7 @@ export {
   ToolDispatcher,
   VFS_SCHEME,
   VercelBlobUploadStore,
+  abnormalEndResponse,
   applyTurnMetadata,
   buildAgentDirectoryName,
   buildApprovalCheckpoints,
@@ -14122,6 +14159,7 @@ export {
   ponchoDocsTool,
   readOpenAICodexSession,
   readSkillResource,
+  realResponseText,
   recordStandardTurnEvent,
   renderAgentPrompt,
   resolveAgentIdentity,

package/package.json

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

package/src/harness.ts

@@ -146,6 +146,14 @@ export interface HarnessOptions {
    * should also be browsable in the VFS. Empty by default.
    */
   systemSkillPaths?: string[];
+  /**
+   * Override the per-run hard wall-clock timeout, in seconds, taking
+   * precedence over the agent definition's `limits.timeout`. Platforms use
+   * this to give background subagents a longer budget than the foreground
+   * agent without forking the agent definition (e.g. a 1h research subagent
+   * vs. a 5-min foreground turn). `0` disables the hard timeout.
+   */
+  runTimeoutSecOverride?: number;
 }
 
 export interface HarnessRunOutput {
@@ -848,6 +856,7 @@ function extractMediaFromToolOutput(output: unknown): {
 export class AgentHarness {
   private readonly workingDir: string;
   private readonly environment: HarnessOptions["environment"];
+  private readonly runTimeoutSecOverride?: number;
   private modelProvider: ModelProviderFactory;
   private readonly modelProviderInjected: boolean;
   private readonly dispatcher = new ToolDispatcher();
@@ -1084,6 +1093,7 @@ export class AgentHarness {
   constructor(options: HarnessOptions = {}) {
     this.workingDir = options.workingDir ?? process.cwd();
     this.environment = options.environment ?? "development";
+    this.runTimeoutSecOverride = options.runTimeoutSecOverride;
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
     this.uploadStore = options.uploadStore;
@@ -2126,7 +2136,9 @@ export class AgentHarness {
     const runId = `run_${randomUUID()}`;
     const start = now();
     const maxSteps = agent.frontmatter.limits?.maxSteps ?? 20;
-    const configuredTimeout = agent.frontmatter.limits?.timeout;
+    // A constructor-level override (e.g. a longer budget for background
+    // subagents) takes precedence over the agent definition's limits.timeout.
+    const configuredTimeout = this.runTimeoutSecOverride ?? agent.frontmatter.limits?.timeout;
     const timeoutMs = this.environment === "development" && configuredTimeout == null
       ? 0 // no hard timeout in development unless explicitly configured
       : (configuredTimeout ?? 300) * 1000;

package/src/orchestrator/index.ts

@@ -47,6 +47,8 @@ export {
 export {
   AgentOrchestrator,
   lastAssistantText,
+  realResponseText,
+  abnormalEndResponse,
   type ActiveConversationRun,
   type EventSink,
   type OrchestratorHooks,

package/src/orchestrator/orchestrator.ts

@@ -67,6 +67,39 @@ export const lastAssistantText = (messages: Message[]): string => {
   return "";
 };
 
+/**
+ * The run loop stuffs a synthetic `[Error: ...]` placeholder into the draft /
+ * persisted assistant text when a run ends on `run:error` (e.g. a timeout).
+ * That placeholder is not real model output — strip it so we don't surface it
+ * to the parent as the subagent's "response".
+ */
+export const realResponseText = (text: string | undefined): string => {
+  const t = (text ?? "").trim();
+  return t.startsWith("[Error:") ? "" : t;
+};
+
+/**
+ * Build the result text delivered to the parent when a subagent ended
+ * abnormally (timeout / error) with no RunResult. We never drop the work it
+ * gathered, and the parent is told it didn't finish — e.g. it may not have
+ * written its output files — plus how to recover (use what's here, send a
+ * write-only follow-up, or read the full transcript).
+ */
+export const abnormalEndResponse = (opts: {
+  subagentId: string;
+  gathered: string;
+  runError?: { code?: string; message?: string };
+}): string => {
+  const timedOut = opts.runError?.code === "TIMEOUT";
+  const head = timedOut
+    ? "[Subagent hit its time limit before finishing — it may not have written its output files.]"
+    : `[Subagent ended before finishing${opts.runError?.message ? `: ${opts.runError.message}` : ""}.]`;
+  const recover = opts.gathered
+    ? "Partial work it gathered is below — write the files yourself from it, or send a tight write-only follow-up with message_subagent."
+    : `Use read_subagent("${opts.subagentId}", mode:"full") to recover what it gathered.`;
+  return opts.gathered ? `${head} ${recover}\n\n${opts.gathered}` : `${head} ${recover}`;
+};
+
 // ── Types ──
 
 export type ActiveConversationRun = {
@@ -762,6 +795,7 @@ export class AgentOrchestrator {
     const draft = createTurnDraftState();
     let latestRunId = "";
     let runResult: { status: "completed" | "error" | "cancelled"; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runError: { code?: string; message?: string } | undefined;
 
     try {
       const conversation = await this.conversationStore.getWithArchive(childConversationId);
@@ -911,6 +945,7 @@ export class AgentOrchestrator {
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(childConversationId, event);
@@ -961,7 +996,17 @@ export class AgentOrchestrator {
           return;
         }
 
-        conv.subagentMeta = { ...conv.subagentMeta!, status: "completed" };
+        // No runResult means the run ended on run:error (timeout / model
+        // error) rather than run:completed — flag the subagent accordingly
+        // instead of faking "completed".
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta!,
+          status: abnormalEnd ? "error" : "completed",
+          ...(abnormalEnd
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
+        };
         await this.conversationStore.update(conv);
       }
 
@@ -972,18 +1017,36 @@ export class AgentOrchestrator {
         conversationId: childConversationId,
       });
 
-      let subagentResponse = (runResult?.response ?? draft.assistantResponse ?? "").trim();
-      if (!subagentResponse) {
+      // Recover the subagent's real output: prefer the run response, then the
+      // streamed draft, then walk the transcript — discarding the synthetic
+      // "[Error: ...]" placeholder at each step.
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(childConversationId);
-        if (freshSubConv) {
-          subagentResponse = lastAssistantText(freshSubConv.messages);
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+
+      // On an abnormal end (timeout / error) there is no runResult; don't drop
+      // the work — deliver what it gathered, tagged so the parent knows it
+      // didn't finish, and build a result so it never renders as "(no result)".
+      const abnormal = !runResult;
+      const subagentResponse = abnormal
+        ? abnormalEndResponse({ subagentId: childConversationId, gathered, runError })
+        : gathered;
       const pendingResult: PendingSubagentResult = {
         subagentId: childConversationId,
         task,
-        status: "completed",
-        result: runResult ? { status: runResult.status, response: subagentResponse, steps: runResult.steps, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult.duration } : undefined,
+        status: abnormal ? "error" : "completed",
+        result: {
+          status: runResult?.status ?? "error",
+          response: subagentResponse,
+          steps: runResult?.steps ?? 0,
+          tokens: { input: 0, output: 0, cached: 0 },
+          duration: runResult?.duration ?? 0,
+        },
+        ...(abnormal
+          ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+          : {}),
         timestamp: Date.now(),
       };
       await this.conversationStore.appendSubagentResult(parentConversationId, pendingResult);
@@ -1271,7 +1334,8 @@ export class AgentOrchestrator {
     this.activeSubagentRuns.set(conversationId, { abortController: childAbortController, harness: childHarness, parentConversationId });
 
     const draft = createTurnDraftState();
-    let runResult: { status: string; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runResult: { status: "completed" | "error" | "cancelled"; response?: string; steps: number; duration: number; continuation?: boolean; continuationMessages?: Message[] } | undefined;
+    let runError: { code?: string; message?: string } | undefined;
 
     try {
       const recallParams = this.hooks?.buildRecallParams?.({ ownerId, tenantId: conversation.tenantId, excludeConversationId: conversationId }) ?? {};
@@ -1306,6 +1370,7 @@ export class AgentOrchestrator {
           }
         }
         if (event.type === "run:error") {
+          runError = { code: event.error.code, message: event.error.message };
           draft.assistantResponse = draft.assistantResponse || `[Error: ${event.error.message}]`;
         }
         await this.eventSink(conversationId, event);
@@ -1355,7 +1420,14 @@ export class AgentOrchestrator {
           return;
         }
 
-        conv.subagentMeta = { ...conv.subagentMeta!, status: "completed" };
+        const abnormalEnd = !runResult;
+        conv.subagentMeta = {
+          ...conv.subagentMeta!,
+          status: abnormalEnd ? "error" : "completed",
+          ...(abnormalEnd
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
+        };
         await this.conversationStore.update(conv);
       }
 
@@ -1366,21 +1438,26 @@ export class AgentOrchestrator {
         conversationId,
       });
 
-      let subagentResponse = (runResult?.response ?? draft.assistantResponse ?? "").trim();
-      if (!subagentResponse) {
+      let gathered = realResponseText(runResult?.response) || realResponseText(draft.assistantResponse);
+      if (!gathered) {
         const freshSubConv = await this.conversationStore.get(conversationId);
-        if (freshSubConv) {
-          subagentResponse = lastAssistantText(freshSubConv.messages);
-        }
+        if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
+      const abnormal = !runResult;
+      const subagentResponse = abnormal
+        ? abnormalEndResponse({ subagentId: conversationId, gathered, runError })
+        : gathered;
 
       const parentConv = await this.conversationStore.get(parentConversationId);
       if (parentConv) {
         const result: PendingSubagentResult = {
           subagentId: conversationId,
           task,
-          status: "completed",
-          result: { status: "completed", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          status: abnormal ? "error" : "completed",
+          result: { status: runResult?.status ?? "error", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
+          ...(abnormal
+            ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
+            : {}),
           timestamp: Date.now(),
         };
         await this.conversationStore.appendSubagentResult(parentConversationId, result);

package/test/orchestrator.test.ts

@@ -9,6 +9,8 @@ import {
   recordStandardTurnEvent,
   executeConversationTurn,
   lastAssistantText,
+  realResponseText,
+  abnormalEndResponse,
 } from "../src/orchestrator/index.js";
 import type { Conversation } from "../src/state.js";
 
@@ -237,3 +239,50 @@ describe("lastAssistantText (subagent result extraction)", () => {
     expect(lastAssistantText(messages)).toBe("");
   });
 });
+
+describe("realResponseText (strips run:error placeholder)", () => {
+  it("drops the synthetic [Error: ...] placeholder", () => {
+    expect(realResponseText("[Error: Run exceeded timeout of 300s]")).toBe("");
+  });
+  it("keeps real text and trims", () => {
+    expect(realResponseText("  done, wrote the file  ")).toBe("done, wrote the file");
+  });
+  it("handles undefined", () => {
+    expect(realResponseText(undefined)).toBe("");
+  });
+});
+
+describe("abnormalEndResponse (graceful timeout / error delivery)", () => {
+  it("timeout WITH gathered work: notes the cutoff and includes the work", () => {
+    const out = abnormalEndResponse({
+      subagentId: "sub_1",
+      gathered: "Found 12 competitors: A, B, C...",
+      runError: { code: "TIMEOUT", message: "Run exceeded timeout of 3600s" },
+    });
+    expect(out).toContain("time limit");
+    expect(out).toContain("may not have written its output files");
+    expect(out).toContain("Found 12 competitors: A, B, C...");
+    expect(out).not.toContain("(no result)");
+  });
+
+  it("timeout WITHOUT gathered work: points at read_subagent to recover", () => {
+    const out = abnormalEndResponse({
+      subagentId: "sub_2",
+      gathered: "",
+      runError: { code: "TIMEOUT", message: "Run exceeded timeout of 3600s" },
+    });
+    expect(out).toContain("time limit");
+    expect(out).toContain('read_subagent("sub_2"');
+    expect(out).toContain('mode:"full"');
+  });
+
+  it("non-timeout error: surfaces the error message", () => {
+    const out = abnormalEndResponse({
+      subagentId: "sub_3",
+      gathered: "",
+      runError: { code: "EMPTY_RESPONSE", message: "model returned no content" },
+    });
+    expect(out).toContain("ended before finishing");
+    expect(out).toContain("model returned no content");
+  });
+});