@xfey/tutti 0.1.107 → 0.1.108

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

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

@@ -0,0 +1,83 @@
+import { Type } from "@sinclair/typebox";
+import { redactText } from "@tutti/shared/utils";
+import { ExternalReferenceTransportError } from "@tutti/relay-client";
+import { ReferenceCacheError } from "../../../reference-access/cache.js";
+import { WorkspaceOpsError } from "../../../workspace-ops/errors.js";
+import { authorizeAgentContextRequest } from "./agent-context-auth.js";
+import { AGENT_CONTEXT_BASE_PATH } from "./agent-context-shared.js";
+export function registerAgentContextExternalReferenceRoutes(app, options) {
+    for (const action of ["list", "read"])
+        app.get(`${AGENT_CONTEXT_BASE_PATH}/references/external${action === "read" ? "/file" : ""}`, {
+            schema: {
+                querystring: action === "read"
+                    ? Type.Object({ source_ref: Type.String({ pattern: "^external_ref_[a-f0-9]{32}$" }) }, { additionalProperties: false })
+                    : Type.Object({}, { additionalProperties: false }),
+            },
+        }, async (request, reply) => {
+            reply.header("cache-control", "no-store");
+            const invocation = authorizeAgentContextRequest(request, options, "references:external");
+            const service = options.externalReferences;
+            if (!service)
+                return { kind: "unavailable", reason: "external_references_not_enabled" };
+            const sourceRef = request.query.source_ref;
+            if (action === "read" &&
+                (sourceRef === undefined || !/^external_ref_[a-f0-9]{32}$/u.test(sourceRef)))
+                return { kind: "unavailable", reason: "reference_source_invalid" };
+            try {
+                if (action === "list")
+                    return { items: await service.list(invocation) };
+                const result = await service.read(invocation, sourceRef);
+                const { copy } = result;
+                request.log.info({
+                    stage: "external_reference_read",
+                    invocation_ref: invocation.reference_invocation_ref,
+                    activity_ref: invocation.activity_ref,
+                    source_ref: copy.source_ref,
+                    revision: copy.revision,
+                    sha256: copy.sha256,
+                    cache_hit: result.cache_hit,
+                    size_bytes: copy.size_bytes,
+                }, "External Reference working copy ready");
+                let text;
+                if (!result.content.includes(0)) {
+                    try {
+                        text = new TextDecoder("utf-8", { fatal: true }).decode(result.content);
+                    }
+                    catch {
+                        /* Binary resources are available as a controlled local working copy. */
+                    }
+                }
+                const limit = 128 * 1024;
+                const safeText = text === undefined ? undefined : Buffer.from(redactText(text), "utf8");
+                return {
+                    kind: text === undefined ? "local_file" : "text",
+                    ...copy,
+                    cache_hit: result.cache_hit,
+                    ...(safeText === undefined
+                        ? {}
+                        : {
+                            text: safeText.subarray(0, limit).toString("utf8"),
+                            truncated: safeText.byteLength > limit,
+                        }),
+                };
+            }
+            catch (error) {
+                const reason = error instanceof ReferenceCacheError
+                    ? error.code
+                    : error instanceof ExternalReferenceTransportError
+                        ? error.reasonCode
+                        : error instanceof WorkspaceOpsError
+                            ? "reference_cache_unsafe"
+                            : "reference_read_unavailable";
+                request.log.warn({
+                    stage: "external_reference_read",
+                    invocation_ref: invocation.reference_invocation_ref,
+                    activity_ref: invocation.activity_ref,
+                    ...(sourceRef === undefined ? {} : { source_ref: sourceRef }),
+                    reason_code: reason,
+                }, "External Reference read unavailable");
+                return { kind: "unavailable", reason };
+            }
+        });
+}
+//# sourceMappingURL=agent-context-external-reference-routes.js.map

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

@@ -1,6 +1,7 @@
 import type { HostProjectStore } from "../../../store/index.js";
 import type { HostProjectApiRouteOptions } from "./project-api.js";
 import type { AgentContextTokenRegistry } from "./agent-context-auth.js";
+import type { ExternalReferenceAccess } from "../../../reference-access/service.js";
 export declare const AGENT_CONTEXT_BASE_PATH: "/internal/agent-context";
 export declare const MESSAGE_LIMIT_DEFAULT = 50;
 export declare const MESSAGE_LIMIT_MAX = 100;
