@xfey/tutti 0.1.105 → 0.1.106

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 { IntegrationDeliveryDisposition, TrustedConversationSourceIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { IntegrationApprovalDecisionDisposition, 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,9 @@ export type HostServerHandle = {
     runtime_endpoint: MachineRuntimeEndpointRecord;
     trusted_relay_metadata_store: TrustedRelaySessionMetadataStore;
     integration_delivery: (command: TrustedConversationSourceIngestionCommand) => IntegrationDeliveryDisposition;
+    integration_approval_decision: (command: TrustedApprovalDecisionCommand) => IntegrationApprovalDecisionDisposition;
+    integration_reference_attachment: (command: TrustedReferenceAttachmentIngestionCommand) => Promise<IntegrationDeliveryDisposition>;
+    integration_managed_reference: (command: TrustedManagedReferenceIngestionCommand) => Promise<IntegrationManagedReferenceDisposition>;
     attachRelayConnectionManager: (manager: HostRelayConnectionManager) => void;
     closed: Promise<void>;
     close: () => Promise<void>;

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

@@ -2,11 +2,11 @@ import { basename, join } from "node:path";
 import { MAX_PROVIDER_MODEL_NAME_LENGTH, } from "@tutti/shared/schemas/api";
 import { serializeRuntimeLogLine } from "@tutti/shared/utils";
 import { completeRelayUpload, deliverRelayPlatformOutbound, RelayHostControlClientError, resolveRelayUpload, } from "@tutti/relay-client";
-import { ApprovalRequestManager } from "../../approvals/index.js";
+import { ApprovalRequestManager, executeApprovalDecisionCommand } from "../../approvals/index.js";
 import { ArtifactPreviewManager } from "../../artifacts/index.js";
 import { ReadOnlyChatAssistant } from "../../chat-assistant/index.js";
 import { CheckProcessCoordinator } from "../../checks/index.js";
-import { ingestTrustedConversationSource } from "../../collaboration-ingestion/index.js";
+import { ingestTrustedConversationSource, 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";
@@ -21,6 +21,7 @@ import { openHostProjectStore } from "../../store/index.js";
 import { resolvePackagedWebStaticRoot } from "../http/static-web.js";
 import { AGENT_CONTEXT_BASE_PATH, AgentContextTokenRegistry, } from "../http/routes/agent-context.js";
 import { readHostRepoProjection } from "../http/routes/project-api.js";
+import { abortDownloadedStagedUpload, cleanupDownloadedStagedUpload, downloadStagedUploadWithResolver, } from "../http/routes/project-api/staged-uploads.js";
 import { WorkspaceEventBus } from "../http/workspace-events.js";
 import { createTrustedRelaySessionMetadataStore, } from "../session/relay-session-context.js";
 import { LaunchError } from "./errors.js";
@@ -308,9 +309,60 @@ export async function startForegroundHostServer(options) {
         },
     });
     controlPlaneLogger.info(staleTempCleanup, "Codex app-server stale temp cleanup completed");
+    const platformOutboundWorker = options.preparation.machine_local.binding.surface_profile.kind === "feishu"
+        ? new HostPlatformOutboundWorker(store, {
+            deliver: async (item) => {
+                const connectionState = relayConnectionManager?.getState();
+                if (connectionState?.status !== "connected") {
+                    throw new RelayHostControlClientError("relay_unavailable", "Relay is not connected for platform outbound handoff", true);
+                }
+                const hostSecret = readHostRegistrationSecret(options.preparation.tutti_home, options.preparation.project_id);
+                const relayProjectRef = connectionState.connection.relay_project_ref;
+                return await deliverRelayPlatformOutbound({
+                    relayUrl: options.preparation.relay_url,
+                    projectId: options.preparation.project_id,
+                    relayProjectRef,
+                    hostConnectionRef: connectionState.connection.host_connection_ref,
+                    hostRegistrationSecret: hostSecret.secret,
+                    intent: {
+                        protocol_version: 1,
+                        intent_ref: item.intent.intent_ref,
+                        relay_project_ref: relayProjectRef,
+                        installation: {
+                            platform: item.intent.platform,
+                            installation_ref: item.intent.installation_ref,
+                        },
+                        binding_ref: item.intent.binding_ref,
+                        ...(item.intent.canonical_message_id === null
+                            ? {}
+                            : { canonical_message_ref: item.intent.canonical_message_id }),
+                        ...(item.intent.trigger_message_id === null
+                            ? {}
+                            : { trigger_message_ref: item.intent.trigger_message_id }),
+                        content: item.content,
+                        event: {
+                            kind: item.intent.event_kind,
+                            event_key: item.intent.event_key,
+                            subject: {
+                                kind: item.intent.subject_kind,
+                                ref: item.intent.subject_ref,
+                            },
+                            target: { kind: item.intent.target_kind },
+                        },
+                        created_at: item.intent.created_at,
+                        attempt: item.intent.attempt_count,
+                    },
+                });
+            },
+        }, platformOutboundLogger, { now })
+        : undefined;
+    const platformOutboundCoordinator = platformOutboundWorker === undefined
+        ? undefined
+        : new HostPlatformOutboundCoordinator(store, platformOutboundWorker, platformOutboundLogger, now);
     const approvalManager = new ApprovalRequestManager({
         events: workspaceEvents,
         now,
+        onPending: (request) => platformOutboundCoordinator?.captureApprovalRequest(request),
     });
     const codexInvocationCoordinator = new CodexAppServerInvocationCoordinator();
     const checkProcessCoordinator = new CheckProcessCoordinator();
@@ -364,43 +416,6 @@ export async function startForegroundHostServer(options) {
             onLifecycleIncident: procedureLifecycleIncident,
         }),
     });
