@xfey/tutti 0.1.110 → 0.1.112

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

@@ -37,6 +37,8 @@ export async function registerHostWithRelay(options) {
         joinToken: { mode: options.joinTokenMode ?? "rotate" },
         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

package/dist/server-shell/http/routes/agent-context-reference-routes.js

@@ -99,9 +99,7 @@ export function registerAgentContextReferenceRoutes(app, options) {
             request.log.warn({
                 ...diagnosticFields,
                 stage: "local_reference_unavailable",
-                reason_code: error instanceof WorkspaceOpsError
-                    ? error.code
-                    : "reference_read_unavailable",
+                reason_code: error instanceof WorkspaceOpsError ? error.code : "reference_read_unavailable",
                 elapsed_ms: Math.round(performance.now() - started),
             }, "Local Reference read unavailable");
             if (error instanceof WorkspaceOpsError) {

package/dist/server-shell/http/routes/project-api/clarification-routes.js

@@ -1,9 +1,8 @@
 import { ActiveClarificationProjectionSchema, GetClarificationRoundMessagesRequestSchema, GetClarificationRoundResponseSchema, GetClarificationThreadResponseSchema, MessageWindowSchema, SendClarificationRoundMessageBodySchema, SendClarificationRoundMessageResponseSchema, SubmitClarificationRoundBodySchema, SubmitClarificationRoundResponseSchema, } from "@tutti/shared/schemas/api";
 import { readActiveClarificationProjection, readClarificationRoundMessagesWindow, readClarificationRoundProjection, readClarificationThreadResponse, } from "../../../../collaboration-state/index.js";
-import { executeIdempotentCommand } from "../../../command-idempotency/index.js";
+import { ingestClarificationMessage, submitClarificationAnswers, } from "../../../../collaboration-ingestion/index.js";
 import { HOST_PROJECT_API_BASE_PATH } from "./constants.js";
 import { HostProjectNotFoundError } from "./errors.js";
-import { clarificationRoundInvalidates } from "./invalidations.js";
 import { requireValidMessageWindowRequest, requireValidRoundMessagePayload, } from "./payload-validation.js";
 import { ClarificationRoundParamsSchema, ClarificationThreadParamsSchema, } from "./schemas.js";
 import { requireControlPlane, requireHostProjectSession, requireProjectStore, } from "./session-requirements.js";
@@ -85,35 +84,20 @@ export function registerClarificationRoutes(app, options) {
         const store = requireProjectStore(options);
         const controlPlane = requireControlPlane(options);
         const payload = requireValidRoundMessagePayload(request.body.payload);
-        const execution = executeIdempotentCommand({
-            db: store.db,
-            command_id: request.body.command_id,
-            command_name: "clarification.message.create",
-            target_ref: request.params.roundId,
-            payload: {
-                body: payload.body,
-                author_ref: session.account.account_ref,
-            },
-            ...(options.now === undefined ? {} : { now: options.now }),
-            execute: () => controlPlane.sendClarificationRoundMessage(request.params.roundId, payload, {
+        return ingestClarificationMessage({
+            store,
+            controlPlane,
+            commandId: request.body.command_id,
+            roundId: request.params.roundId,
+            payload,
+            author: {
                 account_ref: session.account.account_ref,
                 display_name: session.account.display_name,
                 avatar: session.account.avatar,
-            }),
+            },
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.chatAssistant === undefined ? {} : { chatAssistant: options.chatAssistant }),
         });
-        const response = {
-            command_id: execution.command_id,
-            disposition: execution.disposition,
-            invalidates: clarificationRoundInvalidates(request.params.roundId),
-        };
-        if (execution.result !== undefined) {
-            response.result = execution.result;
-        }
-        const message = execution.result?.message;
-        if (!execution.replayed && message !== undefined) {
-            options.chatAssistant?.enqueue({ message });
-        }
-        return response;
     });
     app.post(`${HOST_PROJECT_API_BASE_PATH}/clarifications/rounds/:roundId/submit`, {
         schema: {
@@ -127,24 +111,14 @@ export function registerClarificationRoutes(app, options) {
         requireHostProjectSession(request, options);
         const store = requireProjectStore(options);
         const controlPlane = requireControlPlane(options);
-        const execution = executeIdempotentCommand({
-            db: store.db,
-            command_id: request.body.command_id,
-            command_name: "clarification.round.submit",
-            target_ref: request.params.roundId,
+        return submitClarificationAnswers({
+            store,
+            controlPlane,
+            commandId: request.body.command_id,
+            roundId: request.params.roundId,
             payload: request.body.payload,
             ...(options.now === undefined ? {} : { now: options.now }),
-            execute: () => controlPlane.submitClarificationRound(request.params.roundId, request.body.payload, request.body.command_id),
         });
-        const response = {
-            command_id: execution.command_id,
-            disposition: execution.disposition,
-            invalidates: clarificationRoundInvalidates(request.params.roundId),
-        };
-        if (execution.result !== undefined) {
-            response.result = execution.result;
-        }
-        return response;
     });
 }
 //# sourceMappingURL=clarification-routes.js.map

package/dist/server-shell/http/routes/project-api/openapi-collaboration-routes.d.ts

@@ -266,6 +266,7 @@ export declare const HOST_PROJECT_COLLABORATION_OPENAPI_ROUTES: ({
                     }>;
                     card_message_id: import("@sinclair/typebox").TString;
                     opening_message_id: import("@sinclair/typebox").TString;
+                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -421,6 +422,7 @@ export declare const HOST_PROJECT_COLLABORATION_OPENAPI_ROUTES: ({
                     }>;
                     card_message_id: import("@sinclair/typebox").TString;
                     opening_message_id: import("@sinclair/typebox").TString;
+                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;

package/dist/server-shell/http/routes/project-api/openapi-workspace-routes.d.ts

@@ -1117,6 +1117,7 @@ export declare const HOST_PROJECT_WORKSPACE_OPENAPI_ROUTES: ({
                                     }>;
                                     card_message_id: import("@sinclair/typebox").TString;
                                     opening_message_id: import("@sinclair/typebox").TString;
+                                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;

package/dist/server-shell/http/routes/project-api/openapi.d.ts

@@ -410,6 +410,7 @@ export declare const HOST_PROJECT_OPENAPI_ROUTES: ({
                     }>;
                     card_message_id: import("@sinclair/typebox").TString;
                     opening_message_id: import("@sinclair/typebox").TString;
+                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -565,6 +566,7 @@ export declare const HOST_PROJECT_OPENAPI_ROUTES: ({
                     }>;
                     card_message_id: import("@sinclair/typebox").TString;
                     opening_message_id: import("@sinclair/typebox").TString;
+                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -2400,6 +2402,7 @@ export declare const HOST_PROJECT_OPENAPI_ROUTES: ({
                                     }>;
                                     card_message_id: import("@sinclair/typebox").TString;
                                     opening_message_id: import("@sinclair/typebox").TString;
+                                    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                                     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                                     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                                     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;

package/dist/server-shell/http/routes/project-api/schemas.d.ts

@@ -1081,6 +1081,7 @@ export declare const BootstrapResponseSchema: {
                         }>;
                         card_message_id: import("@sinclair/typebox").TString;
                         opening_message_id: import("@sinclair/typebox").TString;
+                        answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
                         submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                         submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
                         successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;

package/migrations/0022_clarification_projection_cursors.sql

@@ -0,0 +1,7 @@
+CREATE TABLE platform_clarification_projection_cursors (
+  round_id TEXT PRIMARY KEY REFERENCES clarification_rounds(id),
+  binding_ref TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version >= 0),
+  closed INTEGER NOT NULL DEFAULT 0 CHECK (closed IN (0, 1))
+);
+CREATE INDEX idx_platform_clarification_live ON platform_clarification_projection_cursors(closed);

package/node_modules/@tutti/relay-client/dist/host-control.d.ts

@@ -44,6 +44,8 @@ export type RegisterRelayHostConnectionPayload = {
             browser_secret_write: false;
             repo_viewer: boolean;
             integration_source_ingestion_v1?: boolean;
+            integration_development_bot_v1?: boolean;
+            integration_clarification_v1?: boolean;
             integration_external_references_v1?: boolean;
             integration_attachment_ingestion_v1?: boolean;
             integration_managed_reference_ingestion_v1?: boolean;

package/node_modules/@tutti/relay-client/dist/host-control.js

@@ -57,11 +57,17 @@ function createRegisterPayload(options) {
                 browser_secret_write: false,
                 repo_viewer: capabilities.repo_viewer ?? false,
                 integration_source_ingestion_v1: capabilities.integration_source_ingestion_v1 ?? false,
+                ...(capabilities.integration_development_bot_v1 === true
+                    ? { integration_development_bot_v1: true }
+                    : {}),
                 integration_external_references_v1: capabilities.integration_external_references_v1 ?? false,
                 integration_attachment_ingestion_v1: capabilities.integration_attachment_ingestion_v1 ?? false,
                 integration_managed_reference_ingestion_v1: capabilities.integration_managed_reference_ingestion_v1 ?? false,
                 integration_outbound_v1: capabilities.integration_outbound_v1 ?? false,
                 integration_approval_decision_v1: capabilities.integration_approval_decision_v1 ?? false,
+                ...(capabilities.integration_clarification_v1 === true
+                    ? { integration_clarification_v1: true }
+                    : {}),
             },
         },
     };

package/node_modules/@tutti/shared/dist/schemas/api/clarifications.d.ts

@@ -201,6 +201,7 @@ export declare const ClarificationRoundProjectionSchema: import("@sinclair/typeb
     }>;
     card_message_id: import("@sinclair/typebox").TString;
     opening_message_id: import("@sinclair/typebox").TString;
+    answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -299,6 +300,7 @@ export declare const ActiveClarificationProjectionSchema: import("@sinclair/type
         }>;
         card_message_id: import("@sinclair/typebox").TString;
         opening_message_id: import("@sinclair/typebox").TString;
+        answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -437,6 +439,7 @@ export declare const GetClarificationRoundResponseSchema: import("@sinclair/type
         }>;
         card_message_id: import("@sinclair/typebox").TString;
         opening_message_id: import("@sinclair/typebox").TString;
+        answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -471,6 +474,7 @@ export declare const SendClarificationRoundMessagePayloadSchema: import("@sincla
 }>;
 export declare const SendClarificationRoundMessageDispositionSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
     kind: import("@sinclair/typebox").TLiteral<"created">;
+    message_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>, import("@sinclair/typebox").TObject<{
     kind: import("@sinclair/typebox").TLiteral<"stale_round">;
     current_round_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -507,6 +511,7 @@ export declare const SendClarificationRoundMessageResultSchema: import("@sinclai
         message_kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"user_text">, import("@sinclair/typebox").TLiteral<"agent_text">, import("@sinclair/typebox").TLiteral<"system_notice">, import("@sinclair/typebox").TLiteral<"clarification_request">, import("@sinclair/typebox").TLiteral<"clarification_card">]>;
         body: import("@sinclair/typebox").TString;
         refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            development_operator: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<true>>;
             external_reference_reads: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
             external_references: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
                 source_ref: import("@sinclair/typebox").TString;
@@ -705,9 +710,16 @@ export declare const SendClarificationRoundMessageResultSchema: import("@sinclai
 }>;
 export declare const SendClarificationRoundMessageBodySchema: import("@sinclair/typebox").TSchema;
 export declare const SendClarificationRoundMessageResponseSchema: import("@sinclair/typebox").TSchema;
-export declare const SubmitClarificationRoundPayloadSchema: import("@sinclair/typebox").TObject<{}>;
+export declare const SubmitClarificationRoundPayloadSchema: import("@sinclair/typebox").TObject<{
+    expected_answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
 export declare const SubmitClarificationRoundDispositionSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
     kind: import("@sinclair/typebox").TLiteral<"accepted">;
+}>, import("@sinclair/typebox").TObject<{
+    kind: import("@sinclair/typebox").TLiteral<"no_answers">;
+}>, import("@sinclair/typebox").TObject<{
+    kind: import("@sinclair/typebox").TLiteral<"answers_changed">;
+    current_answer_revision: import("@sinclair/typebox").TInteger;
 }>, import("@sinclair/typebox").TObject<{
     kind: import("@sinclair/typebox").TLiteral<"already_submitted">;
     successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;
@@ -789,6 +801,7 @@ export declare const SubmitClarificationRoundResultSchema: import("@sinclair/typ
         }>;
         card_message_id: import("@sinclair/typebox").TString;
         opening_message_id: import("@sinclair/typebox").TString;
+        answer_revision: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         submitted_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         submitted_message_refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         successor_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"not_materialized">, import("@sinclair/typebox").TLiteral<"materialized">]>;

package/node_modules/@tutti/shared/dist/schemas/api/clarifications.js

@@ -119,6 +119,8 @@ export const ClarificationRoundProjectionSchema = Type.Object({
     request_payload: ClarificationRequestPayloadSchema,
     card_message_id: MessageIdSchema,
     opening_message_id: MessageIdSchema,
+    // Append-only eligible answers. Optional for compatibility with older Hosts.
+    answer_revision: Type.Optional(Type.Integer({ minimum: 0 })),
     submitted_at: Type.Optional(IsoDateTimeStringSchema),
     submitted_message_refs: Type.Optional(Type.Array(MessageIdSchema)),
     successor_status: Type.Union([Type.Literal("not_materialized"), Type.Literal("materialized")]),
@@ -168,7 +170,7 @@ export const SendClarificationRoundMessagePayloadSchema = Type.Object({
     body: Type.String({ minLength: 1, maxLength: 8000 }),
 }, { additionalProperties: false });
 export const SendClarificationRoundMessageDispositionSchema = Type.Union([
-    Type.Object({ kind: Type.Literal("created") }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("created"), message_id: Type.Optional(MessageIdSchema) }, { additionalProperties: false }),
     Type.Object({
         kind: Type.Literal("stale_round"),
         current_round_id: Type.Optional(ClarificationRoundRefSchema),
@@ -181,9 +183,14 @@ export const SendClarificationRoundMessageResultSchema = Type.Object({
 }, { additionalProperties: false });
 export const SendClarificationRoundMessageBodySchema = commandEnvelopeSchema(SendClarificationRoundMessagePayloadSchema);
 export const SendClarificationRoundMessageResponseSchema = commandResponseWithResultSchema(SendClarificationRoundMessageDispositionSchema, SendClarificationRoundMessageResultSchema);
-export const SubmitClarificationRoundPayloadSchema = Type.Object({}, { additionalProperties: false });
+export const SubmitClarificationRoundPayloadSchema = Type.Object({ expected_answer_revision: Type.Optional(Type.Integer({ minimum: 0 })) }, { additionalProperties: false });
 export const SubmitClarificationRoundDispositionSchema = Type.Union([
     Type.Object({ kind: Type.Literal("accepted") }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("no_answers") }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("answers_changed"),
+        current_answer_revision: Type.Integer({ minimum: 0 }),
+    }, { additionalProperties: false }),
     Type.Object({
         kind: Type.Literal("already_submitted"),
         successor_status: Type.Union([