@xfey/tutti 0.1.106 → 0.1.108

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

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

@@ -27,6 +27,7 @@ import { createTrustedRelaySessionMetadataStore, } from "../session/relay-sessio
 import { LaunchError } from "./errors.js";
 import { HostProjectRuntimeLifecycle } from "./host-project-runtime-lifecycle.js";
 import { readCliVersion } from "./version.js";
+import { createExternalReferenceRuntime } from "./external-reference-runtime.js";
 import { relayStateFromLaunchStatus } from "./host-relay-status.js";
 import { appendHostLogLine, readHostRegistrationSecret, createMachineRuntimeEndpointToken, deleteMachineRuntimeEndpoint, ensureHostLogFile, getHostLogFilePath, updateMachineProjectDisplayNameSnapshot, writeMachineRuntimeEndpoint, } from "./machine-local.js";
 import { readProjectDescription, readProjectDisplayName, writeProjectDescription, writeProjectDisplayName, } from "./project-identity.js";
@@ -128,6 +129,7 @@ function createAgentContextRuntime(options) {
         baseUrl: new URL(AGENT_CONTEXT_BASE_PATH, options.baseUrl).toString(),
         issueToken: (input) => {
             const token = options.registry.issueToken({
+                ...(input.activityRef === undefined ? {} : { activityRef: input.activityRef }),
                 projectId: options.projectId,
                 selection: input.selectionName,
                 scopes: input.scopes,
@@ -533,7 +535,21 @@ export async function startForegroundHostServer(options) {
                 : { getLaunchStatus: options.getLaunchStatus }),
         });
         app = options.createServer({
-            agentContext: { tokenRegistry: agentContextTokenRegistry },
+            agentContext: {
+                tokenRegistry: agentContextTokenRegistry,
+                ...(options.preparation.machine_local.binding.surface_profile.kind === "feishu" &&
+                    options.getLaunchStatus !== undefined &&
+                    resolveStagedUpload !== undefined
+                    ? {
+                        externalReferences: createExternalReferenceRuntime({
+                            preparation: options.preparation,
+                            store,
+                            getLaunchStatus: options.getLaunchStatus,
+                            resolveStagedUpload,
+                        }),
+                    }
+                    : {}),
+            },
             serviceVersion: HOST_SERVER_VERSION,
             health: {
                 readiness: {

package/dist/server-shell/cli/relay-registration.js

@@ -37,6 +37,7 @@ export async function registerHostWithRelay(options) {
         joinToken: { mode: options.joinTokenMode ?? "rotate" },
         capabilities: {
             integration_source_ingestion_v1: true,
+            integration_external_references_v1: true,
             integration_attachment_ingestion_v1: true,
             integration_managed_reference_ingestion_v1: true,
             integration_outbound_v1: true,

package/dist/server-shell/http/create-server.d.ts

@@ -3,9 +3,11 @@ import { type HostLocalControlOptions } from "./routes/local-control.js";
 import { type HostProjectApiRouteOptions } from "./routes/project-api.js";
 import { AgentContextTokenRegistry } from "./routes/agent-context.js";
 import { type HostWebStaticOptions } from "./static-web.js";
+import type { ExternalReferenceAccess } from "../../reference-access/service.js";
 export type HostServerOptions = {
     agentContext?: false | {
         tokenRegistry?: AgentContextTokenRegistry;
+        externalReferences?: ExternalReferenceAccess;
     };
     health?: {
         readiness?: {

package/dist/server-shell/http/create-server.js

@@ -3,7 +3,7 @@ import { createRedactedLoggerOptions } from "./logger.js";
 import { registerHostHealthRoute } from "./routes/health.js";
 import { registerHostLocalControlRoutes, } from "./routes/local-control.js";
 import { registerHostProjectApiRoutes, } from "./routes/project-api.js";
-import { AgentContextTokenRegistry, registerAgentContextRoutes, } from "./routes/agent-context.js";
+import { AgentContextTokenRegistry, registerAgentContextRoutes } from "./routes/agent-context.js";
 import { registerHostWebStaticRoutes } from "./static-web.js";
 import { registerApiErrorHandler } from "./validation.js";
 export function createHostServer(options = {}) {
@@ -12,9 +12,7 @@ export function createHostServer(options = {}) {
         : fastify({ logger: createRedactedLoggerOptions("tutti-host", options.logger) });
     registerApiErrorHandler(app);
     registerHostHealthRoute(app, {
-        ...(options.health?.readiness === undefined
-            ? {}
-            : { readiness: options.health.readiness }),
+        ...(options.health?.readiness === undefined ? {} : { readiness: options.health.readiness }),
         now: options.now ?? (() => new Date()),
         serviceVersion: options.serviceVersion ?? "0.0.0",
     });
@@ -31,6 +29,9 @@ export function createHostServer(options = {}) {
         }
         if (options.agentContext !== false) {
             registerAgentContextRoutes(app, {
+                ...(options.agentContext?.externalReferences === undefined
+                    ? {}
+                    : { externalReferences: options.agentContext.externalReferences }),
                 project: projectApiOptions.project,
                 ...(projectApiOptions.store === undefined ? {} : { store: projectApiOptions.store }),
                 ...(projectApiOptions.workspaceOps === undefined

package/dist/server-shell/http/routes/agent-context-auth.d.ts

@@ -3,6 +3,7 @@ import type { ActivityRef, ProjectId } from "@tutti/shared/ids";
 import type { CodexAppServerContextApiScope, CodexAppServerSkillSelectionName } from "../../../providers/openai/app-server/skills.js";
 export declare const DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS: number;
 export type AgentContextTokenRecord = {
+    reference_invocation_ref: string;
     token: string;
     project_id: ProjectId;
     activity_ref?: ActivityRef;
@@ -37,5 +38,5 @@ export declare function authorizeAgentContextRequest(request: FastifyRequest, op
         project_id: ProjectId;
     };
     tokenRegistry: AgentContextTokenRegistry;
-}, requiredScope: CodexAppServerContextApiScope): void;
+}, requiredScope: CodexAppServerContextApiScope): AgentContextTokenRecord;
 //# sourceMappingURL=agent-context-auth.d.ts.map

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

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { createEventRef } from "@tutti/shared/ids";
 export const DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS = 30 * 60 * 1000;
 export class AgentContextTokenRegistry {
     options;
@@ -11,6 +12,7 @@ export class AgentContextTokenRegistry {
         const ttlMs = input.ttlMs ?? this.options.ttlMs ?? DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS;
         const token = this.options.tokenFactory?.() ?? `agctx_${randomBytes(32).toString("base64url")}`;
         const record = {
+            reference_invocation_ref: createEventRef(),
             token,
             project_id: input.projectId,
             ...(input.activityRef === undefined ? {} : { activity_ref: input.activityRef }),
@@ -64,7 +66,7 @@ function bearerToken(request) {
     return match[1].trim();
 }
 export function authorizeAgentContextRequest(request, options, requiredScope) {
-    options.tokenRegistry.validate({
+    return options.tokenRegistry.validate({
         token: bearerToken(request),
         projectId: options.project.project_id,
         requiredScope,

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

@@ -0,0 +1,4 @@
+import type { FastifyInstance } from "fastify";
+import type { AgentContextRouteOptions } from "./agent-context-shared.js";
+export declare function registerAgentContextExternalReferenceRoutes(app: FastifyInstance, options: AgentContextRouteOptions): void;
+//# sourceMappingURL=agent-context-external-reference-routes.d.ts.map