@xyne/workflow-sdk 3.2.34 → 3.2.36

package/dist/agents/provider.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Agent provider port — the seam between a workflow's agent step and whoever
+ * actually runs the agent.
+ *
+ * The SDK ships one agent implementation ({@link AgentStep}, which drives an
+ * LLM directly through a pi-mono runtime). That works when the SDK owns the
+ * agent: the step config carries the system prompt, the tool list and the turn
+ * budget, and the SDK drives the loop.
+ *
+ * It does not work when the *host* already owns agent lifecycle. In xyne-spaces
+ * agents live in claw; in xyne-search they live in an `agents` table. In both
+ * cases the prompt, tools, MCP connections and model are the host's to resolve
+ * — a workflow step should name an agent and hand it a task, not re-specify it.
+ *
+ * A provider is that: the host's agent platform, behind a port. It resolves
+ * config into a run and reports back; the step keeps the workflow contract
+ * (output shape, JSON repair, citations, artifacts). See ./host-agent-step.ts.
+ *
+ * Two transports, because hosts genuinely have both:
+ *
+ *  - {@link SyncAgentCapability} streams the run. The step holds a worker slot
+ *    for its duration and forwards progress to the execution viewer. Right for
+ *    a workflow someone is watching.
+ *  - {@link AsyncAgentCapability} dispatches the run and parks the step. The
+ *    worker slot is released and the execution resumes on callback. Right for
+ *    headless automations, and for agents that run for a long time.
+ *
+ * A provider may implement either or both. Where it implements both, the choice
+ * is per-invocation — the same agent, watched or not — so it belongs in step
+ * config, not in the provider's identity.
+ *
+ * Deliberately free of pi-mono imports.
+ */
+import type { z } from 'zod';
+import type { Attachment } from '../common/attachment.js';
+import type { StepExecutionContext } from '../steps/base-step.js';
+import type { ResumePayload } from '../common/resume-payload.js';
+import type { ResponseDefect, ToolCallRecord } from './contract.js';
+/**
+ * One selectable agent, as shown in the step's agent picker.
+ *
+ * Returned by {@link BaseAgentProvider.listAgents} and served over the host's
+ * agents route — never baked into the config JSON Schema, which is generated
+ * once per process and has no tenant context.
+ */
+export interface AgentDescriptor {
+    id: string;
+    name: string;
+    description?: string;
+    avatarUrl?: string;
+}
+/** What the step hands a provider for one invocation. */
+export interface AgentRunInput {
+    /** The instruction for this run, with workflow refs already resolved. */
+    task: string;
+    /** Input documents the agent should have access to. */
+    attachments: Attachment[];
+    /** True when the step expects a JSON object back rather than free text. */
+    expectJson: boolean;
+    /** The JSON Schema the response should match. Present only when `expectJson`. */
+    outputSchema?: Record<string, unknown>;
+    /** True when every data point in the response must carry a source citation. */
+    cite: boolean;
+    /** Aborted when the step's wall-clock budget expires or the execution is cancelled. */
+    signal: AbortSignal;
+    /**
+     * Set when re-prompting after an unusable response. Providers should feed
+     * the defect back to the agent rather than starting a fresh conversation.
+     */
+    repair?: {
+        attempt: number;
+    } & ResponseDefect;
+}
+/**
+ * What a streaming run reports back.
+ *
+ * A provider translates its own transport (SSE frames, a websocket, an
+ * in-process iterator) into these. Failures are thrown, not yielded — a
+ * provider that ends without a `done` event is treated as a failed run.
+ */
+export type AgentRunEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text?: string;
+} | {
+    type: 'tool_start';
+    toolCallId: string;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_end';
+    toolCallId: string;
+    tool: string;
+    result: unknown;
+}
+/** A file the agent produced. The step stores it; the provider only yields bytes. */
+ | {
+    type: 'artifact';
+    name: string;
+    mimeType: string;
+    bytes: Uint8Array;
+} | {
+    type: 'done';
+    result: AgentRunResult;
+};
+/**
+ * The outcome of one agent invocation.
+ *
+ * Note there are no attachments here: artifacts arrive as events and are
+ * persisted by the step through `ctx.storage`, so storage policy stays in the
+ * SDK rather than being re-implemented by every provider.
+ */
+export interface AgentRunResult {
+    /** The agent's response text, unparsed — the step shapes it per `outputType`. */
+    text: string;
+    toolCalls: ToolCallRecord[];
+    turnCount: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /**
+     * Artifacts the provider resolved itself.
+     *
+     * Streaming providers should leave this unset and yield `artifact` events
+     * instead, so the step persists the bytes through `ctx.storage` and storage
+     * policy stays in one place. Dispatching providers have no byte stream to
+     * intercept — their artifacts arrive as references in the callback payload —
+     * so they map them to {@link Attachment} themselves.
+     */
+    attachments?: Attachment[];
+}
+/**
+ * What a parked step remembers about its dispatched run, written under
+ * `data.agent` on the step record and handed back to {@link
+ * AsyncAgentCapability.collect}.
+ *
+ * `provider` is stamped so a provider swap between dispatch and callback is
+ * caught rather than silently mis-resolved. `externalRef` is the correlation
+ * key: the SDK does not persist the one passed to `ctx.pause`, so this is the
+ * durable copy a host's callback route matches against. `attempt` carries the
+ * repair budget across the pause boundary, since the async repair loop is
+ * re-entry rather than iteration.
+ */
+export interface AgentDispatchRecord {
+    provider: string;
+    attempt: number;
+    externalRef: string;
+}
+/**
+ * A host's agent platform, behind a port.
+ *
+ * `TConfig` is the provider's own slice of step config — typically just the
+ * agent reference, since everything else about the agent is the host's to
+ * resolve. The step merges it with the shared contract fields.
+ *
+ * `TCtx` is the host's authorization context, used only by {@link listAgents},
+ * which is called from a request route rather than from step execution.
+ */
+export declare abstract class BaseAgentProvider<TConfig extends z.ZodTypeAny = z.ZodTypeAny, TCtx = unknown> {
+    /** Human-readable provider name. Also stamped on paused step records so a
+     *  provider swap mid-flight is caught rather than silently mis-resolved. */
+    abstract readonly name: string;
+    /** The provider's config fields, merged into the step's config schema. */
+    abstract readonly configSchema: TConfig;
+    /**
+     * List the agents this caller may run. Backs the step's agent picker.
+     *
+     * Omit when the provider's config names an agent some other way (a free-text
+     * id, a fixed single agent); the picker then falls back to a plain field.
+     */
+    listAgents?(ctx: TCtx): Promise<AgentDescriptor[]>;
+    /**
+     * Customize the JSON Schema generated from {@link configSchema} — the same
+     * hook steps have, scoped to the provider's own fields.
+     *
+     * Note this runs once per process with no tenant context, so it can inject
+     * static metadata (formats, enums over process-global lists) but never a
+     * per-workspace list. That is what {@link listAgents} is for.
+     */
+    decorateConfigSchema?(jsonSchema: Record<string, unknown>): Record<string, unknown>;
+}
+/**
+ * Stream the run and report progress as it happens.
+ *
+ * The step consumes the iterable to completion, so a provider holding an open
+ * connection must release it from the generator's `finally` — the step may stop
+ * consuming early (timeout, abort, workflow cancellation).
+ */
+export interface SyncAgentCapability<TConfig extends z.ZodTypeAny = z.ZodTypeAny> {
+    run(config: z.infer<TConfig>, input: AgentRunInput, ctx: StepExecutionContext): AsyncIterable<AgentRunEvent>;
+}
+/**
+ * Dispatch the run and let the step park until the host calls back.
+ *
+ * `dispatch` returns a correlation reference the host's callback route carries;
+ * the step persists it and pauses. `collect` runs on resume and turns the
+ * parked record plus the callback payload into a result.
+ */
+export interface AsyncAgentCapability<TConfig extends z.ZodTypeAny = z.ZodTypeAny> {
+    dispatch(config: z.infer<TConfig>, input: AgentRunInput, ctx: StepExecutionContext): Promise<{
+        externalRef: string;
+    }>;
+    /**
+     * Turn the host's callback into a result.
+     *
+     * `payload` is what the host passed to `runtime.resume()` — a dispatching
+     * provider typically reads its own envelope out of `payload.data`. `record`
+     * is what this provider stored when it dispatched, so a provider that needs
+     * its own correlation reference has it without going near the step row.
+     */
+    collect(payload: ResumePayload, record: AgentDispatchRecord, config: z.infer<TConfig>, ctx: StepExecutionContext): Promise<AgentRunResult>;
+}
+/**
+ * Resolve which transport an invocation should take.
+ *
+ * A provider implementing exactly one capability decides it; one implementing
+ * both defers to step config, where the author chose per invocation.
+ */
+export declare function resolveAgentMode<TConfig extends z.ZodTypeAny, TCtx>(provider: BaseAgentProvider<TConfig, TCtx>, mode: unknown): 'sync' | 'async';
+/** A provider paired with at least one transport. */
+export type AgentProvider<TConfig extends z.ZodTypeAny = z.ZodTypeAny, TCtx = unknown> = BaseAgentProvider<TConfig, TCtx> & (SyncAgentCapability<TConfig> | AsyncAgentCapability<TConfig>);
+export declare function supportsSync<TConfig extends z.ZodTypeAny, TCtx>(provider: BaseAgentProvider<TConfig, TCtx>): provider is BaseAgentProvider<TConfig, TCtx> & SyncAgentCapability<TConfig>;
+export declare function supportsAsync<TConfig extends z.ZodTypeAny, TCtx>(provider: BaseAgentProvider<TConfig, TCtx>): provider is BaseAgentProvider<TConfig, TCtx> & AsyncAgentCapability<TConfig>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/agents/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/agents/provider.ts"],"names":[],"mappings":"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"}

