@xfey/tutti 0.1.127 → 0.1.128

package/dist/chat-assistant/requests.d.ts

@@ -0,0 +1,30 @@
+import { type ChatRequestStatus, type OperationFailure } from "@tutti/shared/schemas/api";
+import type { SqliteDatabase } from "../store/index.js";
+export type ChatRequestRecord = {
+    trigger_message_id: string;
+    status: "queued" | "running" | "succeeded" | "failed";
+    phase: "queue" | "workspace_wait" | "answer" | "settled";
+    revision: number;
+    attempt_ref: string | null;
+    response_message_id: string | null;
+    failure_json: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export declare function readChatRequest(db: SqliteDatabase, messageId: string): ChatRequestRecord | null;
+export declare function chatRequestStatus(row: ChatRequestRecord): ChatRequestStatus;
+export declare function insertChatRequest(db: SqliteDatabase, messageId: string, now: string, failure?: OperationFailure): void;
+export declare function countQueuedChatRequests(db: SqliteDatabase): number;
+export declare function nextQueuedChatRequest(db: SqliteDatabase): ChatRequestRecord | null;
+/** CAS/fencing only. Lifecycle policy belongs to Chat Assistant, not the repository. */
+export declare function updateChatRequest(db: SqliteDatabase, row: ChatRequestRecord, next: {
+    status: ChatRequestRecord["status"];
+    phase: ChatRequestRecord["phase"];
+    attemptRef?: string;
+    responseMessageId?: string;
+    failure?: OperationFailure;
+}, now: string): ChatRequestRecord | null;
+export declare function listRunningChatRequests(db: SqliteDatabase): ChatRequestRecord[];
+/** Correlation only; never changes lifecycle state based on a progress callback. */
+export declare function linkChatRequestInvocation(db: SqliteDatabase, row: ChatRequestRecord, invocationRef: string): void;
+//# sourceMappingURL=requests.d.ts.map

package/dist/chat-assistant/requests.js

@@ -0,0 +1,58 @@
+import { Value } from "@sinclair/typebox/value";
+import { ChatRequestStatusSchema, } from "@tutti/shared/schemas/api";
+export function readChatRequest(db, messageId) {
+    return (db
+        .prepare("SELECT * FROM chat_requests WHERE trigger_message_id = ?")
+        .get(messageId) ?? null);
+}
+export function chatRequestStatus(row) {
+    const value = {
+        operation: { kind: "chat_answer", ref: row.trigger_message_id },
+        status: row.status,
+        phase: row.phase,
+        revision: row.revision,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        ...(row.response_message_id === null ? {} : { response_message_id: row.response_message_id }),
+        ...(row.failure_json === null ? {} : { failure: JSON.parse(row.failure_json) }),
+    };
+    if (!Value.Check(ChatRequestStatusSchema, value))
+        throw new Error("chat_request_invalid");
+    return value;
+}
+export function insertChatRequest(db, messageId, now, failure) {
+    db.prepare(`INSERT INTO chat_requests
+    (trigger_message_id, status, phase, failure_json, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(trigger_message_id) DO NOTHING`).run(messageId, failure ? "failed" : "queued", failure ? "settled" : "queue", failure ? JSON.stringify(failure) : null, now, now);
+}
+export function countQueuedChatRequests(db) {
+    return db
+        .prepare("SELECT count(*) AS count FROM chat_requests WHERE status = 'queued'")
+        .get().count;
+}
+export function nextQueuedChatRequest(db) {
+    return (db
+        .prepare("SELECT * FROM chat_requests WHERE status = 'queued' ORDER BY enqueue_order LIMIT 1")
+        .get() ?? null);
+}
+/** CAS/fencing only. Lifecycle policy belongs to Chat Assistant, not the repository. */
+export function updateChatRequest(db, row, next, now) {
+    const changed = db
+        .prepare(`UPDATE chat_requests SET status = ?, phase = ?,
+    attempt_ref = ?, response_message_id = ?, failure_json = ?, updated_at = ?, revision = revision + 1
+    WHERE trigger_message_id = ? AND revision = ?`)
+        .run(next.status, next.phase, next.attemptRef ?? row.attempt_ref, next.responseMessageId ?? null, next.failure ? JSON.stringify(next.failure) : null, now, row.trigger_message_id, row.revision).changes;
+    return changed === 0 ? null : readChatRequest(db, row.trigger_message_id);
+}
+export function listRunningChatRequests(db) {
+    return db
+        .prepare("SELECT * FROM chat_requests WHERE status = 'running' ORDER BY created_at, trigger_message_id")
+        .all();
+}
+/** Correlation only; never changes lifecycle state based on a progress callback. */
+export function linkChatRequestInvocation(db, row, invocationRef) {
+    db.prepare(`INSERT OR IGNORE INTO chat_request_invocations(message_id, attempt_ref, invocation_ref)
+    SELECT trigger_message_id, attempt_ref, ? FROM chat_requests
+    WHERE trigger_message_id = ? AND attempt_ref = ? AND status = 'running'`).run(invocationRef, row.trigger_message_id, row.attempt_ref);
+}
+//# sourceMappingURL=requests.js.map

package/dist/collaboration-ingestion/clarification.js

@@ -21,8 +21,10 @@ export function ingestClarificationMessage(options) {
         ...(options.now === undefined ? {} : { now: options.now }),
         execute: (tx) => {
             const result = options.controlPlane.sendClarificationRoundMessage(options.roundId, options.payload, options.author);
-            if (result.result?.message !== undefined)
+            if (result.result?.message !== undefined) {
                 options.afterCreate?.(tx, result.result.message);
+                options.chatAssistant?.register(tx, result.result.message);
+            }
             return result;
         },
     });

