@xfey/tutti 0.1.111 → 0.1.112

package/dist/collaboration-state/clarification-snapshot.js

@@ -0,0 +1,29 @@
+import { mapMessageRow } from "./messages.js";
+/** Round messages are append-only; the eligible answer count is a stable CAS revision. */
+export function readClarificationAnswerRevision(db, roundId) {
+    return db
+        .prepare(`
+    SELECT COUNT(*) AS count FROM messages
+    WHERE scope_kind = 'clarification_round' AND clarification_round_id = ?
+      AND message_kind = 'user_text'
+      AND (author_kind = 'human' OR
+        (author_kind = 'system' AND json_extract(refs_json, '$.development_operator') = 1))
+  `)
+        .get(roundId).count;
+}
+/** Read the immutable submitted refs, not a first page or messages appended after sealing. */
+export function readSubmittedClarificationMessages(db, roundId) {
+    return db
+        .prepare(`
+    SELECT messages.* FROM clarification_rounds AS rounds
+    JOIN json_each(rounds.submitted_message_refs_json) AS submitted
+    JOIN messages ON messages.id = submitted.value
+    WHERE rounds.id = ? AND rounds.status = 'sealed'
+      AND messages.scope_kind = 'clarification_round'
+      AND messages.clarification_round_id = rounds.id
+    ORDER BY CAST(submitted.key AS INTEGER)
+  `)
+        .all(roundId)
+        .map((row) => mapMessageRow(row));
+}
+//# sourceMappingURL=clarification-snapshot.js.map

package/dist/collaboration-state/clarification-successors.js

@@ -15,7 +15,7 @@ export function submitClarificationRound(db, input) {
             return;
         }
         if (row.status === "sealed") {
-            round = mapClarificationRoundRow(row);
+            round = mapClarificationRoundRow(row, db);
             return;
         }
         const messageRows = db