package/dist/agents/provider.js

@@ -0,0 +1,72 @@
+/**
+ * Agent provider port — the seam between a workflow's agent step and whoever
+ * actually runs the agent.
+ *
+ * The SDK ships one agent implementation ({@link AgentStep}, which drives an
+ * LLM directly through a pi-mono runtime). That works when the SDK owns the
+ * agent: the step config carries the system prompt, the tool list and the turn
+ * budget, and the SDK drives the loop.
+ *
+ * It does not work when the *host* already owns agent lifecycle. In xyne-spaces
+ * agents live in claw; in xyne-search they live in an `agents` table. In both
+ * cases the prompt, tools, MCP connections and model are the host's to resolve
+ * — a workflow step should name an agent and hand it a task, not re-specify it.
+ *
+ * A provider is that: the host's agent platform, behind a port. It resolves
+ * config into a run and reports back; the step keeps the workflow contract
+ * (output shape, JSON repair, citations, artifacts). See ./host-agent-step.ts.
+ *
+ * Two transports, because hosts genuinely have both:
+ *
+ *  - {@link SyncAgentCapability} streams the run. The step holds a worker slot
+ *    for its duration and forwards progress to the execution viewer. Right for
+ *    a workflow someone is watching.
+ *  - {@link AsyncAgentCapability} dispatches the run and parks the step. The
+ *    worker slot is released and the execution resumes on callback. Right for
+ *    headless automations, and for agents that run for a long time.
+ *
+ * A provider may implement either or both. Where it implements both, the choice
+ * is per-invocation — the same agent, watched or not — so it belongs in step
+ * config, not in the provider's identity.
+ *
+ * Deliberately free of pi-mono imports.
+ */
+// ─── Provider ───
+/**
+ * A host's agent platform, behind a port.
+ *
+ * `TConfig` is the provider's own slice of step config — typically just the
+ * agent reference, since everything else about the agent is the host's to
+ * resolve. The step merges it with the shared contract fields.
+ *
+ * `TCtx` is the host's authorization context, used only by {@link listAgents},
+ * which is called from a request route rather than from step execution.
+ */
+export class BaseAgentProvider {
+}
+/**
+ * Resolve which transport an invocation should take.
+ *
+ * A provider implementing exactly one capability decides it; one implementing
+ * both defers to step config, where the author chose per invocation.
+ */
+export function resolveAgentMode(provider, mode) {
+    const sync = supportsSync(provider);
+    const async = supportsAsync(provider);
+    if (sync && async)
+        return mode === 'async' ? 'async' : 'sync';
+    if (async)
+        return 'async';
+    if (sync)
+        return 'sync';
+    throw new Error(`Agent provider "${provider.name}" implements neither SyncAgentCapability nor AsyncAgentCapability`);
+}
+// ─── Capability Detection ───
+export function supportsSync(provider) {
+    return typeof provider.run === 'function';
+}
+export function supportsAsync(provider) {
+    return typeof provider.dispatch === 'function'
+        && typeof provider.collect === 'function';
+}
+//# sourceMappingURL=provider.js.map

