@poncho-ai/harness 0.41.0 → 0.43.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.41.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.43.0 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            493.42 KB
 ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 238ms
+ESM dist/index.js            506.40 KB
+ESM ⚡️ Build success in 222ms
 DTS Build start
-DTS ⚡️ Build success in 7385ms
-DTS dist/index.d.ts 77.00 KB
+DTS ⚡️ Build success in 6907ms
+DTS dist/index.d.ts 80.85 KB

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @poncho-ai/harness
 
+## 0.43.0
+
+### Minor Changes
+
+- [`ff89631`](https://github.com/cesr/poncho-ai/commit/ff89631715e54d6fdce174943e6e0fc9e4ce5d1e) Thanks [@cesr](https://github.com/cesr)! - harness: export `defaultAgentDefinition` so SDK consumers can match `poncho init` exactly
+
+  Lifts the `AGENT_TEMPLATE` markdown body from `@poncho-ai/cli` (where it lived
+  inside the `init` scaffolding) into a public helper on `@poncho-ai/harness`.
+  SDK consumers (PonchOS, custom servers, anyone calling
+  `new AgentHarness({ agentDefinition })` directly) can now do:
+
+  ```ts
+  import { defaultAgentDefinition } from "@poncho-ai/harness";
+
+  const harness = new AgentHarness({
+    agentDefinition: defaultAgentDefinition({
+      name: "poncho",
+      modelName: "claude-sonnet-4-6",
+    }),
+    // ... storageEngine, config, etc.
+  });
+  ```
+
+  This eliminates hand-copying the template — drift between consumers and
+  `poncho init` is no longer possible.
+
+  The CLI's `AGENT_TEMPLATE` export is preserved as a thin back-compat
+  wrapper that delegates to `defaultAgentDefinition`. No behavior change.
+
+  API additions (harness):
+  - `defaultAgentDefinition(opts?: DefaultAgentDefinitionOptions): string`
+  - `DefaultAgentDefinitionOptions`
+  - `DEFAULT_AGENT_NAME`, `DEFAULT_AGENT_DESCRIPTION`,
+    `DEFAULT_MODEL_PROVIDER`, `DEFAULT_MODEL_NAME`, `DEFAULT_TEMPERATURE`,
+    `DEFAULT_MAX_STEPS`, `DEFAULT_TIMEOUT` constants
+
+## 0.42.0
+
+### Minor Changes
+
+- [`39793b0`](https://github.com/cesr/poncho-ai/commit/39793b0ab11ed26f140af6fc9c0cd3e1b1c83fec) Thanks [@cesr](https://github.com/cesr)! - harness: extract `runConversationTurn` helper; refactor CLI to use it
+
+  Lifts the inline turn lifecycle from the CLI's
+  `POST /api/conversations/:id/messages` handler (~280 lines of orchestration)
+  into a new public helper at `@poncho-ai/harness`.
+
+  The helper handles the full conversation lifecycle for a primary chat
+  turn: load the conversation with archive, resolve canonical history,
+  upload files via the harness's upload store, build stable user/assistant
+  ids, persist the user message immediately, drive `executeConversationTurn`,
+  periodically persist the in-flight assistant draft on `step:completed`
+  and `tool:approval:required`, persist on `tool:approval:checkpoint` and
+  `run:completed` continuation, rebuild history on `compaction:completed`,
+  apply turn metadata on success, and persist partial state on
+  cancel/error.
+
+  Caller responsibilities (auth, active-run dedup, streaming, continuation
+  HTTP self-fetch, title inference) stay outside the helper — passed in
+  via opts or handled around the call. `opts.onEvent` is invoked for every
+  `AgentEvent` for downstream forwarding (SSE, WebSocket, telemetry, etc.).
+
+  The CLI's handler now delegates to `runConversationTurn` (drops from
+  ~430 to ~150 lines). Consumers like PonchOS can call the same helper
+  to ship the _exact_ same conversation lifecycle without duplicating
+  the orchestration.
+
+  Public API additions:
+  - `runConversationTurn(opts): Promise<RunConversationTurnResult>`
+  - `RunConversationTurnOpts`
+  - `RunConversationTurnResult`
+
+  No behavior changes. The helper is a verbatim extraction of the CLI's
+  prior inline implementation.
+
+### Patch Changes
+
+- [`111d24e`](https://github.com/cesr/poncho-ai/commit/111d24efaab054ef7543c396085f8f4d41e7976a) Thanks [@cesr](https://github.com/cesr)! - cli: include VFS skills in the chat input slash command menu
+
+  The `/api/slash-commands` endpoint was returning only repo-loaded skills,
+  so tenant-authored skills stored in the VFS (`/skills/<name>/SKILL.md`)
+  never appeared in the `/` autocomplete bar even though the agent could
+  already see and run them at conversation time.
+
+  The endpoint now resolves skills per-tenant via a new
+  `harness.listSkillsForTenant(tenantId)` and applies the same repo-wins
+  collision semantics used elsewhere in the harness.
+
 ## 0.41.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
 import * as _poncho_ai_sdk from '@poncho-ai/sdk';
-import { Message, ToolContext, ToolDefinition, JsonSchema, RunResult, AgentFailure, RunInput, AgentEvent } from '@poncho-ai/sdk';
+import { Message, ToolContext, ToolDefinition, JsonSchema, RunResult, AgentFailure, RunInput, AgentEvent, FileInput } from '@poncho-ai/sdk';
 export { ToolDefinition, defineTool } from '@poncho-ai/sdk';
 import { z } from 'zod';
 import { IFileSystem, BufferEncoding, FsStat, FileContent, MkdirOptions, RmOptions, CpOptions, Bash } from 'just-bash';
@@ -685,6 +685,43 @@ declare const resolveStateConfig: (config: PonchoConfig | undefined) => StateCon
 declare const resolveMemoryConfig: (config: PonchoConfig | undefined) => MemoryConfig | undefined;
 declare const loadPonchoConfig: (workingDir: string) => Promise<PonchoConfig | undefined>;
 
+interface DefaultAgentDefinitionOptions {
+    /** Display name for the agent. Default: "agent". */
+    name?: string;
+    /**
+     * Stable identifier embedded in the frontmatter. Default: a fresh
+     * `agent_<32hex>`. Note: when an injected `StorageEngine` is also passed
+     * to `AgentHarness`, the engine's `agentId` overrides this at runtime, so
+     * SDK consumers can leave it default.
+     */
+    id?: string;
+    /** Frontmatter description. Default: "A helpful Poncho assistant". */
+    description?: string;
+    /** Model provider. Default: "anthropic". */
+    modelProvider?: "anthropic" | "openai" | "openai-codex";
+    /** Model name. Default: "claude-opus-4-5". */
+    modelName?: string;
+    /** Sampling temperature. Default: 0.2. */
+    temperature?: number;
+    /** Max tool-call steps per run. Default: 20. */
+    maxSteps?: number;
+    /** Hard timeout in seconds. Default: 300. */
+    timeout?: number;
+}
+declare const DEFAULT_AGENT_NAME = "agent";
+declare const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+declare const DEFAULT_MODEL_PROVIDER: "anthropic";
+declare const DEFAULT_MODEL_NAME = "claude-opus-4-5";
+declare const DEFAULT_TEMPERATURE = 0.2;
+declare const DEFAULT_MAX_STEPS = 20;
+declare const DEFAULT_TIMEOUT = 300;
+/**
+ * Returns the canonical default agent definition as a markdown string,
+ * ready to pass to `new AgentHarness({ agentDefinition })`. This is the
+ * exact same template `poncho init` writes to `AGENT.md`.
+ */
+declare const defaultAgentDefinition: (opts?: DefaultAgentDefinitionOptions) => string;
+
 declare const createDefaultTools: (workingDir: string) => ToolDefinition[];
 declare const createWriteTool: (workingDir: string) => ToolDefinition;
 declare const createEditTool: (workingDir: string) => ToolDefinition;
@@ -1186,6 +1223,10 @@ declare class AgentHarness {
         name: string;
         description: string;
     }>;
+    listSkillsForTenant(tenantId: string | undefined | null): Promise<Array<{
+        name: string;
+        description: string;
+    }>>;
     /**
      * Wraps the run() generator with an OTel root span (invoke_agent) so all
      * child spans (LLM calls via AI SDK, tool execution) group under one trace.
@@ -1879,4 +1920,46 @@ declare class AgentOrchestrator {
     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 CreateSkillToolsOptions, 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, 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, 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, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+interface RunConversationTurnOpts {
+    /** Initialised harness instance. */
+    harness: AgentHarness;
+    /** Conversation store backing the turn (typically `engine.conversations` from a StorageEngine). */
+    conversationStore: ConversationStore;
+    conversationId: string;
+    /** The user's new message text. Required (use `""` if you only want to attach files). */
+    task: string;
+    /**
+     * Optional file attachments (FileInput.data is base64 / data URI / https URL).
+     * Files are uploaded via `harness.uploadStore` first so the persisted user
+     * message references stable URLs instead of fat base64 blobs.
+     */
+    files?: FileInput[];
+    /**
+     * Extra parameters merged into runInput.parameters. Use this for recall
+     * corpus, archive lookup keys, messaging metadata, etc. Do NOT include
+     * `__activeConversationId`, `__ownerId`, or the tool-result-archive — the
+     * helper sets those itself.
+     */
+    parameters?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+    tenantId?: string | null;
+    /** Per-event hook — called for every AgentEvent yielded by the run, in order. */
+    onEvent?: (event: AgentEvent) => void | Promise<void>;
+}
+interface RunConversationTurnResult {
+    /** runId of the most recent run started during this turn. */
+    latestRunId: string;
+    /** True if the run was cancelled (via abortSignal or run:cancelled event). */
+    cancelled: boolean;
+    /** True if the run errored. The error has been emitted via onEvent as run:error. */
+    errored: boolean;
+    /** True if the run requested a continuation. Caller is responsible for triggering the continuation. */
+    continuation: boolean;
+    /** True if the run paused at a tool-approval checkpoint. */
+    checkpointed: boolean;
+    contextTokens: number;
+    contextWindow: number;
+}
+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 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, 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, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -565,6 +565,53 @@ var loadPonchoConfig = async (workingDir) => {
   }
 };
 
