@sprigr/apps-app-sdk 0.19.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).
 
@@ -99,8 +100,9 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.
 - `buildConfirmationPolicy({ irreversible, always, rules })` declares a dispatcher's policy beside its action registry; `checkConfirmationPolicy({ policy, registry, ungated, requiredInput })` returns every silent failure (dead rule, `(unset)` placeholder, money threshold, unclassified write) for a one-line test.
+- **Ask once when T1 and T2 both gate an action.** Pass `approval: { covered, conditional }` to `buildConfirmationPolicy` (or `deriveConfirmationPolicy`) and to `checkConfirmationPolicy`: `covered` is your approval spec keys (`Object.keys(APPROVAL_SPECS)`), `conditional` the covered actions your app sends through the gate only under a condition of its own (simpro's `GATE_ONLY_WHEN`), `[]` when there are none. Both are required. Each covered, unconditional, gated action gets `attended: 'approval_card'`, and the platform then skips the confirmation on a turn with a person on it, so the card is the only prompt; unattended runs still confirm. The builder never marks a conditional action, and the check fails a key that no spec covers or that sits on a conditional action (no prompt at all on a call that skips the card), a covered unconditional action without one (it asks twice), and a `conditional` entry with no spec. For flat `requireApproval` tools, run `attendedFindings(tool, rule, { covered, conditional })` over each tool-level rule. Needs a platform with sprigr-team decision 0167; an older one ignores the key and keeps asking twice.
 - `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop. `pin` may hand `restore` a different type from the env (a per-actor token state), may throw (`connection_unavailable`) or return null to refuse (`connection_mismatch`); a restore that throws is `restore_failed` and the copy is kept; a successful restore may return `newId`, `notRestored`, `extra` (spread into the payload) and `note` (appended after the fidelity sentence).
 - `safeCapture(scope, name, id, read)` and `offerUndo({ journal, entity, id, before, connection, fidelity, resource, describe, warning })`: the capture-then-offer halves for a write that is not behind an approval card (a dispatcher `update_*` action). `requireApproval` uses the same two on its granted pass.
-- `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`.
+- `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`. It also refuses an `attended` key with any value other than `'approval_card'`, or on a rule that gates nothing (never baselined).
 
 **Never offer `_undo` for money or messages.** Refunds, captures, cancellations, sent mail: the approval gate is the only control there.

package/bin/check-write-protection.mjs

@@ -93,6 +93,33 @@ export function scanManifest(manifest) {
   return out;
 }
 
+/**
+ * Malformed `attended` keys (sprigr-team decision 0167), as `tool` or
+ * `tool:action` findings. Not baselined: no app may ship one.
+ *
+ * A manifest cannot say whether an approval card really covers the action,
+ * because the specs are code. That half is `checkConfirmationPolicy` /
+ * `attendedFindings` with `approvalCovered`, in the app's own test. What a
+ * manifest CAN show is a key the platform would ignore (any value but
+ * 'approval_card', so the person is quietly asked twice) and a key on a rule
+ * that gates nothing (so there is no confirmation for it to step aside from,
+ * which means it was written by hand).
+ */
+export function scanAttended(manifest) {
+  const out = [];
+  const check = (label, rule) => {
+    if (!rule || typeof rule !== 'object' || !('attended' in rule)) return;
+    if (rule.attended !== 'approval_card') out.push(`${label}: attended must be 'approval_card', got ${JSON.stringify(rule.attended)}`);
+    else if (!isGatedRule(rule)) out.push(`${label}: attended on a rule with no always or when, so it gates nothing`);
+  };
+  for (const tool of manifest.tools || []) {
+    if (!tool || !tool.confirmation || typeof tool.confirmation !== 'object') continue;
+    check(tool.name, tool.confirmation);
+    for (const [a, rule] of Object.entries(tool.confirmation.actions || {})) check(`${tool.name}:${a}`, rule);
+  }
+  return out;
+}
+
 /** Apply the app's allowlist. Returns { violations, stale, unreasoned }. */
 export function applyAllowlist(violations, allowlist) {
   const allow = (allowlist && allowlist.allow) || {};
@@ -151,6 +178,7 @@ export function run(argv, cwd = process.cwd()) {
     const allowlist = existsSync(allowPath) ? readJson(allowPath) : null;
     const raw = scanManifest(manifest);
     const { violations, stale, unreasoned } = applyAllowlist(raw, allowlist);
+    for (const f of scanAttended(manifest)) failures.push(`${slug}: ${f}`);
     for (const k of unreasoned) failures.push(`${slug}: write-protection.json allow entry "${k}" has no reason`);
     for (const k of stale) failures.push(`${slug}: write-protection.json allow entry "${k}" is stale (no longer destructive-and-ungated); remove it`);
 

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.
  *
@@ -1453,6 +1585,18 @@ interface ConfirmRule {
     describe?: string;
     /** Appends "which cannot be undone" so the model cannot undersell it. */
     irreversible?: boolean;
+    /**
+     * `'approval_card'`: this action's human-approval card (an approval spec)
+     * covers it whenever a person is on the turn, so the platform skips the
+     * confirmation there and the person is asked once, by the card. Unattended
+     * runs still confirm. Never hand-write it: pass `approval: { covered,
+     * conditional }` to `buildConfirmationPolicy` / `deriveConfirmationPolicy`
+     * so it follows the specs, and to `checkConfirmationPolicy` so a stale or
+     * conditionally gated key fails the test.
+     * Needs a platform with sprigr-team decision 0167; an older one ignores it
+     * and keeps asking twice.
+     */
+    attended?: 'approval_card';
 }
 interface ConfirmCondition {
     count: string;
@@ -2021,6 +2165,34 @@ interface PolicySource {
     always?: Record<string, string>;
     /** Full rules, for thresholds and anything the two maps above cannot express. */
     rules?: Record<string, ConfirmRule>;
+    /**
+     * Which actions an approval card covers; see {@link ApprovalCoverage}. Each
+     * covered action that also has a rule here, and is not `conditional`, gets
+     * `attended: 'approval_card'`, so the person is asked once on an attended
+     * turn (the card) instead of twice.
+     */
+    approval?: ApprovalCoverage;
+}
+/**
+ * Which actions an approval card covers, for deriving and checking
+ * `attended: 'approval_card'` (sprigr-team decision 0167).
+ *
+ * Both fields are required on purpose. The SDK can see an app's approval
+ * specs but not any condition the app wraps around the gate (simpro sends its
+ * deletes to the gate only with `force: true`), and an action marked attended
+ * whose call skips the card would skip the confirmation too: no prompt at all.
+ * So every app states its conditional actions, `[]` when it has none, and the
+ * builder and the check refuse to mark them.
+ */
+interface ApprovalCoverage {
+    /** Every action with an approval spec: the keys of the specs object you hand to the gate. */
+    covered: Iterable<string>;
+    /**
+     * Covered actions the app sends through the gate only under a condition of
+     * its own (simpro's `GATE_ONLY_WHEN`). Never marked attended; they keep the
+     * confirmation. Pass `[]` when every covered action always reaches the gate.
+     */
+    conditional: Iterable<string>;
 }
 /** Build a sorted `{ actions }` policy. An action named in two groups throws. */
 declare function buildConfirmationPolicy(src: PolicySource): ConfirmationPolicy;
@@ -2053,7 +2225,23 @@ interface PolicyCheckInput {
      */
     nestedUnderInput?: boolean;
     moneyFields?: readonly string[];
+    /**
+     * Which actions an approval card covers. With it, the check fails a rule
+     * carrying `attended: 'approval_card'` on an action no spec covers or that
+     * the app gates conditionally (either way the key removes the person's only
+     * prompt), a covered, unconditional, gated action that lacks the key (it asks
+     * twice), and a `conditional` entry with no spec. Without it, any `attended`
+     * key is itself a finding, because nothing can vouch for it.
+     */
+    approval?: ApprovalCoverage;
 }
+/**
+ * Findings for one rule's `attended` key against the approval coverage.
+ * Exported for apps whose gated tools are flat (`requireApproval`) rather than
+ * one dispatcher: run it over each tool-level rule with the tool names the
+ * specs cover and the ones gated conditionally.
+ */
+declare function attendedFindings(name: string, rule: ConfirmRule, coverage: ApprovalCoverage | null): string[];
 /**
  * Every way a policy can be wrong without erroring, as a list of findings.
  * An app's test is `expect(checkConfirmationPolicy(...)).toEqual([])`.
@@ -2233,6 +2421,8 @@ interface DerivePolicyOptions {
     exempt?: readonly string[];
     /** Explicit rules that win over the verb table (e.g. a hand-written describe). */
     overrides?: Readonly<Record<string, ConfirmRule>>;
+    /** Which actions an approval card covers; see `ApprovalCoverage`. */
+    approval?: ApprovalCoverage;
 }
 interface DerivedPolicy {
     policy: ConfirmationPolicy & {
@@ -3149,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 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, 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";
 
@@ -1367,6 +1658,13 @@ async function runUndoApply(args, opts) {
 }
 
 // src/write-protection/confirmation-policy.ts
+function coverageSets(c) {
+  if (!c) return null;
+  if (c.covered == null || c.conditional == null) {
+    throw new Error("approval coverage needs both `covered` and `conditional` (pass [] when no action is gated conditionally)");
+  }
+  return { covered: new Set(c.covered), conditional: new Set(c.conditional) };
+}
 function buildConfirmationPolicy(src) {
   const actions = {};
   const put = (name, rule, group) => {
@@ -1376,6 +1674,10 @@ function buildConfirmationPolicy(src) {
   for (const [name, describe] of Object.entries(src.irreversible ?? {})) put(name, { always: true, describe, irreversible: true }, "irreversible");
   for (const [name, describe] of Object.entries(src.always ?? {})) put(name, { always: true, describe }, "always");
   for (const [name, rule] of Object.entries(src.rules ?? {})) put(name, rule, "rules");
+  const cov = coverageSets(src.approval);
+  for (const name of cov?.covered ?? []) {
+    if (actions[name] && !cov?.conditional.has(name)) actions[name] = { ...actions[name], attended: "approval_card" };
+  }
   return { actions: Object.fromEntries(Object.entries(actions).sort(([a], [b]) => a.localeCompare(b))) };
 }
 var DEFAULT_WRITE_PREFIXES = [
@@ -1479,6 +1781,22 @@ var PLACEHOLDER = /\{([a-zA-Z0-9_.]+)\}/g;
 function conditions(rule) {
   return !rule.when ? [] : Array.isArray(rule.when) ? rule.when : [rule.when];
 }
+function attendedFindings(name, rule, coverage) {
+  const cov = coverageSets(coverage ?? void 0);
+  const out = [];
+  const attended = rule.attended;
+  const gated = rule.always === true || conditions(rule).length > 0;
+  if (attended !== void 0 && attended !== "approval_card") {
+    out.push(`${name}: attended must be 'approval_card' (got ${JSON.stringify(attended)}); the platform ignores anything else`);
+  } else if (attended === "approval_card") {
+    if (!cov) out.push(`${name}: attended: 'approval_card' cannot be checked; pass approval: { covered, conditional }`);
+    else if (!cov.covered.has(name)) out.push(`${name}: attended: 'approval_card' but no approval spec covers it, so it removes the only prompt`);
+    else if (cov.conditional.has(name)) out.push(`${name}: attended: 'approval_card' on a conditionally gated action, so a call that skips the card gets no prompt at all`);
+  } else if (cov?.covered.has(name) && !cov.conditional.has(name) && gated) {
+    out.push(`${name}: an approval spec covers it but the rule lacks attended: 'approval_card', so it asks twice`);
+  }
+  return out;
+}
 function checkConfirmationPolicy(input) {
   const registry = new Set(input.registry);
   const ungated = input.ungated ?? [];
@@ -1486,8 +1804,13 @@ function checkConfirmationPolicy(input) {
   const nested = input.nestedUnderInput ?? true;
   const money = new Set(input.moneyFields ?? DEFAULT_MONEY_FIELDS);
   const actions = input.policy.actions ?? {};
+  const cov = coverageSets(input.approval);
   const out = [];
+  for (const name of cov?.conditional ?? []) {
+    if (!cov?.covered.has(name)) out.push(`approval.conditional: "${name}" has no approval spec (not in covered)`);
+  }
   for (const [name, rule] of Object.entries(actions)) {
+    out.push(...attendedFindings(name, rule, input.approval ?? null));
     if (!registry.has(name)) out.push(`dead rule: "${name}" is not in the registry, so it gates nothing`);
     if (!rule.always && conditions(rule).length === 0) out.push(`${name}: rule says nothing (no always, no when)`);
     if (!rule.describe || !rule.describe.trim()) out.push(`${name}: describe missing`);
@@ -1596,7 +1919,7 @@ function deriveConfirmationPolicy(registry, opts) {
     }
     if (!hit) unmatched.push(name);
   }
-  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides });
+  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides, approval: opts.approval });
   return { policy, ungated, unmatched };
 }
 function commonDestructiveVerbs(subject) {
@@ -1718,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,
@@ -1803,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,
@@ -1822,6 +2073,7 @@ export {
   VIEWER_PLATFORM_USER_ID_HEADER,
   VIEWER_ROLE_HEADER,
   VIEWER_USER_ID_HEADER,
+  WORKSPACE_FILE_HOW_TO,
   actorKey,
   actorRetiredHook,
   actorTool,
@@ -1833,6 +2085,7 @@ export {
   approvalPreview,
   approvalRecipients,
   archiveOfferRefusal,
+  attendedFindings,
   base64ToBytes,
   buildConfirmationPolicy,
   buildMarketplaceWebhookUrl,
@@ -1870,6 +2123,7 @@ export {
   logToPlatform,
   manifestIsFresh,
   offerUndo,
+  openFileRef,
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
@@ -1878,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.19.0",
+  "version": "0.21.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",