-    const platformOutboundWorker = options.preparation.machine_local.binding.surface_profile.kind === "feishu"
-        ? new HostPlatformOutboundWorker(store, {
-            deliver: async (item) => {
-                const connectionState = relayConnectionManager?.getState();
-                if (connectionState?.status !== "connected") {
-                    throw new RelayHostControlClientError("relay_unavailable", "Relay is not connected for platform outbound handoff", true);
-                }
-                const hostSecret = readHostRegistrationSecret(options.preparation.tutti_home, options.preparation.project_id);
-                const relayProjectRef = connectionState.connection.relay_project_ref;
-                return await deliverRelayPlatformOutbound({
-                    relayUrl: options.preparation.relay_url,
-                    projectId: options.preparation.project_id,
-                    relayProjectRef,
-                    hostConnectionRef: connectionState.connection.host_connection_ref,
-                    hostRegistrationSecret: hostSecret.secret,
-                    intent: {
-                        protocol_version: 1,
-                        intent_ref: item.intent.intent_ref,
-                        relay_project_ref: relayProjectRef,
-                        installation: {
-                            platform: item.intent.platform,
-                            installation_ref: item.intent.installation_ref,
-                        },
-                        binding_ref: item.intent.binding_ref,
-                        canonical_message_ref: item.intent.canonical_message_id,
-                        trigger_message_ref: item.intent.trigger_message_id,
-                        content: { kind: "text", text: item.body },
-                        created_at: item.intent.created_at,
-                        attempt: item.intent.attempt_count,
-                    },
-                });
-            },
-        }, platformOutboundLogger, { now })
-        : undefined;
-    const platformOutboundCoordinator = platformOutboundWorker === undefined
-        ? undefined
-        : new HostPlatformOutboundCoordinator(platformOutboundWorker, platformOutboundLogger, now);
     const chatAssistant = new ReadOnlyChatAssistant({
         project: chatAssistantProject,
         store,
@@ -508,9 +523,10 @@ export async function startForegroundHostServer(options) {
         ...(options.getLaunchStatus === undefined ? {} : { getLaunchStatus: options.getLaunchStatus }),
     };
     let app;
+    let resolveStagedUpload;
     try {
         const webStaticRoot = resolvePackagedWebStaticRoot();
-        const resolveStagedUpload = createStagedUploadResolver({
+        resolveStagedUpload = createStagedUploadResolver({
             preparation: options.preparation,
             ...(options.getLaunchStatus === undefined
                 ? {}
@@ -688,6 +704,78 @@ export async function startForegroundHostServer(options) {
             chatAssistant,
             now,
         }),
+        integration_reference_attachment: async (command) => await ingestTrustedReferenceAttachment({
+            store,
+            workspaceRoot: options.preparation.workspace_root,
+            events: workspaceEvents,
+            command,
+            resolveContent: async () => {
+                if (resolveStagedUpload === undefined) {
+                    throw new Error("Staged upload resolver is unavailable");
+                }
+                const downloaded = await downloadStagedUploadWithResolver({
+                    resolveStagedUpload,
+                    expected: command.staged_upload,
+                    purpose: "reference_file",
+                });
+                return {
+                    content: downloaded.content,
+                    complete: async () => await cleanupDownloadedStagedUpload(downloaded),
+                    abort: async () => await abortDownloadedStagedUpload(downloaded),
+                };
+            },
+            scratchpadSource: {
+                notify: (message) => controlPlane.notifyScratchpadSourceChanged(message),
+            },
+            referenceSummaries: {
+                start: (paths) => controlPlane.startReferenceSummaryRefresh({ paths }),
+            },
+            now,
+        }),
+        integration_managed_reference: async (command) => await ingestTrustedManagedReference({
+            store,
+            workspaceRoot: options.preparation.workspace_root,
+            events: workspaceEvents,
+            command,
+            resolveContent: async () => {
+                if (resolveStagedUpload === undefined) {
+                    throw new Error("Staged upload resolver is unavailable");
+                }
+                const downloaded = await downloadStagedUploadWithResolver({
+                    resolveStagedUpload,
+                    expected: command.staged_upload,
+                    purpose: "reference_file",
+                });
+                return {
+                    content: downloaded.content,
+                    complete: async () => await cleanupDownloadedStagedUpload(downloaded),
+                    abort: async () => await abortDownloadedStagedUpload(downloaded),
+                };
+            },
+            referenceSummaries: {
+                start: (paths) => controlPlane.startReferenceSummaryRefresh({ paths }),
+            },
+            now,
+        }),
+        integration_approval_decision: (command) => {
+            try {
+                return executeApprovalDecisionCommand({
+                    db: store.db,
+                    approvalManager,
+                    commandId: command.command_id,
+                    approvalId: command.approval_id,
+                    decisionId: command.decision_id,
+                    actor: {
+                        account_ref: command.actor.account_ref,
+                        display_name: command.actor.display_name,
+                    },
+                    now,
+                }).disposition;
+            }
+            catch {
+                return { kind: "invalid", reason_code: "approval_command_rejected" };
+            }
+        },
         attachRelayConnectionManager: (manager) => {
             relayConnectionManager = manager;
             platformOutboundCoordinator?.start();

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

@@ -37,7 +37,10 @@ export async function registerHostWithRelay(options) {
         joinToken: { mode: options.joinTokenMode ?? "rotate" },
         capabilities: {
             integration_source_ingestion_v1: true,
+            integration_attachment_ingestion_v1: true,
+            integration_managed_reference_ingestion_v1: true,
             integration_outbound_v1: true,
+            integration_approval_decision_v1: true,
         },
         fetch: options.fetchImpl,
         ...(options.signal === undefined ? {} : { signal: options.signal }),

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

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import type { RelayHostTunnelRequestHandler, RelayHostTunnelStreamRequestHandler } from "@tutti/relay-client";
-import type { IntegrationDeliveryDisposition, TrustedConversationSourceIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { IntegrationApprovalDecisionDisposition, 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 = {
@@ -8,6 +8,9 @@ export type HostProjectApiTunnelDispatchOptions = {
     projectSurface?: ProjectSurface;
     trustedMetadataStore: TrustedRelaySessionMetadataStore;
     integrationDelivery?: (command: TrustedConversationSourceIngestionCommand) => IntegrationDeliveryDisposition;
+    integrationApprovalDecision?: (command: TrustedApprovalDecisionCommand) => IntegrationApprovalDecisionDisposition;
+    integrationReferenceAttachment?: (command: TrustedReferenceAttachmentIngestionCommand) => Promise<IntegrationDeliveryDisposition>;
+    integrationManagedReference?: (command: TrustedManagedReferenceIngestionCommand) => Promise<IntegrationManagedReferenceDisposition>;
 };
 export type HostProjectApiTunnelStreamDispatchOptions = {
     baseUrl: string;

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

@@ -1,5 +1,5 @@
-import { isTrustedConversationSourceIngestionCommand } from "@tutti/shared/schemas/internal";
-import { TRUSTED_INTEGRATION_INGESTION_PATH } from "../../collaboration-ingestion/index.js";
+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 { 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) {
     return projectSurface === "standalone"
@@ -38,6 +38,30 @@ function integrationResponse(requestId, disposition) {
         body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
     };
 }
+function integrationApprovalResponse(requestId, disposition) {
+    const body = {
+        protocol_version: 1,
+        disposition,
+    };
+    return {
+        request_id: requestId,
+        status_code: 200,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
+    };
+}
+function integrationManagedReferenceResponse(requestId, disposition) {
+    const body = {
+        protocol_version: 1,
+        disposition,
+    };
+    return {
+        request_id: requestId,
+        status_code: 200,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
+    };
+}
 function sameInstallation(left, right) {
     return left.platform === right.platform && left.installation_ref === right.installation_ref;
 }
@@ -51,6 +75,15 @@ function dispatchIntegrationDelivery(options, request) {
     if (!("integration_delivery" in request.metadata)) {
         throw new TypeError("Integration delivery metadata is required");
     }
+    if (request.path === INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH) {
+        return dispatchIntegrationApprovalDecision(options, request);
+    }
+    if (request.path === INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH) {
+        return dispatchIntegrationReferenceAttachment(options, request);
+    }
+    if (request.path === INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH) {
+        return dispatchIntegrationManagedReference(options, request);
+    }
     if (request.method.toUpperCase() !== "POST" ||
         request.path !== TRUSTED_INTEGRATION_INGESTION_PATH) {
         return Promise.resolve(integrationResponse(request.request_id, {
@@ -73,7 +106,8 @@ function dispatchIntegrationDelivery(options, request) {
         }));
     }
     const metadata = request.metadata.integration_delivery;
-    if (command.relay_project_ref !== metadata.relay_project_ref ||
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
         command.binding_ref !== metadata.binding_ref ||
         command.receipt.receipt_key !== metadata.receipt_key ||
         command.actor.verified_at !== metadata.verified_at ||
@@ -92,6 +126,143 @@ function dispatchIntegrationDelivery(options, request) {
     }
     return Promise.resolve(integrationResponse(request.request_id, options.integrationDelivery(command)));
 }
+async function dispatchIntegrationReferenceAttachment(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST" ||
+        request.path !== TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        });
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedReferenceAttachmentIngestionCommand(command)) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_attachment_command_invalid",
+        });
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.receipt.receipt_key !== metadata.receipt_key ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.receipt.installation, metadata.installation)) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        });
+    }
+    if (options.integrationReferenceAttachment === undefined) {
+        return integrationResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_attachment_ingestion_unsupported",
+        });
+    }
+    return integrationResponse(request.request_id, await options.integrationReferenceAttachment(command));
+}
+async function dispatchIntegrationManagedReference(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST" ||
+        request.path !== INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        });
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedManagedReferenceIngestionCommand(command)) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_managed_reference_command_invalid",
+        });
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("operation_ref" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.operation_ref !== metadata.operation_ref ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.source.installation, metadata.installation)) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        });
+    }
+    if (options.integrationManagedReference === undefined) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_managed_reference_ingestion_unsupported",
+        });
+    }
+    return integrationManagedReferenceResponse(request.request_id, await options.integrationManagedReference(command));
+}
+function dispatchIntegrationApprovalDecision(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST") {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        }));
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedApprovalDecisionCommand(command)) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_command_invalid",
+        }));
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.receipt.receipt_key !== metadata.receipt_key ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.receipt.installation, metadata.installation)) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        }));
+    }
+    if (options.integrationApprovalDecision === undefined) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_approval_decision_unsupported",
+        }));
+    }
+    return Promise.resolve(integrationApprovalResponse(request.request_id, options.integrationApprovalDecision(command)));
+}
 function injectHeaders(request) {
     const headers = {};
     for (const [name, value] of Object.entries(request.headers)) {

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

@@ -1,9 +1,9 @@
 import { ActiveApprovalProjectionSchema, DecideApprovalBodySchema, DecideApprovalResponseSchema, } from "@tutti/shared/schemas/api";
-import { executeIdempotentCommand } from "../../../command-idempotency/index.js";
+import { executeApprovalDecisionCommand } from "../../../../approvals/index.js";
 import { HOST_PROJECT_API_BASE_PATH } from "./constants.js";
 import { approvalInvalidates } from "./invalidations.js";
-import { ApprovalRequestParamsSchema, } from "./schemas.js";
-import { requireHostProjectSession, requireProjectStore, } from "./session-requirements.js";
+import { ApprovalRequestParamsSchema } from "./schemas.js";
+import { requireHostProjectSession, requireProjectStore } from "./session-requirements.js";
 function readActiveApproval(options) {
     return options.approvalManager?.getActiveApproval() ?? { state: "none" };
 }
@@ -29,26 +29,19 @@ export function registerApprovalRoutes(app, options) {
     }, (request) => {
         const session = requireHostProjectSession(request, options);
         const store = requireProjectStore(options);
-        const execution = executeIdempotentCommand({
+        const execution = executeApprovalDecisionCommand({
             db: store.db,
-            command_id: request.body.command_id,
-            command_name: "approval.decide",
-            target_ref: request.params.approvalId,
-            payload: {
-                decision_id: request.body.payload.decision_id,
+            ...(options.approvalManager === undefined
+                ? {}
+                : { approvalManager: options.approvalManager }),
+            commandId: request.body.command_id,
+            approvalId: request.params.approvalId,
+            decisionId: request.body.payload.decision_id,
+            actor: {
+                account_ref: session.account.account_ref,
+                display_name: session.account.display_name,
             },
             ...(options.now === undefined ? {} : { now: options.now }),
-            execute: () => options.approvalManager?.decide({
-                approvalId: request.params.approvalId,
-                payload: request.body.payload,
-                actor: {
-                    account_ref: session.account.account_ref,
-                    display_name: session.account.display_name,
-                },
-            }) ?? {
-                disposition: { kind: "stale_approval" },
-                result: { approval: { state: "none" } },
-            },
         });
         const response = {
             command_id: execution.command_id,

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

@@ -4,6 +4,12 @@ export type DownloadedStagedUpload = {
     resolved: ResolvedStagedUpload;
     content: Buffer;
 };
+export type StagedUploadResolver = NonNullable<HostProjectApiRouteOptions["resolveStagedUpload"]>;
+export declare function downloadStagedUploadWithResolver(options: {
+    resolveStagedUpload: StagedUploadResolver;
+    expected: StagedUploadReference;
+    purpose: RelayUploadPurpose;
+}): Promise<DownloadedStagedUpload>;
 export declare function downloadStagedUpload(options: {
     routeOptions: HostProjectApiRouteOptions;
     expected: StagedUploadReference;

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

@@ -104,14 +104,14 @@ async function disposeResolvedStagedUpload(upload, status) {
         // Completion metadata is best-effort after the host has decided the terminal status.
     }
 }
-export async function downloadStagedUpload(options) {
+export async function downloadStagedUploadWithResolver(options) {
     const maxBytes = maxStagedUploadBytesForPurpose(options.purpose);
     if (options.expected.size_bytes > maxBytes) {
         throw new HostProjectValidationError(`Upload content cannot exceed ${maxBytes} bytes`);
     }
     let resolved;
     try {
-        resolved = await requireStagedUploadResolver(options.routeOptions)(options.expected.upload_id);
+        resolved = await options.resolveStagedUpload(options.expected.upload_id);
     }
     catch {
         throw new HostProjectValidationError("Upload session could not be resolved");
@@ -140,6 +140,13 @@ export async function downloadStagedUpload(options) {
         content,
     };
 }
+export async function downloadStagedUpload(options) {
+    return downloadStagedUploadWithResolver({
+        resolveStagedUpload: requireStagedUploadResolver(options.routeOptions),
+        expected: options.expected,
+        purpose: options.purpose,
+    });
+}
 export async function cleanupDownloadedStagedUpload(upload) {
     await disposeResolvedStagedUpload(upload.resolved, "completed");
 }

package/dist/workspace-ops/index.d.ts

@@ -3,11 +3,11 @@ export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
-export { uploadReferenceFile } from "./reference-files.js";
+export { readManagedReferenceSnapshotState, uploadReferenceFile, writeManagedReferenceSnapshot, } from "./reference-files.js";
 export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
 export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 export type { WorkspaceOpsErrorCode } from "./errors.js";
-export type { AcceptedCheckpointRecoveryResult, AcceptedCheckpointResult, CreateAcceptedCheckpointOptions, InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, ProjectWorkspaceInspection, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, RunDiffSummary, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";
+export type { AcceptedCheckpointRecoveryResult, AcceptedCheckpointResult, CreateAcceptedCheckpointOptions, InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, ProjectWorkspaceInspection, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, RunDiffSummary, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, WriteManagedReferenceSnapshotOptions, WriteManagedReferenceSnapshotResult, ManagedReferenceSnapshotState, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/workspace-ops/index.js

@@ -3,7 +3,7 @@ export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
-export { uploadReferenceFile } from "./reference-files.js";
+export { readManagedReferenceSnapshotState, uploadReferenceFile, writeManagedReferenceSnapshot, } from "./reference-files.js";
 export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
 export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";

package/dist/workspace-ops/reference-files.d.ts

@@ -1,3 +1,16 @@
-import type { UploadReferenceFileOptions, UploadReferenceFileResult } from "./types.js";
+import type { UploadReferenceFileOptions, UploadReferenceFileResult, WriteManagedReferenceSnapshotOptions, WriteManagedReferenceSnapshotResult, ManagedReferenceSnapshotState } from "./types.js";
 export declare function uploadReferenceFile(options: UploadReferenceFileOptions): UploadReferenceFileResult;
+/**
+ * Writes a caller-managed logical Reference snapshot at one stable path.
+ *
+ * Platform adapters remain responsible for external source identity and
+ * revision discovery. Updates use the committed blob oid as a compare-and-set
+ * boundary so a stale adapter cannot overwrite a newer local snapshot.
+ */
+export declare function writeManagedReferenceSnapshot(options: WriteManagedReferenceSnapshotOptions): WriteManagedReferenceSnapshotResult;
+export declare function readManagedReferenceSnapshotState(options: {
+    workspaceRoot: string;
+    path: string;
+    now?: () => Date;
+}): ManagedReferenceSnapshotState;
 //# sourceMappingURL=reference-files.d.ts.map