package/dist/agents/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/agents/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA8GH,mBAAmB;AAEnB;;;;;;;;;GASG;AACH,MAAM,OAAgB,iBAAiB;CA4BtC;AAiDD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA0C,EAC1C,IAAa;IAEb,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,IAAI,IAAI,KAAK;QAAE,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,IAAI,KAAK;QAAE,OAAO,OAAO,CAAC;IAC1B,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC;IACxB,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,CAAC,IAAI,mEAAmE,CACpG,CAAC;AACJ,CAAC;AASD,+BAA+B;AAE/B,MAAM,UAAU,YAAY,CAC1B,QAA0C;IAE1C,OAAO,OAAQ,QAA8B,CAAC,GAAG,KAAK,UAAU,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,QAA0C;IAE1C,OAAO,OAAQ,QAAmC,CAAC,QAAQ,KAAK,UAAU;WACrE,OAAQ,QAAkC,CAAC,OAAO,KAAK,UAAU,CAAC;AACzE,CAAC"}

package/dist/agents/types.d.ts

@@ -8,7 +8,7 @@
  *
  * Only usable when pi-mono peer dependencies are installed.
  */
-import type { Attachment } from '../common/attachment.js';
+import type { ToolCallRecord } from './contract.js';
 export type { AgentEvent, AgentTool, AgentToolResult, AgentToolUpdateCallback, AgentContext, AgentMessage, AgentLoopConfig, BeforeToolCallResult, AfterToolCallResult, BeforeToolCallContext, AfterToolCallContext, ThinkingLevel, } from '@earendil-works/pi-agent-core';
 export type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
 export type { Message, UserMessage, AssistantMessage, ToolResultMessage, TextContent, ThinkingContent, ImageContent, ToolCall, Tool, Usage, Model, Context, StopReason, } from '@earendil-works/pi-ai';
