@xfey/tutti 0.1.107 → 0.1.109

package/README.md

@@ -4,6 +4,8 @@
 
 `apps/server` 是 Tutti 的项目 host service，也是机器级 Local Console 的进程入口。
 
+`0.1.109` 的 Codex skill 接入统一验证 `skills/extraRoots/set` / `skills/list` 与实际 `SKILL.md` 文件身份；Chat 的安全阶段日志可通过 invocation ref 关联外部 Reference 读取。版本发布、测试 Host 切换和飞书真人门禁分别记录于[按需资料计划](../../docs/roadmap/feishu-on-demand-reference-plan.md)，不以安装版本代替实际读取证据。
+
 它负责：
 
 - `tutti launch` 后的项目绑定、恢复和接管入口
@@ -15,6 +17,7 @@
 - host 到 Relay 的连接与工作区加入协作
 - machine-local `standalone | feishu` Project Surface authority，以及Standalone browser session / Feishu trusted integration的双向Host gate
 - Feishu主群聊Chat Assistant canonical response与Host-owned durable outbound handoff intent
+- Feishu 外部来源的按需读取、受控临时 cache、invocation 版本和 SQLite 读取证据；正式 Reference／Standalone 上传与历史 snapshot 保持，见 [external-reference-access.md](../../docs/system/external-reference-access.md)
 
 ## 结构
 

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

@@ -0,0 +1,17 @@
+import type { ProviderInvocationProgress } from "../providers/invocation-progress.js";
+export type ChatAssistantLogger = {
+    info: (fields: Record<string, unknown>, message: string) => void;
+    warn: (fields: Record<string, unknown>, message: string) => void;
+};
+type ChatAssistantProgress = ProviderInvocationProgress | {
+    stage: "queued" | "inspection_wait" | "model_requested" | "reply_persisted" | "failed" | "skipped";
+    reason_code?: "queue_full" | "stopping" | "context_unavailable" | "answer_failed" | "reply_failed";
+};
+export declare function createChatAssistantDiagnostics(options: {
+    logger?: ChatAssistantLogger;
+    projectId: string;
+    triggerMessageId: string;
+    scope: string;
+}): (event: ChatAssistantProgress) => void;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/chat-assistant/diagnostics.js