+// src/default-agent.ts
+import { randomBytes } from "crypto";
+var DEFAULT_AGENT_NAME = "agent";
+var DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+var DEFAULT_MODEL_PROVIDER = "anthropic";
+var DEFAULT_MODEL_NAME = "claude-opus-4-5";
+var DEFAULT_TEMPERATURE = 0.2;
+var DEFAULT_MAX_STEPS = 20;
+var DEFAULT_TIMEOUT = 300;
+var defaultAgentDefinition = (opts = {}) => {
+  const name = opts.name ?? DEFAULT_AGENT_NAME;
+  const id = opts.id ?? `agent_${randomBytes(16).toString("hex")}`;
+  const description = opts.description ?? DEFAULT_AGENT_DESCRIPTION;
+  const modelProvider = opts.modelProvider ?? DEFAULT_MODEL_PROVIDER;
+  const modelName = opts.modelName ?? DEFAULT_MODEL_NAME;
+  const temperature = opts.temperature ?? DEFAULT_TEMPERATURE;
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+  return `---
+name: ${name}
+id: ${id}
+description: ${description}
+model:
+  provider: ${modelProvider}
+  name: ${modelName}
+  temperature: ${temperature}
+limits:
+  maxSteps: ${maxSteps}
+  timeout: ${timeout}
+---
+
+# {{name}}
+
+You are **{{name}}**, a helpful assistant built with Poncho.
+
+Working directory: {{runtime.workingDir}}
+Environment: {{runtime.environment}}
+
+## Task Guidance
+
+- Use tools when needed
+- Explain your reasoning clearly
+- Ask clarifying questions when requirements are ambiguous
+- Never claim a file/tool change unless the corresponding tool call actually succeeded
+`;
+};
+
 // src/default-tools.ts
 import { mkdir, readdir, readFile as readFile3, rm, unlink, writeFile as writeFile2 } from "fs/promises";
 import { dirname, resolve as resolve4, sep } from "path";