@@ -73,24 +73,5 @@ export interface AgentPauseState {
         outputTokens: number;
     };
 }
-/** Record of a completed tool call with timing — written to workflow context. */
-export interface ToolCallRecord {
-    name: string;
-    args: Record<string, unknown>;
-    result: unknown;
-    durationMs: number;
-}
-/** Final output written to workflow context after agent execution. */
-export interface AgentResult extends Record<string, unknown> {
-    /** Free text (outputType 'string') or a parsed JSON object (outputType 'json'). */
-    response: string | Record<string, unknown>;
-    toolCalls: ToolCallRecord[];
-    turnCount: number;
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-    };
-    /** Files the agent generated in the sandbox, persisted as artifacts. */
-    attachments: Attachment[];
-}
+export type { ToolCallRecord, AgentResult } from './contract.js';
 //# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}

package/dist/authz/attributes.d.ts

@@ -28,11 +28,34 @@
  * This mirrors how TanStack Router (`Register`) and Express (`Request`
  * augmentation) let consumers extend framework types without generics.
  */
+import type { AuthContext } from '../router/types.js';
 export interface Register {
 }
 type ResolvedAttributes = Register extends {
     attributes: infer A;
 } ? A : Record<string, unknown>;
+/**
+ * The product's auth-context shape — the same opt-in as {@link ResolvedAttributes}.
+ *
+ * Declared once:
+ * ```ts
+ * declare module '@xyne/workflow-sdk' {
+ *   interface Register { authContext: { userId: string; workspaceId: string } }
+ * }
+ * ```
+ *
+ * Its first use is {@link StorageScope}: a caller-initiated blob write has a person
+ * and no workflow, so the caller has to be able to say which tenant it is for.
+ *
+ * NOTE: this does not yet constrain the `TCtx` generic threaded through
+ * `WorkflowRuntime` / `WorkflowAuthorizer` / `RouterOptions`. Until it does, a host
+ * declaring one and passing the other can drift — see the cast in the router's
+ * storage call sites. Constraining `TCtx extends ResolvedAuthContext` is the
+ * follow-up, and would let hosts drop those generics entirely.
+ */
+export type ResolvedAuthContext = Register extends {
+    authContext: infer C;
+} ? C : AuthContext;
 /** The product's attribute shape for a resource kind — `unknown` if unaugmented. */
 export type ResourceAttributes<K extends string> = K extends keyof ResolvedAttributes ? ResolvedAttributes[K] : unknown;
 /** Resource kinds that carry product attributes at creation. */