@@ -27,6 +28,7 @@ export declare const USER_SKILL_MD_DEFAULT_MAX_CHARS = 20000;
 export declare const USER_SKILL_MD_MAX_CHARS = 100000;
 export type AgentContextRouteOptions = Pick<HostProjectApiRouteOptions, "project" | "store" | "workspaceOps" | "tuttiHome" | "now"> & {
     tokenRegistry: AgentContextTokenRegistry;
+    externalReferences?: ExternalReferenceAccess;
 };
 export declare function requireProjectStore(options: AgentContextRouteOptions): HostProjectStore;
 export declare function requireWorkspaceRoot(options: AgentContextRouteOptions): string;

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

@@ -1,8 +1,9 @@
 import { registerAgentContextMessageRoutes } from "./agent-context-messages-routes.js";
 import { registerAgentContextProjectDocRoutes } from "./agent-context-project-doc-routes.js";
 import { registerAgentContextReferenceRoutes } from "./agent-context-reference-routes.js";
+import { registerAgentContextExternalReferenceRoutes } from "./agent-context-external-reference-routes.js";
 import { registerAgentContextSkillRoutes } from "./agent-context-skills-routes.js";
-import { AGENT_CONTEXT_BASE_PATH, } from "./agent-context-shared.js";
+import { AGENT_CONTEXT_BASE_PATH } from "./agent-context-shared.js";
 import { registerAgentContextWorkspaceRoutes } from "./agent-context-workspace-routes.js";
 export { DEFAULT_AGENT_CONTEXT_TOKEN_TTL_MS, AgentContextTokenRegistry, } from "./agent-context-auth.js";
 export { AGENT_CONTEXT_BASE_PATH };
@@ -11,6 +12,7 @@ export function registerAgentContextRoutes(app, options) {
     registerAgentContextProjectDocRoutes(app, options);
     registerAgentContextWorkspaceRoutes(app, options);
     registerAgentContextReferenceRoutes(app, options);
+    registerAgentContextExternalReferenceRoutes(app, options);
     registerAgentContextSkillRoutes(app, options);
 }
 //# sourceMappingURL=agent-context.js.map

package/dist/workspace-ops/project-workspace.js

@@ -2,6 +2,7 @@ import { classifyRepositoryPathMetadata } from "@tutti/shared/utils";
 import { WorkspaceOpsError } from "./errors.js";
 import { runGit, runGitRaw, runGitText, stagedChangesExist, summarizeGitFailure, tryGitText, } from "./git.js";
 import { requireMainlineBranch } from "./mainline.js";
