@cjhyy/code-shell-server 0.9.44 → 0.9.47

package/dist/hub/session-management.js

@@ -1,4 +1,5 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, } from "node:fs";
+import { SessionFileError, readSessionFileSync, sessionListStorage, } from "@cjhyy/code-shell-host/session-files";
+import { listSessionEntries } from "@cjhyy/code-shell-core/internal";
 import { join, resolve } from "node:path";
 import { SessionManager } from "@cjhyy/code-shell-core";
 import { replayTranscript, transcriptUserDisplay } from "@cjhyy/code-shell-web";
@@ -21,62 +22,25 @@ function safeSessionId(sessionId) {
 }
 function boundedSessionFile(rootDir, sessionId, filename, limit) {
     safeSessionId(sessionId);
-    let directory;
-    let descriptor;
     try {
-        const root = realpathSync(rootDir);
-        const path = join(root, sessionId);
-        const info = lstatSync(path);
-        if (!info.isDirectory() || info.isSymbolicLink())
-            throw new SessionRequestError(403, "会话存储位置无效。");
-        directory = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_DIRECTORY ?? 0));
-        const openedDirectory = fstatSync(directory);
-        if (openedDirectory.dev !== info.dev || openedDirectory.ino !== info.ino)
-            throw new SessionRequestError(409, "会话存储正在变化，请重试。");
-        descriptor = openSync(process.platform === "linux"
-            ? `/proc/self/fd/${directory}/${filename}`
-            : join(path, filename), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
-        const file = fstatSync(descriptor);
-        if (!file.isFile())
-            throw new SessionRequestError(403, "会话记录不是普通文件。");
-        if (file.size > limit)
-            throw new SessionRequestError(413, filename === "transcript.jsonl"
-                ? "对话记录超过浏览器可读取的 32 MB 上限，请从服务器会话备份中获取完整记录。"
-                : "会话状态记录过大，无法在浏览器读取。");
-        // Snapshot exactly the checked prefix. An append during a running turn can
-        // be picked up by the live overlay without growing this allocation.
-        const buffer = Buffer.alloc(file.size);
-        let bytes = 0;
-        while (bytes < buffer.length) {
-            const count = readSync(descriptor, buffer, bytes, buffer.length - bytes, bytes);
-            if (!count)
-                break;
-            bytes += count;
-        }
-        const currentDirectory = lstatSync(path);
-        const currentFile = lstatSync(join(path, filename));
-        if (currentDirectory.isSymbolicLink() ||
-            currentFile.isSymbolicLink() ||
-            currentDirectory.dev !== info.dev ||
-            currentDirectory.ino !== info.ino ||
-            currentFile.dev !== file.dev ||
-            currentFile.ino !== file.ino)
-            throw new SessionRequestError(409, "会话存储正在变化，请重试。");
-        return buffer.subarray(0, bytes).toString("utf8");
+        return readSessionFileSync(resolve(rootDir), sessionId, filename, limit);
     }
     catch (error) {
+        if (error instanceof SessionFileError) {
+            if (error.code === "too_large")
+                throw new SessionRequestError(413, filename === "transcript.jsonl"
+                    ? "对话记录超过浏览器可读取的 32 MB 上限，请从服务器会话备份中获取完整记录。"
+                    : "会话状态记录过大，无法在浏览器读取。");
+            if (error.code === "changed")
+                throw new SessionRequestError(409, "会话存储正在变化，请重试。");
+            throw new SessionRequestError(403, "会话存储位置无效。");
+        }
         if (error.code === "ENOENT")
             throw new SessionRequestError(404, "会话记录不存在或已移动。");
         if (["ELOOP", "ENOTDIR"].includes(error.code ?? ""))
             throw new SessionRequestError(403, "不能读取符号链接中的会话记录。");
         throw error;
     }