package/dist/authz/attributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/authz/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAQ;CAAG;AAE5B,KAAK,kBAAkB,GAAG,QAAQ,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9D,CAAC,GACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,kBAAkB,GACjF,kBAAkB,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC;AAEZ,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC"}
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/authz/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,QAAQ;CAAG;AAE5B,KAAK,kBAAkB,GAAG,QAAQ,SAAS;IAAE,UAAU,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9D,CAAC,GACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,SAAS;IAAE,WAAW,EAAE,MAAM,CAAC,CAAA;CAAE,GACvE,CAAC,GACD,WAAW,CAAC;AAEhB,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,kBAAkB,GACjF,kBAAkB,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC;AAEZ,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC"}

package/dist/router/workflow-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-router.d.ts","sourceRoot":"","sources":["../../src/router/workflow-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAA+B,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4J3G,wBAAgB,oBAAoB,CAAC,IAAI,GAAG,WAAW,EAGrD,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,EAEnC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GACzB,eAAe,CAAC,IAAI,CAAC,EAAE,CAk6CzB"}
+{"version":3,"file":"workflow-router.d.ts","sourceRoot":"","sources":["../../src/router/workflow-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAA+B,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4J3G,wBAAgB,oBAAoB,CAAC,IAAI,GAAG,WAAW,EAGrD,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,EAEnC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GACzB,eAAe,CAAC,IAAI,CAAC,EAAE,CAs6CzB"}

package/dist/router/workflow-router.js

@@ -487,8 +487,9 @@ _opts) {
         method: 'POST',
         path: '/uploads',
         multipart: 'files',
-        // TODO(uploads): guard/scope via the authorizer once uploads are ACL-modeled.
-        handler: async (req, _auth) => {
+        // TODO(uploads): guard via the authorizer once blobs are ACL-modeled. The scope
+        // below gives tenant attribution; it is not authorization.
+        handler: async (req, auth) => {
             if (!runtime.storage) {
                 return error(501, 'No StorageAdapter configured — file uploads are disabled');
             }
@@ -507,10 +508,11 @@ _opts) {
                     }
                 }
             }
-            // TODO(uploads): uploads are not yet ACL-scoped. The storage scope must be
-            // produceable from BOTH a caller (here) and a workflow (execution-time
-            // writes have no caller) — designed in the uploads pass. Empty for now.
-            const scope = {};
+            // The host's auth context IS its storage scope for caller-initiated work: an
+            // upload has a person and no workflow yet. Not provable here (TCtx is unbound
+            // at this point), so the host's adapter validates and rejects a scope it
+            // cannot read a tenant from.
+            const scope = auth;
             try {
                 const attachments = [];
                 for (const file of files) {
@@ -539,7 +541,7 @@ _opts) {
     routes.push({
         method: 'GET',
         path: '/attachments',
-        handler: async (req, _auth) => {
+        handler: async (req, auth) => {
             if (!runtime.storage) {
                 return error(501, 'No StorageAdapter configured — downloads are disabled');
             }
@@ -554,7 +556,9 @@ _opts) {
                     const url = await runtime.storage.signUrl(attachment, 300);
                     return { status: 302, body: null, headers: { Location: url } };
                 }
-                const bytes = await runtime.storage.read(attachment);
+                // Pass the caller so a tenant-enforcing adapter can refuse a reference
+                // owned by another workspace. `ref` is client-supplied.
+                const bytes = await runtime.storage.read(attachment, auth);
                 return {
                     status: 200,
                     body: bytes,
@@ -1287,7 +1291,7 @@ _opts) {
                             if (typeof att.attachment.size === 'number' && att.attachment.size > MAX_MOUNT_BYTES)
                                 continue;
                             try {
-                                const bytes = await runtime.storage.read(att.attachment);
+                                const bytes = await runtime.storage.read(att.attachment, auth);
                                 preloadFiles.push({ path: att.sandboxPath, bytes });
                                 mountedPaths.set(att.attachment.data, att.sandboxPath);
                             }