@sprigr/apps-app-sdk 0.20.0 → 0.21.0

package/README.md

@@ -79,6 +79,7 @@ export default {
 - `putAppFile` / `putAppFileStream` / `appFileUrl` / `getAppFile` / `listAppFiles` / `deleteAppFile` — durable app-scoped file storage from outside the injected bridge
 - `fetchFileBytes` / `fetchFileAsBase64` / `bytesToBase64` / `base64ToBytes` — file byte helpers
 - `readableStoredKey(appKey, downloadUrl)` / `agentFileKeyFromUrl` — turn the install-relative key your app stored a file under into the absolute key the platform's `read_file` tool opens (read off the signed URL `appFileUrl` minted). Return it as a tool's `file_key` so an agent can open the file. `appKeyFromCallerKey` / `callerKeyRefusal` go the other way, for a key an agent hands back to your tool (0.17.0)
+- `readFileRef(env, { file_key } | { file_url }, { maxBytes })` / `resolveFileRef`: accept a file an agent hands your tool. `resolveFileRef` only validates (run it before an approval card): a key in this install's store in any form, or an https link on `files.sprigr.com` (a link into this install is read as its key; a company link must be signed and in this company; workspace keys, other installs and every other host are refused with a `FileRefError` whose message says what to pass instead). `readFileRef` then reads the bytes with a size cap, a 20 s time cap and no redirects; `openFileRef` does the same as a stream, for a large attachment passed on without buffering. `FILE_REF_SOURCES_HELP` is the agent-facing list of accepted sources, for a tool's input description (0.21.0)
 
 Full platform semantics: [`docs/platform-reference.md`](../../docs/platform-reference.md).
 

package/dist/index.d.ts

@@ -164,6 +164,256 @@ declare function fetchFileAsBase64(url: string, opts?: {
     size: number;
 }>;
 
+/**
+ * App-scoped R2 file storage (platform feature, 2026-06).
+ *
+ * Marketplace apps get a contained file store: every key is confined
+ * server-side to `_apps/{installId}/...` so an app can only ever touch
+ * its own files. The app never holds a raw R2 binding — these helpers
+ * call the platform over the same per-install token channel as
+ * `env.SPRIGR.emit` (provisioning `/internal/wfp/file/*`).
+ *
+ * Auth: `Authorization: Bearer <SPRIGR_INSTALL_TOKEN>` against
+ * `<SPRIGR_PLATFORM_BASE>/internal/wfp/file/<op>`. Both bindings are
+ * stamped onto every per-install WFP upload.
+ *
+ * Keys are app-relative (`simpro-files/123.jpg`); the platform adds and
+ * strips the `_apps/{installId}/` prefix, so the app stays unaware of it
+ * and physically cannot escape its namespace.
+ */
+interface AppFilesEnv {
+    SPRIGR_INSTALL_TOKEN?: string;
+    SPRIGR_PLATFORM_BASE?: string;
+}
+interface PutAppFileArgs {
+    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
+    key: string;
+    /** File bytes, base64-encoded. */
+    base64: string;
+    /** MIME type stored as the object's content-type. */
+    contentType?: string;
+    /** Optional display filename. */
+    filename?: string;
+}
+interface PutAppFileResult {
+    ok: true;
+    key: string;
+    bytes: number;
+    contentType: string;
+}
+interface PutAppFileStreamArgs {
+    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
+    key: string;
+    /**
+     * Raw file bytes. A `ReadableStream` is piped straight through to R2 so
+     * the bytes never fully materialise in the app isolate — use it for large
+     * blobs (full-res photos, PDFs). An `ArrayBuffer`/`Uint8Array` is also
+     * accepted when the bytes are already in hand.
+     */
+    body: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array;
+    /** MIME type stored as the object's content-type. */
+    contentType?: string;
+    /** Optional display filename. */
+    filename?: string;
+    /**
+     * Declared byte length. Forward it when known (e.g. the source's
+     * Content-Length) so the platform can enforce its size cap before opening
+     * the R2 write. Streamed bodies carry no Content-Length, so this is the
+     * only length signal the platform gets. Omit for unknown-length streams.
+     */
+    contentLength?: number;
+}
+interface AppFileUrlArgs {
+    key: string;
+    /** Seconds the signed URL stays valid (default 24h, min 60s, max ~10y, clamped server-side). */
+    expiresIn?: number;
+}
+interface AppFileUrlResult {
+    ok: true;
+    url: string;
+    expires_at: number;
+    key: string;
+}
+interface GetAppFileResult {
+    ok: true;
+    key: string;
+    base64: string;
+    contentType: string;
+    filename?: string;
+    bytes: number;
+}
+interface AppFileListItem {
+    key: string;
+    bytes: number;
+    uploaded?: string;
+    filename?: string;
+    contentType?: string;
+}
+/** Store bytes in the app's contained R2 namespace (base64 JSON). */
+declare function putAppFile(env: AppFilesEnv, args: PutAppFileArgs): Promise<PutAppFileResult>;
+/**
+ * Store bytes by streaming the raw body straight into the app's contained
+ * R2 namespace. Unlike `putAppFile`, this never base64-encodes the bytes
+ * and (with a `ReadableStream` body) never buffers them whole in the
+ * isolate — pipe a source `Response.body` directly through for multi-MB
+ * blobs. Metadata travels in headers; the body is opaque bytes.
+ *
+ * The platform's put-stream route cannot retry a transient R2 fault itself
+ * (its body is spent once read), so a resendable body — `ArrayBuffer` /
+ * `Uint8Array` already in hand, not a `ReadableStream` — gets a bounded
+ * retry here instead. The key is deterministic, so a retry is a full
+ * overwrite, exactly the argument the platform's buffered `put` route makes
+ * for its own retry (wfp-files.ts, sprigr-team).
+ */
+declare function putAppFileStream(env: AppFilesEnv, args: PutAppFileStreamArgs): Promise<PutAppFileResult>;
+/** Mint a signed, time-limited download URL for an app file. */
+declare function appFileUrl(env: AppFilesEnv, args: AppFileUrlArgs): Promise<AppFileUrlResult>;
+/** Read an app file back as base64. */
+declare function getAppFile(env: AppFilesEnv, key: string): Promise<GetAppFileResult>;
+/** List app files under an optional app-relative prefix. */
+declare function listAppFiles(env: AppFilesEnv, prefix?: string): Promise<{
+    ok: true;
+    files: AppFileListItem[];
+    truncated: boolean;
+}>;
+/** Delete an app file. */
+declare function deleteAppFile(env: AppFilesEnv, key: string): Promise<{
+    ok: true;
+    key: string;
+}>;
+
+/**
+ * A file an agent hands an app tool: `{ file_key }` or `{ file_url }`
+ * (sprigr/sprigr-app-kit#120).
+ *
+ * The platform resolves no file argument for an app. An agent passes a plain
+ * string and the app turns it into bytes. Three apps had each written that
+ * (trello `readInstallFile`, dropbox `resolveSource`, skusavvy `readRef`), and
+ * the copies had drifted: only dropbox checked that a company link was signed
+ * and in this company, only skusavvy capped time and refused redirects. This
+ * module is the one version, with the strictest rules of each.
+ *
+ * Two steps, usable apart:
+ *
+ *   resolveFileRef  validation only, no I/O. Run it before an approval card or
+ *                   any other side effect, so a malformed call fails first.
+ *   openFileRef     resolve, then open the bytes as a stream with a size cap,
+ *                   a time cap and no redirects, so a large attachment is
+ *                   passed on without being buffered first.
+ *   readFileRef     openFileRef, read into memory, for files an app buffers.
+ *
+ * What a reference may be:
+ *   - file_key: a key in THIS install's file store, in any form a tool hands
+ *     out (app-relative, absolute `_apps/<installId>/...`, or its signed link),
+ *     via appKeyFromCallerKey. A key in the company's own storage (an agent's
+ *     workspace file) cannot be opened by an app: refused, with how to pass it.
+ *   - file_url: an https link on a Sprigr file host only. A link into this
+ *     install's storage is read as a key (so it opens the caller's own copy);
+ *     a link into the company's storage must be signed and in THIS company.
+ *     Nothing else is fetched, so an agent cannot point an app at an arbitrary
+ *     host, and every host it can reach is the platform's own.
+ */
+
+/** Hosts the platform serves signed file links from (the file proxy, prod and staging). */
+declare const SPRIGR_FILE_HOSTS: ReadonlySet<string>;
+/** Default time to read one file before giving up. */
+declare const DEFAULT_FILE_READ_TIMEOUT_MS = 20000;
+/** How an agent gets a workspace file to an app: a short-lived signed link. */
+declare const WORKSPACE_FILE_HOW_TO = "Apps cannot open a file in your own Sprigr storage by key. Mint a short-lived download link for it (the files tool's generate_url; a few minutes is enough) and pass that link as file_url: the app fetches it itself, so the link never leaves Sprigr.";
+/**
+ * The sources a file argument accepts, written for the agent. Put it in a
+ * tool's input description so the agent knows what to pass before it calls;
+ * the not_one and not_sprigr_host refusals repeat it.
+ */
+declare const FILE_REF_SOURCES_HELP = "Pass exactly one of: file_key, a key this app's own tools returned; or file_url, an https Sprigr file link (on files.sprigr.com), either the download_url another app's tool returned or, for a file in your own Sprigr storage, a short-lived link from the files tool's generate_url.";
+type FileRefErrorCode = 'not_one' | 'bad_url' | 'not_sprigr_host' | 'unsigned_link' | 'other_company' | 'workspace_key' | 'other_install' | 'malformed_key' | 'internal_key' | 'no_file_store' | 'not_found' | 'too_large' | 'timeout' | 'read_failed';
+/** A refusal or read failure, with a message written for the agent that made the call. */
+declare class FileRefError extends Error {
+    readonly code: FileRefErrorCode;
+    constructor(code: FileRefErrorCode, message: string);
+}
+interface FileRef {
+    file_key?: unknown;
+    file_url?: unknown;
+}
+interface ResolveFileRefOptions {
+    /** env.INSTALL_ID: refuses an absolute key or link for another install. */
+    installId?: string | null;
+    /** env.COMPANY_ID: a company link must be in this company; also spots workspace keys. */
+    companyId?: string | null;
+    /** App-relative prefixes of the app's own working storage, never a tool's output. */
+    internalPrefixes?: readonly string[];
+    /** Field name used in messages (default `file`), e.g. `image` or `images[1]`. */
+    label?: string;
+}
+type ResolvedFileRef = {
+    kind: 'stored';
+    appKey: string;
+    filename: string;
+} | {
+    kind: 'url';
+    url: string;
+    filename: string;
+};
+/**
+ * Check a `{ file_key } | { file_url }` reference and say what to read.
+ * Pure: no request is made. Throws FileRefError.
+ */
+declare function resolveFileRef(ref: FileRef | null | undefined, opts?: ResolveFileRefOptions): ResolvedFileRef;
+interface FileRefEnv extends Partial<AppFilesEnv> {
+    INSTALL_ID?: string;
+    COMPANY_ID?: string;
+    /** Present on dispatched handlers: env.SPRIGR.files.url mints a read link. */
+    SPRIGR?: unknown;
+}
+interface ReadFileRefOptions extends Omit<ResolveFileRefOptions, 'installId' | 'companyId'> {
+    /** Byte ceiling for one file (required: pick the downstream API's limit). */
+    maxBytes: number;
+    /**
+     * Time for the whole read, headers and body, default
+     * {@link DEFAULT_FILE_READ_TIMEOUT_MS}. A streaming caller sending a large
+     * file onward should raise it to cover the upload too.
+     */
+    timeoutMs?: number;
+}
+/** How the bytes were read: a minted link to a stored key, the install-token fallback, or the caller's link. */
+type FileRefVia = 'bridge' | 'install_token' | 'url';
+interface FileRefContent {
+    bytes: Uint8Array;
+    size: number;
+    contentType: string;
+    filename: string;
+    via: FileRefVia;
+}
+interface FileRefStream {
+    /**
+     * The file's bytes. Errors with a FileRefError (`too_large`, `timeout`,
+     * `read_failed`) if the cap or the time runs out mid-read; cancel it if you
+     * stop early.
+     */
+    body: ReadableStream<Uint8Array>;
+    /** The declared length when the source sent one, else null. */
+    size: number | null;
+    contentType: string;
+    filename: string;
+    via: FileRefVia;
+}
+/**
+ * Resolve a reference (with the env's install and company) and open it as a
+ * stream, so a large attachment is passed on without being buffered first.
+ * Every fetch is time-capped, size-capped (on the declared length up front and
+ * on the bytes as they arrive), and refuses redirects, so a Sprigr link cannot
+ * bounce the read to another host. The install-token fallback returns its
+ * bytes in one chunk (that transport is base64 JSON). Throws FileRefError.
+ */
+declare function openFileRef(env: FileRefEnv, ref: FileRef | null | undefined, opts: ReadFileRefOptions): Promise<FileRefStream>;
+/**
+ * {@link openFileRef}, read into memory. For files an app sends on in one
+ * request body; use openFileRef to pass a large file on as a stream.
+ * Throws FileRefError.
+ */
+declare function readFileRef(env: FileRefEnv, ref: FileRef | null | undefined, opts: ReadFileRefOptions): Promise<FileRefContent>;
+
 /**
  * Per-env resolver for the platform webhook host that marketplace
  * apps use as the callback URL when registering provider webhooks.
@@ -1292,124 +1542,6 @@ declare function parseActorRetiredArgs(args: unknown): ActorRetired;
  */
 declare function actorRetiredHook<Env>(fn: (env: Env, retired: ActorRetired) => Promise<ActorRetiredResult>): (args: unknown, env: Env) => Promise<ActorRetiredResult>;
 
-/**
- * App-scoped R2 file storage (platform feature, 2026-06).
- *
- * Marketplace apps get a contained file store: every key is confined
- * server-side to `_apps/{installId}/...` so an app can only ever touch
- * its own files. The app never holds a raw R2 binding — these helpers
- * call the platform over the same per-install token channel as
- * `env.SPRIGR.emit` (provisioning `/internal/wfp/file/*`).
- *
- * Auth: `Authorization: Bearer <SPRIGR_INSTALL_TOKEN>` against
- * `<SPRIGR_PLATFORM_BASE>/internal/wfp/file/<op>`. Both bindings are
- * stamped onto every per-install WFP upload.
- *
- * Keys are app-relative (`simpro-files/123.jpg`); the platform adds and
- * strips the `_apps/{installId}/` prefix, so the app stays unaware of it
- * and physically cannot escape its namespace.
- */
-interface AppFilesEnv {
-    SPRIGR_INSTALL_TOKEN?: string;
-    SPRIGR_PLATFORM_BASE?: string;
-}
-interface PutAppFileArgs {
-    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
-    key: string;
-    /** File bytes, base64-encoded. */
-    base64: string;
-    /** MIME type stored as the object's content-type. */
-    contentType?: string;
-    /** Optional display filename. */
-    filename?: string;
-}
-interface PutAppFileResult {
-    ok: true;
-    key: string;
-    bytes: number;
-    contentType: string;
-}
-interface PutAppFileStreamArgs {
-    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
-    key: string;
-    /**
-     * Raw file bytes. A `ReadableStream` is piped straight through to R2 so
-     * the bytes never fully materialise in the app isolate — use it for large
-     * blobs (full-res photos, PDFs). An `ArrayBuffer`/`Uint8Array` is also
-     * accepted when the bytes are already in hand.
-     */
-    body: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array;
-    /** MIME type stored as the object's content-type. */
-    contentType?: string;
-    /** Optional display filename. */
-    filename?: string;
-    /**
-     * Declared byte length. Forward it when known (e.g. the source's
-     * Content-Length) so the platform can enforce its size cap before opening
-     * the R2 write. Streamed bodies carry no Content-Length, so this is the
-     * only length signal the platform gets. Omit for unknown-length streams.
-     */
-    contentLength?: number;
-}
-interface AppFileUrlArgs {
-    key: string;
-    /** Seconds the signed URL stays valid (default 24h, min 60s, max ~10y, clamped server-side). */
-    expiresIn?: number;
-}
-interface AppFileUrlResult {
-    ok: true;
-    url: string;
-    expires_at: number;
-    key: string;
-}
-interface GetAppFileResult {
-    ok: true;
-    key: string;
-    base64: string;
-    contentType: string;
-    filename?: string;
-    bytes: number;
-}
-interface AppFileListItem {
-    key: string;
-    bytes: number;
-    uploaded?: string;
-    filename?: string;
-    contentType?: string;
-}
-/** Store bytes in the app's contained R2 namespace (base64 JSON). */
-declare function putAppFile(env: AppFilesEnv, args: PutAppFileArgs): Promise<PutAppFileResult>;
-/**
- * Store bytes by streaming the raw body straight into the app's contained
- * R2 namespace. Unlike `putAppFile`, this never base64-encodes the bytes
- * and (with a `ReadableStream` body) never buffers them whole in the
- * isolate — pipe a source `Response.body` directly through for multi-MB
- * blobs. Metadata travels in headers; the body is opaque bytes.
- *
- * The platform's put-stream route cannot retry a transient R2 fault itself
- * (its body is spent once read), so a resendable body — `ArrayBuffer` /
- * `Uint8Array` already in hand, not a `ReadableStream` — gets a bounded
- * retry here instead. The key is deterministic, so a retry is a full
- * overwrite, exactly the argument the platform's buffered `put` route makes
- * for its own retry (wfp-files.ts, sprigr-team).
- */
-declare function putAppFileStream(env: AppFilesEnv, args: PutAppFileStreamArgs): Promise<PutAppFileResult>;
-/** Mint a signed, time-limited download URL for an app file. */
-declare function appFileUrl(env: AppFilesEnv, args: AppFileUrlArgs): Promise<AppFileUrlResult>;
-/** Read an app file back as base64. */
-declare function getAppFile(env: AppFilesEnv, key: string): Promise<GetAppFileResult>;
-/** List app files under an optional app-relative prefix. */
-declare function listAppFiles(env: AppFilesEnv, prefix?: string): Promise<{
-    ok: true;
-    files: AppFileListItem[];
-    truncated: boolean;
-}>;
-/** Delete an app file. */
-declare function deleteAppFile(env: AppFilesEnv, key: string): Promise<{
-    ok: true;
-    key: string;
-}>;
-
 /**
  * Write-protection types, mirrored from the Sprigr platform.
  *
@@ -3207,4 +3339,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };
+export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_FILE_READ_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, FILE_REF_SOURCES_HELP, type FetchFileResult, type FetchWithRetryOptions, type FileRef, type FileRefContent, type FileRefEnv, FileRefError, type FileRefErrorCode, type FileRefStream, type FileRefVia, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ReadFileRefOptions, type RequireApprovalOptions, type ResolveFileRefOptions, type ResolveViewerOptions, type ResolvedFileRef, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_FILE_HOSTS, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, WORKSPACE_FILE_HOW_TO, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -155,6 +155,409 @@ async function fetchFileAsBase64(url, opts = {}) {
   return { base64: bytesToBase64(bytes), contentType, size };
 }
 
+// src/app-files.ts
+var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
+function platformBase(env) {
+  return (env.SPRIGR_PLATFORM_BASE ?? DEFAULT_PLATFORM_BASE).trim().replace(/\/+$/, "");
+}
+var AppFilesError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "AppFilesError";
+    this.status = status;
+  }
+};
+function requireToken(env) {
+  const token = env.SPRIGR_INSTALL_TOKEN;
+  if (!token) {
+    throw new AppFilesError("app file storage unavailable: SPRIGR_INSTALL_TOKEN unset", 500);
+  }
+  return token;
+}
+async function parseResult(res, op) {
+  const text = await res.text();
+  let parsed = void 0;
+  try {
+    parsed = text ? JSON.parse(text) : void 0;
+  } catch {
+  }
+  if (!res.ok) {
+    const detail = parsed && typeof parsed === "object" ? parsed.hint ?? parsed.detail ?? parsed.error : text.slice(0, 200);
+    throw new AppFilesError(`app file ${op} failed (${res.status}): ${String(detail)}`, res.status);
+  }
+  return parsed;
+}
+async function call(env, op, body) {
+  const token = requireToken(env);
+  const res = await fetch(`${platformBase(env)}/internal/wfp/file/${op}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(body ?? {})
+  });
+  return parseResult(res, op);
+}
+function putAppFile(env, args) {
+  return call(env, "put", {
+    key: args.key,
+    base64: args.base64,
+    contentType: args.contentType,
+    filename: args.filename
+  });
+}
+var STREAM_PUT_MAX_ATTEMPTS = 3;
+var STREAM_PUT_BASE_DELAY_MS = 500;
+function isTransientPutStreamFailure(status, message) {
+  if (status === 503) return true;
+  if (status !== 502) return false;
+  const msg = message.toLowerCase();
+  return msg.includes("(10001)") || msg.includes("(10043)");
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function putAppFileStream(env, args) {
+  const token = requireToken(env);
+  const headers = {
+    authorization: `Bearer ${token}`,
+    "content-type": args.contentType || "application/octet-stream",
+    "x-app-file-key": args.key,
+    "x-app-file-content-type": args.contentType || "application/octet-stream"
+  };
+  if (args.filename) headers["x-app-file-name"] = encodeURIComponent(args.filename);
+  if (typeof args.contentLength === "number" && Number.isFinite(args.contentLength)) {
+    headers["x-app-file-length"] = String(args.contentLength);
+  }
+  const resendable = !(args.body instanceof ReadableStream);
+  const attempts = resendable ? STREAM_PUT_MAX_ATTEMPTS : 1;
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const res = await fetch(`${platformBase(env)}/internal/wfp/file/put-stream`, {
+      method: "POST",
+      headers,
+      body: args.body,
+      // Required by the Workers runtime when sending a streaming request body.
+      ...args.body instanceof ReadableStream ? { duplex: "half" } : {}
+    });
+    try {
+      return await parseResult(res, "put-stream");
+    } catch (err) {
+      lastErr = err;
+      if (!resendable || attempt === attempts || !(err instanceof AppFilesError) || !isTransientPutStreamFailure(err.status, err.message)) {
+        throw err;
+      }
+      await sleep2(STREAM_PUT_BASE_DELAY_MS * 2 ** (attempt - 1));
+    }
+  }
+  throw lastErr;
+}
+function appFileUrl(env, args) {
+  return call(env, "url", { key: args.key, expiresIn: args.expiresIn });
+}
+function getAppFile(env, key) {
+  return call(env, "get", { key });
+}
+function listAppFiles(env, prefix) {
+  return call(env, "list", { prefix });
+}
+function deleteAppFile(env, key) {
+  return call(env, "delete", { key });
+}
+
+// src/stored-file-keys.ts
+var APP_FILES_ROOT = "_apps/";
+var APP_OWNER_SEGMENT = "~u";
+function isSegment(s) {
+  return typeof s === "string" && s.length > 0 && !s.includes("/");
+}
+function trimLeadingSlashes(key) {
+  return key.replace(/^\/+/, "");
+}
+function parseAbsolute(key) {
+  if (!key.startsWith(APP_FILES_ROOT)) return null;
+  const parts = key.slice(APP_FILES_ROOT.length).split("/");
+  const installId = parts[0];
+  if (!isSegment(installId)) return null;
+  let i = 1;
+  let ownerHash = null;
+  if (parts[1] === APP_OWNER_SEGMENT) {
+    if (!isSegment(parts[2])) return null;
+    ownerHash = parts[2];
+    i = 3;
+  }
+  const rest = parts.slice(i).join("/");
+  if (!rest || rest.split("/").some((seg) => seg === "")) return null;
+  return { installId, ownerHash, rest };
+}
+function urlPathKey(url) {
+  try {
+    return trimLeadingSlashes(decodeURIComponent(new URL(url).pathname));
+  } catch {
+    return null;
+  }
+}
+function agentFileKeyFromUrl(downloadUrl, appKey) {
+  const rel = trimLeadingSlashes(appKey);
+  if (!rel) return null;
+  const path = urlPathKey(downloadUrl);
+  if (!path) return null;
+  const parsed = parseAbsolute(path);
+  if (!parsed || parsed.rest !== rel) return null;
+  return path;
+}
+function readableStoredKey(appKey, downloadUrl) {
+  return agentFileKeyFromUrl(downloadUrl, appKey) ?? appKey;
+}
+function appKeyFromCallerKey(key, ownInstallId) {
+  let candidate = key.trim();
+  let wasAbsolute = false;
+  if (/^https?:\/\//i.test(candidate)) {
+    const path = urlPathKey(candidate);
+    if (!path || !path.startsWith(APP_FILES_ROOT)) return { ok: false, reason: "malformed" };
+    candidate = path;
+  }
+  candidate = trimLeadingSlashes(candidate);
+  if (candidate.startsWith(APP_FILES_ROOT)) {
+    const parsed = parseAbsolute(candidate);
+    if (!parsed) return { ok: false, reason: "malformed" };
+    if (ownInstallId && parsed.installId !== ownInstallId) {
+      return { ok: false, reason: "other_install", installId: parsed.installId };
+    }
+    return { ok: true, appKey: parsed.rest, wasAbsolute: true };
+  }
+  const parts = candidate.split("/");
+  if (parts[0] === APP_OWNER_SEGMENT) {
+    const rest = parts.slice(2).join("/");
+    if (!isSegment(parts[1]) || !rest) return { ok: false, reason: "malformed" };
+    return { ok: true, appKey: rest, wasAbsolute: true };
+  }
+  return { ok: true, appKey: candidate, wasAbsolute };
+}
+function callerKeyRefusal(key, r) {
+  if (r.reason === "other_install") {
+    return `"${key}" is a stored file of a different app install (${r.installId}), not this one. Pass a file_key this app returned to you.`;
+  }
+  return `"${key}" is not a stored file key: it has no file path after the app storage prefix.`;
+}
+
+// src/file-ref.ts
+var SPRIGR_FILE_HOSTS = /* @__PURE__ */ new Set(["files.sprigr.com", "staging-files.sprigr.com"]);
+var DEFAULT_FILE_READ_TIMEOUT_MS = 2e4;
+var STORED_READ_URL_TTL_SECONDS = 300;
+var WORKSPACE_FILE_HOW_TO = "Apps cannot open a file in your own Sprigr storage by key. Mint a short-lived download link for it (the files tool's generate_url; a few minutes is enough) and pass that link as file_url: the app fetches it itself, so the link never leaves Sprigr.";
+var FILE_REF_SOURCES_HELP = "Pass exactly one of: file_key, a key this app's own tools returned; or file_url, an https Sprigr file link (on files.sprigr.com), either the download_url another app's tool returned or, for a file in your own Sprigr storage, a short-lived link from the files tool's generate_url.";
+var FileRefError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FileRefError";
+    this.code = code;
+  }
+};
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function lastSegment(path, fallback) {
+  const tail = path.split("/").filter(Boolean).pop();
+  if (!tail) return fallback;
+  try {
+    return decodeURIComponent(tail);
+  } catch {
+    return tail;
+  }
+}
+function isWorkspaceKey(key, companyId) {
+  const k = key.replace(/^\/+/, "");
+  if (k.startsWith(APP_FILES_ROOT)) return false;
+  if (companyId && k.startsWith(`${companyId}/`)) return true;
+  return /^(?:comp_|agt_)[^/]+\//.test(k);
+}
+function stored(appKey, original, opts) {
+  if ((opts.internalPrefixes ?? []).some((p) => appKey.startsWith(p))) {
+    throw new FileRefError("internal_key", `"${original}" is this app's internal working storage, not a file a tool returned. Pass a file_key a tool gave you.`);
+  }
+  return { kind: "stored", appKey, filename: lastSegment(appKey, "file") };
+}
+function resolveFileRef(ref, opts = {}) {
+  const label = opts.label ?? "file";
+  const key = str(ref?.file_key);
+  const url = str(ref?.file_url);
+  if (key === null === (url === null)) {
+    throw new FileRefError("not_one", `${label} takes exactly one of file_key or file_url. ${FILE_REF_SOURCES_HELP}`);
+  }
+  if (url !== null) {
+    let u;
+    let path;
+    try {
+      u = new URL(url);
+      path = decodeURIComponent(u.pathname).replace(/^\/+/, "");
+    } catch {
+      throw new FileRefError("bad_url", `${label}.file_url is not a valid URL.`);
+    }
+    if (u.protocol !== "https:" || !SPRIGR_FILE_HOSTS.has(u.hostname.toLowerCase())) {
+      throw new FileRefError(
+        "not_sprigr_host",
+        `${label}.file_url is not a Sprigr file link, and other web addresses are not fetched. ${FILE_REF_SOURCES_HELP}`
+      );
+    }
+    if (path.startsWith(APP_FILES_ROOT)) {
+      const own = appKeyFromCallerKey(url, opts.installId);
+      if (own.ok) return stored(own.appKey, url, opts);
+      return { kind: "url", url, filename: lastSegment(path, "file") };
+    }
+    if (!opts.companyId || !path.startsWith(`${opts.companyId}/`)) {
+      throw new FileRefError("other_company", `${label}.file_url is not a file in this workspace. ${WORKSPACE_FILE_HOW_TO}`);
+    }
+    if (!u.searchParams.get("token") || !u.searchParams.get("expires")) {
+      throw new FileRefError("unsigned_link", `${label}.file_url must be a signed download link (with its token). ${WORKSPACE_FILE_HOW_TO}`);
+    }
+    return { kind: "url", url, filename: lastSegment(path, "file") };
+  }
+  if (isWorkspaceKey(key, opts.companyId)) {
+    throw new FileRefError("workspace_key", `"${key}" is a file in your own Sprigr storage. ${WORKSPACE_FILE_HOW_TO}`);
+  }
+  const resolved = appKeyFromCallerKey(key, opts.installId);
+  if (!resolved.ok) {
+    if (resolved.reason === "other_install") {
+      throw new FileRefError(
+        "other_install",
+        `"${key}" is a file of another app. Pass that app's download_url for it as file_url instead; a file_key only opens inside the app that stored it.`
+      );
+    }
+    throw new FileRefError("malformed_key", callerKeyRefusal(key, resolved));
+  }
+  return stored(resolved.appKey, key, opts);
+}
+var round1 = (n) => Math.round(n * 10) / 10;
+var human = (n) => n >= 1024 * 1024 ? `${round1(n / (1024 * 1024))} MB` : n >= 1024 ? `${round1(n / 1024)} KB` : `${n} bytes`;
+async function openFileRef(env, ref, opts) {
+  const label = opts.label ?? "file";
+  const resolved = resolveFileRef(ref, { ...opts, installId: env.INSTALL_ID, companyId: env.COMPANY_ID });
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_FILE_READ_TIMEOUT_MS;
+  const tooLarge = (size) => new FileRefError(
+    "too_large",
+    size === null ? `${label} is over the ${human(opts.maxBytes)} limit, so it was not read.` : `${label} is ${human(size)}, over the ${human(opts.maxBytes)} limit, so it was not read.`
+  );
+  const failure = (err) => {
+    if (err instanceof FileRefError) return err;
+    const name = err instanceof Error ? err.name : "";
+    const message = err instanceof Error ? err.message : String(err);
+    if (name === "TimeoutError" || name === "AbortError") {
+      return new FileRefError("timeout", `Reading ${label} took longer than ${Math.round(timeoutMs / 1e3)}s, so it was not read.`);
+    }
+    return new FileRefError("read_failed", `Could not read ${label}: ${message}`);
+  };
+  const openUrl = async (url, via, filename) => {
+    let res;
+    try {
+      res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: "error" });
+    } catch (err) {
+      throw failure(err);
+    }
+    if (!res.ok) {
+      await res.body?.cancel().catch(() => {
+      });
+      if (res.status === 404) throw new FileRefError("not_found", `There is no file at ${label} (the link or key may have expired or been deleted).`);
+      throw new FileRefError("read_failed", `Could not read ${label}: the file host answered HTTP ${res.status}.`);
+    }
+    const declared = Number(res.headers.get("content-length") || "");
+    const size = Number.isFinite(declared) && declared >= 0 && res.headers.has("content-length") ? declared : null;
+    if (size !== null && size > opts.maxBytes) {
+      await res.body?.cancel().catch(() => {
+      });
+      throw tooLarge(size);
+    }
+    const contentType = res.headers.get("content-type")?.split(";")[0]?.trim() || "application/octet-stream";
+    const reader = (res.body ?? new ReadableStream({ start: (c) => c.close() })).getReader();
+    let total = 0;
+    const body = new ReadableStream({
+      async pull(ctrl) {
+        let chunk;
+        try {
+          chunk = await reader.read();
+        } catch (err) {
+          ctrl.error(failure(err));
+          return;
+        }
+        if (chunk.done) {
+          ctrl.close();
+          return;
+        }
+        total += chunk.value.byteLength;
+        if (total > opts.maxBytes) {
+          await reader.cancel().catch(() => {
+          });
+          ctrl.error(tooLarge(null));
+          return;
+        }
+        ctrl.enqueue(chunk.value);
+      },
+      cancel(reason) {
+        return reader.cancel(reason);
+      }
+    });
+    return { body, size, contentType, filename, via };
+  };
+  if (resolved.kind === "url") return openUrl(resolved.url, "url", resolved.filename);
+  const files = env.SPRIGR?.files;
+  if (typeof files?.url === "function") {
+    const minted = await files.url(resolved.appKey, { expiresIn: STORED_READ_URL_TTL_SECONDS });
+    if (!minted?.url) throw new FileRefError("not_found", `This app's file store has no file at "${resolved.appKey}".`);
+    return openUrl(minted.url, "bridge", resolved.filename);
+  }
+  if (env.SPRIGR_INSTALL_TOKEN && env.SPRIGR_PLATFORM_BASE) {
+    let got;
+    try {
+      got = await getAppFile(env, resolved.appKey);
+    } catch (err) {
+      throw failure(err);
+    }
+    if (got.bytes > opts.maxBytes) throw tooLarge(got.bytes);
+    const bytes = base64ToBytes(got.base64 ?? "");
+    if (bytes.byteLength > opts.maxBytes) throw tooLarge(bytes.byteLength);
+    return {
+      body: new ReadableStream({
+        start(ctrl) {
+          ctrl.enqueue(bytes);
+          ctrl.close();
+        }
+      }),
+      size: bytes.byteLength,
+      contentType: got.contentType || "application/octet-stream",
+      filename: got.filename || resolved.filename,
+      via: "install_token"
+    };
+  }
+  throw new FileRefError(
+    "no_file_store",
+    `This runtime has no file store to read ${label}.file_key from (no env.SPRIGR.files and no install token). Pass a Sprigr file link as file_url instead.`
+  );
+}
+async function readFileRef(env, ref, opts) {
+  const opened = await openFileRef(env, ref, opts);
+  const chunks = [];
+  let size = 0;
+  const reader = opened.body.getReader();
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    size += value.byteLength;
+  }
+  const bytes = chunks.length === 1 ? chunks[0] : new Uint8Array(size);
+  if (chunks.length !== 1) {
+    let at = 0;
+    for (const c of chunks) {
+      bytes.set(c, at);
+      at += c.byteLength;
+    }
+  }
+  return { bytes, size, contentType: opened.contentType, filename: opened.filename, via: opened.via };
+}
+
 // src/platform-host.ts
 var FALLBACK_PLATFORM_BASE = "https://webhooks.sprigr.com";
 function resolvePlatformWebhookBase(env, override) {
@@ -864,14 +1267,14 @@ function parseActorRetiredArgs(args) {
     throw new Error("on_actor_retired: refused, the call carries an actor; only the platform hook may call this");
   }
   if (b.trigger !== "actor_retired") throw new Error(`on_actor_retired: trigger must be actor_retired, got ${String(b.trigger)}`);
-  const str = (k) => {
+  const str2 = (k) => {
     const v = b[k];
     if (typeof v !== "string" || v === "") throw new Error(`on_actor_retired: ${k} is required`);
     return v;
   };
-  const installId = str("install_id");
-  const companyId = str("company_id");
-  const key = str("actor_key");
+  const installId = str2("install_id");
+  const companyId = str2("company_id");
+  const key = str2("actor_key");
   const m = KEY_RE.exec(key);
   if (!m) throw new Error(`on_actor_retired: actor_key must be u:<id> or a:<id>, got ${key.slice(0, 80)}`);
   const actor = m[1] === "u" ? { platformUserId: m[2] } : { agentId: m[2] };
@@ -886,9 +1289,9 @@ function parseActorRetiredArgs(args) {
   if (typeof reason !== "string" || !ACTOR_RETIRE_REASONS.includes(reason)) {
     throw new Error(`on_actor_retired: unknown reason ${String(reason)}`);
   }
-  const storageOwnerRef = str("storage_owner_ref");
+  const storageOwnerRef = str2("storage_owner_ref");
   if (!OWNER_REF_RE.test(storageOwnerRef)) throw new Error("on_actor_retired: storage_owner_ref must be 32 lowercase hex characters");
-  const requestedAt = Date.parse(str("requested_at"));
+  const requestedAt = Date.parse(str2("requested_at"));
   if (!Number.isFinite(requestedAt)) throw new Error("on_actor_retired: requested_at is not a date");
   const attempt = typeof b.attempt === "number" && b.attempt >= 1 ? b.attempt : 1;
   return {
@@ -915,118 +1318,6 @@ function actorRetiredHook(fn) {
   };
 }
 
-// src/app-files.ts
-var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
-function platformBase(env) {
-  return (env.SPRIGR_PLATFORM_BASE ?? DEFAULT_PLATFORM_BASE).trim().replace(/\/+$/, "");
-}
-var AppFilesError = class extends Error {
-  status;
-  constructor(message, status) {
-    super(message);
-    this.name = "AppFilesError";
-    this.status = status;
-  }
-};
-function requireToken(env) {
-  const token = env.SPRIGR_INSTALL_TOKEN;
-  if (!token) {
-    throw new AppFilesError("app file storage unavailable: SPRIGR_INSTALL_TOKEN unset", 500);
-  }
-  return token;
-}
-async function parseResult(res, op) {
-  const text = await res.text();
-  let parsed = void 0;
-  try {
-    parsed = text ? JSON.parse(text) : void 0;
-  } catch {
-  }
-  if (!res.ok) {
-    const detail = parsed && typeof parsed === "object" ? parsed.hint ?? parsed.detail ?? parsed.error : text.slice(0, 200);
-    throw new AppFilesError(`app file ${op} failed (${res.status}): ${String(detail)}`, res.status);
-  }
-  return parsed;
-}
-async function call(env, op, body) {
-  const token = requireToken(env);
-  const res = await fetch(`${platformBase(env)}/internal/wfp/file/${op}`, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body ?? {})
-  });
-  return parseResult(res, op);
-}
-function putAppFile(env, args) {
-  return call(env, "put", {
-    key: args.key,
-    base64: args.base64,
-    contentType: args.contentType,
-    filename: args.filename
-  });
-}
-var STREAM_PUT_MAX_ATTEMPTS = 3;
-var STREAM_PUT_BASE_DELAY_MS = 500;
-function isTransientPutStreamFailure(status, message) {
-  if (status === 503) return true;
-  if (status !== 502) return false;
-  const msg = message.toLowerCase();
-  return msg.includes("(10001)") || msg.includes("(10043)");
-}
-function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function putAppFileStream(env, args) {
-  const token = requireToken(env);
-  const headers = {
-    authorization: `Bearer ${token}`,
-    "content-type": args.contentType || "application/octet-stream",
-    "x-app-file-key": args.key,
-    "x-app-file-content-type": args.contentType || "application/octet-stream"
-  };
-  if (args.filename) headers["x-app-file-name"] = encodeURIComponent(args.filename);
-  if (typeof args.contentLength === "number" && Number.isFinite(args.contentLength)) {
-    headers["x-app-file-length"] = String(args.contentLength);
-  }
-  const resendable = !(args.body instanceof ReadableStream);
-  const attempts = resendable ? STREAM_PUT_MAX_ATTEMPTS : 1;
-  let lastErr;
-  for (let attempt = 1; attempt <= attempts; attempt++) {
-    const res = await fetch(`${platformBase(env)}/internal/wfp/file/put-stream`, {
-      method: "POST",
-      headers,
-      body: args.body,
-      // Required by the Workers runtime when sending a streaming request body.
-      ...args.body instanceof ReadableStream ? { duplex: "half" } : {}
-    });
-    try {
-      return await parseResult(res, "put-stream");
-    } catch (err) {
-      lastErr = err;
-      if (!resendable || attempt === attempts || !(err instanceof AppFilesError) || !isTransientPutStreamFailure(err.status, err.message)) {
-        throw err;
-      }
-      await sleep2(STREAM_PUT_BASE_DELAY_MS * 2 ** (attempt - 1));
-    }
-  }
-  throw lastErr;
-}
-function appFileUrl(env, args) {
-  return call(env, "url", { key: args.key, expiresIn: args.expiresIn });
-}
-function getAppFile(env, key) {
-  return call(env, "get", { key });
-}
-function listAppFiles(env, prefix) {
-  return call(env, "list", { prefix });
-}
-function deleteAppFile(env, key) {
-  return call(env, "delete", { key });
-}
-
 // src/write-protection/types.ts
 var APPROVAL_GRANTED_KEY = "_approval_granted";
 
@@ -1750,82 +2041,6 @@ async function connectDisconnect(env, req) {
   if (!bridge) throw new Error("connectDisconnect: SPRIGR_PLATFORM_BASE / SPRIGR_INSTALL_TOKEN are not bound");
   return await installTokenPost(bridge, "/internal/wfp/connect/disconnect", req, { label: "connect disconnect" });
 }
-
-// src/stored-file-keys.ts
-var APP_FILES_ROOT = "_apps/";
-var APP_OWNER_SEGMENT = "~u";
-function isSegment(s) {
-  return typeof s === "string" && s.length > 0 && !s.includes("/");
-}
-function trimLeadingSlashes(key) {
-  return key.replace(/^\/+/, "");
-}
-function parseAbsolute(key) {
-  if (!key.startsWith(APP_FILES_ROOT)) return null;
-  const parts = key.slice(APP_FILES_ROOT.length).split("/");
-  const installId = parts[0];
-  if (!isSegment(installId)) return null;
-  let i = 1;
-  let ownerHash = null;
-  if (parts[1] === APP_OWNER_SEGMENT) {
-    if (!isSegment(parts[2])) return null;
-    ownerHash = parts[2];
-    i = 3;
-  }
-  const rest = parts.slice(i).join("/");
-  if (!rest || rest.split("/").some((seg) => seg === "")) return null;
-  return { installId, ownerHash, rest };
-}
-function urlPathKey(url) {
-  try {
-    return trimLeadingSlashes(decodeURIComponent(new URL(url).pathname));
-  } catch {
-    return null;
-  }
-}
-function agentFileKeyFromUrl(downloadUrl, appKey) {
-  const rel = trimLeadingSlashes(appKey);
-  if (!rel) return null;
-  const path = urlPathKey(downloadUrl);
-  if (!path) return null;
-  const parsed = parseAbsolute(path);
-  if (!parsed || parsed.rest !== rel) return null;
-  return path;
-}
-function readableStoredKey(appKey, downloadUrl) {
-  return agentFileKeyFromUrl(downloadUrl, appKey) ?? appKey;
-}
-function appKeyFromCallerKey(key, ownInstallId) {
-  let candidate = key.trim();
-  let wasAbsolute = false;
-  if (/^https?:\/\//i.test(candidate)) {
-    const path = urlPathKey(candidate);
-    if (!path || !path.startsWith(APP_FILES_ROOT)) return { ok: false, reason: "malformed" };
-    candidate = path;
-  }
-  candidate = trimLeadingSlashes(candidate);
-  if (candidate.startsWith(APP_FILES_ROOT)) {
-    const parsed = parseAbsolute(candidate);
-    if (!parsed) return { ok: false, reason: "malformed" };
-    if (ownInstallId && parsed.installId !== ownInstallId) {
-      return { ok: false, reason: "other_install", installId: parsed.installId };
-    }
-    return { ok: true, appKey: parsed.rest, wasAbsolute: true };
-  }
-  const parts = candidate.split("/");
-  if (parts[0] === APP_OWNER_SEGMENT) {
-    const rest = parts.slice(2).join("/");
-    if (!isSegment(parts[1]) || !rest) return { ok: false, reason: "malformed" };
-    return { ok: true, appKey: rest, wasAbsolute: true };
-  }
-  return { ok: true, appKey: candidate, wasAbsolute };
-}
-function callerKeyRefusal(key, r) {
-  if (r.reason === "other_install") {
-    return `"${key}" is a stored file of a different app install (${r.installId}), not this one. Pass a file_key this app returned to you.`;
-  }
-  return `"${key}" is not a stored file key: it has no file path after the app storage prefix.`;
-}
 export {
   ACTOR_RETIRED_HOOK_TOOL,
   ACTOR_RETIRE_REASONS,
@@ -1835,15 +2050,19 @@ export {
   APP_OWNER_SEGMENT,
   DATA_PARTIAL_UPDATE_PATH,
   DEFAULT_EMIT_TIMEOUT_MS,
+  DEFAULT_FILE_READ_TIMEOUT_MS,
   DEFAULT_LOG_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
   DEFAULT_MONEY_FIELDS,
   DEFAULT_WRITE_PREFIXES,
+  FILE_REF_SOURCES_HELP,
+  FileRefError,
   INBOX_SEND_CONTRACT_V1,
   InboxSendRefusal,
   InvalidUndoEnvelopeError,
   NotConnectedError,
   SPRIGR_DATA_MAX_OBJECTS_PER_CALL,
+  SPRIGR_FILE_HOSTS,
   SPRIGR_LOG_LEVELS,
   SPRIGR_LOG_LIMITS,
   SprigrDataValidationError,
@@ -1854,6 +2073,7 @@ export {
   VIEWER_PLATFORM_USER_ID_HEADER,
   VIEWER_ROLE_HEADER,
   VIEWER_USER_ID_HEADER,
+  WORKSPACE_FILE_HOW_TO,
   actorKey,
   actorRetiredHook,
   actorTool,
@@ -1903,6 +2123,7 @@ export {
   logToPlatform,
   manifestIsFresh,
   offerUndo,
+  openFileRef,
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
@@ -1911,10 +2132,12 @@ export {
   putAppFile,
   putAppFileStream,
   randomHex,
+  readFileRef,
   readableStoredKey,
   recreatedWarning,
   refuseWithoutForce,
   requireApproval,
+  resolveFileRef,
   resolveInstallBridge,
   resolveOAuthBouncerBase,
   resolveOAuthBouncerCallbackUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",