-    finally {
-        if (descriptor !== undefined)
-            closeSync(descriptor);
-        if (directory !== undefined)
-            closeSync(directory);
-    }
 }
 /** Synchronous, side-effect-free transcript snapshot used by HTTP exports and WS replay. */
 export function readHubTranscript(sessionRootDir, sessionId) {
@@ -120,7 +84,8 @@ export function readHubSessionState(sessionRootDir, sessionId) {
     }
 }
 export function createHubSessions(options) {
-    const manager = new SessionManager(options.sessionRootDir);
+    const sessionRootDir = resolve(options.sessionRootDir);
+    const manager = new SessionManager(sessionRootDir);
     const titles = createSessionTitlesStore(join(options.dataDir, "session-titles.json"), {
         strictMutations: true,
     });
@@ -130,7 +95,7 @@ export function createHubSessions(options) {
         safeSessionId(sessionId);
         try {
             // Reading state alone avoids loading a large transcript for a rename.
-            const state = readHubSessionState(options.sessionRootDir, sessionId);
+            const state = readHubSessionState(sessionRootDir, sessionId);
             if (!state ||
                 state.sessionId !== sessionId ||
                 typeof state.cwd !== "string" ||
@@ -190,7 +155,7 @@ export function createHubSessions(options) {
         }
         const customTitles = await titles.listTitles();
         const search = query.toLocaleLowerCase();
-        const entries = manager.list(limit + 1, {
+        const entries = listSessionEntries(sessionRootDir, limit + 1, {
             cwd,
             rootsOnly: true,
             ...(archived !== "all" ? { archived: archived === "true" } : {}),
@@ -200,7 +165,7 @@ export function createHubSessions(options) {
                     .toLocaleLowerCase()
                     .includes(search)
                 : undefined,
-        });
+        }, sessionListStorage(sessionRootDir));
         const page = entries.slice(0, limit);
         const last = page.at(-1);
         return {
@@ -249,7 +214,7 @@ export function createHubSessions(options) {
                     throw new SessionRequestError(429, "正在导出的对话过多，请稍后重试。");
                 activeExports++;
                 exporting = true;
-                const transcript = readHubTranscript(options.sessionRootDir, sessionId);
+                const transcript = readHubTranscript(sessionRootDir, sessionId);
                 const format = url.searchParams.get("format") ?? "markdown";
                 if (format !== "json" && format !== "markdown")
                     throw new SessionRequestError(400, "不支持这个导出格式。");

package/dist/hub/skills-management.js

@@ -1,8 +1,8 @@
 import { randomBytes, createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { SettingsManager, scanSkills, invalidateSkillCache, userHome, } from "@cjhyy/code-shell-core";
-import { computeEffectiveDisabledLists } from "@cjhyy/code-shell-core/internal";
+import { scanSkills, invalidateSkillCache, userHome } from "@cjhyy/code-shell-core";
+import { readSkillInventory } from "@cjhyy/code-shell-host";
 import { assertSafeSkillName, assertOwnedSkillDirectory, readSkillBundle, readBoundedSkillFile, validateSkillMarkdown, skillRoot, stageSkillDirectory, commitSkillDirectory, editSkillMarkdown, removeOwnedSkill, SkillConflictError, inspectRepo, getRefCommit, downloadSkillTree, parseSkillSourceMeta, SKILL_META_FILE, } from "@cjhyy/code-shell-core/internal/skills";
 import { HubConfigurationError } from "./configuration.js";
 const ROOT = "/api/v1/skills";
@@ -59,11 +59,9 @@ export function createHubSkills(options) {
         return skill;
     }
     function snapshot() {
-        invalidateSkillCache();
-        const manager = new SettingsManager(options.cwd, "full");
-        const disabled = computeEffectiveDisabledLists(manager, options.cwd);
-        const enabled = new Set(scanSkills(options.cwd, disabled).map((entry) => entry.name));
-        const skills = scanSkills(options.cwd).map((skill) => {
+        const inventory = readSkillInventory(options.cwd, { refresh: true });
+        const disabled = inventory;
+        const skills = inventory.skills.map(({ definition: skill, enabled }) => {
             let editable = false;
             let revision = createHash("sha256").update(skill.content).digest("hex");
             let readOnlyReason;
@@ -89,7 +87,7 @@ export function createHubSkills(options) {
                 name: skill.name,
                 description: skill.description,
                 source: skill.source,
-                enabled: enabled.has(skill.name),
+                enabled,
                 editable,
                 removable: editable,
                 revision,

package/dist/hub/uploads.d.ts

@@ -13,10 +13,20 @@ export declare class HubUploads {
     private readonly uploads;
     private readonly active;
     private closed;
+    /** This Host's own spool directory, held by a renewed lease while it runs. */
+    private readonly spool;
+    private releaseLease?;
     constructor(root: string, cwd: string);
     ready(): Promise<void>;
+    private reclaimAbandoned;
     accept(id: string, owner: string, req: IncomingMessage, res: ServerResponse, stillAuthorized: () => Promise<boolean>): Promise<void>;
     prepare(ids: unknown, owner: string, sessionId: unknown): Promise<PreparedHubUploads>;
+    /**
+     * Drop an owner's unsent upload, for example when it is removed from the
+     * draft. An upload being claimed by a send stays put. Returns whether the
+     * upload was discarded.
+     */
+    discard(id: string, owner: string): Promise<boolean>;
     sweep(): Promise<void>;
     close(): Promise<void>;
 }

package/dist/hub/uploads.js

@@ -2,9 +2,18 @@ import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, lstat, mkdir, open, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { markAttachmentsSent, stageFileBytes, stageImageBytes, } from "../attachment-service.js";
+import { lockSync } from "@cjhyy/code-shell-core/internal";
+import { isStageableImageMime, markAttachmentsSent, MAX_STAGED_IMAGE_BYTES, stageFileBytes, stageImageBytes, } from "../attachment-service.js";
 const MAX_BYTES = 20 * 1024 * 1024;
 const TTL_MS = 15 * 60 * 1000;
+/** Instance leases are renewed every 10s; a lease idle for 30s belongs to a dead Host. */
+const LEASE_STALE_MS = 30_000;
+const LEASE_UPDATE_MS = 10_000;
+const UUID = "[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}";
+const LEGACY_SPOOL = new RegExp(`^${UUID}\\.upload$`);
+const INSTANCE_ENTRY = new RegExp(`^(instance-${UUID})(?:\\.lock)?$`);
+/** Image MIME types go through image staging; everything else is staged as a file. */
+const routesToImageStaging = (mimeType) => mimeType.startsWith("image/") && mimeType !== "image/svg+xml";
 const SAFE_ID = /^[a-zA-Z0-9_-]{8,80}$/;
 // Match the session/history boundary so existing dotted session IDs can attach files.
 const SAFE_SESSION_ID = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$/;
@@ -30,9 +39,13 @@ export class HubUploads {
     uploads = new Map();
     active = new Set();
     closed = false;
+    /** This Host's own spool directory, held by a renewed lease while it runs. */
+    spool;
+    releaseLease;
     constructor(root, cwd) {
         this.root = root;
         this.cwd = cwd;
+        this.spool = join(root, `instance-${randomUUID()}`);
     }
     async ready() {
         await mkdir(this.root, { recursive: true, mode: 0o700 });
@@ -40,10 +53,55 @@ export class HubUploads {
         if (!info.isDirectory() || info.isSymbolicLink())
             throw new Error("unsafe upload directory");
         await chmod(this.root, 0o700);
-        // A pending draft cannot survive a restart; staged attachments live in the workspace.
+        // A pending draft cannot survive a restart; staged attachments live in the
+        // workspace. Several Hosts (a duplicate launch that has not bound its port
+        // yet, or another port) can share this root, so reclaim only spools that
+        // are provably unused instead of everything present.
+        await this.reclaimAbandoned();
+        await mkdir(this.spool, { mode: 0o700 });
+        this.releaseLease = lockSync(this.spool, {
+            stale: LEASE_STALE_MS,
+            update: LEASE_UPDATE_MS,
+            realpath: false,
+            retries: 0,
+            // A lost lease only risks another Host reclaiming these drafts; sends then
+            // fail with "upload not found", which the client already handles.
+            onCompromised: () => { },
+        });
+    }
+    async reclaimAbandoned() {
+        const instances = new Set();
         for (const name of await readdir(this.root)) {
-            if (/^[a-f0-9-]{36}\.upload$/.test(name))
-                await rm(join(this.root, name), { force: true });
+            const instance = INSTANCE_ENTRY.exec(name)?.[1];
+            if (instance) {
+                instances.add(instance);
+                continue;
+            }
+            // Hosts before instance leases spooled into the root. An older live Host
+            // rejects anything past the TTL, so only expired files are safe to remove.
+            if (!LEGACY_SPOOL.test(name))
+                continue;
+            const path = join(this.root, name);
+            const entry = await lstat(path).catch(() => undefined);
+            if (entry?.isFile() && Date.now() - entry.mtimeMs >= TTL_MS)
+                await rm(path, { force: true });
+        }
+        for (const instance of instances) {
+            const path = join(this.root, instance);
+            let release;
+            try {
+                // Succeeds only when no live Host renews this instance's lease.
+                release = lockSync(path, { stale: LEASE_STALE_MS, realpath: false, retries: 0 });
+            }
+            catch {
+                continue;
+            }
+            try {
+                await rm(path, { recursive: true, force: true });
+            }
+            finally {
+                release();
+            }
         }
     }
     async accept(id, owner, req, res, stillAuthorized) {
@@ -70,6 +128,21 @@ export class HubUploads {
             return reject(400, "empty or invalid upload");
         if (size > MAX_BYTES)
             return reject(413, "attachment exceeds 20 MiB");
+        const mimeType = String(req.headers["content-type"] ?? "application/octet-stream")
+            .split(";", 1)[0]
+            .trim()
+            .toLowerCase();
+        if (mimeType.length > 128 || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(mimeType)) {
+            return reject(400, "invalid content type");
+        }
+        // Admit only what the send path can stage, so a draft never looks
+        // uploaded and then fails on every Send.
+        if (routesToImageStaging(mimeType)) {
+            if (!isStageableImageMime(mimeType))
+                return reject(415, "unsupported image type");
+            if (size > MAX_STAGED_IMAGE_BYTES)
+                return reject(413, "image exceeds 10 MiB");
+        }
         if ([...this.uploads.values()].reduce((sum, entry) => sum + entry.size, size) >
             128 * 1024 * 1024) {
             return reject(429, "upload storage quota exceeded");
@@ -84,20 +157,13 @@ export class HubUploads {
         if (!name.trim() || name.length > 255 || /[\x00-\x1f/\\]/.test(name)) {
             return reject(400, "invalid file name");
         }
-        const mimeType = String(req.headers["content-type"] ?? "application/octet-stream")
-            .split(";", 1)[0]
-            .trim()
-            .toLowerCase();
-        if (mimeType.length > 128 || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(mimeType)) {
-            return reject(400, "invalid content type");
-        }
         const upload = {
             id,
             owner,
             name,
             mimeType,
             size,
-            path: join(this.root, `${randomUUID()}.upload`),
+            path: join(this.spool, `${randomUUID()}.upload`),
             createdAt: Date.now(),
             status: "receiving",
         };
@@ -108,8 +174,11 @@ export class HubUploads {
         deadline.unref?.();
         try {
             // Recheck the managed root: a workspace tool must not redirect the upload writer via symlink.
-            if (!(await lstat(this.root)).isDirectory() || (await lstat(this.root)).isSymbolicLink()) {
-                throw new Error("unsafe upload directory");
+            for (const directory of [this.root, this.spool]) {
+                const current = await lstat(directory);
+                if (!current.isDirectory() || current.isSymbolicLink()) {
+                    throw new Error("unsafe upload directory");
+                }
             }
             handle = await open(upload.path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
             let received = 0;
@@ -188,7 +257,7 @@ export class HubUploads {
                     bytes,
                     origin: "mobile",
                 };
-                result.push(record.mimeType.startsWith("image/") && record.mimeType !== "image/svg+xml"
+                result.push(routesToImageStaging(record.mimeType)
                     ? await stageImageBytes(input)
                     : await stageFileBytes(input));
             }
@@ -224,6 +293,19 @@ export class HubUploads {
             throw error;
         }
     }
+    /**
+     * Drop an owner's unsent upload, for example when it is removed from the
+     * draft. An upload being claimed by a send stays put. Returns whether the
+     * upload was discarded.
+     */
+    async discard(id, owner) {
+        const record = this.uploads.get(id);
+        if (!record || record.owner !== owner || record.status !== "ready")
+            return false;
+        this.uploads.delete(id);
+        await rm(record.path, { force: true });
+        return true;
+    }
     async sweep() {
         for (const [id, record] of this.uploads) {
             if (record.status === "ready" && Date.now() - record.createdAt >= TTL_MS) {
@@ -239,5 +321,15 @@ export class HubUploads {
         for (const record of this.uploads.values())
             await rm(record.path, { force: true });
         this.uploads.clear();
+        if (this.releaseLease) {
+            await rm(this.spool, { recursive: true, force: true });
+            try {
+                this.releaseLease();
+            }
+            catch {
+                /* A compromised lease has nothing left to release. */
+            }
+            this.releaseLease = undefined;
+        }
     }
 }

package/dist/index.desktop-web.d.ts

@@ -1,2 +1,3 @@
 /** Shared Web business HTTP API hosted by Desktop's existing remote listener. */
 export * from "./desktop-web/http-api.js";
+export * from "./model-trace-http.js";

package/dist/index.desktop-web.js

@@ -1,2 +1,3 @@
 /** Shared Web business HTTP API hosted by Desktop's existing remote listener. */
 export * from "./desktop-web/http-api.js";
+export * from "./model-trace-http.js";

package/dist/index.links.d.ts

@@ -4,4 +4,7 @@ export * from "./links/device-oauth.js";
 export * from "./links/service.js";
 export * from "./links/types.js";
 export * from "./links/http.js";
+export type { LinkAuthorizationDiagnostic, LinkAuthorizationDiagnosticStage, LinkAuthorizationDiagnosticCode, LinkAuthorizationDiagnosticSink, } from "./links/diagnostics.js";
 export * from "./links/remote-configuration.js";
+export { readRemoteProviderCatalog, readRemoteProviderCapabilities, RemoteLinkCatalogError, type RemoteLinkCatalogFailureReason, type RemoteProviderCapabilities, } from "./links/remote-catalog.js";
+export { createDefaultLinkProviders, installDefaultLinkProviders, createLinkProviderModule, } from "./links/providers/index.js";

package/dist/index.links.js

@@ -5,3 +5,5 @@ export * from "./links/service.js";
 export * from "./links/types.js";
 export * from "./links/http.js";
 export * from "./links/remote-configuration.js";
+export { readRemoteProviderCatalog, readRemoteProviderCapabilities, RemoteLinkCatalogError, } from "./links/remote-catalog.js";
+export { createDefaultLinkProviders, installDefaultLinkProviders, createLinkProviderModule, } from "./links/providers/index.js";

package/dist/index.panels.d.ts

@@ -25,3 +25,4 @@ export * from "./panels/task-cookies.js";
 export * from "./panels/task-cookie-host.js";
 export * from "./panels/execution-gate.js";
 export * from "./panels/package-mutation.js";
+export * from "./panels/model-traces.js";

package/dist/index.panels.js

@@ -24,3 +24,4 @@ export * from "./panels/task-cookies.js";
 export * from "./panels/task-cookie-host.js";
 export * from "./panels/execution-gate.js";
 export * from "./panels/package-mutation.js";
+export * from "./panels/model-traces.js";

package/dist/index.serve.d.ts

@@ -1,5 +1,6 @@
 /** Ready-made headless HTTP/WebSocket host and CLI composition helpers. */
 export * from "./serve/headless-server.js";
+export * from "./model-trace-http.js";
 export { startProjectControlServer, type ProjectControlServerOptions, } from "./project-runtime/control-server.js";
 export { CLOUD_MANAGEMENT_AUTHORITY_VERSION } from "./project-runtime/cloud-account-auth.js";
 export { CLOUD_BROWSER_AUTHORITY_VERSION } from "./project-runtime/cloud-browser-auth.js";

package/dist/index.serve.js

@@ -1,5 +1,6 @@
 /** Ready-made headless HTTP/WebSocket host and CLI composition helpers. */
 export * from "./serve/headless-server.js";
+export * from "./model-trace-http.js";
 export { startProjectControlServer, } from "./project-runtime/control-server.js";
 export { CLOUD_MANAGEMENT_AUTHORITY_VERSION } from "./project-runtime/cloud-account-auth.js";
 export { CLOUD_BROWSER_AUTHORITY_VERSION } from "./project-runtime/cloud-browser-auth.js";

package/dist/index.storage.d.ts

@@ -9,4 +9,5 @@ export * from "./client-message-id.js";
 export * from "./image-byte-probe.js";
 export * from "./sessions-service.js";
 export * from "./session-titles-store.js";
+export * from "./model-trace-history.js";
 export * from "./panels/storage-store.js";

package/dist/index.storage.js

@@ -9,4 +9,5 @@ export * from "./client-message-id.js";
 export * from "./image-byte-probe.js";
 export * from "./sessions-service.js";
 export * from "./session-titles-store.js";
+export * from "./model-trace-history.js";
 export * from "./panels/storage-store.js";

package/dist/links/catalog.js

@@ -1,3 +1,4 @@
+import { installDefaultLinkProviders } from "./providers/index.js";
 import { LINK_PROVIDER_MANIFESTS } from "@cjhyy/code-shell-link";
 import { listLocalLinkProviders } from "@cjhyy/code-shell-core";
 function unique(values) {
@@ -37,5 +38,6 @@ export function composeLinkProviderCatalog(manifests, executors) {
     });
 }
 export function listDesktopLinkProviders() {
+    installDefaultLinkProviders();
     return composeLinkProviderCatalog(LINK_PROVIDER_MANIFESTS, listLocalLinkProviders());
 }

package/dist/links/diagnostics.d.ts

@@ -0,0 +1,60 @@
+import type { LinkAuthorization, LinkErrorCode } from "./types.js";
+export type LinkAuthorizationDiagnosticStage = "authorization" | "body_validation" | "input_validation" | "host_store_read" | "remote_configuration" | "remote_catalog" | "mode_selection" | "connection_review" | "job_creation" | "final_authorization";
+/** Fixed internal reasons, independent of exception text and provider responses. */
+export type LinkAuthorizationDiagnosticCode = "authorization_check_failed" | "request_body_invalid" | "input_validation_failed" | "host_store_unreadable" | "host_store_read_failed" | "remote_configuration_missing" | "remote_configuration_invalid" | "catalog_network" | "catalog_timeout" | "catalog_http_status" | "catalog_invalid_json" | "catalog_invalid_schema" | "catalog_unreviewed_capability" | "catalog_unsupported_auth" | "catalog_response_limit" | "catalog_unexpected_error" | "catalog_unavailable" | "provider_capability_missing" | "auth_mode_unavailable" | "connection_review_failed" | "job_capacity_exceeded" | "remote_authorization_invalid" | "authorization_job_failed" | "final_authorization_failed";
+/** Deliberately excludes all URLs, request data, account IDs, secrets, and exception text. */
+export interface LinkAuthorizationDiagnostic {
+    event: "link_authorization";
+    transport: "http" | "host";
+    requestId: string;
+    outcome: "stage" | "success" | "failure";
+    stage: LinkAuthorizationDiagnosticStage;
+    elapsedMs: number;
+    providerId?: string;
+    methodId?: string;
+    authModeId?: string;
+    internalCode?: LinkAuthorizationDiagnosticCode;
+    publicCode?: LinkErrorCode;
+    httpStatus?: number;
+    upstreamStatus?: number;
+    /** API success can return an authorization job that has already failed. */
+    authorizationState?: LinkAuthorization["state"];
+}
+export type LinkAuthorizationDiagnosticSink = (diagnostic: Readonly<LinkAuthorizationDiagnostic>) => void | Promise<void>;
+interface Failure {
+    stage: LinkAuthorizationDiagnosticStage;
+    internalCode: LinkAuthorizationDiagnosticCode;
+    upstreamStatus?: number;
+}
+declare class AuthorizationTrace {
+    private readonly sink?;
+    private readonly transport;
+    readonly requestId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly startedAt;
+    private active;
+    private stage;
+    private failure?;
+    private identity;
+    constructor(sink?: LinkAuthorizationDiagnosticSink | undefined, transport?: "http" | "host");
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    isActive(): boolean;
+    setStage(stage: LinkAuthorizationDiagnosticStage): void;
+    setIdentity(identity: typeof this.identity): void;
+    setFailure(failure: Failure): void;
+    complete(httpStatus: number, publicCode?: LinkErrorCode, authorizationState?: LinkAuthorization["state"]): void;
+    private httpStatus;
+    /** Detached authorization jobs inherit ALS; they must lose authority to edit this trace. */
+    deactivate(): void;
+    private emit;
+}
+export declare function createLinkAuthorizationTrace(sink?: LinkAuthorizationDiagnosticSink): AuthorizationTrace;
+/** Native Host callers share the same diagnostics; HTTP already owns its longer request lifetime. */
+export declare function withLinkAuthorizationTrace(sink: LinkAuthorizationDiagnosticSink | undefined, operation: () => Promise<LinkAuthorization>, failure: (error: unknown) => {
+    status: number;
+    code: LinkErrorCode;
+}): Promise<LinkAuthorization>;
+export declare function authorizationDiagnosticStage(stage: LinkAuthorizationDiagnosticStage): void;
+/** Callers must select identity values from the compiled provider/method/mode catalog. */
+export declare function authorizationDiagnosticIdentity(identity: Pick<LinkAuthorizationDiagnostic, "providerId" | "methodId" | "authModeId">): void;
+export declare function authorizationDiagnosticFailure(stage: LinkAuthorizationDiagnosticStage, internalCode: LinkAuthorizationDiagnosticCode, upstreamStatus?: number): void;
+export {};