+import { assertReferenceCacheIsolation } from "./reference-cache-policy.js";
 const MAX_RUN_DIFF_SUMMARY_BYTES = 32 * 1024;
 const ACCEPTED_TAG_PREFIX = "tutti/accepted/";
 function truncateText(text, maxBytes) {
@@ -48,6 +49,7 @@ function requireGitCommandSuccess(args, workspaceRoot) {
     return result;
 }
 export function collectProjectSourceDiff(workspaceRoot) {
+    assertReferenceCacheIsolation(workspaceRoot);
     const status = requireGitCommandSuccess(["status", "--porcelain=v1", "-z"], workspaceRoot);
     const changedPaths = parsePorcelainChangedPaths(status.stdout);
     const summaryParts = [];
@@ -80,12 +82,8 @@ function acceptedTagName(workspaceRoot, activityRef) {
     return tagName;
 }
 function nearestAcceptedCommit(workspaceRoot) {
-    const refs = requireGitCommandSuccess([
-        "for-each-ref",
-        "--format=%(objectname) %(refname:short)",
-        `refs/tags/${ACCEPTED_TAG_PREFIX}`,
-    ], workspaceRoot).stdout
-        .toString("utf8")
+    const refs = requireGitCommandSuccess(["for-each-ref", "--format=%(objectname) %(refname:short)", `refs/tags/${ACCEPTED_TAG_PREFIX}`], workspaceRoot)
+        .stdout.toString("utf8")
         .trim();
     if (refs.length === 0) {
         return null;
@@ -209,7 +207,9 @@ export function createAcceptedCheckpoint(options) {
         };
     }
     const inspection = inspectProjectWorkspace(options.workspaceRoot);
+    assertReferenceCacheIsolation(options.workspaceRoot);
     runGit(["add", "-A"], options.workspaceRoot);
+    assertReferenceCacheIsolation(options.workspaceRoot);
     if (!stagedChangesExist(options.workspaceRoot)) {
         throw new WorkspaceOpsError("validation_failed", "Accepted checkpoint has no staged source changes", { reason_code: "accepted_checkpoint_candidate_missing" });
     }

package/dist/workspace-ops/reference-cache-policy.d.ts

@@ -0,0 +1,6 @@
+export declare const REFERENCE_CACHE_PATH = "docs/reference/.tutti-cache";
+/** Only the exact managed namespace is eligible. Never adopt an existing directory. */
+export declare function initializeReferenceCacheDirectory(workspaceRoot: string): string;
+/** Fail closed on force-added cache or ignore drift; never unstage or delete user changes. */
+export declare function assertReferenceCacheIsolation(workspaceRoot: string, required?: boolean): void;
+//# sourceMappingURL=reference-cache-policy.d.ts.map

package/dist/workspace-ops/reference-cache-policy.js

@@ -0,0 +1,79 @@
+import { lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { WorkspaceOpsError } from "./errors.js";
+import { runGit, runGitRaw, runGitText, tryGitText } from "./git.js";
+export const REFERENCE_CACHE_PATH = "docs/reference/.tutti-cache";
+const CONFIG_KEY = "tutti.reference-cache-path";
+function reject() {
+    throw new WorkspaceOpsError("conflict", "Reference cache isolation is unavailable", {
+        reason_code: "reference_cache_unsafe",
+    });
+}
+/** Only the exact managed namespace is eligible. Never adopt an existing directory. */
+export function initializeReferenceCacheDirectory(workspaceRoot) {
+    const root = realpathSync(workspaceRoot);
+    const configured = tryGitText(["config", "--local", "--get", CONFIG_KEY], root);
+    if (configured !== null && configured !== REFERENCE_CACHE_PATH)
+        reject();
+    let current = root;
+    for (const part of REFERENCE_CACHE_PATH.split("/")) {
+        current = join(current, part);
+        const stat = lstatSync(current, { throwIfNoEntry: false });
+        if (stat !== undefined) {
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                reject();
+            if (current === join(root, REFERENCE_CACHE_PATH) && configured === null)
+                reject();
+        }
+    }
+    if (runGitText(["ls-files", "--", REFERENCE_CACHE_PATH], root) !== "")
+        reject();
+    // Git-local exclusion preserves the project's own .gitignore and unrelated index state.
+    const gitPath = runGitText(["rev-parse", "--git-path", "info/exclude"], root);
+    const exclude = isAbsolute(gitPath) ? gitPath : resolve(root, gitPath);
+    const gitDirectory = realpathSync(dirname(dirname(exclude)));
+    const info = join(gitDirectory, "info");
+    const infoStat = lstatSync(info, { throwIfNoEntry: false });
+    if (infoStat !== undefined && (!infoStat.isDirectory() || infoStat.isSymbolicLink()))
+        reject();
+    mkdirSync(info, { recursive: true });
+    const excludeStat = lstatSync(exclude, { throwIfNoEntry: false });
+    if (excludeStat !== undefined && (!excludeStat.isFile() || excludeStat.isSymbolicLink()))
+        reject();
+    const previous = excludeStat === undefined ? "" : readFileSync(exclude, "utf8");
+    const rule = `/${REFERENCE_CACHE_PATH}/`;
+    if (!previous.split(/\r?\n/u).includes(rule)) {
+        writeFileSync(exclude, `${previous}${previous.endsWith("\n") ? "" : "\n"}${rule}\n`, {
+            flag: excludeStat === undefined ? "wx" : "w",
+            mode: 0o600,
+        });
+    }
+    runGit(["config", "--local", CONFIG_KEY, REFERENCE_CACHE_PATH], root);
+    assertReferenceCacheIsolation(root);
+    mkdirSync(join(root, REFERENCE_CACHE_PATH), { recursive: true, mode: 0o700 });
+    return join(root, REFERENCE_CACHE_PATH);
+}
+/** Fail closed on force-added cache or ignore drift; never unstage or delete user changes. */
+export function assertReferenceCacheIsolation(workspaceRoot, required = false) {
+    const configured = tryGitText(["config", "--local", "--get", CONFIG_KEY], workspaceRoot);
+    if (configured === null) {
+        if (required || lstatSync(join(workspaceRoot, REFERENCE_CACHE_PATH), { throwIfNoEntry: false }))
+            reject();
+        return;
+    }
+    if (configured !== REFERENCE_CACHE_PATH)
+        reject();
+    if (runGitText(["ls-files", "--", REFERENCE_CACHE_PATH], workspaceRoot) !== "")
+        reject();
+    const ignored = runGitRaw(["check-ignore", "--no-index", "-q", `${REFERENCE_CACHE_PATH}/isolation-probe`], workspaceRoot);
+    if (ignored.status !== 0)
+        reject();
+    let current = realpathSync(workspaceRoot);
+    for (const part of REFERENCE_CACHE_PATH.split("/")) {
+        current = join(current, part);
+        const stat = lstatSync(current, { throwIfNoEntry: false });
+        if (stat !== undefined && (!stat.isDirectory() || stat.isSymbolicLink()))
+            reject();
+    }
+}
+//# sourceMappingURL=reference-cache-policy.js.map

package/migrations/0021_external_reference_reads.sql

@@ -0,0 +1,11 @@
+CREATE TABLE external_reference_reads (
+  invocation_ref TEXT NOT NULL,
+  activity_ref TEXT,
+  source_ref TEXT NOT NULL,
+  revision TEXT NOT NULL,
+  content_sha256 TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL CHECK (size_bytes >= 0),
+  checked_at TEXT NOT NULL,
+  PRIMARY KEY (invocation_ref, source_ref)
+);
+CREATE INDEX external_reference_reads_activity ON external_reference_reads(activity_ref);

package/node_modules/@tutti/relay-client/dist/external-references.d.ts

@@ -0,0 +1,11 @@
+import { type ExternalReferenceHostRequest } from "@tutti/shared/schemas/internal";
+export declare class ExternalReferenceTransportError extends Error {
+    readonly reasonCode: string;
+    constructor(reasonCode: string);
+}
+export declare function requestExternalReferences(options: {
+    relayUrl: string;
+    body: ExternalReferenceHostRequest;
+    fetchImpl?: typeof fetch;
+}): Promise<unknown>;
+//# sourceMappingURL=external-references.d.ts.map

package/node_modules/@tutti/relay-client/dist/external-references.js

@@ -0,0 +1,63 @@
+import { EXTERNAL_REFERENCE_HOST_PATH, isExternalReferenceList, isExternalReferenceReadResult, } from "@tutti/shared/schemas/internal";
+export class ExternalReferenceTransportError extends Error {
+    reasonCode;
+    constructor(reasonCode) {
+        super(reasonCode);
+        this.reasonCode = reasonCode;
+        this.name = "ExternalReferenceTransportError";
+    }
+}
+export async function requestExternalReferences(options) {
+    try {
+        const response = await (options.fetchImpl ?? fetch)(new URL(EXTERNAL_REFERENCE_HOST_PATH, options.relayUrl), {
+            method: "POST",
+            redirect: "error",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(options.body),
+            signal: AbortSignal.timeout(90_000),
+        });
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new ExternalReferenceTransportError("reference_transport_invalid_response");
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                if (!(next.value instanceof Uint8Array))
+                    throw new ExternalReferenceTransportError("reference_transport_invalid_response");
+                size += next.value.byteLength;
+                if (size > 512 * 1024)
+                    throw new ExternalReferenceTransportError("reference_transport_invalid_response");
+                chunks.push(next.value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!response.ok) {
+            const reason = typeof value === "object" && value !== null && "reason_code" in value
+                ? value.reason_code
+                : null;
+            throw new ExternalReferenceTransportError(typeof reason === "string" &&
+                /^(reference|document_wiki|feishu|attachment)_[a-z_]{1,70}$/u.test(reason)
+                ? reason
+                : "reference_transport_unavailable");
+        }
+        if (options.body.action === "list"
+            ? !isExternalReferenceList(value)
+            : !isExternalReferenceReadResult(value))
+            throw new ExternalReferenceTransportError("reference_transport_invalid_response");
+        return value;
+    }
+    catch (error) {
+        throw error instanceof ExternalReferenceTransportError
+            ? error
+            : new ExternalReferenceTransportError("reference_transport_unavailable");
+    }
+}
+//# sourceMappingURL=external-references.js.map

package/node_modules/@tutti/relay-client/dist/host-control.d.ts

@@ -44,6 +44,7 @@ export type RegisterRelayHostConnectionPayload = {
             browser_secret_write: false;
             repo_viewer: boolean;
             integration_source_ingestion_v1?: boolean;
+            integration_external_references_v1?: boolean;
             integration_attachment_ingestion_v1?: boolean;
             integration_managed_reference_ingestion_v1?: boolean;
             integration_outbound_v1?: boolean;

package/node_modules/@tutti/relay-client/dist/host-control.js

@@ -57,6 +57,7 @@ function createRegisterPayload(options) {
                 browser_secret_write: false,
                 repo_viewer: capabilities.repo_viewer ?? false,
                 integration_source_ingestion_v1: capabilities.integration_source_ingestion_v1 ?? false,
+                integration_external_references_v1: capabilities.integration_external_references_v1 ?? false,
                 integration_attachment_ingestion_v1: capabilities.integration_attachment_ingestion_v1 ?? false,
                 integration_managed_reference_ingestion_v1: capabilities.integration_managed_reference_ingestion_v1 ?? false,
                 integration_outbound_v1: capabilities.integration_outbound_v1 ?? false,

package/node_modules/@tutti/relay-client/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./host-control.js";
 export * from "./tunnel.js";
+export * from "./external-references.js";
 //# sourceMappingURL=index.d.ts.map

package/node_modules/@tutti/relay-client/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./host-control.js";
 export * from "./tunnel.js";
+export * from "./external-references.js";
 //# sourceMappingURL=index.js.map

package/node_modules/@tutti/shared/dist/schemas/api/clarifications.d.ts

@@ -507,6 +507,12 @@ export declare const SendClarificationRoundMessageResultSchema: import("@sinclai
         message_kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"user_text">, import("@sinclair/typebox").TLiteral<"agent_text">, import("@sinclair/typebox").TLiteral<"system_notice">, import("@sinclair/typebox").TLiteral<"clarification_request">, import("@sinclair/typebox").TLiteral<"clarification_card">]>;
         body: import("@sinclair/typebox").TString;
         refs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            external_references: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                source_ref: import("@sinclair/typebox").TString;
+                kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"feishu_docx">, import("@sinclair/typebox").TLiteral<"feishu_file">, import("@sinclair/typebox").TLiteral<"feishu_image">]>;
+                name: import("@sinclair/typebox").TString;
+                created_at: import("@sinclair/typebox").TString;
+            }>>>;
             task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             workflow_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/node_modules/@tutti/shared/dist/schemas/api/external-references.d.ts

@@ -0,0 +1,23 @@
+import { type Static } from "@sinclair/typebox";
+export declare const ExternalReferenceRefSchema: import("@sinclair/typebox").TString;
+export declare const ExternalReferenceDescriptorSchema: import("@sinclair/typebox").TObject<{
+    source_ref: import("@sinclair/typebox").TString;
+    kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"feishu_docx">, import("@sinclair/typebox").TLiteral<"feishu_file">, import("@sinclair/typebox").TLiteral<"feishu_image">]>;
+    name: import("@sinclair/typebox").TString;
+    created_at: import("@sinclair/typebox").TString;
+}>;
+export declare const ExternalReferenceListSchema: import("@sinclair/typebox").TObject<{
+    can_register: import("@sinclair/typebox").TBoolean;
+    items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        source_ref: import("@sinclair/typebox").TString;
+        kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"feishu_docx">, import("@sinclair/typebox").TLiteral<"feishu_file">, import("@sinclair/typebox").TLiteral<"feishu_image">]>;
+        name: import("@sinclair/typebox").TString;
+        created_at: import("@sinclair/typebox").TString;
+    }>>;
+}>;
+export declare const RegisterExternalReferenceBodySchema: import("@sinclair/typebox").TObject<{
+    document_url: import("@sinclair/typebox").TString;
+}>;
+export type ExternalReferenceDescriptor = Static<typeof ExternalReferenceDescriptorSchema>;
+export type ExternalReferenceList = Static<typeof ExternalReferenceListSchema>;
+//# sourceMappingURL=external-references.d.ts.map

package/node_modules/@tutti/shared/dist/schemas/api/external-references.js

@@ -0,0 +1,21 @@
+import { Type } from "@sinclair/typebox";
+import { IsoDateTimeStringSchema } from "../domain/index.js";
+export const ExternalReferenceRefSchema = Type.String({ pattern: "^external_ref_[a-f0-9]{32}$" });
+export const ExternalReferenceDescriptorSchema = Type.Object({
+    source_ref: ExternalReferenceRefSchema,
+    kind: Type.Union([
+        Type.Literal("feishu_docx"),
+        Type.Literal("feishu_file"),
+        Type.Literal("feishu_image"),
+    ]),
+    name: Type.String({ minLength: 1, maxLength: 240 }),
+    created_at: IsoDateTimeStringSchema,
+}, { additionalProperties: false });
+export const ExternalReferenceListSchema = Type.Object({
+    can_register: Type.Boolean(),
+    items: Type.Array(ExternalReferenceDescriptorSchema, { maxItems: 500 }),
+}, { additionalProperties: false });
+export const RegisterExternalReferenceBodySchema = Type.Object({
+    document_url: Type.String({ minLength: 1, maxLength: 2048 }),
+}, { additionalProperties: false });
+//# sourceMappingURL=external-references.js.map