@@ -0,0 +1,27 @@
+import { createEventRef } from "@tutti/shared/ids";
+export function createChatAssistantDiagnostics(options) {
+    const requestRef = createEventRef();
+    const started = performance.now();
+    return (event) => {
+        try {
+            const fields = {
+                project_id: options.projectId,
+                chat_request_ref: requestRef,
+                trigger_message_ref: options.triggerMessageId,
+                scope: options.scope,
+                elapsed_ms: Math.round(performance.now() - started),
+                ...event,
+            };
+            if (event.stage === "failed" || event.stage === "provider_failed") {
+                options.logger?.warn(fields, "Chat assistant progress");
+            }
+            else {
+                options.logger?.info(fields, "Chat assistant progress");
+            }
+        }
+        catch {
+            /* Logging must not replace the answer or interrupt queue draining. */
+        }
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

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

@@ -1,5 +1,7 @@
 import type { ProjectId } from "@tutti/shared/ids";
 import type { MessageProjection } from "@tutti/shared/schemas/api";
+import { type ChatAssistantLogger } from "./diagnostics.js";
+import type { ProviderInvocationProgressObserver } from "../providers/invocation-progress.js";
 import { type HostProjectStore, type SqliteDatabase } from "../store/index.js";
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
 export declare const CHAT_ASSISTANT_OUTPUT_SCHEMA: {
@@ -19,6 +21,7 @@ export type ChatAssistantOutput = {
 };
 export type ChatAssistantPromptInput = {
     prompt: string;
+    onProgress?: ProviderInvocationProgressObserver;
 };
 export type ReadOnlyChatAssistantModel = {
     answer: (input: ChatAssistantPromptInput) => Promise<ChatAssistantOutput>;
@@ -35,6 +38,7 @@ export type ReadOnlyChatAssistantHandle = {
     stopAccepting: () => void;
 };
 export type ReadOnlyChatAssistantOptions = {
+    logger?: ChatAssistantLogger;
     project: {
         project_id: ProjectId;
         display_name: string;

package/dist/chat-assistant/index.js

@@ -1,3 +1,4 @@
+import { createChatAssistantDiagnostics } from "./diagnostics.js";
 import { createClarificationRoundAgentMessage, createMainChatAgentMessage, readClarificationRoundMessagesWindow, readClarificationRoundProjection, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMessageProjectionById, } from "../collaboration-state/index.js";
 import { renderPromptTemplate } from "../prompt-templates/index.js";
 import { withHostStoreTransaction, } from "../store/index.js";
@@ -111,13 +112,21 @@ export class ReadOnlyChatAssistant {
         if (!this.accepting) {
             return { triggered: false };
         }
+        const report = createChatAssistantDiagnostics({
+            ...(this.options.logger === undefined ? {} : { logger: this.options.logger }),
+            projectId: this.options.project.project_id,
+            triggerMessageId: input.message.id,
+            scope: input.message.scope.kind,
+        });
         if (this.pending.length >= this.maxQueuedMentions) {
+            report({ stage: "failed", reason_code: "queue_full" });
             this.appendAssistantMessageForTrigger(input.message, assistantFailureMessage(), {
                 scratchpad_source: "exclude",
             });
             return { triggered: true };
         }
-        this.pending.push(input.message);
+        report({ stage: "queued" });
+        this.pending.push({ message: input.message, report });
         this.pump();
         return { triggered: true };
     }
@@ -132,7 +141,8 @@ export class ReadOnlyChatAssistant {
             return;
         }
         this.accepting = false;
-        for (const message of this.pending.splice(0)) {
+        for (const { message, report } of this.pending.splice(0)) {
+            report({ stage: "skipped", reason_code: "stopping" });
             this.appendAssistantMessageForTrigger(message, assistantFailureMessage(), {
                 scratchpad_source: "exclude",
             });
@@ -143,12 +153,14 @@ export class ReadOnlyChatAssistant {
         if (this.active !== null) {
             return;
         }
-        const message = this.pending.shift();
-        if (message === undefined) {
+        const pending = this.pending.shift();
+        if (pending === undefined) {
             this.resolveIdleIfNeeded();
             return;
         }
-        const task = this.respond(message).catch(() => undefined);
+        const task = this.respond(pending.message, pending.report).catch(() => {
+            pending.report({ stage: "failed", reason_code: "reply_failed" });
+        });
         this.active = task;
         void task.finally(() => {
             if (this.active === task) {
@@ -311,23 +323,34 @@ export class ReadOnlyChatAssistant {
         }
         this.appendMainChatAssistantMessage(triggerMessage, body, refs);
     }
-    async respond(triggerMessage) {
+    async respond(triggerMessage, report) {
+        let answer;
         try {
+            report({ stage: "inspection_wait" });
             await this.options.waitForInspectionAvailability?.();
             const prompt = this.renderPrompt(triggerMessage);
             if (prompt === null) {
+                report({ stage: "skipped", reason_code: "context_unavailable" });
                 return;
             }
+            report({ stage: "model_requested" });
             const output = await this.options.model.answer({
                 prompt,
+                onProgress: report,
             });
-            this.appendAssistantMessageForTrigger(triggerMessage, normalizeAnswer(output.answer));
+            answer = normalizeAnswer(output.answer);
         }
         catch {
+            report({ stage: "failed", reason_code: "answer_failed" });
             this.appendAssistantMessageForTrigger(triggerMessage, assistantFailureMessage(), {
                 scratchpad_source: "exclude",
             });
+            report({ stage: "reply_persisted" });
+            return;
         }
+        // Persistence/outbound-hook failure must not retry by creating a second reply.
+        this.appendAssistantMessageForTrigger(triggerMessage, answer);
+        report({ stage: "reply_persisted" });
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/collaboration-ingestion/external-source.js

@@ -86,7 +86,13 @@ export function ingestTrustedConversationSource(options) {
             account_ref: options.command.actor.account_ref,
             display_name: options.command.actor.display_name,
         },
-        materialize: () => ({ kind: "message", body: source.content.text }),
+        materialize: () => ({
+            kind: "message",
+            body: source.content.text,
+            ...(source.external_references === undefined
+                ? {}
+                : { refs: { external_references: source.external_references } }),
+        }),
         idempotencyContext: {
             kind: "external_conversation_source",
             platform: source.locator.conversation.installation.platform,
@@ -94,6 +100,9 @@ export function ingestTrustedConversationSource(options) {
             external_message_ref: source.locator.message_ref,
             binding_ref: options.command.binding_ref,
             receipt_key: options.command.receipt.receipt_key,
+            ...(source.external_references === undefined
+                ? {}
+                : { external_references: source.external_references }),
         },
         afterCreate: (tx, message) => insertExternalSourceEvidence(tx, options.command, message),
         ...(options.scratchpadSource === undefined

package/dist/control-plane/task-source-context-types.d.ts

@@ -1,8 +1,9 @@
-import type { ClarificationRequestPayload } from "@tutti/shared/schemas/api";
+import type { ClarificationRequestPayload, ExternalReferenceDescriptor } from "@tutti/shared/schemas/api";
 export type PromptSourceMessage = {
     role: "human" | "tutti";
     author_display_name?: string;
     text: string;
+    external_references?: ExternalReferenceDescriptor[];
 };
 export type TaskCompileClarificationContext = {
     request_payload: ClarificationRequestPayload;

package/dist/control-plane/task-source-context.js

@@ -16,6 +16,13 @@ function promptSourceMessage(db, source) {
                 ? {}
                 : { author_display_name: displayName }),
             text: messageTextForModel(message),
+            ...(message.refs?.external_references === undefined
+                ? {}
+                : {
+                    external_references: message.refs.external_references.map((reference) => ({
+                        ...reference,
+                    })),
+                }),
         };
     }
     if (message.message_kind === "agent_text" && message.author.kind === "agent") {

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 {
@@ -145,6 +149,9 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
                 : { builtInSkillsRoot: options.builtInSkillsRoot }),
         });
         contextRuntimeHint = resolveCodexAppServerContextRuntimeHint({
+            ...(options.runtimeTelemetry?.activityRef === undefined
+                ? {}
+                : { activityRef: options.runtimeTelemetry.activityRef }),
             ...(options.skillSelectionName === undefined
                 ? {}
                 : { selectionName: options.skillSelectionName }),
@@ -164,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");
@@ -220,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;
@@ -245,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", {
@@ -295,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;
@@ -347,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);
@@ -405,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

@@ -1,3 +1,4 @@
+import type { ActivityRef } from "@tutti/shared/ids";
 export type CodexAppServerSkillInput = {
     name: string;
     path: string;
@@ -15,40 +16,35 @@ export type CodexAppServerSkillInputItem = {
 export type CodexAppServerTurnInputItem = CodexAppServerSkillInputItem | CodexAppServerTextInputItem;
 export type CodexAppServerBuiltInSkillName = "read-main-chat" | "read-project-docs" | "read-scratchpad" | "read-worklist" | "read-references" | "read-user-skills";
 export type CodexAppServerSkillSelectionName = "chat_assistant" | "project_context_bootstrap" | "task_compile" | "context_sync" | "reference_summary_refresh" | "workspace_write_run" | "follow_up_run";
-export type CodexAppServerContextApiScope = "messages:read" | "project-docs:list" | "project-docs:read" | "scratchpad:read" | "worklist:read" | "task:read" | "references:list" | "references:read" | "skills:list" | "skills:read";
+export type CodexAppServerContextApiScope = "messages:read" | "project-docs:list" | "project-docs:read" | "scratchpad:read" | "worklist:read" | "task:read" | "references:list" | "references:read" | "references:external" | "skills:list" | "skills:read";
 export type CodexAppServerSkillSelection = {
     builtInSkillNames: CodexAppServerBuiltInSkillName[];
     userSkillMode: "disabled" | "all_enabled";
     contextApiScopes: CodexAppServerContextApiScope[];
 };
 export type CodexAppServerAgentContextTokenRequest = {
+    activityRef?: ActivityRef;
     selectionName: CodexAppServerSkillSelectionName;
     scopes: CodexAppServerContextApiScope[];
 };
 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;
@@ -58,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[];
@@ -76,6 +66,7 @@ export declare function buildCodexAppServerContextRuntimeHint(options: {
     expiresAt?: string;
 }): string;
 export declare function resolveCodexAppServerContextRuntimeHint(options: {
+    activityRef?: ActivityRef;
     selectionName?: CodexAppServerSkillSelectionName;
     agentContext?: CodexAppServerAgentContextRuntime;
 }): CodexAppServerContextRuntimeHint | undefined;

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";
@@ -30,6 +30,7 @@ export const CODEX_APP_SERVER_SKILL_SELECTIONS = {
             "task:read",
             "references:list",
             "references:read",
+            "references:external",
             "skills:list",
             "skills:read",
         ],
@@ -42,6 +43,7 @@ export const CODEX_APP_SERVER_SKILL_SELECTIONS = {
             "project-docs:read",
             "references:list",
             "references:read",
+            "references:external",
         ],
     },
     task_compile: {
@@ -54,6 +56,7 @@ export const CODEX_APP_SERVER_SKILL_SELECTIONS = {
             "task:read",
             "references:list",
             "references:read",
+            "references:external",
         ],
     },
     context_sync: {
@@ -74,23 +77,29 @@ export const CODEX_APP_SERVER_SKILL_SELECTIONS = {
         contextApiScopes: [],
     },
     workspace_write_run: {
-        builtInSkillNames: ["read-project-docs", "read-worklist"],
+        builtInSkillNames: ["read-project-docs", "read-worklist", "read-references"],
         userSkillMode: "all_enabled",
         contextApiScopes: [
             "project-docs:list",
             "project-docs:read",
             "worklist:read",
             "task:read",
+            "references:list",
+            "references:read",
+            "references:external",
         ],
     },
     follow_up_run: {
-        builtInSkillNames: ["read-project-docs", "read-worklist"],
+        builtInSkillNames: ["read-project-docs", "read-worklist", "read-references"],
         userSkillMode: "all_enabled",
         contextApiScopes: [
             "project-docs:list",
             "project-docs:read",
             "worklist:read",
             "task:read",
+            "references:list",
+            "references:read",
+            "references:external",
         ],
     },
 };
@@ -112,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) {
@@ -140,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",
@@ -206,6 +189,7 @@ export function resolveCodexAppServerContextRuntimeHint(options) {
         return undefined;
     }
     const issued = options.agentContext.issueToken({
+        ...(options.activityRef === undefined ? {} : { activityRef: options.activityRef }),
         selectionName: options.selectionName,
         scopes: selection.contextApiScopes,
     });
@@ -218,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