@poncho-ai/harness 0.37.2 → 0.39.0

package/dist/index.d.ts

@@ -174,6 +174,13 @@ interface Conversation {
     contextTokens?: number;
     contextWindow?: number;
     parentConversationId?: string;
+    parentMessageId?: string;
+    threadMeta?: {
+        /** First ~200 chars of the anchor message text, cached for cheap rendering. */
+        parentMessageSummary?: string;
+        /** Length of the snapshot at fork time. messages[snapshotLength-1] is the anchor. */
+        snapshotLength: number;
+    };
     subagentMeta?: {
         task: string;
         status: "running" | "completed" | "error" | "stopped";
@@ -196,16 +203,42 @@ interface Conversation {
     createdAt: number;
     updatedAt: number;
 }
+interface ConversationCreateInit {
+    parentConversationId?: string;
+    parentMessageId?: string;
+    threadMeta?: Conversation["threadMeta"];
+    subagentMeta?: Conversation["subagentMeta"];
+    messages?: Message[];
+    channelMeta?: Conversation["channelMeta"];
+}
 interface ConversationStore {
     list(ownerId?: string, tenantId?: string | null): Promise<Conversation[]>;
     listSummaries(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
+    /**
+     * Cheap column-level fetch — returns summary fields only, no data blob.
+     * Use this on hot polling paths where the caller just needs to know
+     * whether the conversation has changed since last fetch.
+     */
+    getStatusSnapshot(conversationId: string): Promise<ConversationStatusSnapshot | undefined>;
+    /**
+     * Load a conversation WITHOUT the tool_result_archive blob. Default for
+     * read paths — archive can grow unboundedly and most callers don't need it.
+     */
     get(conversationId: string): Promise<Conversation | undefined>;
-    create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+    /**
+     * Load a conversation WITH the tool_result_archive. Use this only on
+     * run-entry paths that reseed the harness (via withToolResultArchiveParam
+     * or by passing the archive to runCronAgent).
+     */
+    getWithArchive(conversationId: string): Promise<Conversation | undefined>;
+    create(ownerId?: string, title?: string, tenantId?: string | null, init?: ConversationCreateInit): Promise<Conversation>;
     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>;
     clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
+    /** List thread conversations anchored under `parentConversationId`. */
+    listThreads(parentConversationId: string): Promise<ConversationSummary[]>;
 }
 type StateProviderName = "local" | "memory" | "sqlite" | "postgresql" | "redis" | "upstash" | "dynamodb";
 interface StateConfig {
@@ -234,12 +267,15 @@ declare class InMemoryConversationStore implements ConversationStore {
     list(ownerId?: string, tenantId?: string | null): Promise<Conversation[]>;
     listSummaries(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
     get(conversationId: string): Promise<Conversation | undefined>;
-    create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+    getWithArchive(conversationId: string): Promise<Conversation | undefined>;
+    getStatusSnapshot(conversationId: string): Promise<ConversationStatusSnapshot | undefined>;
+    create(ownerId?: string, title?: string, tenantId?: string | null, init?: ConversationCreateInit): Promise<Conversation>;
     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>;
     clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
+    listThreads(parentConversationId: string): Promise<ConversationSummary[]>;
 }
 type ConversationSummary = {
     conversationId: string;
@@ -249,6 +285,7 @@ type ConversationSummary = {
     ownerId: string;
     tenantId?: string | null;
     parentConversationId?: string;
+    parentMessageId?: string;
     messageCount?: number;
     hasPendingApprovals?: boolean;
     channelMeta?: {
@@ -257,6 +294,22 @@ type ConversationSummary = {
         platformThreadId: string;
     };
 };
+/**
+ * Lightweight status snapshot — column-level reads only, no data blob.
+ * Used by cheap polling endpoints that just need to know "has anything
+ * changed?" without paying to deserialize the full conversation.
+ */
+type ConversationStatusSnapshot = {
+    conversationId: string;
+    updatedAt: number;
+    messageCount: number;
+    hasPendingApprovals: boolean;
+    hasContinuationMessages: boolean;
+    parentConversationId: string | null;
+    ownerId: string;
+    tenantId: string | null;
+    runStatus: "running" | "idle" | null;
+};
 declare const createStateStore: (config?: StateConfig, _options?: {
     workingDir?: string;
     agentId?: string;
@@ -682,6 +735,20 @@ interface TodoStore {
 }
 
 type ReminderStatus = "pending" | "fired" | "cancelled";
+type RecurrenceType = "daily" | "weekly" | "monthly" | "cron";
+interface Recurrence {
+    type: RecurrenceType;
+    /** Repeat every N units (e.g. every 2 days). Defaults to 1. */
+    interval?: number;
+    /** For weekly: which days (0=Sun … 6=Sat). */
+    daysOfWeek?: number[];
+    /** For type "cron": a 5-field cron expression. */
+    expression?: string;
+    /** Stop recurring after this epoch-ms timestamp. */
+    endsAt?: number;
+    /** Stop recurring after this many total firings. */
+    maxOccurrences?: number;
+}
 interface Reminder {
     id: string;
     task: string;
@@ -692,20 +759,35 @@ interface Reminder {
     conversationId: string;
     ownerId?: string;
     tenantId?: string | null;
+    recurrence?: Recurrence | null;
+    occurrenceCount?: number;
+}
+interface ReminderCreateInput {
+    task: string;
+    scheduledAt: number;
+    timezone?: string;
+    conversationId: string;
+    ownerId?: string;
+    tenantId?: string | null;
+    recurrence?: Recurrence | null;
 }
 interface ReminderStore {
     list(): Promise<Reminder[]>;
-    create(input: {
-        task: string;
-        scheduledAt: number;
-        timezone?: string;
-        conversationId: string;
-        ownerId?: string;
-        tenantId?: string | null;
+    create(input: ReminderCreateInput): Promise<Reminder>;
+    update(id: string, fields: {
+        scheduledAt?: number;
+        occurrenceCount?: number;
+        status?: ReminderStatus;
     }): Promise<Reminder>;
     cancel(id: string): Promise<Reminder>;
     delete(id: string): Promise<void>;
 }
+/**
+ * Given a reminder's current scheduledAt and its recurrence config, compute the
+ * next fire time. Returns null if the recurrence is exhausted (maxOccurrences
+ * reached or endsAt passed).
+ */
+declare const computeNextOccurrence: (reminder: Reminder) => number | null;
 declare const createReminderStore: (_agentId: string, _config?: StateConfig, _options?: {
     workingDir?: string;
 }) => ReminderStore;
@@ -730,14 +812,32 @@ interface StorageEngine {
     close(): Promise<void>;
     conversations: {
         list(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
+        /**
+         * Load a conversation WITHOUT the tool_result_archive blob. Use this on
+         * read paths (UI loads, existence checks, etc.) — the archive can grow
+         * unboundedly as tool calls accumulate, and most callers never touch it.
+         */
         get(conversationId: string): Promise<Conversation | undefined>;
-        create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+        /**
+         * Load a conversation WITH the tool_result_archive. Only use this when
+         * starting/resuming a harness run — the archive needs to be reseeded so
+         * the agent can retrieve previously-archived tool results by id.
+         */
+        getWithArchive(conversationId: string): Promise<Conversation | undefined>;
+        /**
+         * Cheap column-level snapshot — no data blob, no heavy columns. For hot
+         * polling paths. Returns undefined if the conversation doesn't exist.
+         */
+        getStatusSnapshot(conversationId: string): Promise<ConversationStatusSnapshot | undefined>;
+        create(ownerId?: string, title?: string, tenantId?: string | null, init?: ConversationCreateInit): Promise<Conversation>;
         update(conversation: Conversation): Promise<void>;
         rename(conversationId: string, title: string): Promise<Conversation | undefined>;
         delete(conversationId: string): Promise<boolean>;
         search(query: string, tenantId?: string | null): Promise<ConversationSummary[]>;
         appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
         clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
+        /** List thread conversations anchored under `parentConversationId`. */
+        listThreads(parentConversationId: string): Promise<ConversationSummary[]>;
     };
     memory: {
         get(tenantId?: string | null): Promise<MainMemory>;
@@ -749,13 +849,11 @@ interface StorageEngine {
     };
     reminders: {
         list(tenantId?: string | null): Promise<Reminder[]>;
-        create(input: {
-            task: string;
-            scheduledAt: number;
-            timezone?: string;
-            conversationId: string;
-            ownerId?: string;
-            tenantId?: string | null;
+        create(input: ReminderCreateInput): Promise<Reminder>;
+        update(id: string, fields: {
+            scheduledAt?: number;
+            occurrenceCount?: number;
+            status?: ReminderStatus;
         }): Promise<Reminder>;
         cancel(id: string): Promise<Reminder>;
         delete(id: string): Promise<void>;
@@ -1165,13 +1263,16 @@ declare class InMemoryEngine implements StorageEngine {
     conversations: {
         list: (ownerId?: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
         get: (conversationId: string) => Promise<Conversation | undefined>;
-        create: (ownerId?: string, title?: string, tenantId?: string | null) => Promise<Conversation>;
+        getWithArchive: (conversationId: string) => Promise<Conversation | undefined>;
+        getStatusSnapshot: (conversationId: string) => Promise<ConversationStatusSnapshot | undefined>;
+        create: (ownerId?: string, title?: string, tenantId?: string | null, init?: ConversationCreateInit) => Promise<Conversation>;
         update: (conversation: Conversation) => Promise<void>;
         rename: (conversationId: string, title: string) => Promise<Conversation | undefined>;
         delete: (conversationId: string) => Promise<boolean>;
         search: (query: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
         appendSubagentResult: (conversationId: string, result: PendingSubagentResult) => Promise<void>;
         clearCallbackLock: (conversationId: string) => Promise<Conversation | undefined>;
+        listThreads: (parentConversationId: string) => Promise<ConversationSummary[]>;
     };
     memory: {
         get: (tenantId?: string | null) => Promise<MainMemory>;
@@ -1183,13 +1284,11 @@ declare class InMemoryEngine implements StorageEngine {
     };
     reminders: {
         list: (tenantId?: string | null) => Promise<Reminder[]>;
-        create: (input: {
-            task: string;
-            scheduledAt: number;
-            timezone?: string;
-            conversationId: string;
-            ownerId?: string;
-            tenantId?: string | null;
+        create: (input: ReminderCreateInput) => Promise<Reminder>;
+        update: (id: string, fields: {
+            scheduledAt?: number;
+            occurrenceCount?: number;
+            status?: ReminderStatus;
         }) => Promise<Reminder>;
         cancel: (id: string) => Promise<Reminder>;
         delete: (id: string) => Promise<void>;
@@ -1249,26 +1348,48 @@ interface QueryExecutor {
     /** Run multiple statements in a transaction. */
     transaction(fn: () => Promise<void>): Promise<void>;
 }
+interface EgressBucket {
+    calls: number;
+    bytes: number;
+}
+declare class ConversationEgressMeter {
+    readonly read: Record<string, EgressBucket>;
+    readonly write: Record<string, EgressBucket>;
+    private lastLogAt;
+    private readonly logIntervalMs;
+    private readonly enabled;
+    constructor(logIntervalMs?: number);
+    trackRead(method: string, bytes: number): void;
+    trackWrite(method: string, bytes: number): void;
+    private maybeLog;
+    flush(): void;
+}
 declare abstract class SqlStorageEngine implements StorageEngine {
     protected readonly dialect: Dialect;
     protected readonly agentId: string;
     protected abstract readonly executor: QueryExecutor;
+    protected readonly egressMeter: ConversationEgressMeter;
     constructor(dialect: Dialect, agentId: string);
     initialize(): Promise<void>;
     abstract close(): Promise<void>;
+    /** Flush egress stats before shutdown. Subclasses should call super. */
+    protected flushEgressStats(): void;
     /** Hook for subclass-specific setup (e.g. WAL mode). */
     protected onBeforeInit(): Promise<void>;
     private runMigrations;
     conversations: {
         list: (ownerId?: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
         get: (conversationId: string) => Promise<Conversation | undefined>;
-        create: (ownerId?: string, title?: string, tenantId?: string | null) => Promise<Conversation>;
+        getStatusSnapshot: (conversationId: string) => Promise<ConversationStatusSnapshot | undefined>;
+        getWithArchive: (conversationId: string) => Promise<Conversation | undefined>;
+        create: (ownerId?: string, title?: string, tenantId?: string | null, init?: ConversationCreateInit) => Promise<Conversation>;
         update: (conversation: Conversation) => Promise<void>;
         rename: (conversationId: string, title: string) => Promise<Conversation | undefined>;
         delete: (conversationId: string) => Promise<boolean>;
         search: (query: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
         appendSubagentResult: (conversationId: string, result: PendingSubagentResult) => Promise<void>;
         clearCallbackLock: (conversationId: string) => Promise<Conversation | undefined>;
+        listThreads: (parentConversationId: string) => Promise<ConversationSummary[]>;
     };
     memory: {
         get: (tenantId?: string | null) => Promise<MainMemory>;
@@ -1280,13 +1401,11 @@ declare abstract class SqlStorageEngine implements StorageEngine {
     };
     reminders: {
         list: (tenantId?: string | null) => Promise<Reminder[]>;
-        create: (input: {
-            task: string;
-            scheduledAt: number;
-            timezone?: string;
-            conversationId: string;
-            ownerId?: string;
-            tenantId?: string | null;
+        create: (input: ReminderCreateInput) => Promise<Reminder>;
+        update: (id: string, fields: {
+            scheduledAt?: number;
+            occurrenceCount?: number;
+            status?: ReminderStatus;
         }) => Promise<Reminder>;
         cancel: (id: string) => Promise<Reminder>;
         delete: (id: string) => Promise<void>;
@@ -1419,12 +1538,15 @@ declare class BashEnvironmentManager {
     private engine;
     private limits;
     private environments;
+    private filesystems;
     private readonly workingDir;
     private readonly bashOptions;
     constructor(engine: StorageEngine, limits: {
         maxFileSize: number;
         maxTotalStorage: number;
     }, workingDir: string | null, bashConfig?: BashConfig, network?: NetworkConfig);
+    /** Return the combined IFileSystem (VFS + optional /project mount) for a tenant. */
+    getFs(tenantId: string): IFileSystem;
     getOrCreate(tenantId: string): Bash;
     getAdapter(tenantId: string): PonchoFsAdapter;
     /** Refresh the PostgreSQL path cache before a bash.exec() call. */
@@ -1447,4 +1569,245 @@ declare function verifyTenantToken(signingKey: string, token: string): Promise<T
 
 declare const createSubagentTools: (manager: SubagentManager) => ToolDefinition[];
 
-export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type Conversation, type ConversationState, type ConversationStore, type ConversationSummary, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentResult, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Reminder, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, buildAgentDirectoryName, buildSkillContextWindow, compactMessages, completeOpenAICodexDeviceAuth, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createUploadStore, createWriteTool, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, findSafeSplitPoint, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readOpenAICodexSession, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, writeOpenAICodexSession };
+type HistorySource = "harness" | "continuation" | "messages";
+type RunRequest = {
+    conversationId: string;
+    messages: Message[];
+    preferContinuation?: boolean;
+};
+type RunOutcome = {
+    source: HistorySource;
+    shouldRebuildCanonical: boolean;
+    messages: Message[];
+};
+declare const isMessageArray: (value: unknown) => value is Message[];
+declare const loadCanonicalHistory: (conversation: Conversation) => {
+    messages: Message[];
+    source: HistorySource;
+};
+declare const loadRunHistory: (conversation: Conversation, options?: {
+    preferContinuation?: boolean;
+}) => {
+    messages: Message[];
+    source: HistorySource;
+    shouldRebuildCanonical: boolean;
+};
+declare const resolveRunRequest: (conversation: Conversation, request: RunRequest) => RunOutcome;
+
+type StoredApproval = NonNullable<Conversation["pendingApprovals"]>[number];
+type PendingToolCall = {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type ApprovalEventItem = {
+    approvalId: string;
+    tool: string;
+    toolCallId?: string;
+    input: Record<string, unknown>;
+};
+type TurnSection = {
+    type: "text" | "tools";
+    content: string | string[];
+};
+type TurnDraftState = {
+    assistantResponse: string;
+    toolTimeline: string[];
+    sections: TurnSection[];
+    currentTools: string[];
+    currentText: string;
+};
+type ExecuteTurnResult = {
+    latestRunId: string;
+    runCancelled: boolean;
+    runContinuation: boolean;
+    runContinuationMessages?: Message[];
+    runHarnessMessages?: Message[];
+    runContextTokens: number;
+    runContextWindow: number;
+    runSteps: number;
+    runMaxSteps?: number;
+    draft: TurnDraftState;
+};
+type TurnResultMetadata = {
+    latestRunId: string;
+    contextTokens: number;
+    contextWindow: number;
+    continuation?: boolean;
+    continuationMessages?: Message[];
+    harnessMessages?: Message[];
+    toolResultArchive?: Conversation["_toolResultArchive"];
+};
+declare const createTurnDraftState: () => TurnDraftState;
+declare const cloneSections: (sections: TurnSection[]) => TurnSection[];
+declare const flushTurnDraft: (draft: TurnDraftState) => void;
+/** Build enriched tool:completed text with input details (bash command, URL, etc.) */
+declare const buildToolCompletedText: (event: AgentEvent & {
+    type: "tool:completed";
+}) => string;
+declare const recordStandardTurnEvent: (draft: TurnDraftState, event: AgentEvent) => void;
+declare const buildAssistantMetadata: (draft: TurnDraftState, sectionsOverride?: TurnSection[], opts?: {
+    id?: string;
+    timestamp?: number;
+}) => Message["metadata"] | undefined;
+declare const executeConversationTurn: ({ harness, runInput, events, initialContextTokens, initialContextWindow, onEvent, }: {
+    harness: AgentHarness;
+    runInput?: Parameters<AgentHarness["runWithTelemetry"]>[0];
+    events?: AsyncIterable<AgentEvent>;
+    initialContextTokens?: number;
+    initialContextWindow?: number;
+    onEvent?: (event: AgentEvent, draft: TurnDraftState) => void | Promise<void>;
+}) => Promise<ExecuteTurnResult>;
+declare const normalizeApprovalCheckpoint: (approval: StoredApproval, fallbackMessages: Message[]) => StoredApproval;
+declare const buildApprovalCheckpoints: ({ approvals, runId, checkpointMessages, baseMessageCount, pendingToolCalls, }: {
+    approvals: ApprovalEventItem[];
+    runId: string;
+    checkpointMessages: Message[];
+    baseMessageCount: number;
+    pendingToolCalls: PendingToolCall[];
+}) => NonNullable<Conversation["pendingApprovals"]>;
+declare const applyTurnMetadata: (conv: Conversation, meta: TurnResultMetadata, opts?: {
+    clearContinuation?: boolean;
+    clearApprovals?: boolean;
+    setIdle?: boolean;
+    shouldRebuildCanonical?: boolean;
+}) => void;
+
+declare const TOOL_RESULT_ARCHIVE_PARAM = "__toolResultArchive";
+declare const withToolResultArchiveParam: (parameters: Record<string, unknown> | undefined, conversation: Conversation) => Record<string, unknown>;
+declare const MAX_CONTINUATION_COUNT = 20;
+
+type ActiveSubagentRun = {
+    abortController: AbortController;
+    harness: AgentHarness;
+    parentConversationId: string;
+};
+type PendingSubagentApproval = {
+    resolve: (decidedApprovals: NonNullable<Conversation["pendingApprovals"]>) => void;
+    childHarness: AgentHarness;
+    checkpoint: NonNullable<Conversation["pendingApprovals"]>[number];
+    childConversationId: string;
+    parentConversationId: string;
+};
+/** root -> L1 -> L2 = 3 levels; L2 cannot spawn further */
+declare const MAX_SUBAGENT_NESTING = 3;
+declare const MAX_CONCURRENT_SUBAGENTS = 2;
+declare const MAX_SUBAGENT_CALLBACK_COUNT = 20;
+declare const CALLBACK_LOCK_STALE_MS: number;
+declare const STALE_SUBAGENT_THRESHOLD_MS: number;
+
+type ActiveConversationRun = {
+    ownerId: string;
+    abortController: AbortController;
+    runId: string | null;
+};
+type EventSink = (conversationId: string, event: AgentEvent) => void | Promise<void>;
+interface OrchestratorHooks {
+    /** Called before a continuation run starts. Resets/creates event streams. */
+    onContinuationStart?(conversationId: string): void;
+    /** Called after a continuation run finishes. Cleans up event streams. */
+    onContinuationEnd?(conversationId: string): void;
+    /** Called when an approval checkpoint is stored during resumeRunFromCheckpoint.
+     *  Transport layer can use this for platform-specific notifications (e.g. Telegram). */
+    onApprovalCheckpoint?(conversationId: string, approvals: Array<{
+        approvalId: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }>): void;
+    /** Called after resumeRunFromCheckpoint completes. Transport layer can check
+     *  for pending subagent callbacks and manage stream lifecycle.
+     *  @deprecated Orchestrator handles post-resume subagent work internally in Phase 5+. */
+    onResumeComplete?(conversationId: string, checkpointedRun: boolean): void;
+    /** Create a child AgentHarness for subagent execution. Required for subagent support. */
+    createChildHarness?(): Promise<AgentHarness>;
+    /** Build recall parameters injected into run parameters for conversation context. */
+    buildRecallParams?(opts: {
+        ownerId: string;
+        tenantId?: string | null;
+        excludeConversationId: string;
+    }): Record<string, unknown>;
+    /** Dispatch a background task via serverless self-fetch. If not provided,
+     *  the orchestrator calls methods directly (long-lived mode). */
+    dispatchBackground?(type: "subagent-run" | "subagent-callback" | "continuation", conversationId: string): void;
+    /** Called when a conversation's event stream should be closed/finished. */
+    onStreamEnd?(conversationId: string): void;
+    /** Called when processSubagentCallback needs to open/reset the parent's event stream. */
+    onCallbackStreamReset?(conversationId: string): void;
+    /** Notify a messaging platform about a subagent callback result. */
+    onMessagingNotify?(conversationId: string, text: string): void;
+}
+/** @deprecated Use OrchestratorHooks instead */
+type ContinuationHooks = OrchestratorHooks;
+interface OrchestratorOptions {
+    harness: AgentHarness;
+    conversationStore: ConversationStore;
+    eventSink: EventSink;
+    telemetry?: TelemetryEmitter;
+    hooks?: OrchestratorHooks;
+    /** @deprecated Use hooks instead */
+    continuationHooks?: OrchestratorHooks;
+    /** Agent identity ID for tool context. Falls back to harness frontmatter ID. */
+    agentId?: string;
+    /** Working directory for tool context. */
+    workingDir?: string;
+}
+declare class AgentOrchestrator {
+    readonly harness: AgentHarness;
+    readonly conversationStore: ConversationStore;
+    readonly eventSink: EventSink;
+    readonly telemetry?: TelemetryEmitter;
+    /** @internal */
+    hooks?: OrchestratorHooks;
+    private readonly agentId;
+    private readonly workingDir;
+    readonly activeConversationRuns: Map<string, ActiveConversationRun>;
+    readonly runOwners: Map<string, string>;
+    readonly runConversations: Map<string, string>;
+    readonly approvalDecisionTracker: Map<string, Map<string, boolean>>;
+    readonly activeSubagentRuns: Map<string, ActiveSubagentRun>;
+    readonly recentlySpawnedParents: Map<string, number>;
+    readonly pendingSubagentApprovals: Map<string, PendingSubagentApproval>;
+    readonly pendingCallbackNeeded: Set<string>;
+    constructor(options: OrchestratorOptions);
+    setHooks(hooks: OrchestratorHooks): void;
+    /** @deprecated Use setHooks instead */
+    setContinuationHooks(hooks: OrchestratorHooks): void;
+    private get isServerless();
+    runContinuation(conversationId: string, onYield?: (event: AgentEvent) => void | Promise<void>): Promise<void>;
+    runChatContinuation(conversationId: string, conversation: Conversation, continuationMessages: Message[], onYield?: (event: AgentEvent) => void | Promise<void>): Promise<void>;
+    findPendingApproval(approvalId: string, owner: string): Promise<{
+        conversation: Conversation;
+        approval: StoredApproval;
+    } | undefined>;
+    resumeRunFromCheckpoint(conversationId: string, conversation: Conversation, checkpoint: StoredApproval, toolResults: Array<{
+        callId: string;
+        toolName: string;
+        result?: unknown;
+        error?: string;
+    }>): Promise<void>;
+    /** After a resume completes, check for deferred subagent callbacks. */
+    private _handlePostResumeWork;
+    hasRunningSubagentsForParent(parentConversationId: string): boolean;
+    getRunningSubagentCountForParent(parentId: string): number;
+    getSubagentDepth(conversationId: string): Promise<number>;
+    hasPendingSubagentWorkForParent(parentConversationId: string, _owner: string): Promise<boolean>;
+    /**
+     * Submit an approval decision for a pending subagent approval.
+     * Returns whether the approval was found, the child conversation, and whether all approvals are now decided.
+     */
+    submitSubagentApprovalDecision(approvalId: string, approved: boolean): Promise<{
+        found: boolean;
+        childConversationId?: string;
+        allDecided: boolean;
+    }>;
+    handleSubagentCompletion(subagentId: string): Promise<void>;
+    resumeSubagentFromCheckpoint(subagentId: string): Promise<void>;
+    runSubagent(childConversationId: string, parentConversationId: string, task: string, ownerId: string): Promise<void>;
+    triggerParentCallback(parentConversationId: string): Promise<void>;
+    processSubagentCallback(conversationId: string, skipLockCheck?: boolean): Promise<void>;
+    runSubagentContinuation(conversationId: string, conversation: Conversation, continuationMessages: Message[]): AsyncGenerator<AgentEvent>;
+    createSubagentManager(): SubagentManager;
+    recoverStaleSubagents(): Promise<void>;
+}
+
+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 CronJobConfig, 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 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 RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, 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, 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, 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, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };