@xfey/tutti 0.1.107 → 0.1.108

package/README.md

@@ -15,6 +15,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/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/openai/app-server/read-only-procedure.js

@@ -145,6 +145,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 }),

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,13 +16,14 @@ 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[];
 };
@@ -76,6 +78,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

@@ -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",
         ],
     },
 };
@@ -206,6 +215,7 @@ export function resolveCodexAppServerContextRuntimeHint(options) {
         return undefined;
     }
     const issued = options.agentContext.issueToken({
+        ...(options.activityRef === undefined ? {} : { activityRef: options.activityRef }),
         selectionName: options.selectionName,
         scopes: selection.contextApiScopes,
     });

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

@@ -174,7 +174,9 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
     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
                 ? {}
@@ -182,11 +184,18 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
         });
         skillsListWarmup = resolveCodexAppServerSkillsListWarmup({
             cwd: options.workspaceRoot,
-            ...(options.skillSelectionName === undefined ? {} : { selectionName: options.skillSelectionName }),
+            ...(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 }),
         });
     }
@@ -264,10 +273,7 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
             ...entry.extraUserRoots,
         ]) ?? []),
     ];
-    const strictLeakCheckValues = [
-        options.apiKey,
-        ...(contextRuntimeHint?.sensitiveValues ?? []),
-    ];
+    const strictLeakCheckValues = [options.apiKey, ...(contextRuntimeHint?.sensitiveValues ?? [])];
     let primaryError;
     let runResult;
     let lifecycleError;
@@ -336,9 +342,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,

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