@xfey/tutti 0.1.108 → 0.1.110

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" | "done" | "todo" | "running" | "pending";
+            status: "failed" | "done" | "pending" | "todo" | "running";
             task_id: string;
             title: string;
             summary: string;

package/dist/providers/invocation-progress.d.ts

@@ -0,0 +1,10 @@
+export type ProviderInvocationProgress = {
+    stage: "provider_queued" | "provider_started" | "context_ready" | "skills_ready" | "turn_started" | "turn_completed" | "provider_failed";
+    invocation_ref?: string;
+    skill_count?: number;
+    completed_tool_count?: number;
+    reason_code?: "provider_unavailable" | "app_server_protocol_error" | "auth_failed" | "thread_start_failed" | "turn_failed" | "turn_timeout" | "unexpected_server_request" | "skill_selection_failed" | "output_parse_failed" | "output_validation_failed" | "file_read_not_observed" | "write_detected" | "secret_leak_detected" | "process_lifecycle_failed" | "admission_unavailable";
+};
+export type ProviderInvocationProgressObserver = (event: ProviderInvocationProgress) => void;
+export declare function reportProviderInvocationProgress(observer: ProviderInvocationProgressObserver | undefined, event: ProviderInvocationProgress): void;
+//# sourceMappingURL=invocation-progress.d.ts.map

package/dist/providers/invocation-progress.js

@@ -0,0 +1,9 @@
+export function reportProviderInvocationProgress(observer, event) {
+    try {
+        observer?.(event);
+    }
+    catch {
+        /* Diagnostics cannot change the provider outcome. */
+    }
+}
+//# sourceMappingURL=invocation-progress.js.map

package/dist/providers/openai/app-server/read-only-procedure.d.ts

@@ -1,3 +1,4 @@
+import { type ProviderInvocationProgressObserver } from "../../invocation-progress.js";
 import { type CodexAppServerLifecycleIncident } from "./invocation-lifecycle.js";
 import { type CodexAppServerInvocationCoordinator, type CodexAppServerInvocationLease } from "./invocation-coordinator.js";
 import { type CodexAppServerRuntimeTelemetryOptions } from "./runtime-telemetry.js";
@@ -5,6 +6,7 @@ import { type CodexAppServerAgentContextRuntime, type CodexAppServerSkillSelecti
 import { type OpenAiTokenUsage } from "../token-usage.js";
 export type CodexAppServerWebSearchMode = "disabled" | "cached" | "live";
 export type CodexAppServerReadOnlyProcedureInput<TOutput> = {
+    onProgress?: ProviderInvocationProgressObserver;
     apiKey: string;
     apiBaseUrl?: string;
     defaultModel?: string;

package/dist/providers/openai/app-server/read-only-procedure.js

@@ -1,7 +1,9 @@
 import { execFileSync, spawn } from "node:child_process";
 import { mkdirSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { discoverCodexAppServerSkills } from "./skill-discovery.js";
+import { reportProviderInvocationProgress, } from "../../invocation-progress.js";
 import { buildCodexAppServerProcessPlan } from "../codex-app-server.js";
 import { DEFAULT_OPENAI_MODEL } from "../model-config.js";
 import { CodexAppServerJsonRpcClient, CodexAppServerProtocolError } from "./json-rpc.js";
@@ -113,6 +115,7 @@ function structuredOutputDetails(client, text) {
 }
 export async function runCodexAppServerReadOnlyProcedure(options) {
     if (options.invocationCoordinator !== undefined && options.invocationLease === undefined) {
+        reportProviderInvocationProgress(options.onProgress, { stage: "provider_queued" });
         let lease;
         try {
             lease = await options.invocationCoordinator.acquire();
@@ -132,6 +135,7 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
             lease.release();
         }
     }
+    reportProviderInvocationProgress(options.onProgress, { stage: "provider_started" });
     let skillInputs;
     let contextRuntimeHint;
     try {
@@ -167,6 +171,13 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
             options.builtInSkillsRoot ?? "",
         ]));
     }
+    if (contextRuntimeHint !== undefined)
+        reportProviderInvocationProgress(options.onProgress, {
+            stage: "context_ready",
+            ...(contextRuntimeHint.invocation_ref === undefined
+                ? {}
+                : { invocation_ref: contextRuntimeHint.invocation_ref }),
+        });
     const model = options.defaultModel ?? DEFAULT_OPENAI_MODEL;
     const tempRoot = mkdtempSync(join(tmpdir(), "tutti-codex-readonly-procedure-"));
     const codexHome = options.session?.codexHome ?? join(tempRoot, "codex-home");
@@ -223,7 +234,7 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
         options.userSkillsRoot ?? "",
         options.builtInSkillsRoot ?? "",
         ...(contextRuntimeHint?.sensitiveValues ?? []),
-        ...skillInputs.map((skill) => skill.path),
+        ...skillInputs.flatMap((skill) => [skill.path, dirname(skill.path)]),
     ];
     const strictLeakCheckValues = [options.apiKey, ...(contextRuntimeHint?.sensitiveValues ?? [])];
     let primaryError;
