@poncho-ai/harness 0.41.0 → 0.42.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.42.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/index.js            504.78 KB
 ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 238ms
+ESM ⚡️ Build success in 228ms
 DTS Build start
-DTS ⚡️ Build success in 7385ms
-DTS dist/index.d.ts 77.00 KB
+DTS ⚡️ Build success in 7856ms
+DTS dist/index.d.ts 79.11 KB

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @poncho-ai/harness
 
+## 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';
@@ -1186,6 +1186,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 +1883,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, 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, 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

@@ -9654,6 +9654,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 +12995,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 {
@@ -13098,6 +13407,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.42.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

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/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,
+    };
+  }
+};