@@ -64,7 +64,7 @@ export function materializeClarificationSuccessor(db, input) {
             return;
         }
         if (row.successor_status === "materialized") {
-            round = mapClarificationRoundRow(row);
+            round = mapClarificationRoundRow(row, db);
             return;
         }
         db.prepare(`
@@ -120,7 +120,7 @@ export function materializeTaskBoundRunSuccessor(db, input) {
             result = {
                 kind: "already_materialized",
                 thread: mapClarificationThreadRow(thread),
-                round: mapClarificationRoundRow(row),
+                round: mapClarificationRoundRow(row, db),
                 task: readTaskProjection(db, thread.owner_task_id),
             };
             return;
@@ -182,7 +182,7 @@ export function materializeTaskBoundRunSuccessor(db, input) {
         result = {
             kind: "materialized",
             thread: mapClarificationThreadRow(updatedThread),
-            round: mapClarificationRoundRow(updatedRound),
+            round: mapClarificationRoundRow(updatedRound, db),
             task: updatedTask,
         };
     })();
@@ -210,7 +210,7 @@ export function closeTaskBoundClarificationAsRetaskingRequired(db, input) {
             return {
                 kind: "already_materialized",
                 thread: mapClarificationThreadRow(thread),
-                round: mapClarificationRoundRow(row),
+                round: mapClarificationRoundRow(row, db),
                 task: readTaskProjection(tx, taskId),
                 task_detail: readTaskDetailProjection(tx, taskId),
             };
@@ -308,7 +308,7 @@ export function closeTaskBoundClarificationAsRetaskingRequired(db, input) {
         return {
             kind: "closed",
             thread: mapClarificationThreadRow(updatedThread),
-            round: mapClarificationRoundRow(updatedRound),
+            round: mapClarificationRoundRow(updatedRound, db),
             task,
             task_detail: taskDetail,
             message,

package/dist/collaboration-state/index.d.ts

@@ -1,4 +1,5 @@
 export { CollaborationStateCursorError } from "./serialization.js";
+export { readClarificationAnswerRevision, readSubmittedClarificationMessages, } from "./clarification-snapshot.js";
 export { createIdleExecutionStatusProjection } from "./execution-status.js";
 export { createMainChatAgentMessage, createMainChatMessage, createMainChatSystemMessage, ensureInitialProjectWelcomeMessage, hasMainChatArtifactPreviewMessage, hasMainChatTaskResultMessage, hasMainChatWorklistCompileMessage, hasMainChatWorklistFeedbackMessage, readCompletedWorklistFeedbackTaskIds, readMessageProjectionById, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMainChatMessagesForScratchpadCycle, } from "./messages.js";
 export { createEmptyScratchpadProjection, readScratchpadReceiptSourceRefs, readScratchpadProjection, upsertScratchpadProjection, } from "./scratchpad.js";

package/dist/collaboration-state/index.js

@@ -1,4 +1,5 @@
 export { CollaborationStateCursorError } from "./serialization.js";
+export { readClarificationAnswerRevision, readSubmittedClarificationMessages, } from "./clarification-snapshot.js";
 export { createIdleExecutionStatusProjection } from "./execution-status.js";
 export { createMainChatAgentMessage, createMainChatMessage, createMainChatSystemMessage, ensureInitialProjectWelcomeMessage, hasMainChatArtifactPreviewMessage, hasMainChatTaskResultMessage, hasMainChatWorklistCompileMessage, hasMainChatWorklistFeedbackMessage, readCompletedWorklistFeedbackTaskIds, readMessageProjectionById, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMainChatMessagesForScratchpadCycle, } from "./messages.js";
 export { createEmptyScratchpadProjection, readScratchpadReceiptSourceRefs, readScratchpadProjection, upsertScratchpadProjection, } from "./scratchpad.js";

package/dist/collaboration-state/run-recording.js

@@ -227,7 +227,7 @@ export function recordRunNeedsHumanResult(db, input) {
             task: updatedTask,
             task_detail: taskDetail,
             thread: mapClarificationThreadRow(thread),
-            round: mapClarificationRoundRow(round),
+            round: mapClarificationRoundRow(round, db),
             card_message: mapMessageRow(cardMessage, tx),
             opening_message: mapMessageRow(openingMessage),
         };

package/dist/collaboration-state/task-compile-context.d.ts

@@ -15,8 +15,8 @@ export declare function completeTaskCompileContext(db: SqliteDatabase, input: Co
     updated_by_activity_ref?: string;
     submitted_by_activity_ref?: string;
     submitted_by_workflow_ref?: string;
-    id: "current";
     state: "ready" | "empty" | "submitted";
+    id: "current";
     topic: string;
     background_summary: string;
     current_consensus: string[];

package/dist/collaboration-state/types.d.ts

@@ -279,6 +279,7 @@ export type CreateClarificationRoundMessageInput = {
     round_id: ClarificationRoundRef;
     body: string;
     author: MessageAuthorInput;
+    refs?: MessageProjection["refs"];
     now?: () => Date;
 };
 export type CreateClarificationRoundAgentMessageInput = {

package/dist/control-plane/clarification-commands.d.ts

@@ -2,13 +2,14 @@ import type { ClarificationRoundRef, IdempotencyKey } from "@tutti/shared/ids";
 import type { SendClarificationRoundMessageDisposition, SendClarificationRoundMessagePayload, SendClarificationRoundMessageResult, SubmitClarificationRoundDisposition, SubmitClarificationRoundPayload, SubmitClarificationRoundResult } from "@tutti/shared/schemas/api";
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
 import { type HostProjectStore } from "../store/index.js";
-import type { ControlPlaneCommandResult, TrustedHumanAuthor } from "./types.js";
+import type { ControlPlaneCommandResult } from "./types.js";
+import type { TrustedCollaborationAuthor } from "../collaboration-ingestion/types.js";
 export declare function runSendClarificationRoundMessage(options: {
     store: HostProjectStore;
     events: WorkspaceEventBus;
     roundId: ClarificationRoundRef;
     payload: SendClarificationRoundMessagePayload;
-    author: TrustedHumanAuthor;
+    author: TrustedCollaborationAuthor;
     now: () => Date;
 }): ControlPlaneCommandResult<SendClarificationRoundMessageDisposition, SendClarificationRoundMessageResult>;
 export declare function runSubmitClarificationRound(options: {

package/dist/control-plane/clarification-commands.js

@@ -1,4 +1,4 @@
-import { createClarificationRoundMessage, readActiveClarificationProjection, submitClarificationRound, } from "../collaboration-state/index.js";
+import { createClarificationRoundMessage, readActiveClarificationProjection, readClarificationAnswerRevision, submitClarificationRound, } from "../collaboration-state/index.js";
 import { withHostStoreTransaction } from "../store/index.js";
 import { enqueueControlPlaneIntent } from "./dispatch-intents.js";
 import { clarificationInvalidates } from "./invalidations.js";
@@ -19,11 +19,14 @@ export function runSendClarificationRoundMessage(options) {
         round_id: options.roundId,
         body: options.payload.body,
         author: {
-            kind: "human",
+            kind: options.author.kind === "development_operator" ? "system" : "human",
             ref: options.author.account_ref,
             display_name: options.author.display_name,
             ...(options.author.avatar === undefined ? {} : { avatar: options.author.avatar }),
         },
+        ...(options.author.kind === "development_operator"
+            ? { refs: { development_operator: true } }
+            : {}),
         now: options.now,
     });
     options.events.publish({
@@ -41,12 +44,11 @@ export function runSendClarificationRoundMessage(options) {
         invalidates: clarificationInvalidates(options.roundId, active.thread.id),
     });
     return {
-        disposition: { kind: "created" },
+        disposition: { kind: "created", message_id: message.id },
         result: { message },
     };
 }
 export function runSubmitClarificationRound(options) {
-    void options.payload;
     const active = readActiveClarificationProjection(options.store.db);
     if (active.state === "none") {
         return { disposition: { kind: "chain_closed" } };
@@ -71,6 +73,13 @@ export function runSubmitClarificationRound(options) {
             result: { round: active.round },
         };
     }
+    const answerRevision = readClarificationAnswerRevision(options.store.db, options.roundId);
+    if (options.payload.expected_answer_revision !== undefined &&
+        options.payload.expected_answer_revision !== answerRevision) {
+        return { disposition: { kind: "answers_changed", current_answer_revision: answerRevision } };
+    }
+    if (answerRevision === 0)
+        return { disposition: { kind: "no_answers" } };
     const sealed = withHostStoreTransaction(options.store.db, (tx) => {
         const submitted = submitClarificationRound(tx, {
             round_id: options.roundId,

package/dist/control-plane/follow-up-context.js

@@ -1,12 +1,10 @@
-import { readClarificationRoundMessagesWindow, readClarificationRoundProjection, readClarificationRoundsForThread, readTaskDetailProjection, readTaskRunResultsPage, } from "../collaboration-state/index.js";
+import { clarificationAnswerRole } from "@tutti/shared/utils";
+import { readSubmittedClarificationMessages, readClarificationRoundProjection, readClarificationRoundsForThread, readTaskDetailProjection, readTaskRunResultsPage, } from "../collaboration-state/index.js";
 import { toDomainRunLineage } from "./run-lineage.js";
 const CONTINUATION_CLARIFICATION_MESSAGE_LIMIT = 200;
 export function readFollowUpCheckInputFromStore(input) {
     const taskDetail = readTaskDetailProjection(input.db, input.task_id);
     const round = readClarificationRoundProjection(input.db, input.round_id);
-    const messagesWindow = readClarificationRoundMessagesWindow(input.db, input.round_id, {
-        anchor: "start",
-    });
     const latestRunResult = readTaskRunResultsPage(input.db, input.task_id, {
         limit: 1,
     })?.items[0];
@@ -29,7 +27,7 @@ export function readFollowUpCheckInputFromStore(input) {
             clarification_round_ref: input.round_id,
             clarification_request_payload: round.request_payload,
             submitted_message_refs: (round.submitted_message_refs ?? []),
-            round_messages: messagesWindow?.items ?? [],
+            round_messages: readSubmittedClarificationMessages(input.db, input.round_id),
             latest_run_result: latestRunResult,
             run_lineage: toDomainRunLineage(latestRunResult.run_lineage),
         },
@@ -51,18 +49,14 @@ export function readRunContinuationContextFromStore(input) {
     }
     let messagesTruncated = false;
     const resolvedRounds = rounds.map((round) => {
-        const messagesWindow = readClarificationRoundMessagesWindow(input.db, round.id, { anchor: "start", limit: CONTINUATION_CLARIFICATION_MESSAGE_LIMIT });
-        if (messagesWindow === null ||
-            messagesWindow.window.has_older ||
-            messagesWindow.window.has_newer) {
+        const submitted = readSubmittedClarificationMessages(input.db, round.id).filter((message) => clarificationAnswerRole(message) !== null);
+        if (submitted.length > CONTINUATION_CLARIFICATION_MESSAGE_LIMIT)
             messagesTruncated = true;
-        }
-        const submittedMessageRefs = new Set((round.submitted_message_refs ?? []));
-        const answerMessages = (messagesWindow?.items ?? [])
-            .filter((message) => message.author.kind === "human")
-            .filter((message) => submittedMessageRefs.size === 0 || submittedMessageRefs.has(message.id))
+        const answerMessages = submitted
+            .slice(0, CONTINUATION_CLARIFICATION_MESSAGE_LIMIT)
             .map((message) => ({
             author: message.author,
+            role: clarificationAnswerRole(message),
             text: message.body,
             created_at: message.created_at,
         }));

package/dist/control-plane/index.d.ts

@@ -1,7 +1,8 @@
 import { type ActivityRef, type ClarificationRoundRef, type IdempotencyKey, type TaskId, type WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { TrustedCollaborationAuthor } from "../collaboration-ingestion/types.js";
 import type { ExecutionStatusProjection, MessageProjection, ContextSyncDisposition, ContextSyncResult, RefreshScratchpadDisposition, RefreshScratchpadResult, RunSchedulerNowDisposition, RunSchedulerNowPayload, RetryTaskDisposition, RetryTaskPayload, RefreshReferenceSummariesDisposition, RefreshReferenceSummariesPayload, RefreshReferenceSummariesResult, SendClarificationRoundMessageDisposition, SendClarificationRoundMessagePayload, SendClarificationRoundMessageResult, SubmitClarificationRoundDisposition, SubmitClarificationRoundPayload, SubmitClarificationRoundResult, SubmitWorklistDisposition, SubmitWorklistPayload, SubmitWorklistResult, ProcedureLane } from "@tutti/shared/schemas/api";
 import type { ContextSyncWorkflowTrigger } from "./workflows/index.js";
-import type { ControlPlaneCommandResult, Phase5ControlPlaneOptions, StartupRecoveryOptions, StartupRecoveryResult, TrustedHumanAuthor } from "./types.js";
+import type { ControlPlaneCommandResult, Phase5ControlPlaneOptions, StartupRecoveryOptions, StartupRecoveryResult } from "./types.js";
 import { type ProjectBriefRefreshReason, type RefreshProjectBriefProjectionResult } from "./project-brief-refresh.js";
 export type { ControlPlaneCommandResult, ControlPlaneLogger, Phase5ControlPlaneOptions, RunCorrectionContext, RunContinuationContext, RunDispatchContext, RunDispatchTrigger, RunPipelineInput, RunPipelineResolution, RunPipelineResolver, RunPipelineResult, RunPipelineRunner, StartupRecoveryOptions, StartupRecoveryResult, TrustedHumanAuthor, } from "./types.js";
 export declare class Phase5ControlPlane {
@@ -50,7 +51,7 @@ export declare class Phase5ControlPlane {
     startContextSyncAnalysis(trigger?: ContextSyncWorkflowTrigger): ControlPlaneCommandResult<ContextSyncDisposition, ContextSyncResult>;
     startReferenceSummaryRefresh(payload?: RefreshReferenceSummariesPayload): ControlPlaneCommandResult<RefreshReferenceSummariesDisposition, RefreshReferenceSummariesResult>;
     private tryStartPendingReferenceSummaryRefresh;
-    sendClarificationRoundMessage(roundId: ClarificationRoundRef, payload: SendClarificationRoundMessagePayload, author: TrustedHumanAuthor): ControlPlaneCommandResult<SendClarificationRoundMessageDisposition, SendClarificationRoundMessageResult>;
+    sendClarificationRoundMessage(roundId: ClarificationRoundRef, payload: SendClarificationRoundMessagePayload, author: TrustedCollaborationAuthor): ControlPlaneCommandResult<SendClarificationRoundMessageDisposition, SendClarificationRoundMessageResult>;
     submitClarificationRound(roundId: ClarificationRoundRef, payload: SubmitClarificationRoundPayload, commandId: IdempotencyKey): ControlPlaneCommandResult<SubmitClarificationRoundDisposition, SubmitClarificationRoundResult>;
     waitForIdle(): Promise<void>;
     private trackAsyncOwner;

package/dist/control-plane/task-compile-clarification-context.js

@@ -1,3 +1,4 @@
+import { clarificationAnswerRole } from "@tutti/shared/utils";
 import { readActiveClarificationProjection, readClarificationRoundProjection, readClarificationRoundsForThread, readMessageProjectionById, readTaskCompileClarificationRoundsByWorkflowRef, } from "../collaboration-state/index.js";
 function answerMessage(store, messageId, roundId) {
     const message = readMessageProjectionById(store.db, messageId);
@@ -7,11 +8,15 @@ function answerMessage(store, messageId, roundId) {
         (message.message_kind !== "user_text" && message.message_kind !== "agent_text")) {
         return null;
     }
-    const role = message.author.kind === "agent" ? "tutti" : "human";
+    const role = message.author.kind === "agent" && message.message_kind === "agent_text"
+        ? "tutti"
+        : clarificationAnswerRole(message);
+    if (role === null)
+        return null;
     const displayName = message.author.display_name?.trim();
     return {
         role,
-        ...(role === "human" && displayName !== undefined && displayName !== ""
+        ...(role !== "tutti" && displayName !== undefined && displayName !== ""
             ? { author_display_name: displayName }
             : {}),
         text: message.body,

package/dist/control-plane/types.d.ts

@@ -75,6 +75,7 @@ export type RunContinuationContext = {
             request_payload: ClarificationRequestPayload;
             answer_messages: Array<{
                 author: MessageProjection["author"];
+                role?: "human" | "operator";
                 text: string;
                 created_at: string;
             }>;

package/dist/control-plane/workflows/openai.js

@@ -2,6 +2,7 @@ import { copyFileSync, mkdtempSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import { clarificationAnswerRole } from "@tutti/shared/utils";
 import { renderPromptTemplate } from "../../prompt-templates/index.js";
 import { createOpenAiStructuredOutputClient, runOpenAiStructuredOutput, } from "../../providers/openai/sdk-procedure-runner.js";
 import { readOpenAiApiKeyCredential } from "../../providers/openai/credential-store.js";
@@ -162,10 +163,10 @@ function referenceFileSummaryWorkflowOutput(output, originalPath) {
 function followUpCheckPromptInput(input) {
     const submittedMessageRefs = new Set(input.submitted_message_refs);
     const answers = input.round_messages
-        .filter((message) => message.author.kind === "human")
-        .filter((message) => submittedMessageRefs.size === 0 || submittedMessageRefs.has(message.id))
-        .map((message) => message.body.trim())
-        .filter((text) => text.length > 0);
+        .filter((message) => clarificationAnswerRole(message) !== null)
+        .filter((message) => submittedMessageRefs.has(message.id))
+        .filter((message) => message.body.trim().length > 0)
+        .map((message) => ({ role: clarificationAnswerRole(message), text: message.body.trim() }));
     return {
         title: input.task_detail.task.title,
         goal: input.task_detail.detail.contract.goal,

package/dist/platform-outbound/repository.js

@@ -1,6 +1,7 @@
-import { createIdempotencyKey } from "@tutti/shared/ids";
+import { createIdempotencyKey, } from "@tutti/shared/ids";
 import { Value } from "@sinclair/typebox/value";
 import { PlatformOutboundContentSchema, } from "@tutti/shared/schemas/internal";
+import { readClarificationRoundProjection, readClarificationThreadResponse, } from "../collaboration-state/index.js";
 const MAX_PLATFORM_OUTBOUND_TEXT_LENGTH = 4_000;
 function boundedPlatformOutboundText(value) {
     const characters = [...value.trim()];
@@ -134,10 +135,13 @@ export function materializePlatformStatusOutboundIntents(db, now = () => new Dat
                     subjectRef: roundRef,
                     targetKind: "project",
                     canonicalMessageId: candidate.id,
+                    content: clarificationContent(db, roundRef),
                     now,
                 });
                 if (result?.created === true) {
                     created.push(result.intent);
+                    const content = clarificationContent(db, roundRef);
+                    db.prepare("INSERT OR IGNORE INTO platform_clarification_projection_cursors (round_id, binding_ref, version) VALUES (?, ?, ?)").run(roundRef, result.intent.binding_ref, content.version);
                 }
                 continue;
             }
@@ -162,9 +166,61 @@ export function materializePlatformStatusOutboundIntents(db, now = () => new Dat
                 created.push(result.intent);
             }
         }
+        for (const cursor of db
+            .prepare("SELECT round_id, binding_ref, version FROM platform_clarification_projection_cursors WHERE closed = 0")
+            .all()) {
+            const content = clarificationContent(db, cursor.round_id);
+            if (content === null || readLatestFeishuDestination(db)?.binding_ref !== cursor.binding_ref) {
+                db.prepare("UPDATE platform_clarification_projection_cursors SET closed = 1 WHERE round_id = ?").run(cursor.round_id);
+                continue;
+            }
+            if (content.version <= cursor.version)
+                continue;
+            const result = createPlatformStatusOutboundIntent(db, {
+                eventKind: "needs_input",
+                eventKey: `clarification_round:${cursor.round_id}:state:${content.version}`,
+                subjectKind: "clarification_round",
+                subjectRef: cursor.round_id,
+                targetKind: "project",
+                content,
+                now,
+            });
+            if (result !== null) {
+                db.prepare("UPDATE platform_clarification_projection_cursors SET version = ?, closed = ? WHERE round_id = ?").run(content.version, content.state === "closed" ? 1 : 0, cursor.round_id);
+                if (result.created)
+                    created.push(result.intent);
+            }
+        }
         return created;
     })();
 }
+function clarificationContent(db, roundId) {
+    const round = readClarificationRoundProjection(db, roundId);
+    if (round === null)
+        return null;
+    const thread = readClarificationThreadResponse(db, round.thread_id)?.thread;
+    const state = thread?.status !== "active" || thread.current_round_id !== round.id
+        ? "closed"
+        : round.successor_status === "materialized"
+            ? "continued"
+            : round.status === "sealed"
+                ? "submitted"
+                : "writable";
+    const answerRevision = round.answer_revision ?? 0;
+    return {
+        kind: "clarification",
+        round_id: round.id,
+        answer_revision: answerRevision,
+        version: answerRevision * 4 + { writable: 0, submitted: 1, continued: 2, closed: 3 }[state],
+        state,
+        ...(state === "closed" && thread?.closed_reason !== undefined
+            ? { closed_reason: thread.closed_reason }
+            : {}),
+        title: (round.request_payload.title ?? "Needs your input").slice(0, 512),
+        request: round.request_payload.request.slice(0, 4_000),
+        opened_at: round.created_at,
+    };
+}
 export function createPlatformOutboundIntent(tx, input) {
     const existing = tx
         .prepare("SELECT * FROM platform_outbound_intents WHERE canonical_message_id = ?")
@@ -172,13 +228,27 @@ export function createPlatformOutboundIntent(tx, input) {
     if (existing !== undefined) {
         return { created: false, intent: existing };
     }
+    // An H5 round answer can finish before the periodic status worker observes the
+    // opening card. Capture its destination first, in this same transaction.
+    if (tx
+        .prepare("SELECT 1 FROM messages WHERE id = ? AND scope_kind = 'clarification_round'")
+        .get(input.triggerMessageId) !== undefined)
+        materializePlatformStatusOutboundIntents(tx, input.now);
     const destination = tx
         .prepare(`
         SELECT platform, installation_ref, binding_ref
         FROM external_source_mappings
         WHERE message_id = ? AND platform = 'feishu'
       `)
-        .get(input.triggerMessageId);
+        .get(input.triggerMessageId) ??
+        tx
+            .prepare(`
+      SELECT i.platform, i.installation_ref, i.binding_ref FROM messages m
+      JOIN platform_clarification_projection_cursors c ON c.round_id = m.clarification_round_id
+      JOIN platform_outbound_intents i ON i.event_key = 'clarification_round:' || c.round_id || ':opened'
+      WHERE m.id = ? AND m.scope_kind = 'clarification_round'
+    `)
+            .get(input.triggerMessageId);
     if (destination === undefined) {
         return null;
     }
@@ -216,7 +286,7 @@ export function claimDuePlatformOutboundIntent(db, now = () => new Date()) {
         const row = db
             .prepare(`
           SELECT platform_outbound_intents.*,
-                 COALESCE(platform_outbound_intents.content_text, messages.body) AS body
+                 COALESCE(platform_outbound_intents.content_text, messages.body) AS body, messages.clarification_round_id
           FROM platform_outbound_intents
           LEFT JOIN messages ON messages.id = platform_outbound_intents.canonical_message_id
           WHERE platform_outbound_intents.disposition IN ('pending', 'retry_wait')
@@ -243,7 +313,16 @@ export function claimDuePlatformOutboundIntent(db, now = () => new Date()) {
         }
         else if (row.body !== null) {
             const body = boundedPlatformOutboundText(row.body);
-            content = body.length === 0 ? null : { kind: "text", text: body };
+            content =
+                body.length === 0
+                    ? null
+                    : {
+                        kind: "text",
+                        text: body,
+                        ...(row.clarification_round_id == null
+                            ? {}
+                            : { clarification_round_ref: row.clarification_round_id }),
+                    };
         }
         if (content === null) {
             return null;

package/dist/server-shell/cli/host-lifecycle.js

@@ -311,6 +311,7 @@ export async function startLaunchProject(options) {
                 projectSurface: preparation.machine_local.binding.surface_profile.kind,
                 trustedMetadataStore: host.trusted_relay_metadata_store,
                 integrationDelivery: host.integration_delivery,
+                integrationClarification: host.integration_clarification,
                 integrationReferenceAttachment: host.integration_reference_attachment,
                 integrationManagedReference: host.integration_managed_reference,
                 integrationApprovalDecision: host.integration_approval_decision,

package/dist/server-shell/cli/host-server-runtime.d.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import { type ExecutionStatusProjection } from "@tutti/shared/schemas/api";
-import type { IntegrationApprovalDecisionDisposition, IntegrationDeliveryDisposition, IntegrationManagedReferenceDisposition, TrustedApprovalDecisionCommand, TrustedConversationSourceIngestionCommand, TrustedManagedReferenceIngestionCommand, TrustedReferenceAttachmentIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { IntegrationApprovalDecisionDisposition, IntegrationClarificationResponse, TrustedClarificationCommand, IntegrationDeliveryDisposition, IntegrationManagedReferenceDisposition, TrustedApprovalDecisionCommand, TrustedConversationSourceIngestionCommand, TrustedManagedReferenceIngestionCommand, TrustedReferenceAttachmentIngestionCommand } from "@tutti/shared/schemas/internal";
 import { type HostProjectStore } from "../../store/index.js";
 import type { createHostServer } from "../http/create-server.js";
 import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
@@ -19,6 +19,7 @@ export type HostServerHandle = {
     runtime_endpoint: MachineRuntimeEndpointRecord;
     trusted_relay_metadata_store: TrustedRelaySessionMetadataStore;
     integration_delivery: (command: TrustedConversationSourceIngestionCommand) => IntegrationDeliveryDisposition;
+    integration_clarification: (command: TrustedClarificationCommand) => IntegrationClarificationResponse;
     integration_approval_decision: (command: TrustedApprovalDecisionCommand) => IntegrationApprovalDecisionDisposition;
     integration_reference_attachment: (command: TrustedReferenceAttachmentIngestionCommand) => Promise<IntegrationDeliveryDisposition>;
     integration_managed_reference: (command: TrustedManagedReferenceIngestionCommand) => Promise<IntegrationManagedReferenceDisposition>;

package/dist/server-shell/cli/host-server-runtime.js

@@ -6,7 +6,7 @@ import { ApprovalRequestManager, executeApprovalDecisionCommand } from "../../ap
 import { ArtifactPreviewManager } from "../../artifacts/index.js";
 import { ReadOnlyChatAssistant } from "../../chat-assistant/index.js";
 import { CheckProcessCoordinator } from "../../checks/index.js";
-import { ingestTrustedConversationSource, ingestTrustedManagedReference, ingestTrustedReferenceAttachment, } from "../../collaboration-ingestion/index.js";
+import { ingestTrustedConversationSource, executeTrustedClarification, ingestTrustedManagedReference, ingestTrustedReferenceAttachment, } from "../../collaboration-ingestion/index.js";
 import { ensureInitialProjectWelcomeMessage } from "../../collaboration-state/index.js";
 import { Phase5ControlPlane } from "../../control-plane/index.js";
 import { resolveProjectOpenAiProcedureWorkflowRunner } from "../../control-plane/workflows/index.js";
@@ -447,7 +447,7 @@ export async function startForegroundHostServer(options) {
         ...(platformOutboundCoordinator === undefined
             ? {}
             : {
-                onMainChatAgentMessageCreated: ({ tx, triggerMessage, responseMessage }) => platformOutboundCoordinator.captureAgentResponse(tx, {
+                onAgentMessageCreated: ({ tx, triggerMessage, responseMessage }) => platformOutboundCoordinator.captureAgentResponse(tx, {
                     triggerMessage,
                     responseMessage,
                 }),
@@ -714,6 +714,7 @@ export async function startForegroundHostServer(options) {
         trusted_relay_metadata_store: trustedMetadataStore,
         integration_delivery: (command) => ingestTrustedConversationSource({
             store,
+            controlPlane,
             events: workspaceEvents,
             command,
             scratchpadSource: {
@@ -722,6 +723,7 @@ export async function startForegroundHostServer(options) {
             chatAssistant,
             now,
         }),
+        integration_clarification: (command) => executeTrustedClarification({ store, controlPlane, command, now }),
         integration_reference_attachment: async (command) => await ingestTrustedReferenceAttachment({
             store,
             workspaceRoot: options.preparation.workspace_root,

package/dist/server-shell/cli/relay-registration.js

@@ -38,6 +38,7 @@ export async function registerHostWithRelay(options) {
         capabilities: {
             integration_source_ingestion_v1: true,
             integration_development_bot_v1: true,
+            integration_clarification_v1: true,
             integration_external_references_v1: true,
             integration_attachment_ingestion_v1: true,
             integration_managed_reference_ingestion_v1: true,

package/dist/server-shell/http/host-tunnel.d.ts

@@ -1,12 +1,13 @@
 import type { FastifyInstance } from "fastify";
 import type { RelayHostTunnelRequestHandler, RelayHostTunnelStreamRequestHandler } from "@tutti/relay-client";
-import type { IntegrationApprovalDecisionDisposition, IntegrationDeliveryDisposition, IntegrationManagedReferenceDisposition, TrustedApprovalDecisionCommand, TrustedConversationSourceIngestionCommand, TrustedManagedReferenceIngestionCommand, TrustedReferenceAttachmentIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { IntegrationApprovalDecisionDisposition, IntegrationClarificationResponse, TrustedClarificationCommand, IntegrationDeliveryDisposition, IntegrationManagedReferenceDisposition, TrustedApprovalDecisionCommand, TrustedConversationSourceIngestionCommand, TrustedManagedReferenceIngestionCommand, TrustedReferenceAttachmentIngestionCommand } from "@tutti/shared/schemas/internal";
 import type { ProjectSurface } from "@tutti/shared/domain";
 import { type TrustedRelaySessionMetadataStore } from "../session/relay-session-context.js";
 export type HostProjectApiTunnelDispatchOptions = {
     app: FastifyInstance;
     projectSurface?: ProjectSurface;
     trustedMetadataStore: TrustedRelaySessionMetadataStore;
+    integrationClarification?: (command: TrustedClarificationCommand) => IntegrationClarificationResponse;
     integrationDelivery?: (command: TrustedConversationSourceIngestionCommand) => IntegrationDeliveryDisposition;
     integrationApprovalDecision?: (command: TrustedApprovalDecisionCommand) => IntegrationApprovalDecisionDisposition;
     integrationReferenceAttachment?: (command: TrustedReferenceAttachmentIngestionCommand) => Promise<IntegrationDeliveryDisposition>;

package/dist/server-shell/http/host-tunnel.js

@@ -1,4 +1,5 @@
-import { INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH, INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH, INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH, isTrustedApprovalDecisionCommand, isTrustedConversationSourceIngestionCommand, isTrustedManagedReferenceIngestionCommand, isTrustedReferenceAttachmentIngestionCommand, } from "@tutti/shared/schemas/internal";
+import { dispatchIntegrationClarification } from "./integration-clarification-dispatch.js";
+import { INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH, INTEGRATION_CLARIFICATION_TUNNEL_PATH, INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH, INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH, isTrustedApprovalDecisionCommand, isTrustedConversationSourceIngestionCommand, isTrustedManagedReferenceIngestionCommand, isTrustedReferenceAttachmentIngestionCommand, } from "@tutti/shared/schemas/internal";
 import { TRUSTED_INTEGRATION_INGESTION_PATH, TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH, } from "../../collaboration-ingestion/index.js";
 import { TRUSTED_RELAY_METADATA_REQUEST_HEADER, } from "../session/relay-session-context.js";
 function browserMetadataMatchesSurface(projectSurface, request) {
@@ -78,6 +79,8 @@ function dispatchIntegrationDelivery(options, request) {
     if (request.path === INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH) {
         return dispatchIntegrationApprovalDecision(options, request);
     }
+    if (request.path === INTEGRATION_CLARIFICATION_TUNNEL_PATH)
+        return Promise.resolve(dispatchIntegrationClarification(options, request));
     if (request.path === INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH) {
         return dispatchIntegrationReferenceAttachment(options, request);
     }

package/dist/server-shell/http/integration-clarification-dispatch.d.ts

@@ -0,0 +1,6 @@
+import type { RelayHostTunnelRequest, RelayHostTunnelResponse } from "@tutti/relay-client";
+import { type IntegrationClarificationResponse, type TrustedClarificationCommand } from "@tutti/shared/schemas/internal";
+export declare function dispatchIntegrationClarification(options: {
+    integrationClarification?: (command: TrustedClarificationCommand) => IntegrationClarificationResponse;
+}, request: RelayHostTunnelRequest): RelayHostTunnelResponse;
+//# sourceMappingURL=integration-clarification-dispatch.d.ts.map

package/dist/server-shell/http/integration-clarification-dispatch.js

@@ -0,0 +1,43 @@
+import { INTEGRATION_CLARIFICATION_TUNNEL_PATH, isTrustedClarificationCommand, } from "@tutti/shared/schemas/internal";
+export function dispatchIntegrationClarification(options, request) {
+    const finish = (body) => ({
+        request_id: request.request_id,
+        status_code: 200,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
+    });
+    const invalid = (reason_code) => finish({ protocol_version: 1, disposition: { kind: "invalid", reason_code } });
+    if (request.method !== "POST" ||
+        request.path !== INTEGRATION_CLARIFICATION_TUNNEL_PATH ||
+        !("integration_delivery" in request.metadata))
+        return invalid("internal_route_invalid");
+    let command;
+    try {
+        command = JSON.parse(Buffer.from(request.body_base64 ?? "", "base64").toString("utf8"));
+    }
+    catch {
+        return invalid("trusted_command_invalid");
+    }
+    if (!isTrustedClarificationCommand(command))
+        return invalid("trusted_command_invalid");
+    const metadata = request.metadata.integration_delivery;
+    if (!("operation_ref" in metadata) ||
+        command.operation_ref !== metadata.operation_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.actor.verified_at !== metadata.verified_at ||
+        command.conversation.installation.platform !== metadata.installation.platform ||
+        command.conversation.installation.installation_ref !== metadata.installation.installation_ref)
+        return invalid("trusted_metadata_mismatch");
+    if (options.integrationClarification === undefined)
+        return finish({
+            protocol_version: 1,
+            disposition: {
+                kind: "unavailable",
+                retryable: true,
+                reason_code: "integration_clarification_unsupported",
+            },
+        });
+    return finish(options.integrationClarification(command));
+}
+//# sourceMappingURL=integration-clarification-dispatch.js.map