package/dist/collaboration-ingestion/main-chat.js

@@ -39,6 +39,7 @@ export function ingestMainChatMessage(options) {
                 ...(options.now === undefined ? {} : { now: options.now }),
             });
             options.afterCreate?.(tx, message);
+            options.chatAssistant?.register(tx, message);
             return {
                 disposition: { kind: "created", message_id: message.id },
                 result: { message },

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

@@ -1,5 +1,6 @@
 import type { AccountAvatarProjection } from "@tutti/shared/domain";
 import type { MessageProjection } from "@tutti/shared/schemas/api";
+import type { SqliteDatabase } from "../store/index.js";
 export type TrustedCollaborationAuthor = {
     kind?: "human" | "development_operator";
     account_ref: string;
@@ -10,6 +11,7 @@ export type ScratchpadSourceNotifier = {
     notify: (message: MessageProjection) => void;
 };
 export type ChatAssistantEnqueuer = {
+    register: (tx: SqliteDatabase, message: MessageProjection) => void;
     enqueue: (input: {
         message: MessageProjection;
     }) => unknown;

package/dist/collaboration-state/clarification-snapshot.d.ts

@@ -13,8 +13,9 @@ export declare function readSubmittedClarificationMessages(db: SqliteDatabase, r
         is_current_round: boolean;
     };
     refs?: {
-        task_id?: string;
         activity_ref?: string;
+        workflow_ref?: string;
+        task_id?: string;
         artifact_feedback?: {
             summary?: string;
             kind: "artifact_feedback";
@@ -106,15 +107,14 @@ export declare function readSubmittedClarificationMessages(db: SqliteDatabase, r
             blob_oid?: string;
             path: string;
             name: string;
-            source: "human_upload" | "tutti_output";
             category: "file" | "image";
+            source: "human_upload" | "tutti_output";
             size_bytes: number;
             text_read: {
                 blocked_reason?: "unknown" | "binary" | "too_large" | "unsupported_encoding" | "restricted_path" | "secret_like";
                 can_read: boolean;
             };
         };
-        workflow_ref?: string;
         clarification_round_ref?: string;
         clarification_thread_ref?: string;
         task_result?: {
@@ -141,10 +141,10 @@ export declare function readSubmittedClarificationMessages(db: SqliteDatabase, r
         };
         worklist_compile?: {
             kind: "worklist_compile";
-            title: string;
             workflow_ref: string;
+            title: string;
             tasks: {
-                status: "failed" | "pending" | "done" | "todo" | "running";
+                status: "failed" | "pending" | "running" | "done" | "todo";
                 task_id: string;
                 title: string;
                 summary: string;

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

@@ -24,7 +24,7 @@ export declare function completeTaskCompileContext(db: SqliteDatabase, input: Co
     task_changes: string[];
     receipts: {
         compiled_tasks?: {
-            status: "failed" | "pending" | "done" | "todo" | "running";
+            status: "failed" | "pending" | "running" | "done" | "todo";
             task_id: string;
             title: string;
             summary: string;

package/dist/collaboration-state/task-compile-context.js

@@ -3,6 +3,7 @@ import { readScratchpadProjection } from "./scratchpad.js";
 import { readCommunicationLanguage, copyCommunicationLanguage } from "./communication-language.js";
 import { readScratchpadSourceState } from "./scratchpad-source-state.js";
 import { nowIso, stringifyJson } from "./serialization.js";
+import { registerTaskCompileRequest, closeFailedTaskCompileRequest, } from "./task-compile-requests.js";
 function cursorIsAfter(left, right) {
     if (left === undefined) {
         return false;
@@ -145,6 +146,7 @@ export function recordTaskCompileSubmission(db, input) {
     if (readActiveTaskCompileContext(db) !== null) {
         throw new Error("An active Task Compile Context already exists");
     }
+    registerTaskCompileRequest(db, input.workflow_ref, input.accepted_activity_ref, nowIso(input.now));
     db.prepare(`
       INSERT INTO pending_task_compile_submissions (
         id,
@@ -226,6 +228,7 @@ export function captureTaskCompileContext(db, input) {
                 : { created_at: lastSource.created_at, message_id: lastSource.message_id });
         const after = submission?.source_window.after ?? sourceState.cycle_start_cursor;
         const submittedAt = nowIso(input.now);
+        registerTaskCompileRequest(tx, input.workflow_ref, input.captured_by_activity_ref, submittedAt);
         tx.prepare(`
         INSERT INTO active_task_compile_context (
           id,
@@ -337,9 +340,16 @@ export function rollbackTaskCompileContext(db, input) {
     return withHostStoreTransaction(db, (tx) => {
         const context = readActiveTaskCompileContext(tx, input.workflow_ref);
         if (context === null) {
-            return false;
+            const pending = readPendingTaskCompileSubmission(tx, input.workflow_ref);
+            if (pending === null)
+                return false;
+            // Before capture the source cursor has not moved: release only this admission.
+            closeFailedTaskCompileRequest(tx, input.workflow_ref, nowIso(input.now));
+            tx.prepare("DELETE FROM pending_task_compile_submissions WHERE workflow_ref = ?").run(input.workflow_ref);
+            return true;
         }
         const rolledBackAt = nowIso(input.now);
+        closeFailedTaskCompileRequest(tx, input.workflow_ref, rolledBackAt);
         const sourceState = readScratchpadSourceState(tx);
         const after = context.source_window.after;
         const through = context.source_window.through;

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

@@ -0,0 +1,6 @@
+import type { SqliteDatabase } from "../store/index.js";
+/** Persistence only: callers own acceptance, stage selection and rollback. */
+export declare function registerTaskCompileRequest(db: SqliteDatabase, workflowRef: string, activityRef: string, createdAt: string): void;
+export declare function linkTaskCompileActivity(db: SqliteDatabase, workflowRef: string, activityRef: string): void;
+export declare function closeFailedTaskCompileRequest(db: SqliteDatabase, workflowRef: string, now: string, code?: "task_compile_failed" | "scratchpad_empty_after_refresh"): void;
+//# sourceMappingURL=task-compile-requests.d.ts.map

package/dist/collaboration-state/task-compile-requests.js

@@ -0,0 +1,16 @@
+/** Persistence only: callers own acceptance, stage selection and rollback. */
+export function registerTaskCompileRequest(db, workflowRef, activityRef, createdAt) {
+    db.prepare(`INSERT OR IGNORE INTO task_compile_requests
+    (workflow_ref, accepted_activity_ref, current_activity_ref, created_at)
+    VALUES (?, ?, ?, ?)`).run(workflowRef, activityRef, activityRef, createdAt);
+}
+export function linkTaskCompileActivity(db, workflowRef, activityRef) {
+    db.prepare(`UPDATE task_compile_requests SET current_activity_ref = ?
+    WHERE workflow_ref = ? AND closed_at IS NULL`).run(activityRef, workflowRef);
+}
+export function closeFailedTaskCompileRequest(db, workflowRef, now, code = "task_compile_failed") {
+    db.prepare(`UPDATE task_compile_requests SET failure_code = ?, closed_at = ?
+    WHERE workflow_ref = ? AND closed_at IS NULL
+      AND NOT EXISTS (SELECT 1 FROM scratchpad_receipts WHERE workflow_ref = ?)`).run(code, now, workflowRef, workflowRef);
+}
+//# sourceMappingURL=task-compile-requests.js.map

package/dist/control-plane/task-compile-continuation.js

@@ -1,5 +1,6 @@
 import { materializeClarificationSuccessor, readActiveTaskCompileContext, readClarificationRoundProjection, readWorklistProjection, rollbackTaskCompileContext, } from "../collaboration-state/index.js";
 import { withHostStoreTransaction } from "../store/index.js";
+import { linkTaskCompileActivity } from "../collaboration-state/task-compile-requests.js";
 import { clarificationInvalidates } from "./invalidations.js";
 import { applyTaskCompileProcedureOutput } from "./task-compile-output.js";
 import { readTaskCompileClarificationRounds } from "./task-compile-clarification-context.js";
@@ -27,6 +28,7 @@ export function startControlPlaneTaskCompileContinuation(options) {
         summary: "Continuing task_compile from clarification input.",
         now: options.now,
         onTransition: (state) => {
+            linkTaskCompileActivity(options.store.db, workflowRef, state.activity.activity_ref);
             options.publishProcedureTransition(state);
             if (state.transition_kind === "terminal") {
                 options.onTerminal?.(state.activity.status === "failed"

package/dist/control-plane/task-compile-request-status.d.ts

@@ -0,0 +1,6 @@
+import type { ExecutionStatusProjection, WorklistSubmissionStatus } from "@tutti/shared/schemas/api";
+import type { SqliteDatabase } from "../store/index.js";
+/** Pure projection of owned records. A missing receipt is never proof of failure. */
+export declare function readTaskCompileRequestStatus(db: SqliteDatabase, execution: ExecutionStatusProjection, workflowRef?: string): WorklistSubmissionStatus | null;
+export declare function readTaskCompileCommandRef(db: SqliteDatabase, commandId: string): string | undefined;
+//# sourceMappingURL=task-compile-request-status.d.ts.map

package/dist/control-plane/task-compile-request-status.js

@@ -0,0 +1,70 @@
+import { readActiveClarificationProjection, readActiveTaskCompileContext, readPendingTaskCompileSubmission, } from "../collaboration-state/index.js";
+/** Pure projection of owned records. A missing receipt is never proof of failure. */
+export function readTaskCompileRequestStatus(db, execution, workflowRef) {
+    const row = workflowRef === undefined
+        ? db
+            .prepare("SELECT * FROM task_compile_requests ORDER BY rowid DESC LIMIT 1")
+            .get()
+        : db
+            .prepare("SELECT * FROM task_compile_requests WHERE workflow_ref = ?")
+            .get(workflowRef);
+    if (row === undefined)
+        return null;
+    const common = {
+        operation: { kind: "worklist_submit", ref: row.workflow_ref },
+        created_at: row.created_at,
+        activity_ref: row.current_activity_ref,
+    };
+    if (db.prepare("SELECT 1 FROM scratchpad_receipts WHERE workflow_ref = ?").get(row.workflow_ref)) {
+        return { ...common, status: "succeeded", phase: "settled" };
+    }
+    if (row.failure_code !== null) {
+        return {
+            ...common,
+            status: "failed",
+            phase: "settled",
+            failure: {
+                code: row.failure_code,
+                category: "internal",
+                recovery: "none",
+                diagnostic_id: row.workflow_ref,
+            },
+        };
+    }
+    const clarification = readActiveClarificationProjection(db);
+    if (clarification.state === "active" &&
+        clarification.thread.owner.kind === "task_compile" &&
+        clarification.thread.owner.workflow_ref === row.workflow_ref &&
+        clarification.round.status === "writable") {
+        return {
+            ...common,
+            status: "waiting_input",
+            phase: "clarification",
+            round_id: clarification.round.id,
+        };
+    }
+    const activities = execution.active_activities ?? (execution.active_activity ? [execution.active_activity] : []);
+    const active = activities.find((entry) => entry.activity_ref === row.current_activity_ref || entry.workflow_ref === row.workflow_ref);
+    if (active !== undefined) {
+        const kind = active.workflow_kind;
+        const phase = kind === "scratchpad_refresh" ||
+            kind === "reference_summary_refresh" ||
+            kind === "project_context_bootstrap" ||
+            kind === "task_compile"
+            ? kind
+            : "preparing";
+        return { ...common, activity_ref: active.activity_ref, status: "running", phase };
+    }
+    const ref = row.workflow_ref;
+    if (readPendingTaskCompileSubmission(db, ref) !== null ||
+        readActiveTaskCompileContext(db, ref) !== null) {
+        return { ...common, status: "running", phase: "preparing" };
+    }
+    return { ...common, status: "unknown", phase: "unconfirmed" };
+}
+export function readTaskCompileCommandRef(db, commandId) {
+    return db
+        .prepare("SELECT workflow_ref FROM task_compile_request_commands WHERE command_id = ?")
+        .get(commandId)?.workflow_ref;
+}
+//# sourceMappingURL=task-compile-request-status.js.map

package/dist/control-plane/task-compile-start.js

@@ -12,10 +12,15 @@ import { enqueueControlPlaneIntent } from "./dispatch-intents.js";
 import { materializePromptSourceMessages } from "./task-source-context.js";
 import { materializeRecentReferences, readPendingRecentReferenceSummaryPaths, readRecentReferenceSources, } from "./recent-references.js";
 import { startReferenceSummaryRefreshProcedure } from "./reference-summary-refresh.js";
+import { linkTaskCompileActivity, closeFailedTaskCompileRequest, } from "../collaboration-state/task-compile-requests.js";
 export function startControlPlaneTaskCompile(options) {
     const activeContext = readActiveTaskCompileContext(options.store.db);
     if (activeContext !== null) {
         return {
+            result: {
+                submission_ref: activeContext.workflow_ref,
+                activity_ref: activeContext.captured_by_activity_ref,
+            },
             disposition: {
                 kind: "already_running",
                 activity_ref: activeContext.captured_by_activity_ref,
@@ -25,6 +30,10 @@ export function startControlPlaneTaskCompile(options) {
     const pendingSubmission = readPendingTaskCompileSubmission(options.store.db);
     if (pendingSubmission !== null) {
         return {
+            result: {
+                submission_ref: pendingSubmission.workflow_ref,
+                activity_ref: pendingSubmission.accepted_activity_ref,
+            },
             disposition: {
                 kind: "already_running",
                 activity_ref: pendingSubmission.accepted_activity_ref,
@@ -72,7 +81,7 @@ export function startControlPlaneTaskCompile(options) {
                 },
             };
         }
-        return startScratchpadRefreshBeforeTaskCompileActivity({
+        const started = startScratchpadRefreshBeforeTaskCompileActivity({
             ...options,
             runner: runnerResolution.runner,
             sourceBatch,
@@ -86,6 +95,7 @@ export function startControlPlaneTaskCompile(options) {
                 now: options.now,
             }),
         });
+        return withSubmissionRef(started, taskCompileWorkflowRef);
     }
     if (!scratchpadHasSubmittableContent(scratchpad)) {
         return { disposition: { kind: "scratchpad_empty" } };
@@ -108,7 +118,12 @@ export function startControlPlaneTaskCompile(options) {
             now: options.now,
         });
     }
-    return started;
+    return withSubmissionRef(started, taskCompileWorkflowRef);
+}
+function withSubmissionRef(result, submissionRef) {
+    return result.disposition.kind === "accepted"
+        ? { ...result, result: { ...result.result, submission_ref: submissionRef } }
+        : result;
 }
 function recordTaskCompileSubmissionIntent(options) {
     return withHostStoreTransaction(options.store.db, (tx) => {
@@ -152,6 +167,7 @@ function startControlPlaneTaskCompileActivity(options) {
         summary: "Compiling Scratchpad into Worklist tasks.",
         now: options.now,
         onTransition: (state) => {
+            linkTaskCompileActivity(options.store.db, options.taskCompileWorkflowRef, state.activity.activity_ref);
             options.publishProcedureTransition(state);
             if (state.transition_kind === "terminal") {
                 options.onChainTerminal?.(state.activity.status === "failed"
@@ -206,11 +222,16 @@ function startScratchpadRefreshBeforeTaskCompileActivity(options) {
         summary: "Refreshing Scratchpad before submitting to Worklist.",
         now: options.now,
         onTransition: (state) => {
+            linkTaskCompileActivity(options.store.db, options.taskCompileWorkflowRef, state.activity.activity_ref);
             options.publishProcedureTransition(state);
             if (state.transition_kind !== "terminal") {
                 return;
             }
             if (state.activity.status !== "finished") {
+                rollbackTaskCompileContext(options.store.db, {
+                    workflow_ref: options.taskCompileWorkflowRef,
+                    now: options.now,
+                });
                 options.onChainTerminal?.({
                     state: "failed",
                     errorCode: "scratchpad_refresh_failed",
@@ -222,6 +243,10 @@ function startScratchpadRefreshBeforeTaskCompileActivity(options) {
             }
             const scratchpad = readScratchpadProjection(options.store.db);
             if (!scratchpadHasSubmittableContent(scratchpad)) {
+                withHostStoreTransaction(options.store.db, (tx) => {
+                    closeFailedTaskCompileRequest(tx, options.taskCompileWorkflowRef, options.now().toISOString(), "scratchpad_empty_after_refresh");
+                    tx.prepare("DELETE FROM pending_task_compile_submissions WHERE workflow_ref = ?").run(options.taskCompileWorkflowRef);
+                });
                 options.onChainTerminal?.({
                     state: "failed",
                     errorCode: "scratchpad_empty_after_refresh",
@@ -230,6 +255,10 @@ function startScratchpadRefreshBeforeTaskCompileActivity(options) {
             }
             const next = startReferenceSummaryGateOrNextStage(options);
             if (next.disposition.kind !== "accepted" && next.disposition.kind !== "already_running") {
+                rollbackTaskCompileContext(options.store.db, {
+                    workflow_ref: options.taskCompileWorkflowRef,
+                    now: options.now,
+                });
                 options.onChainTerminal?.({
                     state: "failed",
                     errorCode: "task_compile_stage_unavailable",
@@ -413,6 +442,10 @@ function startReferenceSummaryGateOrNextStage(options) {
         });
         registerReferenceSummaryGateWaiter(options, activeReferenceSummary.activity_ref);
         return {
+            result: {
+                submission_ref: options.taskCompileWorkflowRef,
+                activity_ref: activeReferenceSummary.activity_ref,
+            },
             disposition: {
                 kind: "already_running",
                 activity_ref: activeReferenceSummary.activity_ref,
@@ -514,6 +547,10 @@ function startProjectContextBootstrapActivity(options) {
                 return;
             }
             if (state.activity.status !== "finished") {
+                rollbackTaskCompileContext(options.store.db, {
+                    workflow_ref: options.taskCompileWorkflowRef,
+                    now: options.now,
+                });
                 options.onChainTerminal?.({ state: "failed", errorCode: "project_context_failed" });
                 return;
             }
@@ -697,6 +734,7 @@ function readOrCaptureTaskCompileContext(input) {
                 captured_by_activity_ref: input.activityRef,
                 now: input.now,
             });
+        linkTaskCompileActivity(tx, input.workflowRef, input.activityRef);
         enqueueControlPlaneIntent(tx, {
             kind: "task_compile_start",
             ownerKind: "task_compile",

package/dist/providers/failure-classification.d.ts

@@ -0,0 +1,23 @@
+declare const aliases: {
+    readonly provider_not_configured: "provider_not_configured";
+    readonly provider_auth_invalid: "provider_auth_invalid";
+    readonly provider_quota_or_billing_required: "provider_quota_or_billing_required";
+    readonly provider_rate_limited: "provider_rate_limited";
+    readonly provider_model_unavailable: "provider_model_unavailable";
+    readonly provider_network_error: "provider_network_error";
+    readonly auth_failed: "provider_auth_invalid";
+    readonly host_delegation_revoked: "provider_auth_invalid";
+    readonly authority_invalid: "provider_auth_invalid";
+    readonly gateway_rate_limited: "provider_rate_limited";
+    readonly control_queue_full: "provider_rate_limited";
+    readonly turn_timeout: "provider_timeout";
+    readonly output_parse_failed: "provider_output_invalid";
+    readonly output_validation_failed: "provider_output_invalid";
+    readonly process_lifecycle_failed: "provider_lifecycle_failed";
+    readonly process_tree_not_terminated: "provider_lifecycle_failed";
+};
+export type ProviderFailureCode = (typeof aliases)[keyof typeof aliases];
+/** Facts only, never a retry policy. Do not parse provider prose or raw stderr. */
+export declare function providerFailureCode(error: unknown): ProviderFailureCode | undefined;
+export {};
+//# sourceMappingURL=failure-classification.d.ts.map

package/dist/providers/failure-classification.js

@@ -0,0 +1,43 @@
+const aliases = {
+    provider_not_configured: "provider_not_configured",
+    provider_auth_invalid: "provider_auth_invalid",
+    provider_quota_or_billing_required: "provider_quota_or_billing_required",
+    provider_rate_limited: "provider_rate_limited",
+    provider_model_unavailable: "provider_model_unavailable",
+    provider_network_error: "provider_network_error",
+    auth_failed: "provider_auth_invalid",
+    host_delegation_revoked: "provider_auth_invalid",
+    authority_invalid: "provider_auth_invalid",
+    gateway_rate_limited: "provider_rate_limited",
+    control_queue_full: "provider_rate_limited",
+    turn_timeout: "provider_timeout",
+    output_parse_failed: "provider_output_invalid",
+    output_validation_failed: "provider_output_invalid",
+    process_lifecycle_failed: "provider_lifecycle_failed",
+    process_tree_not_terminated: "provider_lifecycle_failed",
+};
+/** Facts only, never a retry policy. Do not parse provider prose or raw stderr. */
+export function providerFailureCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const value = error;
+    const code = typeof value.code === "string" ? value.code : value.reason;
+    if (typeof code === "string" && Object.hasOwn(aliases, code))
+        return aliases[code];
+    if (code !== "turn_failed" || typeof value.details !== "object" || value.details === null)
+        return undefined;
+    const details = value.details;
+    // Quota can also carry HTTP 429; the specific bounded code takes precedence.
+    if (details.turn_error_code === "insufficient_quota")
+        return "provider_quota_or_billing_required";
+    if (details.turn_error_code === "invalid_api_key")
+        return "provider_auth_invalid";
+    if (details.turn_error_code === "model_not_found")
+        return "provider_model_unavailable";
+    if (details.turn_error_code === "rate_limit_exceeded" || details.turn_error_http_status === 429)
+        return "provider_rate_limited";
+    if (details.turn_error_http_status === 401)
+        return "provider_auth_invalid";
+    return undefined;
+}
+//# sourceMappingURL=failure-classification.js.map

package/dist/reference-access/read-evidence.d.ts

@@ -1,6 +1,8 @@
 import type { SqliteDatabase } from "../store/index.js";
 import type { ReferenceCopy } from "./cache.js";
 import type { ReferenceInvocation } from "./service.js";
+import type { ReferenceAuthorization } from "@tutti/shared/schemas/api";
+export declare function recordExternalReferenceAccessRequirement(db: SqliteDatabase, invocation: ReferenceInvocation, requestRef: string, authorization: ReferenceAuthorization, now?: () => Date): void;
 /** Prior answer context only: a source reference is not proof of freshness in a later turn. */
 export declare function readExternalReferenceReadSources(db: SqliteDatabase, invocationRef: string): string[];
 /** Durable observation, separate from evictable cache metadata; no content or locator. */

package/dist/reference-access/read-evidence.js

@@ -1,3 +1,8 @@
+export function recordExternalReferenceAccessRequirement(db, invocation, requestRef, authorization, now = () => new Date()) {
+    db.prepare(`INSERT OR IGNORE INTO external_reference_access_requirements
+    (invocation_ref, request_ref, activity_ref, authorization_ref, profile, observed_at)
+    VALUES (?, ?, ?, ?, ?, ?)`).run(invocation.reference_invocation_ref, requestRef, invocation.activity_ref ?? null, authorization.authorization_ref, authorization.profile, now().toISOString());
+}
 /** Prior answer context only: a source reference is not proof of freshness in a later turn. */
 export function readExternalReferenceReadSources(db, invocationRef) {
     return db

package/dist/reference-access/service.d.ts

@@ -8,6 +8,8 @@ export type ReferenceInvocation = {
 };
 export declare class ReferenceAuthorizationRequiredError extends Error {
     readonly result: ReferenceAuthorizationRequired;
+    readonly code = "reference_authorization_required";
+    readonly continuation = "explicit_request";
     constructor(result: ReferenceAuthorizationRequired);
 }
 export declare class ExternalReferenceAccess {

package/dist/reference-access/service.js

@@ -1,6 +1,8 @@
 import { ReferenceCacheError } from "./cache.js";
 export class ReferenceAuthorizationRequiredError extends Error {
     result;
+    code = "reference_authorization_required";
+    continuation = "explicit_request";
     constructor(result) {
         super("reference_authorization_required");
         this.result = result;

package/dist/runtime-failures.js

@@ -1,3 +1,4 @@
+import { providerFailureCode } from "./providers/failure-classification.js";
 const STABLE_FAILURE_CODE = /^[a-z][a-z0-9_]{0,63}$/u;
 export function stableRuntimeFailureCode(error, fallback) {
     if (typeof error === "object" &&
@@ -17,6 +18,19 @@ export function safeRuntimeFailureSummary(subject, error, fallbackCode) {
     if (code === "admission_unavailable" || code === "admission_closed") {
         return `${subject} stopped because provider execution is unavailable while the Host is closing. Retry after the Host is ready. (${code})`;
     }
-    return `${subject} failed because the runtime returned an internal error. Retry the action. (${code})`;
+    if (code === "reference_authorization_required") {
+        return `${subject} needs document access. Authorize using the group card, then review the task or request before continuing. (${code})`;
+    }
+    const providerCode = providerFailureCode(error);
+    if (providerCode === "provider_auth_invalid" ||
+        providerCode === "provider_quota_or_billing_required" ||
+        providerCode === "provider_model_unavailable" ||
+        providerCode === "provider_not_configured") {
+        return `${subject} could not use model access. Ask the project owner to check the provider or account, then review available recovery actions. (${providerCode})`;
+    }
+    if (providerCode === "provider_rate_limited") {
+        return `${subject} stopped because the model service is busy. Wait, then review available recovery actions. (${providerCode})`;
+    }
+    return `${subject} could not complete. Review its status and available recovery actions before continuing. (${code})`;
 }
 //# sourceMappingURL=runtime-failures.js.map

package/dist/server-shell/cli/external-reference-runtime.js

@@ -4,7 +4,7 @@ import { requestExternalReferences } from "@tutti/relay-client";
 import { isExternalReferenceList, isExternalReferenceReadResult, isExternalReferenceDescriptor, isReferenceAuthorizationRequired, } from "@tutti/shared/schemas/internal";
 import { ExternalReferenceCache } from "../../reference-access/cache.js";
 import { ExternalReferenceAccess, ReferenceAuthorizationRequiredError, } from "../../reference-access/service.js";
-import { recordExternalReferenceRead } from "../../reference-access/read-evidence.js";
+import { recordExternalReferenceRead, recordExternalReferenceAccessRequirement, } from "../../reference-access/read-evidence.js";
 import { downloadStagedUploadWithResolver, cleanupDownloadedStagedUpload, } from "../http/routes/project-api/staged-uploads.js";
 import { readHostRegistrationSecret } from "./machine-local.js";
 export function createExternalReferenceRuntime(options) {
@@ -14,6 +14,7 @@ export function createExternalReferenceRuntime(options) {
         if (!relay)
             throw new Error("reference_host_offline");
         const secret = readHostRegistrationSecret(preparation.tutti_home, preparation.project_id);
+        const requestRef = `eref_${randomUUID().replaceAll("-", "")}`;
         const result = await requestExternalReferences({
             relayUrl: preparation.relay_url,
             body: {
@@ -22,15 +23,17 @@ export function createExternalReferenceRuntime(options) {
                 host_auth: { kind: "host_registration_secret_v1", secret: secret.secret },
                 relay_project_ref: relay.relay_project_ref,
                 host_connection_ref: relay.host_connection_ref,
-                request_ref: `eref_${randomUUID().replaceAll("-", "")}`,
+                request_ref: requestRef,
                 invocation_ref: invocation.reference_invocation_ref,
                 action,
                 ...(sourceRef === undefined ? {} : { source_ref: sourceRef }),
                 ...(documentUrl === undefined ? {} : { document_url: documentUrl }),
             },
         });
-        if (isReferenceAuthorizationRequired(result))
+        if (isReferenceAuthorizationRequired(result)) {
+            recordExternalReferenceAccessRequirement(options.store.db, invocation, requestRef, result.authorization);
             throw new ReferenceAuthorizationRequiredError(result);
+        }
         return result;
     }
     return new ExternalReferenceAccess({