@@ -248,6 +259,16 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
         if (!isApiKeyAccount(loginResponse)) {
             throw new CodexAppServerReadOnlyProcedureError("auth_failed", "Codex app-server did not accept API key auth.");
         }
+        await discoverCodexAppServerSkills({
+            client,
+            cwd: appServerCwd,
+            skills: skillInputs,
+            requestTimeoutMs,
+        });
+        reportProviderInvocationProgress(options.onProgress, {
+            stage: "skills_ready",
+            skill_count: skillInputs.length,
+        });
         let threadId;
         if (options.session?.threadId === undefined) {
             const threadStartResponse = await client.request("thread/start", {
@@ -298,6 +319,7 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
             modelProvider,
             outputSchema: options.outputSchema,
         }, requestTimeoutMs);
+        reportProviderInvocationProgress(options.onProgress, { stage: "turn_started" });
         const turnCompletedPromise = client.waitForNotification((notification) => notification.method === "turn/completed", turnTimeoutMs);
         const serverRequestPromise = client.waitForServerRequest(turnTimeoutMs);
         let completedOrRequest;
@@ -350,6 +372,10 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
         const agentText = client.notifications
             .map((notification) => extractAgentText(notification))
             .join("");
+        reportProviderInvocationProgress(options.onProgress, {
+            stage: "turn_completed",
+            completed_tool_count: structuredOutputDetails(client, agentText).completed_tool_count ?? 0,
+        });
         let parsed;
         try {
             parsed = parseCodexAppServerStructuredJson(agentText);
@@ -408,6 +434,9 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
         if (error instanceof CodexAppServerReadOnlyProcedureError) {
             primaryError = error;
         }
+        else if (error instanceof CodexAppServerSkillSelectionError) {
+            primaryError = new CodexAppServerReadOnlyProcedureError("skill_selection_failed", error.message);
+        }
         else if (error instanceof CodexAppServerProtocolError) {
             primaryError = new CodexAppServerReadOnlyProcedureError("app_server_protocol_error", redactWithKnownValues(error.message, sensitiveValues));
         }

package/dist/providers/openai/app-server/skill-discovery.d.ts

@@ -0,0 +1,10 @@
+import { type CodexAppServerSkillInput } from "./skills.js";
+export declare function discoverCodexAppServerSkills(options: {
+    client: {
+        request: (method: string, params: unknown, timeoutMs: number) => Promise<unknown>;
+    };
+    cwd: string;
+    skills: CodexAppServerSkillInput[];
+    requestTimeoutMs: number;
+}): Promise<void>;
+//# sourceMappingURL=skill-discovery.d.ts.map

package/dist/providers/openai/app-server/skill-discovery.js

@@ -0,0 +1,29 @@
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+import { isRecord } from "./runtime-helpers.js";
+import { CodexAppServerSkillSelectionError } from "./skills.js";
+// Use the pinned binary's protocol, not fields accepted only by a newer client.
+// Extra roots are process-local; each invocation owns its app-server process.
+export async function discoverCodexAppServerSkills(options) {
+    if (options.skills.length === 0)
+        return;
+    try {
+        const cwd = realpathSync(options.cwd);
+        await options.client.request("skills/extraRoots/set", { extraRoots: [...new Set(options.skills.map((skill) => dirname(skill.path)))] }, options.requestTimeoutMs);
+        const response = await options.client.request("skills/list", { cwds: [cwd], forceReload: true }, options.requestTimeoutMs);
+        const entry = isRecord(response) && Array.isArray(response.data)
+            ? response.data.find((entry) => isRecord(entry) && entry.cwd === cwd)
+            : undefined;
+        const discovered = isRecord(entry) && Array.isArray(entry.skills) ? entry.skills : [];
+        if (!options.skills.every((skill) => discovered.some((candidate) => isRecord(candidate) &&
+            candidate.name === skill.name &&
+            candidate.path === skill.path &&
+            candidate.enabled === true)))
+            throw new Error("Selected skill was not discovered");
+    }
+    catch {
+        // No discovered paths, parser errors or arbitrary RPC error bodies in diagnostics.
+        throw new CodexAppServerSkillSelectionError("skill_discovery_failed", "Codex app-server could not discover the selected skills.");
+    }
+}
+//# sourceMappingURL=skill-discovery.js.map

package/dist/providers/openai/app-server/skills.d.ts

@@ -30,27 +30,21 @@ export type CodexAppServerAgentContextTokenRequest = {
 export type CodexAppServerAgentContextToken = {
     token: string;
     expires_at?: string;
+    invocation_ref?: string;
 };
 export type CodexAppServerAgentContextRuntime = {
     baseUrl: string;
     issueToken: (input: CodexAppServerAgentContextTokenRequest) => CodexAppServerAgentContextToken;
 };
-export type CodexAppServerSkillsListWarmup = {
-    cwds: string[];
-    forceReload: true;
-    perCwdExtraUserRoots: Array<{
-        cwd: string;
-        extraUserRoots: string[];
-    }>;
-};
 export type CodexAppServerContextRuntimeHint = {
     text: string;
     sensitiveValues: string[];
     scopes: CodexAppServerContextApiScope[];
+    invocation_ref?: string;
 };
 export declare class CodexAppServerSkillSelectionError extends Error {
-    readonly code: "built_in_skill_not_found" | "built_in_skill_invalid";
-    constructor(code: "built_in_skill_not_found" | "built_in_skill_invalid", message: string);
+    readonly code: "built_in_skill_not_found" | "built_in_skill_invalid" | "skill_discovery_failed";
+    constructor(code: "built_in_skill_not_found" | "built_in_skill_invalid" | "skill_discovery_failed", message: string);
 }
 export declare const CODEX_APP_SERVER_SKILL_SELECTIONS: Record<CodexAppServerSkillSelectionName, CodexAppServerSkillSelection>;
 export declare function resolveCodexAppServerSkillSelection(selectionName: CodexAppServerSkillSelectionName): CodexAppServerSkillSelection;
@@ -60,12 +54,6 @@ export declare function resolveCodexAppServerSkillInputs(options: {
     builtInSkillsRoot?: string;
     userSkillsRoot?: string;
 }): CodexAppServerSkillInput[];
-export declare function resolveCodexAppServerSkillsListWarmup(options: {
-    cwd: string;
-    selectionName?: CodexAppServerSkillSelectionName;
-    selection?: CodexAppServerSkillSelection;
-    userSkillsRoot?: string;
-}): CodexAppServerSkillsListWarmup | undefined;
 export declare function buildCodexAppServerTurnInput(options: {
     prompt: string;
     skills?: CodexAppServerSkillInput[];

package/dist/providers/openai/app-server/skills.js

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { listUserSkills } from "../../../skills/index.js";
@@ -121,12 +121,12 @@ function resolveBuiltInSkill(options) {
     if (!statSync(skillMdPath).isFile()) {
         throw new CodexAppServerSkillSelectionError("built_in_skill_invalid", `Built-in skill is invalid: ${options.name}`);
     }
-    return { name: options.name, path };
+    return { name: options.name, path: realpathSync(skillMdPath) };
 }
 function resolveUserSkill(options) {
     return {
         name: options.name,
-        path: join(options.userSkillsRoot, options.name),
+        path: realpathSync(join(options.userSkillsRoot, options.name, "SKILL.md")),
     };
 }
 export function resolveCodexAppServerSkillSelection(selectionName) {
@@ -149,32 +149,6 @@ export function resolveCodexAppServerSkillInputs(options) {
         : [];
     return [...builtInSkills, ...userSkills];
 }
-export function resolveCodexAppServerSkillsListWarmup(options) {
-    const selection = options.selection ??
-        (options.selectionName === undefined
-            ? {
-                builtInSkillNames: [],
-                userSkillMode: "disabled",
-                contextApiScopes: [],
-            }
-            : resolveCodexAppServerSkillSelection(options.selectionName));
-    if (selection.userSkillMode !== "all_enabled" || options.userSkillsRoot === undefined) {
-        return undefined;
-    }
-    if (listUserSkills(options.userSkillsRoot).length === 0) {
-        return undefined;
-    }
-    return {
-        cwds: [options.cwd],
-        forceReload: true,
-        perCwdExtraUserRoots: [
-            {
-                cwd: options.cwd,
-                extraUserRoots: [options.userSkillsRoot],
-            },
-        ],
-    };
-}
 function createTextInputItem(text) {
     return {
         type: "text",
@@ -228,6 +202,7 @@ export function resolveCodexAppServerContextRuntimeHint(options) {
         }),
         sensitiveValues: [issued.token, options.agentContext.baseUrl],
         scopes: selection.contextApiScopes,
+        ...(issued.invocation_ref === undefined ? {} : { invocation_ref: issued.invocation_ref }),
     };
 }
 //# sourceMappingURL=skills.js.map

package/dist/providers/openai/app-server/workspace-write-run.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { mkdirSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { discoverCodexAppServerSkills } from "./skill-discovery.js";
 import { buildCodexAppServerProcessPlan } from "../codex-app-server.js";
 import { DEFAULT_OPENAI_MODEL } from "../model-config.js";
 import { CodexAppServerJsonRpcClient, CodexAppServerProtocolError, } from "./json-rpc.js";
@@ -10,7 +11,7 @@ import { CodexAppServerAdmissionError, } from "./invocation-coordinator.js";
 import { createCodexAppServerRuntimeObserver, } from "./runtime-telemetry.js";
 import { createReadOnlySandboxPolicy, createWorkspaceWriteSandboxPolicy, } from "./sandbox-policy.js";
 import { buildCodexAppServerProviderConfigOverrides, resolveCodexAppServerModelProvider, } from "./provider-config.js";
-import { buildCodexAppServerTurnInput, resolveCodexAppServerContextRuntimeHint, resolveCodexAppServerSkillsListWarmup, resolveCodexAppServerSkillInputs, CodexAppServerSkillSelectionError, } from "./skills.js";
+import { buildCodexAppServerTurnInput, resolveCodexAppServerContextRuntimeHint, resolveCodexAppServerSkillInputs, CodexAppServerSkillSelectionError, } from "./skills.js";
 import { compactText, containsKnownSecret, createCodexSpawnEnv, extractAgentText, extractServerRequestMethod, findJsonObjectCandidates, isApiKeyAccount, readThreadId, readTurnError, readTurnStatus, redactWithKnownValues, } from "./runtime-helpers.js";
 import { extractCodexAppServerTokenUsage } from "../token-usage.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
@@ -170,7 +171,6 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         }
     }
     let skillInputs;
-    let skillsListWarmup;
     let contextRuntimeHint;
     try {
         skillInputs = resolveCodexAppServerSkillInputs({
@@ -182,13 +182,6 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
                 ? {}
                 : { builtInSkillsRoot: options.builtInSkillsRoot }),
         });
-        skillsListWarmup = resolveCodexAppServerSkillsListWarmup({
-            cwd: options.workspaceRoot,
-            ...(options.skillSelectionName === undefined
-                ? {}
-                : { selectionName: options.skillSelectionName }),
-            ...(options.userSkillsRoot === undefined ? {} : { userSkillsRoot: options.userSkillsRoot }),
-        });
         contextRuntimeHint = resolveCodexAppServerContextRuntimeHint({
             ...(options.approvalContext?.activityRef === undefined
                 ? {}
@@ -267,11 +260,7 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         options.userSkillsRoot ?? "",
         options.builtInSkillsRoot ?? "",
         ...(contextRuntimeHint?.sensitiveValues ?? []),
-        ...skillInputs.map((skill) => skill.path),
-        ...(skillsListWarmup?.perCwdExtraUserRoots.flatMap((entry) => [
-            entry.cwd,
-            ...entry.extraUserRoots,
-        ]) ?? []),
+        ...skillInputs.flatMap((skill) => [skill.path, dirname(skill.path)]),
     ];
     const strictLeakCheckValues = [options.apiKey, ...(contextRuntimeHint?.sensitiveValues ?? [])];
     let primaryError;
@@ -297,9 +286,12 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         if (!isApiKeyAccount(loginResponse)) {
             throw new CodexAppServerWorkspaceWriteRunError("auth_failed", "Codex app-server did not accept API key auth.");
         }
-        if (skillsListWarmup !== undefined) {
-            await client.request("skills/list", skillsListWarmup, requestTimeoutMs);
-        }
+        await discoverCodexAppServerSkills({
+            client,
+            cwd: options.workspaceRoot,
+            skills: skillInputs,
+            requestTimeoutMs,
+        });
         let threadId;
         if (options.session?.threadId === undefined) {
             const threadStartResponse = await client.request("thread/start", {
@@ -484,7 +476,9 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         }
         else {
             const message = error instanceof Error ? error.message : String(error);
-            primaryError = new CodexAppServerWorkspaceWriteRunError("app_server_protocol_error", redactWithKnownValues(message, sensitiveValues), { turn_start_state: turnStartState });
+            primaryError = new CodexAppServerWorkspaceWriteRunError(error instanceof CodexAppServerSkillSelectionError
+                ? "skill_selection_failed"
+                : "app_server_protocol_error", redactWithKnownValues(message, sensitiveValues), { turn_start_state: turnStartState });
         }
     }
     finally {

package/dist/providers/openai/chat-assistant.js

@@ -1,12 +1,14 @@
 import { CHAT_ASSISTANT_OUTPUT_SCHEMA, isChatAssistantOutput, } from "../../chat-assistant/index.js";
 import { readOpenAiApiKeyCredential } from "./credential-store.js";
-import { resolveOpenAiProviderConfig, } from "./provider-config.js";
-import { runCodexAppServerReadOnlyProcedure } from "./app-server/read-only-procedure.js";
+import { resolveOpenAiProviderConfig } from "./provider-config.js";
+import { CodexAppServerReadOnlyProcedureError, runCodexAppServerReadOnlyProcedure, } from "./app-server/read-only-procedure.js";
+import { reportProviderInvocationProgress } from "../invocation-progress.js";
 import { getProjectUserSkillsRoot } from "../../skills/index.js";
 export function createOpenAiReadOnlyChatAssistantModel(options) {
     return {
         async answer(input) {
             const result = await runCodexAppServerReadOnlyProcedure({
+                ...(input.onProgress === undefined ? {} : { onProgress: input.onProgress }),
                 apiKey: options.apiKey,
                 workspaceRoot: options.workspaceRoot,
                 prompt: input.prompt,
@@ -37,6 +39,14 @@ export function createOpenAiReadOnlyChatAssistantModel(options) {
                 ...(options.onLifecycleIncident === undefined
                     ? {}
                     : { onLifecycleIncident: options.onLifecycleIncident }),
+            }).catch((error) => {
+                reportProviderInvocationProgress(input.onProgress, {
+                    stage: "provider_failed",
+                    reason_code: error instanceof CodexAppServerReadOnlyProcedureError
+                        ? error.code
+                        : "provider_unavailable",
+                });
+                throw error;
             });
             if (options.recordUsage !== undefined && result.usage !== undefined) {
                 options.recordUsage({

package/dist/reference-access/message-context.d.ts

@@ -0,0 +1,6 @@
+import type { MessageProjection } from "@tutti/shared/schemas/api";
+/** Location hints, not access grants or current-read evidence. Never copy private locators. */
+export declare function externalReferenceMessageContext(refs: MessageProjection["refs"]): {
+    external_reference_sources?: string[];
+};
+//# sourceMappingURL=message-context.d.ts.map

package/dist/reference-access/message-context.js

@@ -0,0 +1,11 @@
+/** Location hints, not access grants or current-read evidence. Never copy private locators. */
+export function externalReferenceMessageContext(refs) {
+    const sources = [
+        ...(refs?.external_references?.map((source) => source.source_ref) ?? []),
+        ...(refs?.external_reference_reads ?? []),
+    ];
+    return sources.length === 0
+        ? {}
+        : { external_reference_sources: [...new Set(sources)].slice(0, 16) };
+}
+//# sourceMappingURL=message-context.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";
+/** 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. */
 export declare function recordExternalReferenceRead(db: SqliteDatabase, invocation: ReferenceInvocation, copy: ReferenceCopy): void;
 //# sourceMappingURL=read-evidence.d.ts.map

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

@@ -1,3 +1,11 @@
+/** Prior answer context only: a source reference is not proof of freshness in a later turn. */
+export function readExternalReferenceReadSources(db, invocationRef) {
+    return db
+        .prepare(`SELECT source_ref FROM external_reference_reads
+       WHERE invocation_ref = ? ORDER BY checked_at, source_ref LIMIT 16`)
+        .all(invocationRef)
+        .map((row) => row.source_ref);
+}
 /** Durable observation, separate from evictable cache metadata; no content or locator. */
 export function recordExternalReferenceRead(db, invocation, copy) {
     const invocationRef = invocation.reference_invocation_ref;

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

@@ -17,6 +17,7 @@ export function createExternalReferenceRuntime(options) {
         return requestExternalReferences({
             relayUrl: preparation.relay_url,
             body: {
+                supports_drive_files: true,
                 project_identity: { source: "git_config", project_id: preparation.project_id },
                 host_auth: { kind: "host_registration_secret_v1", secret: secret.secret },
                 relay_project_ref: relay.relay_project_ref,

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

@@ -137,6 +137,7 @@ function createAgentContextRuntime(options) {
             return {
                 token: token.token,
                 expires_at: token.expires_at,
+                invocation_ref: token.reference_invocation_ref,
             };
         },
     };
@@ -419,6 +420,7 @@ export async function startForegroundHostServer(options) {
         }),
     });
     const chatAssistant = new ReadOnlyChatAssistant({
+        logger: createHostRuntimeLogger({ component: "chat-assistant", logFilePath, now }),
         project: chatAssistantProject,
         store,
         events: workspaceEvents,

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

@@ -16,20 +16,43 @@ export function registerAgentContextExternalReferenceRoutes(app, options) {
         }, async (request, reply) => {
             reply.header("cache-control", "no-store");
             const invocation = authorizeAgentContextRequest(request, options, "references:external");
+            const started = performance.now();
+            const diagnosticFields = {
+                action,
+                invocation_ref: invocation.reference_invocation_ref,
+                activity_ref: invocation.activity_ref,
+            };
+            request.log.info({ ...diagnosticFields, stage: "external_reference_request" }, "External Reference request started");
             const service = options.externalReferences;
-            if (!service)
+            if (!service) {
+                request.log.info({
+                    ...diagnosticFields,
+                    stage: "external_reference_unavailable",
+                    reason_code: "external_references_not_enabled",
+                }, "External Reference service unavailable");
                 return { kind: "unavailable", reason: "external_references_not_enabled" };
+            }
             const sourceRef = request.query.source_ref;
             if (action === "read" &&
                 (sourceRef === undefined || !/^external_ref_[a-f0-9]{32}$/u.test(sourceRef)))
                 return { kind: "unavailable", reason: "reference_source_invalid" };
             try {
-                if (action === "list")
-                    return { items: await service.list(invocation) };
+                if (action === "list") {
+                    const items = await service.list(invocation);
+                    request.log.info({
+                        ...diagnosticFields,
+                        stage: "external_reference_list",
+                        source_count: items.length,
+                        elapsed_ms: Math.round(performance.now() - started),
+                    }, "External Reference sources listed");
+                    return { items };
+                }
                 const result = await service.read(invocation, sourceRef);
                 const { copy } = result;
                 request.log.info({
                     stage: "external_reference_read",
+                    action,
+                    elapsed_ms: Math.round(performance.now() - started),
                     invocation_ref: invocation.reference_invocation_ref,
                     activity_ref: invocation.activity_ref,
                     source_ref: copy.source_ref,
@@ -53,6 +76,7 @@ export function registerAgentContextExternalReferenceRoutes(app, options) {
                     kind: text === undefined ? "local_file" : "text",
                     ...copy,
                     cache_hit: result.cache_hit,
+                    provenance: { origin: "external_reference", verification: "this_invocation" },
                     ...(safeText === undefined
                         ? {}
                         : {
@@ -70,7 +94,9 @@ export function registerAgentContextExternalReferenceRoutes(app, options) {
                             ? "reference_cache_unsafe"
                             : "reference_read_unavailable";
                 request.log.warn({
-                    stage: "external_reference_read",
+                    stage: "external_reference_unavailable",
+                    action,
+                    elapsed_ms: Math.round(performance.now() - started),
                     invocation_ref: invocation.reference_invocation_ref,
                     activity_ref: invocation.activity_ref,
                     ...(sourceRef === undefined ? {} : { source_ref: sourceRef }),

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

@@ -1,4 +1,5 @@
 import { readMainChatMessageWindow } from "../../../collaboration-state/index.js";
+import { externalReferenceMessageContext } from "../../../reference-access/message-context.js";
 import { authorizeAgentContextRequest } from "./agent-context-auth.js";
 import { AgentContextBadRequestError } from "./agent-context-errors.js";
 import { boundedLimit, queryString, truncateText } from "./agent-context-query.js";
@@ -44,6 +45,7 @@ export function registerAgentContextMessageRoutes(app, options) {
                     },
                     body: body.text,
                     body_truncated: body.truncated,
+                    ...externalReferenceMessageContext(message.refs),
                     ...(message.refs?.reference_file === undefined
                         ? {}
                         : {

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

@@ -3,11 +3,17 @@ import { VIEWER_HARD_READ_LIMIT_BYTES, WorkspaceOpsError, readReferenceSummaryIn
 import { authorizeAgentContextRequest } from "./agent-context-auth.js";
 import { AgentContextBadRequestError } from "./agent-context-errors.js";
 import { boundedLimit, pageByOffset, queryString } from "./agent-context-query.js";
-import { mapReferenceUnavailableReason, referenceListItems, } from "./agent-context-references.js";
+import { mapReferenceUnavailableReason, localReferenceProvenance, managedReferencePaths, referenceListItems, } from "./agent-context-references.js";
 import { AGENT_CONTEXT_BASE_PATH, REFERENCE_FILE_DEFAULT_MAX_BYTES, REFERENCE_FILE_MAX_BYTES, REFERENCES_LIMIT_DEFAULT, REFERENCES_LIMIT_MAX, requireWorkspaceRoot, } from "./agent-context-shared.js";
 export function registerAgentContextReferenceRoutes(app, options) {
     app.get(`${AGENT_CONTEXT_BASE_PATH}/references`, (request) => {
-        authorizeAgentContextRequest(request, options, "references:list");
+        const invocation = authorizeAgentContextRequest(request, options, "references:list");
+        const started = performance.now();
+        request.log.info({
+            stage: "local_reference_request",
+            action: "list",
+            invocation_ref: invocation.reference_invocation_ref,
+        }, "Local Reference request started");
         const query = request.query;
         const limit = boundedLimit(query.limit, {
             default: REFERENCES_LIMIT_DEFAULT,
@@ -20,6 +26,12 @@ export function registerAgentContextReferenceRoutes(app, options) {
             ...(cursor === undefined ? {} : { cursor }),
             limit,
         });
+        request.log.info({
+            stage: "local_reference_list",
+            invocation_ref: invocation.reference_invocation_ref,
+            source_count: page.items.length,
+            elapsed_ms: Math.round(performance.now() - started),
+        }, "Local References listed; remote freshness not checked");
         return {
             items: page.items,
             page: {
@@ -29,7 +41,13 @@ export function registerAgentContextReferenceRoutes(app, options) {
         };
     });
     app.get(`${AGENT_CONTEXT_BASE_PATH}/references/file`, (request) => {
-        authorizeAgentContextRequest(request, options, "references:read");
+        const invocation = authorizeAgentContextRequest(request, options, "references:read");
+        const started = performance.now();
+        const diagnosticFields = {
+            invocation_ref: invocation.reference_invocation_ref,
+            action: "read",
+        };
+        request.log.info({ ...diagnosticFields, stage: "local_reference_request" }, "Local Reference request started");
         const path = queryString(request.query.path);
         if (path === undefined || path.trim() === "") {
             throw new AgentContextBadRequestError("Reference path is required");
@@ -49,12 +67,21 @@ export function registerAgentContextReferenceRoutes(app, options) {
                 entry: file.file,
                 summaries: readReferenceSummaryIndex({ workspaceRoot: requireWorkspaceRoot(options) }),
             });
+            const provenance = localReferenceProvenance(file.file.path, managedReferencePaths(options));
+            request.log.info({
+                ...diagnosticFields,
+                stage: "local_reference_read",
+                ...provenance,
+                result_kind: file.content.kind,
+                elapsed_ms: Math.round(performance.now() - started),
+            }, "Local Reference read; remote freshness not checked");
             if (file.content.kind !== "text") {
                 return {
                     kind: "unavailable",
                     path,
                     reason: file.content.reason,
                     summary,
+                    provenance,
                 };
             }
             return {
@@ -62,12 +89,21 @@ export function registerAgentContextReferenceRoutes(app, options) {
                 path: file.file.path,
                 name: file.file.name,
                 summary,
+                provenance,
                 text: redactText(file.content.text),
                 truncated: file.content.truncated,
                 bytes_read: file.content.bytes_returned,
             };
         }
         catch (error) {
+            request.log.warn({
+                ...diagnosticFields,
+                stage: "local_reference_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) {
                 return {
                     kind: "unavailable",