@@ -5562,14 +5609,14 @@ var createTodoTools = (store) => {
 };
 
 // src/secrets-store.ts
-import { createCipheriv, createDecipheriv, randomBytes, createHash as createHash3 } from "crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2, createHash as createHash3 } from "crypto";
 import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
 import { dirname as dirname3, resolve as resolve7 } from "path";
 function deriveKey(signingKey) {
   return createHash3("sha256").update("poncho-secrets-v1:" + signingKey).digest();
 }
 function encrypt(plaintext, key) {
-  const iv = randomBytes(12);
+  const iv = randomBytes2(12);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -9654,6 +9701,10 @@ var AgentHarness = class _AgentHarness {
   listSkills() {
     return this.loadedSkills.map((s) => ({ name: s.name, description: s.description }));
   }
+  async listSkillsForTenant(tenantId) {
+    const skills = await this.getSkillsForTenant(tenantId);
+    return skills.map((s) => ({ name: s.name, description: s.description }));
+  }
   /**
    * Wraps the run() generator with an OTel root span (invoke_agent) so all
    * child spans (LLM calls via AI SDK, tool execution) group under one trace.
@@ -12991,6 +13042,311 @@ ${resultBody}`,
   }
 };
 
+// src/orchestrator/run-conversation-turn.ts
+import { randomUUID as randomUUID6 } from "crypto";
+import { createLogger as createLogger7 } from "@poncho-ai/sdk";
+var log = createLogger7("orchestrator");
+var runConversationTurn = async (opts) => {
+  const conversation = await opts.conversationStore.getWithArchive(opts.conversationId);
+  if (!conversation) {
+    throw new Error(`Conversation not found: ${opts.conversationId}`);
+  }
+  const canonicalHistory = resolveRunRequest(conversation, {
+    conversationId: opts.conversationId,
+    messages: conversation.messages
+  });
+  const shouldRebuildCanonical = canonicalHistory.shouldRebuildCanonical;
+  const harnessMessages = [...canonicalHistory.messages];
+  const historyMessages = [...conversation.messages];
+  const preRunMessages = [...conversation.messages];
+  let userContent = opts.task;
+  if (opts.files && opts.files.length > 0 && opts.harness.uploadStore) {
+    const uploadedParts = await Promise.all(
+      opts.files.map(async (f) => {
+        const buf = Buffer.from(f.data, "base64");
+        const key = deriveUploadKey(buf, f.mediaType);
+        const ref = await opts.harness.uploadStore.put(key, buf, f.mediaType);
+        return {
+          type: "file",
+          data: ref,
+          mediaType: f.mediaType,
+          filename: f.filename
+        };
+      })
+    );
+    userContent = [
+      { type: "text", text: opts.task },
+      ...uploadedParts
+    ];
+  }
+  const turnTimestamp = Date.now();
+  const userMessage = {
+    role: "user",
+    content: userContent,
+    metadata: { id: randomUUID6(), timestamp: turnTimestamp }
+  };
+  const assistantId = randomUUID6();
+  const draft = createTurnDraftState();
+  let latestRunId = conversation.runtimeRunId ?? "";
+  let runCancelled = false;
+  let runContinuationMessages;
+  let cancelHarnessMessages;
+  let checkpointedRun = false;
+  const buildMessages = () => {
+    const draftSections = cloneSections(draft.sections);
+    if (draft.currentTools.length > 0) {
+      draftSections.push({ type: "tools", content: [...draft.currentTools] });
+    }
+    if (draft.currentText.length > 0) {
+      draftSections.push({ type: "text", content: draft.currentText });
+    }
+    const userTurn = [userMessage];
+    const hasDraftContent = draft.assistantResponse.length > 0 || draft.toolTimeline.length > 0 || draftSections.length > 0;
+    if (!hasDraftContent) {
+      return [...historyMessages, ...userTurn];
+    }
+    return [
+      ...historyMessages,
+      ...userTurn,
+      {
+        role: "assistant",
+        content: draft.assistantResponse,
+        metadata: buildAssistantMetadata(draft, draftSections, {
+          id: assistantId,
+          timestamp: turnTimestamp
+        })
+      }
+    ];
+  };
+  const persistDraft = async () => {
+    if (draft.assistantResponse.length === 0 && draft.toolTimeline.length === 0) return;
+    conversation.messages = buildMessages();
+    conversation.updatedAt = Date.now();
+    await opts.conversationStore.update(conversation);
+  };
+  conversation.messages = [...historyMessages, userMessage];
+  conversation.subagentCallbackCount = 0;
+  conversation._continuationCount = void 0;
+  conversation.updatedAt = Date.now();
+  opts.conversationStore.update(conversation).catch((err) => {
+    log.error(
+      `failed to persist user turn: ${err instanceof Error ? err.message : String(err)}`
+    );
+  });
+  try {
+    const execution = await executeConversationTurn({
+      harness: opts.harness,
+      runInput: {
+        task: opts.task,
+        conversationId: opts.conversationId,
+        tenantId: opts.tenantId ?? void 0,
+        parameters: withToolResultArchiveParam(
+          {
+            ...opts.parameters ?? {},
+            __activeConversationId: opts.conversationId,
+            __ownerId: conversation.ownerId
+          },
+          conversation
+        ),
+        messages: harnessMessages,
+        files: opts.files && opts.files.length > 0 ? opts.files : void 0,
+        abortSignal: opts.abortSignal
+      },
+      initialContextTokens: conversation.contextTokens ?? 0,
+      initialContextWindow: conversation.contextWindow ?? 0,
+      onEvent: async (event, eventDraft) => {
+        draft.assistantResponse = eventDraft.assistantResponse;
+        draft.toolTimeline = eventDraft.toolTimeline;
+        draft.sections = eventDraft.sections;
+        draft.currentTools = eventDraft.currentTools;
+        draft.currentText = eventDraft.currentText;
+        if (event.type === "run:started") {
+          latestRunId = event.runId;
+        }
+        if (event.type === "run:cancelled") {
+          runCancelled = true;
+          if (event.messages) cancelHarnessMessages = event.messages;
+        }
+        if (event.type === "compaction:completed") {
+          if (event.compactedMessages) {
+            historyMessages.length = 0;
+            historyMessages.push(...event.compactedMessages);
+            const preservedFromHistory = historyMessages.length - 1;
+            const removedCount = preRunMessages.length - Math.max(0, preservedFromHistory);
+            const existingHistory = conversation.compactedHistory ?? [];
+            conversation.compactedHistory = [
+              ...existingHistory,
+              ...preRunMessages.slice(0, removedCount)
+            ];
+          }
+        }
+        if (event.type === "step:completed") {
+          await persistDraft();
+        }
+        if (event.type === "tool:approval:required") {
+          const toolText = `- approval required \`${event.tool}\``;
+          draft.toolTimeline.push(toolText);
+          draft.currentTools.push(toolText);
+          const existing = Array.isArray(conversation.pendingApprovals) ? conversation.pendingApprovals : [];
+          if (!existing.some((a) => a.approvalId === event.approvalId)) {
+            conversation.pendingApprovals = [
+              ...existing,
+              {
+                approvalId: event.approvalId,
+                runId: latestRunId || conversation.runtimeRunId || "",
+                tool: event.tool,
+                toolCallId: void 0,
+                input: event.input ?? {},
+                checkpointMessages: void 0,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: []
+              }
+            ];
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+          await persistDraft();
+        }
+        if (event.type === "tool:approval:checkpoint") {
+          conversation.messages = buildMessages();
+          conversation.pendingApprovals = buildApprovalCheckpoints({
+            approvals: event.approvals,
+            runId: latestRunId,
+            checkpointMessages: event.checkpointMessages,
+            baseMessageCount: historyMessages.length,
+            pendingToolCalls: event.pendingToolCalls
+          });
+          conversation._toolResultArchive = opts.harness.getToolResultArchive(
+            opts.conversationId
+          );
+          conversation.updatedAt = Date.now();
+          await opts.conversationStore.update(conversation);
+          checkpointedRun = true;
+        }
+        if (event.type === "run:completed") {
+          if (event.result.continuation && event.result.continuationMessages) {
+            runContinuationMessages = event.result.continuationMessages;
+            conversation.messages = buildMessages();
+            conversation._continuationMessages = runContinuationMessages;
+            conversation._harnessMessages = runContinuationMessages;
+            conversation._toolResultArchive = opts.harness.getToolResultArchive(
+              opts.conversationId
+            );
+            conversation.runtimeRunId = latestRunId || conversation.runtimeRunId;
+            if (!checkpointedRun) {
+              conversation.pendingApprovals = [];
+            }
+            if ((event.result.contextTokens ?? 0) > 0) {
+              conversation.contextTokens = event.result.contextTokens;
+            }
+            if ((event.result.contextWindow ?? 0) > 0) {
+              conversation.contextWindow = event.result.contextWindow;
+            }
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+        }
+        if (opts.onEvent) {
+          await opts.onEvent(event);
+        }
+      }
+    });
+    flushTurnDraft(draft);
+    latestRunId = execution.latestRunId || latestRunId;
+    if (!checkpointedRun && !runContinuationMessages) {
+      conversation.messages = buildMessages();
+      applyTurnMetadata(
+        conversation,
+        {
+          latestRunId,
+          contextTokens: execution.runContextTokens,
+          contextWindow: execution.runContextWindow,
+          harnessMessages: execution.runHarnessMessages,
+          toolResultArchive: opts.harness.getToolResultArchive(opts.conversationId)
+        },
+        { shouldRebuildCanonical }
+      );
+      await opts.conversationStore.update(conversation);
+    }
+    return {
+      latestRunId,
+      cancelled: runCancelled,
+      errored: false,
+      continuation: !!runContinuationMessages,
+      checkpointed: checkpointedRun,
+      contextTokens: execution.runContextTokens,
+      contextWindow: execution.runContextWindow
+    };
+  } catch (error) {
+    flushTurnDraft(draft);
+    const aborted = opts.abortSignal?.aborted === true;
+    if (aborted || runCancelled) {
+      if (draft.assistantResponse.length > 0 || draft.toolTimeline.length > 0 || draft.sections.length > 0) {
+        conversation.messages = buildMessages();
+        applyTurnMetadata(
+          conversation,
+          {
+            latestRunId,
+            contextTokens: 0,
+            contextWindow: 0,
+            harnessMessages: cancelHarnessMessages,
+            toolResultArchive: opts.harness.getToolResultArchive(opts.conversationId)
+          },
+          { shouldRebuildCanonical: true }
+        );
+        await opts.conversationStore.update(conversation);
+      }
+      if (!checkpointedRun) {
+        const fresh = await opts.conversationStore.get(opts.conversationId);
+        if (fresh && Array.isArray(fresh.pendingApprovals) && fresh.pendingApprovals.length > 0) {
+          fresh.pendingApprovals = [];
+          await opts.conversationStore.update(fresh);
+        }
+      }
+      return {
+        latestRunId,
+        cancelled: true,
+        errored: false,
+        continuation: false,
+        checkpointed: checkpointedRun,
+        contextTokens: 0,
+        contextWindow: 0
+      };
+    }
+    const errorEvent = {
+      type: "run:error",
+      runId: latestRunId || "run_unknown",
+      error: {
+        code: "RUN_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error"
+      }
+    };
+    if (opts.onEvent) {
+      try {
+        await opts.onEvent(errorEvent);
+      } catch (hookErr) {
+        log.error(
+          `onEvent threw on run:error: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`
+        );
+      }
+    }
+    if (draft.assistantResponse.length > 0 || draft.toolTimeline.length > 0 || draft.sections.length > 0) {
+      conversation.messages = buildMessages();
+      conversation.updatedAt = Date.now();
+      await opts.conversationStore.update(conversation);
+    }
+    return {
+      latestRunId,
+      cancelled: false,
+      errored: true,
+      continuation: false,
+      checkpointed: checkpointedRun,
+      contextTokens: 0,
+      contextWindow: 0
+    };
+  }
+};
+
 // src/index.ts
 import { defineTool as defineTool13 } from "@poncho-ai/sdk";
 export {
@@ -12998,6 +13354,13 @@ export {
   AgentOrchestrator,
   BashEnvironmentManager,
   CALLBACK_LOCK_STALE_MS,
+  DEFAULT_AGENT_DESCRIPTION,
+  DEFAULT_AGENT_NAME,
+  DEFAULT_MAX_STEPS,
+  DEFAULT_MODEL_NAME,
+  DEFAULT_MODEL_PROVIDER,
+  DEFAULT_TEMPERATURE,
+  DEFAULT_TIMEOUT,
   InMemoryConversationStore,
   InMemoryEngine,
   InMemoryStateStore,
@@ -13054,6 +13417,7 @@ export {
   createTurnDraftState,
   createUploadStore,
   createWriteTool,
+  defaultAgentDefinition,
   defineTool13 as defineTool,
   deleteOpenAICodexSession,
   deriveUploadKey,
@@ -13098,6 +13462,7 @@ export {
   resolveRunRequest,
   resolveSkillDirs,
   resolveStateConfig,
+  runConversationTurn,
   slugifyStorageComponent,
   startOpenAICodexDeviceAuth,
   verifyTenantToken,

package/package.json

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

package/src/default-agent.ts

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// Canonical default agent definition.
+//
+// This is the same agent.md a fresh `poncho init` produces. The CLI's
+// AGENT_TEMPLATE in `packages/cli/src/templates.ts` delegates to this helper
+// so there is exactly one source of truth, and SDK consumers (PonchOS, custom
+// servers, etc.) can pass the same default to `new AgentHarness({ agentDefinition: ... })`
+// without hand-copying the template.
+// ---------------------------------------------------------------------------
+
+import { randomBytes } from "node:crypto";
+
+export interface DefaultAgentDefinitionOptions {
+  /** Display name for the agent. Default: "agent". */
+  name?: string;
+  /**
+   * Stable identifier embedded in the frontmatter. Default: a fresh
+   * `agent_<32hex>`. Note: when an injected `StorageEngine` is also passed
+   * to `AgentHarness`, the engine's `agentId` overrides this at runtime, so
+   * SDK consumers can leave it default.
+   */
+  id?: string;
+  /** Frontmatter description. Default: "A helpful Poncho assistant". */
+  description?: string;
+  /** Model provider. Default: "anthropic". */
+  modelProvider?: "anthropic" | "openai" | "openai-codex";
+  /** Model name. Default: "claude-opus-4-5". */
+  modelName?: string;
+  /** Sampling temperature. Default: 0.2. */
+  temperature?: number;
+  /** Max tool-call steps per run. Default: 20. */
+  maxSteps?: number;
+  /** Hard timeout in seconds. Default: 300. */
+  timeout?: number;
+}
+
+export const DEFAULT_AGENT_NAME = "agent";
+export const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+export const DEFAULT_MODEL_PROVIDER = "anthropic" as const;
+export const DEFAULT_MODEL_NAME = "claude-opus-4-5";
+export const DEFAULT_TEMPERATURE = 0.2;
+export const DEFAULT_MAX_STEPS = 20;
+export const DEFAULT_TIMEOUT = 300;
+
+/**
+ * Returns the canonical default agent definition as a markdown string,
+ * ready to pass to `new AgentHarness({ agentDefinition })`. This is the
+ * exact same template `poncho init` writes to `AGENT.md`.
+ */
+export const defaultAgentDefinition = (
+  opts: DefaultAgentDefinitionOptions = {},
+): string => {
+  const name = opts.name ?? DEFAULT_AGENT_NAME;
+  const id = opts.id ?? `agent_${randomBytes(16).toString("hex")}`;
+  const description = opts.description ?? DEFAULT_AGENT_DESCRIPTION;
+  const modelProvider = opts.modelProvider ?? DEFAULT_MODEL_PROVIDER;
+  const modelName = opts.modelName ?? DEFAULT_MODEL_NAME;
+  const temperature = opts.temperature ?? DEFAULT_TEMPERATURE;
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+
+  return `---
+name: ${name}
+id: ${id}
+description: ${description}
+model:
+  provider: ${modelProvider}
+  name: ${modelName}
+  temperature: ${temperature}
+limits:
+  maxSteps: ${maxSteps}
+  timeout: ${timeout}
+---
+
+# {{name}}
+
+You are **{{name}}**, a helpful assistant built with Poncho.
+
+Working directory: {{runtime.workingDir}}
+Environment: {{runtime.environment}}
+
+## Task Guidance
+
+- Use tools when needed
+- Explain your reasoning clearly
+- Ask clarifying questions when requirements are ambiguous
+- Never claim a file/tool change unless the corresponding tool call actually succeeded
+`;
+};

package/src/harness.ts

@@ -1940,6 +1940,13 @@ export class AgentHarness {
     return this.loadedSkills.map((s) => ({ name: s.name, description: s.description }));
   }
 
+  async listSkillsForTenant(
+    tenantId: string | undefined | null,
+  ): Promise<Array<{ name: string; description: string }>> {
+    const skills = await this.getSkillsForTenant(tenantId);
+    return skills.map((s) => ({ name: s.name, description: s.description }));
+  }
+
   /**
    * Wraps the run() generator with an OTel root span (invoke_agent) so all
    * child spans (LLM calls via AI SDK, tool execution) group under one trace.

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./agent-parser.js";
 export * from "./agent-identity.js";
 export * from "./compaction.js";
 export * from "./config.js";
+export * from "./default-agent.js";
 export * from "./default-tools.js";
 export * from "./harness.js";
 export * from "./memory.js";

package/src/orchestrator/index.ts

@@ -52,3 +52,9 @@ export {
   type ContinuationHooks,
   type OrchestratorOptions,
 } from "./orchestrator.js";
+
+export {
+  runConversationTurn,
+  type RunConversationTurnOpts,
+  type RunConversationTurnResult,
+} from "./run-conversation-turn.js";

package/src/orchestrator/run-conversation-turn.ts

@@ -0,0 +1,420 @@
+// ---------------------------------------------------------------------------
+// runConversationTurn — load-bearing helper that runs a single primary chat
+// turn end-to-end against a ConversationStore: loads the conversation,
+// persists the user message before the run, drives the model + tool loop
+// via executeConversationTurn, periodically persists the in-flight assistant
+// draft, handles approval checkpoints + continuations + cancellation, and
+// finalises the conversation row on completion.
+//
+// This was extracted from packages/cli/src/index.ts (POST
+// /api/conversations/:id/messages handler) so consumers other than the CLI
+// (PonchOS, custom servers) can ship the *same* conversation lifecycle
+// without copy-pasting hundreds of lines.
+//
+// Caller responsibilities (NOT done here):
+//   - auth / ownership checks
+//   - active-run dedup (one run at a time per conversation)
+//   - streaming events to a real client (use opts.onEvent)
+//   - triggering continuation runs after this returns continuation: true
+//   - conversation title inference (helper preserves existing title)
+// ---------------------------------------------------------------------------
+
+import { randomUUID } from "node:crypto";
+import type { AgentEvent, FileInput, Message } from "@poncho-ai/sdk";
+import { createLogger } from "@poncho-ai/sdk";
+import type { AgentHarness } from "../harness.js";
+import type { ConversationStore } from "../state.js";
+import { deriveUploadKey } from "../upload-store.js";
+import { withToolResultArchiveParam } from "./continuation.js";
+import { resolveRunRequest } from "./history.js";
+import {
+  applyTurnMetadata,
+  buildApprovalCheckpoints,
+  buildAssistantMetadata,
+  cloneSections,
+  createTurnDraftState,
+  executeConversationTurn,
+  flushTurnDraft,
+} from "./turn.js";
+
+const log = createLogger("orchestrator");
+
+export interface RunConversationTurnOpts {
+  /** Initialised harness instance. */
+  harness: AgentHarness;
+  /** Conversation store backing the turn (typically `engine.conversations` from a StorageEngine). */
+  conversationStore: ConversationStore;
+  conversationId: string;
+  /** The user's new message text. Required (use `""` if you only want to attach files). */
+  task: string;
+  /**
+   * Optional file attachments (FileInput.data is base64 / data URI / https URL).
+   * Files are uploaded via `harness.uploadStore` first so the persisted user
+   * message references stable URLs instead of fat base64 blobs.
+   */
+  files?: FileInput[];
+  /**
+   * Extra parameters merged into runInput.parameters. Use this for recall
+   * corpus, archive lookup keys, messaging metadata, etc. Do NOT include
+   * `__activeConversationId`, `__ownerId`, or the tool-result-archive — the
+   * helper sets those itself.
+   */
+  parameters?: Record<string, unknown>;
+  abortSignal?: AbortSignal;
+  tenantId?: string | null;
+  /** Per-event hook — called for every AgentEvent yielded by the run, in order. */
+  onEvent?: (event: AgentEvent) => void | Promise<void>;
+}
+
+export interface RunConversationTurnResult {
+  /** runId of the most recent run started during this turn. */
+  latestRunId: string;
+  /** True if the run was cancelled (via abortSignal or run:cancelled event). */
+  cancelled: boolean;
+  /** True if the run errored. The error has been emitted via onEvent as run:error. */
+  errored: boolean;
+  /** True if the run requested a continuation. Caller is responsible for triggering the continuation. */
+  continuation: boolean;
+  /** True if the run paused at a tool-approval checkpoint. */
+  checkpointed: boolean;
+  contextTokens: number;
+  contextWindow: number;
+}
+
+export const runConversationTurn = async (
+  opts: RunConversationTurnOpts,
+): Promise<RunConversationTurnResult> => {
+  const conversation = await opts.conversationStore.getWithArchive(opts.conversationId);
+  if (!conversation) {
+    throw new Error(`Conversation not found: ${opts.conversationId}`);
+  }
+
+  const canonicalHistory = resolveRunRequest(conversation, {
+    conversationId: opts.conversationId,
+    messages: conversation.messages,
+  });
+  const shouldRebuildCanonical = canonicalHistory.shouldRebuildCanonical;
+  const harnessMessages = [...canonicalHistory.messages];
+  const historyMessages = [...conversation.messages];
+  const preRunMessages = [...conversation.messages];
+
+  // Build user content — upload any files first so the persisted message
+  // carries stable refs instead of fat base64 blobs.
+  let userContent: Message["content"] = opts.task;
+  if (opts.files && opts.files.length > 0 && opts.harness.uploadStore) {
+    const uploadedParts = await Promise.all(
+      opts.files.map(async (f) => {
+        const buf = Buffer.from(f.data, "base64");
+        const key = deriveUploadKey(buf, f.mediaType);
+        const ref = await opts.harness.uploadStore!.put(key, buf, f.mediaType);
+        return {
+          type: "file" as const,
+          data: ref,
+          mediaType: f.mediaType,
+          filename: f.filename,
+        };
+      }),
+    );
+    userContent = [
+      { type: "text" as const, text: opts.task },
+      ...uploadedParts,
+    ];
+  }
+
+  const turnTimestamp = Date.now();
+  const userMessage: Message = {
+    role: "user",
+    content: userContent,
+    metadata: { id: randomUUID(), timestamp: turnTimestamp },
+  };
+  const assistantId = randomUUID();
+  const draft = createTurnDraftState();
+
+  let latestRunId = conversation.runtimeRunId ?? "";
+  let runCancelled = false;
+  let runContinuationMessages: Message[] | undefined;
+  let cancelHarnessMessages: Message[] | undefined;
+  let checkpointedRun = false;
+
+  const buildMessages = (): Message[] => {
+    const draftSections = cloneSections(draft.sections);
+    if (draft.currentTools.length > 0) {
+      draftSections.push({ type: "tools", content: [...draft.currentTools] });
+    }
+    if (draft.currentText.length > 0) {
+      draftSections.push({ type: "text", content: draft.currentText });
+    }
+    const userTurn: Message[] = [userMessage];
+    const hasDraftContent =
+      draft.assistantResponse.length > 0 ||
+      draft.toolTimeline.length > 0 ||
+      draftSections.length > 0;
+    if (!hasDraftContent) {
+      return [...historyMessages, ...userTurn];
+    }
+    return [
+      ...historyMessages,
+      ...userTurn,
+      {
+        role: "assistant" as const,
+        content: draft.assistantResponse,
+        metadata: buildAssistantMetadata(draft, draftSections, {
+          id: assistantId,
+          timestamp: turnTimestamp,
+        }),
+      },
+    ];
+  };
+
+  const persistDraft = async (): Promise<void> => {
+    if (draft.assistantResponse.length === 0 && draft.toolTimeline.length === 0) return;
+    conversation.messages = buildMessages();
+    conversation.updatedAt = Date.now();
+    await opts.conversationStore.update(conversation);
+  };
+
+  // Persist the user turn immediately so a crash mid-run still records what
+  // the user said. Fire-and-forget — don't block the run.
+  conversation.messages = [...historyMessages, userMessage];
+  conversation.subagentCallbackCount = 0;
+  conversation._continuationCount = undefined;
+  conversation.updatedAt = Date.now();
+  opts.conversationStore.update(conversation).catch((err) => {
+    log.error(
+      `failed to persist user turn: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+
+  try {
+    const execution = await executeConversationTurn({
+      harness: opts.harness,
+      runInput: {
+        task: opts.task,
+        conversationId: opts.conversationId,
+        tenantId: opts.tenantId ?? undefined,
+        parameters: withToolResultArchiveParam(
+          {
+            ...(opts.parameters ?? {}),
+            __activeConversationId: opts.conversationId,
+            __ownerId: conversation.ownerId,
+          },
+          conversation,
+        ),
+        messages: harnessMessages,
+        files: opts.files && opts.files.length > 0 ? opts.files : undefined,
+        abortSignal: opts.abortSignal,
+      },
+      initialContextTokens: conversation.contextTokens ?? 0,
+      initialContextWindow: conversation.contextWindow ?? 0,
+      onEvent: async (event, eventDraft) => {
+        // Sync our outer draft from the executor's so persistDraft sees the latest state.
+        draft.assistantResponse = eventDraft.assistantResponse;
+        draft.toolTimeline = eventDraft.toolTimeline;
+        draft.sections = eventDraft.sections;
+        draft.currentTools = eventDraft.currentTools;
+        draft.currentText = eventDraft.currentText;
+
+        if (event.type === "run:started") {
+          latestRunId = event.runId;
+        }
+        if (event.type === "run:cancelled") {
+          runCancelled = true;
+          if (event.messages) cancelHarnessMessages = event.messages;
+        }
+        if (event.type === "compaction:completed") {
+          if (event.compactedMessages) {
+            historyMessages.length = 0;
+            historyMessages.push(...event.compactedMessages);
+            const preservedFromHistory = historyMessages.length - 1;
+            const removedCount =
+              preRunMessages.length - Math.max(0, preservedFromHistory);
+            const existingHistory = conversation.compactedHistory ?? [];
+            conversation.compactedHistory = [
+              ...existingHistory,
+              ...preRunMessages.slice(0, removedCount),
+            ];
+          }
+        }
+        if (event.type === "step:completed") {
+          await persistDraft();
+        }
+        if (event.type === "tool:approval:required") {
+          const toolText = `- approval required \`${event.tool}\``;
+          draft.toolTimeline.push(toolText);
+          draft.currentTools.push(toolText);
+          const existing = Array.isArray(conversation.pendingApprovals)
+            ? conversation.pendingApprovals
+            : [];
+          if (!existing.some((a) => a.approvalId === event.approvalId)) {
+            conversation.pendingApprovals = [
+              ...existing,
+              {
+                approvalId: event.approvalId,
+                runId: latestRunId || conversation.runtimeRunId || "",
+                tool: event.tool,
+                toolCallId: undefined,
+                input: (event.input ?? {}) as Record<string, unknown>,
+                checkpointMessages: undefined,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: [],
+              },
+            ];
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+          await persistDraft();
+        }
+        if (event.type === "tool:approval:checkpoint") {
+          conversation.messages = buildMessages();
+          conversation.pendingApprovals = buildApprovalCheckpoints({
+            approvals: event.approvals,
+            runId: latestRunId,
+            checkpointMessages: event.checkpointMessages,
+            baseMessageCount: historyMessages.length,
+            pendingToolCalls: event.pendingToolCalls,
+          });
+          conversation._toolResultArchive = opts.harness.getToolResultArchive(
+            opts.conversationId,
+          );
+          conversation.updatedAt = Date.now();
+          await opts.conversationStore.update(conversation);
+          checkpointedRun = true;
+        }
+        if (event.type === "run:completed") {
+          if (event.result.continuation && event.result.continuationMessages) {
+            runContinuationMessages = event.result.continuationMessages;
+            conversation.messages = buildMessages();
+            conversation._continuationMessages = runContinuationMessages;
+            conversation._harnessMessages = runContinuationMessages;
+            conversation._toolResultArchive = opts.harness.getToolResultArchive(
+              opts.conversationId,
+            );
+            conversation.runtimeRunId = latestRunId || conversation.runtimeRunId;
+            if (!checkpointedRun) {
+              conversation.pendingApprovals = [];
+            }
+            if ((event.result.contextTokens ?? 0) > 0) {
+              conversation.contextTokens = event.result.contextTokens!;
+            }
+            if ((event.result.contextWindow ?? 0) > 0) {
+              conversation.contextWindow = event.result.contextWindow!;
+            }
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+        }
+
+        if (opts.onEvent) {
+          await opts.onEvent(event);
+        }
+      },
+    });
+
+    flushTurnDraft(draft);
+    latestRunId = execution.latestRunId || latestRunId;
+
+    if (!checkpointedRun && !runContinuationMessages) {
+      conversation.messages = buildMessages();
+      applyTurnMetadata(
+        conversation,
+        {
+          latestRunId,
+          contextTokens: execution.runContextTokens,
+          contextWindow: execution.runContextWindow,
+          harnessMessages: execution.runHarnessMessages,
+          toolResultArchive: opts.harness.getToolResultArchive(opts.conversationId),
+        },
+        { shouldRebuildCanonical },
+      );
+      await opts.conversationStore.update(conversation);
+    }
+
+    return {
+      latestRunId,
+      cancelled: runCancelled,
+      errored: false,
+      continuation: !!runContinuationMessages,
+      checkpointed: checkpointedRun,
+      contextTokens: execution.runContextTokens,
+      contextWindow: execution.runContextWindow,
+    };
+  } catch (error) {
+    flushTurnDraft(draft);
+    const aborted = opts.abortSignal?.aborted === true;
+    if (aborted || runCancelled) {
+      if (
+        draft.assistantResponse.length > 0 ||
+        draft.toolTimeline.length > 0 ||
+        draft.sections.length > 0
+      ) {
+        conversation.messages = buildMessages();
+        applyTurnMetadata(
+          conversation,
+          {
+            latestRunId,
+            contextTokens: 0,
+            contextWindow: 0,
+            harnessMessages: cancelHarnessMessages,
+            toolResultArchive: opts.harness.getToolResultArchive(opts.conversationId),
+          },
+          { shouldRebuildCanonical: true },
+        );
+        await opts.conversationStore.update(conversation);
+      }
+      if (!checkpointedRun) {
+        // Clear any pending approvals — the run was cancelled, they're stale.
+        const fresh = await opts.conversationStore.get(opts.conversationId);
+        if (fresh && Array.isArray(fresh.pendingApprovals) && fresh.pendingApprovals.length > 0) {
+          fresh.pendingApprovals = [];
+          await opts.conversationStore.update(fresh);
+        }
+      }
+      return {
+        latestRunId,
+        cancelled: true,
+        errored: false,
+        continuation: false,
+        checkpointed: checkpointedRun,
+        contextTokens: 0,
+        contextWindow: 0,
+      };
+    }
+
+    // Real error: emit run:error, persist whatever we have.
+    const errorEvent: AgentEvent = {
+      type: "run:error",
+      runId: latestRunId || "run_unknown",
+      error: {
+        code: "RUN_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+    };
+    if (opts.onEvent) {
+      try {
+        await opts.onEvent(errorEvent);
+      } catch (hookErr) {
+        log.error(
+          `onEvent threw on run:error: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`,
+        );
+      }
+    }
+    if (
+      draft.assistantResponse.length > 0 ||
+      draft.toolTimeline.length > 0 ||
+      draft.sections.length > 0
+    ) {
+      conversation.messages = buildMessages();
+      conversation.updatedAt = Date.now();
+      await opts.conversationStore.update(conversation);
+    }
+    return {
+      latestRunId,
+      cancelled: false,
+      errored: true,
+      continuation: false,
+      checkpointed: checkpointedRun,
+      contextTokens: 0,
+      contextWindow: 0,
+    };
+  }
+};