@xfey/tutti 0.1.107 → 0.1.109

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,23 +171,24 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         }
     }
     let skillInputs;
-    let skillsListWarmup;
     let contextRuntimeHint;
     try {
         skillInputs = resolveCodexAppServerSkillInputs({
-            ...(options.skillSelectionName === undefined ? {} : { selectionName: options.skillSelectionName }),
+            ...(options.skillSelectionName === undefined
+                ? {}
+                : { selectionName: options.skillSelectionName }),
             ...(options.userSkillsRoot === undefined ? {} : { userSkillsRoot: options.userSkillsRoot }),
             ...(options.builtInSkillsRoot === undefined
                 ? {}
                 : { builtInSkillsRoot: options.builtInSkillsRoot }),
         });
-        skillsListWarmup = resolveCodexAppServerSkillsListWarmup({
-            cwd: options.workspaceRoot,
-            ...(options.skillSelectionName === undefined ? {} : { selectionName: options.skillSelectionName }),
-            ...(options.userSkillsRoot === undefined ? {} : { userSkillsRoot: options.userSkillsRoot }),
-        });
         contextRuntimeHint = resolveCodexAppServerContextRuntimeHint({
-            ...(options.skillSelectionName === undefined ? {} : { selectionName: options.skillSelectionName }),
+            ...(options.approvalContext?.activityRef === undefined
+                ? {}
+                : { activityRef: options.approvalContext.activityRef }),
+            ...(options.skillSelectionName === undefined
+                ? {}
+                : { selectionName: options.skillSelectionName }),
             ...(options.agentContext === undefined ? {} : { agentContext: options.agentContext }),
         });
     }
@@ -258,16 +260,9 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         options.userSkillsRoot ?? "",
         options.builtInSkillsRoot ?? "",
         ...(contextRuntimeHint?.sensitiveValues ?? []),
-        ...skillInputs.map((skill) => skill.path),
-        ...(skillsListWarmup?.perCwdExtraUserRoots.flatMap((entry) => [
-            entry.cwd,
-            ...entry.extraUserRoots,
-        ]) ?? []),
-    ];
-    const strictLeakCheckValues = [
-        options.apiKey,
-        ...(contextRuntimeHint?.sensitiveValues ?? []),
+        ...skillInputs.flatMap((skill) => [skill.path, dirname(skill.path)]),
     ];
+    const strictLeakCheckValues = [options.apiKey, ...(contextRuntimeHint?.sensitiveValues ?? [])];
     let primaryError;
     let runResult;
     let lifecycleError;
@@ -291,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", {
@@ -336,9 +334,7 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
             input: buildCodexAppServerTurnInput({
                 prompt: options.prompt,
                 skills: skillInputs,
-                ...(contextRuntimeHint === undefined
-                    ? {}
-                    : { runtimeHints: [contextRuntimeHint.text] }),
+                ...(contextRuntimeHint === undefined ? {} : { runtimeHints: [contextRuntimeHint.text] }),
             }),
             cwd: options.workspaceRoot,
             approvalPolicy,
@@ -480,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/cache.d.ts

@@ -0,0 +1,50 @@
+export declare class ReferenceCacheError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export type ReferenceCopy = {
+    source_ref: string;
+    revision: string;
+    sha256: string;
+    path: string;
+    size_bytes: number;
+    media_type: string;
+    checked_at: string;
+};
+export type ReferenceFetchResult = {
+    revision: string;
+    media_type: string;
+    content: Uint8Array;
+};
+export declare class ExternalReferenceCache {
+    private readonly options;
+    private readonly workspace;
+    private readonly ledgerFile;
+    private readonly ledger;
+    private tail;
+    constructor(options: {
+        workspaceRoot: string;
+        ledgerRoot: string;
+        now?: () => number;
+        maxTotalBytes?: number;
+        retentionMs?: number;
+    });
+    private now;
+    private validateLedger;
+    private save;
+    private bytes;
+    /** A pin belongs to a server-issued invocation, never to model-supplied identity. */
+    acquire(input: {
+        sourceRef: string;
+        invocationRef: string;
+        expiresAt: number;
+        fetch: () => Promise<ReferenceFetchResult>;
+    }): Promise<{
+        copy: ReferenceCopy;
+        cache_hit: boolean;
+        content: Buffer;
+    }>;
+    private projection;
+    private prune;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/reference-access/cache.js

@@ -0,0 +1,268 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { assertReferenceCacheIsolation, initializeReferenceCacheDirectory, REFERENCE_CACHE_PATH, } from "../workspace-ops/reference-cache-policy.js";
+const MAX_BYTES = 10 * 1024 * 1024;
+const SAFE_REF = /^[A-Za-z0-9_-]{1,128}$/u;
+const DIGEST = /^[a-f0-9]{64}$/u;
+const MAX_PIN_MS = 24 * 60 * 60 * 1000;
+export class ReferenceCacheError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "ReferenceCacheError";
+    }
+}
+function fail() {
+    throw new ReferenceCacheError("reference_cache_invalid");
+}
+function hash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function regular(path) {
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (stat === undefined)
+        return false;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        fail();
+    return true;
+}
+function ensureDirectories(path) {
+    const absolute = resolve(path);
+    const parent = dirname(absolute);
+    if (parent !== absolute)
+        ensureDirectories(parent);
+    const stat = lstatSync(absolute, { throwIfNoEntry: false });
+    if (stat !== undefined) {
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            fail();
+    }
+    else
+        mkdirSync(absolute, { mode: 0o700 });
+}
+function relativeCopyPath(source, digest) {
+    return `${REFERENCE_CACHE_PATH}/${source}/${digest}.bin`;
+}
+export class ExternalReferenceCache {
+    options;
+    workspace;
+    ledgerFile;
+    ledger;
+    tail = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.workspace = realpathSync(options.workspaceRoot);
+        if ((options.maxTotalBytes !== undefined &&
+            (!Number.isSafeInteger(options.maxTotalBytes) || options.maxTotalBytes < 1)) ||
+            (options.retentionMs !== undefined &&
+                (!Number.isSafeInteger(options.retentionMs) || options.retentionMs < 0)))
+            fail();
+        const ledgerRoot = resolve(options.ledgerRoot);
+        if (ledgerRoot === this.workspace || ledgerRoot.startsWith(`${this.workspace}/`))
+            fail();
+        ensureDirectories(ledgerRoot);
+        this.ledgerFile = join(ledgerRoot, "cache.json");
+        if (regular(this.ledgerFile)) {
+            try {
+                const parsed = JSON.parse(readFileSync(this.ledgerFile, "utf8"));
+                this.ledger = this.validateLedger(parsed);
+            }
+            catch {
+                fail();
+            }
+        }
+        else {
+            this.ledger = { version: 1, workspace: this.workspace, entries: {}, pins: {} };
+        }
+        initializeReferenceCacheDirectory(this.workspace);
+        this.save();
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    validateLedger(value) {
+        if (value === null || typeof value !== "object")
+            fail();
+        const candidate = value;
+        if (candidate.version !== 1 ||
+            candidate.workspace !== this.workspace ||
+            !candidate.entries ||
+            !candidate.pins ||
+            typeof candidate.entries !== "object" ||
+            typeof candidate.pins !== "object" ||
+            Array.isArray(candidate.entries) ||
+            Array.isArray(candidate.pins))
+            fail();
+        for (const [key, entry] of Object.entries(candidate.entries)) {
+            if (!entry ||
+                !SAFE_REF.test(entry.source_ref) ||
+                !DIGEST.test(entry.sha256) ||
+                key !== `${entry.source_ref}:${entry.sha256}` ||
+                entry.path !== relativeCopyPath(entry.source_ref, entry.sha256) ||
+                typeof entry.revision !== "string" ||
+                entry.revision.length > 256 ||
+                typeof entry.media_type !== "string" ||
+                entry.media_type.length > 128 ||
+                !Number.isSafeInteger(entry.size_bytes) ||
+                entry.size_bytes < 0 ||
+                entry.size_bytes > MAX_BYTES ||
+                !Number.isFinite(entry.last_used_at) ||
+                !Number.isFinite(Date.parse(entry.checked_at)))
+                fail();
+        }
+        for (const [key, pin] of Object.entries(candidate.pins)) {
+            if (!/^[a-f0-9]{64}$/u.test(key) ||
+                !pin ||
+                !Number.isFinite(pin.expires_at) ||
+                !Object.hasOwn(candidate.entries, pin.key) ||
+                !pin.copy ||
+                pin.copy.path !== candidate.entries[pin.key]?.path ||
+                pin.copy.sha256 !== candidate.entries[pin.key]?.sha256 ||
+                pin.copy.source_ref !== candidate.entries[pin.key]?.source_ref ||
+                pin.copy.size_bytes !== candidate.entries[pin.key]?.size_bytes ||
+                typeof pin.copy.media_type !== "string" ||
+                pin.copy.media_type.length > 128 ||
+                typeof pin.copy.revision !== "string" ||
+                !pin.copy.revision ||
+                pin.copy.revision.length > 256 ||
+                !Number.isFinite(Date.parse(pin.copy.checked_at)))
+                fail();
+        }
+        return candidate;
+    }
+    save() {
+        regular(this.ledgerFile);
+        const temporary = `${this.ledgerFile}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify(this.ledger), { flag: "wx", mode: 0o600 });
+        renameSync(temporary, this.ledgerFile);
+    }
+    bytes(entry) {
+        assertReferenceCacheIsolation(this.workspace, true);
+        const directory = join(this.workspace, REFERENCE_CACHE_PATH, entry.source_ref);
+        const stat = lstatSync(directory, { throwIfNoEntry: false });
+        if (!stat?.isDirectory() || stat.isSymbolicLink())
+            fail();
+        const path = join(this.workspace, entry.path);
+        if (!regular(path))
+            throw new ReferenceCacheError("reference_cache_missing");
+        if (lstatSync(path).size !== entry.size_bytes)
+            fail();
+        const content = readFileSync(path);
+        if (hash(content) !== entry.sha256)
+            fail();
+        return content;
+    }
+    /** A pin belongs to a server-issued invocation, never to model-supplied identity. */
+    async acquire(input) {
+        if (!SAFE_REF.test(input.sourceRef) ||
+            !SAFE_REF.test(input.invocationRef) ||
+            !Number.isFinite(input.expiresAt) ||
+            input.expiresAt <= this.now() ||
+            input.expiresAt > this.now() + MAX_PIN_MS)
+            fail();
+        const operation = this.tail.then(async () => {
+            if (input.expiresAt <= this.now())
+                throw new ReferenceCacheError("reference_invocation_expired");
+            assertReferenceCacheIsolation(this.workspace, true);
+            const pinKey = hash(Buffer.from(`${input.invocationRef}\0${input.sourceRef}`));
+            const pin = this.ledger.pins[pinKey];
+            if (pin !== undefined && pin.expires_at > this.now()) {
+                const entry = this.ledger.entries[pin.key];
+                if (entry === undefined)
+                    fail();
+                const content = this.bytes(entry);
+                entry.last_used_at = this.now();
+                this.save();
+                return { copy: pin.copy, cache_hit: true, content };
+            }
+            // A new invocation checks access and content. Failures never silently use stale bytes.
+            const fetched = await input.fetch();
+            assertReferenceCacheIsolation(this.workspace, true);
+            if (input.expiresAt <= this.now())
+                throw new ReferenceCacheError("reference_invocation_expired");
+            if (fetched.content.byteLength > MAX_BYTES ||
+                !fetched.revision ||
+                fetched.revision.length > 256 ||
+                !fetched.media_type ||
+                fetched.media_type.length > 128)
+                fail();
+            const content = Buffer.from(fetched.content);
+            const digest = hash(content);
+            const key = `${input.sourceRef}:${digest}`;
+            const existing = this.ledger.entries[key];
+            this.prune(content.byteLength, key);
+            const entry = {
+                source_ref: input.sourceRef,
+                revision: fetched.revision,
+                sha256: digest,
+                path: relativeCopyPath(input.sourceRef, digest),
+                size_bytes: content.byteLength,
+                media_type: fetched.media_type,
+                checked_at: new Date(this.now()).toISOString(),
+                last_used_at: this.now(),
+            };
+            ensureDirectories(join(this.workspace, REFERENCE_CACHE_PATH, input.sourceRef));
+            const path = join(this.workspace, entry.path);
+            if (existing !== undefined && regular(path))
+                this.bytes(existing);
+            else if (regular(path)) {
+                // Response-loss/crash orphan: adopt only an exact content-addressed regular file.
+                if (!readFileSync(path).equals(content))
+                    fail();
+            }
+            else {
+                const temporary = `${path}.${randomUUID()}.tmp`;
+                writeFileSync(temporary, content, { flag: "wx", mode: 0o600 });
+                renameSync(temporary, path);
+            }
+            // Each version records its own observation. Pins capture revision independently below.
+            this.ledger.entries[key] = entry;
+            this.ledger.pins[pinKey] = { key, expires_at: input.expiresAt, copy: this.projection(entry) };
+            this.save();
+            return { copy: this.projection(entry), cache_hit: existing !== undefined, content };
+        });
+        this.tail = operation.catch(() => undefined);
+        return operation;
+    }
+    projection(entry) {
+        return {
+            source_ref: entry.source_ref,
+            revision: entry.revision,
+            sha256: entry.sha256,
+            path: entry.path,
+            size_bytes: entry.size_bytes,
+            media_type: entry.media_type,
+            checked_at: entry.checked_at,
+        };
+    }
+    prune(incomingBytes, incomingKey) {
+        const now = this.now();
+        for (const [key, pin] of Object.entries(this.ledger.pins)) {
+            if (pin.expires_at <= now)
+                delete this.ledger.pins[key];
+        }
+        const protectedKeys = new Set(Object.values(this.ledger.pins).map((pin) => pin.key));
+        const entries = Object.entries(this.ledger.entries).sort((a, b) => a[1].last_used_at - b[1].last_used_at);
+        let total = entries.reduce((sum, [, entry]) => sum + entry.size_bytes, 0);
+        const additional = Object.hasOwn(this.ledger.entries, incomingKey) ? 0 : incomingBytes;
+        const maximum = this.options.maxTotalBytes ?? 100 * 1024 * 1024;
+        const retention = this.options.retentionMs ?? 7 * 24 * 60 * 60 * 1000;
+        for (const [key, entry] of entries) {
+            if (key === incomingKey || protectedKeys.has(key))
+                continue;
+            if (total + additional <= maximum && entry.last_used_at + retention > now)
+                continue;
+            if (regular(join(this.workspace, entry.path))) {
+                this.bytes(entry); // Reject replacement/symlink/tampering before removal.
+                unlinkSync(join(this.workspace, entry.path));
+            }
+            delete this.ledger.entries[key];
+            total -= entry.size_bytes;
+        }
+        this.save();
+        if (total + additional > maximum)
+            throw new ReferenceCacheError("reference_cache_capacity");
+    }
+}
+//# sourceMappingURL=cache.js.map

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

@@ -0,0 +1,6 @@
+import type { SqliteDatabase } from "../store/index.js";
+import type { ReferenceCopy } from "./cache.js";
+import type { ReferenceInvocation } from "./service.js";
+/** 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

@@ -0,0 +1,15 @@
+/** Durable observation, separate from evictable cache metadata; no content or locator. */
+export function recordExternalReferenceRead(db, invocation, copy) {
+    const invocationRef = invocation.reference_invocation_ref;
+    const existing = db
+        .prepare(`
+    SELECT revision, content_sha256 FROM external_reference_reads WHERE invocation_ref = ? AND source_ref = ?`)
+        .get(invocationRef, copy.source_ref);
+    if (existing &&
+        (existing.revision !== copy.revision || existing.content_sha256 !== copy.sha256)) {
+        throw new Error("reference_read_evidence_conflict");
+    }
+    db.prepare(`INSERT OR IGNORE INTO external_reference_reads
+    (invocation_ref, activity_ref, source_ref, revision, content_sha256, size_bytes, checked_at) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(invocationRef, invocation.activity_ref ?? null, copy.source_ref, copy.revision, copy.sha256, copy.size_bytes, copy.checked_at);
+}
+//# sourceMappingURL=read-evidence.js.map

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

@@ -0,0 +1,26 @@
+import type { ExternalReferenceDescriptor } from "@tutti/shared/schemas/api";
+import type { ReferenceCopy, ReferenceFetchResult } from "./cache.js";
+import { type ExternalReferenceCache } from "./cache.js";
+export type ReferenceInvocation = {
+    reference_invocation_ref: string;
+    activity_ref?: string;
+    expires_at: string;
+};
+export declare class ExternalReferenceAccess {
+    private readonly options;
+    private cache;
+    private readonly selections;
+    constructor(options: {
+        createCache: () => ExternalReferenceCache;
+        list: (invocation: ReferenceInvocation) => Promise<ExternalReferenceDescriptor[]>;
+        read: (sourceRef: string, invocation: ReferenceInvocation) => Promise<ReferenceFetchResult>;
+        recordRead: (invocation: ReferenceInvocation, copy: ReferenceCopy) => void;
+    });
+    list(invocation: ReferenceInvocation): Promise<ExternalReferenceDescriptor[]>;
+    read(invocation: ReferenceInvocation, sourceRef: string): Promise<{
+        copy: ReferenceCopy;
+        cache_hit: boolean;
+        content: Buffer;
+    }>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/reference-access/service.js

@@ -0,0 +1,42 @@
+import { ReferenceCacheError } from "./cache.js";
+export class ExternalReferenceAccess {
+    options;
+    cache;
+    selections = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async list(invocation) {
+        const now = Date.now();
+        for (const [key, selection] of this.selections)
+            if (selection.expires <= now)
+                this.selections.delete(key);
+        let selection = this.selections.get(invocation.reference_invocation_ref);
+        if (!selection) {
+            if (this.selections.size >= 128)
+                throw new ReferenceCacheError("reference_reader_busy");
+            selection = {
+                expires: Date.parse(invocation.expires_at),
+                sources: this.options.list(invocation),
+            };
+            this.selections.set(invocation.reference_invocation_ref, selection);
+            selection.sources.catch(() => this.selections.delete(invocation.reference_invocation_ref));
+        }
+        return selection.sources;
+    }
+    async read(invocation, sourceRef) {
+        const sources = await this.list(invocation);
+        if (!sources.some((source) => source.source_ref === sourceRef))
+            throw new ReferenceCacheError("reference_source_not_selected");
+        this.cache ??= this.options.createCache();
+        const result = await this.cache.acquire({
+            sourceRef,
+            invocationRef: invocation.reference_invocation_ref,
+            expiresAt: Date.parse(invocation.expires_at),
+            fetch: () => this.options.read(sourceRef, invocation),
+        });
+        this.options.recordRead(invocation, result.copy);
+        return result;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/server-shell/cli/external-reference-runtime.d.ts

@@ -0,0 +1,12 @@
+import { ExternalReferenceAccess } from "../../reference-access/service.js";
+import type { HostProjectStore } from "../../store/index.js";
+import { type StagedUploadResolver } from "../http/routes/project-api/staged-uploads.js";
+import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
+import type { LaunchPreparationResult } from "./launch.js";
+export declare function createExternalReferenceRuntime(options: {
+    preparation: LaunchPreparationResult;
+    store: HostProjectStore;
+    resolveStagedUpload: StagedUploadResolver;
+    getLaunchStatus: () => HostLocalLaunchStatus;
+}): ExternalReferenceAccess;
+//# sourceMappingURL=external-reference-runtime.d.ts.map

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

@@ -0,0 +1,75 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { requestExternalReferences } from "@tutti/relay-client";
+import { isExternalReferenceList, isExternalReferenceReadResult, } from "@tutti/shared/schemas/internal";
+import { ExternalReferenceCache } from "../../reference-access/cache.js";
+import { ExternalReferenceAccess, } from "../../reference-access/service.js";
+import { recordExternalReferenceRead } 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) {
+    const { preparation } = options;
+    async function request(action, invocation, sourceRef) {
+        const relay = options.getLaunchStatus().relay;
+        if (!relay)
+            throw new Error("reference_host_offline");
+        const secret = readHostRegistrationSecret(preparation.tutti_home, preparation.project_id);
+        return requestExternalReferences({
+            relayUrl: preparation.relay_url,
+            body: {
+                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,
+                host_connection_ref: relay.host_connection_ref,
+                request_ref: `eref_${randomUUID().replaceAll("-", "")}`,
+                invocation_ref: invocation.reference_invocation_ref,
+                action,
+                ...(sourceRef === undefined ? {} : { source_ref: sourceRef }),
+            },
+        });
+    }
+    return new ExternalReferenceAccess({
+        createCache: () => new ExternalReferenceCache({
+            workspaceRoot: preparation.workspace_root,
+            ledgerRoot: join(preparation.tutti_home, "projects", preparation.project_id, "reference-cache"),
+        }),
+        list: async (invocation) => {
+            const result = await request("list", invocation);
+            if (!isExternalReferenceList(result))
+                throw new Error("reference_list_invalid");
+            return result.items;
+        },
+        read: async (sourceRef, invocation) => {
+            const result = await request("read", invocation, sourceRef);
+            if (!isExternalReferenceReadResult(result) || result.source.source_ref !== sourceRef)
+                throw new Error("reference_read_invalid");
+            if (result.size_bytes === 0)
+                return {
+                    content: Buffer.alloc(0),
+                    revision: result.revision,
+                    media_type: result.media_type,
+                };
+            if (!result.upload_id)
+                throw new Error("reference_read_invalid");
+            const downloaded = await downloadStagedUploadWithResolver({
+                resolveStagedUpload: options.resolveStagedUpload,
+                purpose: "reference_file",
+                expected: {
+                    upload_id: result.upload_id,
+                    file_name: `${sourceRef}.bin`,
+                    size_bytes: result.size_bytes,
+                    sha256: `sha256:${result.sha256}`,
+                    media_type: result.media_type,
+                },
+            });
+            await cleanupDownloadedStagedUpload(downloaded);
+            return {
+                content: downloaded.content,
+                revision: result.revision,
+                media_type: result.media_type,
+            };
+        },
+        recordRead: (invocation, copy) => recordExternalReferenceRead(options.store.db, invocation, copy),
+    });
+}
+//# sourceMappingURL=external-reference-runtime.js.map