@north-light/api 0.3.580 → 0.3.587

package/dist/core/spaces/stop.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import { readJobSupervisorState, signalBashJob, unfinishedBashJobIds } from '../bash-jobs.js';
+import { contextDir } from '../canvas/node-agent-paths.js';
+import { getNode } from '../canvas/index.js';
+import { withCanvasWrite, openDb } from '../canvas/db.js';
+import { finishJob, ownerRunsRemotely, runningJobs, startJob } from '../graph/jobs.js';
+import { getById, nodeObject } from '../graph/objects.js';
+import { readLiveSession } from '../canvas/sessions.js';
+import { conversationStore } from '../conversation-store/index.js';
+import { requestBrokerTeardown } from '../runtime/host.js';
+import { holdRecovery, waitForRecoveryHold } from '../runtime/recovery-hold.js';
+/** End the job object of a backgrounded command as killed. A command that was never backgrounded
+ *  has no job object; that answers false. Daemon-only: opens canvas.db. */
+export async function killBashJobObject(jobId, killedBy, reason) {
+    return await withCanvasWrite(async (db) => {
+        const job = await getById(db, jobId);
+        if (job === null || job.type !== 'job')
+            return false;
+        await finishJob(db, job, { killedBy: await killedBy(db), ...(reason === undefined ? {} : { reason }) });
+        return true;
+    });
+}
+/** Record a backgrounded command as its node's job object (id = job id); an existing job
+ *  object is returned as is. The one path for both the broker's record call and the
+ *  daemon adopting a job the broker backgrounded while exiting. Daemon-only. */
+export async function recordBashJobObject(nodeId, jobId, spec) {
+    return await withCanvasWrite(async (db) => {
+        const existing = await getById(db, jobId);
+        if (existing !== null) {
+            if (existing.type !== 'job')
+                throw new Error(`${jobId} names a ${existing.type}`);
+            return existing;
+        }
+        return await startJob(db, await nodeObject(db, nodeId), { id: jobId, ...spec });
+    });
+}
+/** This process's stops in flight, so a second caller in the process gets the first's result (and its `after` runs once).
+ *  Across processes the single-flight is the node's recovery hold row. */
+const stopping = new Map();
+/** Another process holds the node's stop. Waits for its hold to clear. A holder that finished released the hold, so this
+ *  only confirms the broker is gone through this process's own teardown. A holder that died or stalled past the hold's
+ *  expiry never ran its `after`, so this stop takes the node over and runs the whole stop with its own `after`, once: the
+ *  claim is one row update, so of several waiters one takes over and the rest wait for its release. */
+async function stopHeldElsewhere(nodeId, reason, options) {
+    if (await waitForRecoveryHold(nodeId) === 'lapsed')
+        return await stopNodeSandboxes(nodeId, reason, options);
+    return await requestBrokerTeardown(nodeId, { excludePid: options.excludePid });
+}
+/** Stop the broker first so it cannot start another job during the job scan. */
+export async function stopNodeSandboxes(nodeId, reason, options = {}) {
+    const existing = stopping.get(nodeId);
+    if (existing)
+        return existing;
+    const node = await getNode(nodeId);
+    if (!node)
+        return Promise.resolve({ confirmed: false, error: new Error(`missing node ${nodeId}`) });
+    const session = (await readLiveSession(nodeId))?.sessionId;
+    const latestTurn = async () => await (await openDb()).prepare(`SELECT type, body_json FROM run_events WHERE node_id = ?
+    AND type IN ('node.turn.started', 'node.turn.completed') ORDER BY sequence_number DESC LIMIT 1`)
+        .get(nodeId);
+    const pendingTurn = node.run_id !== null && node.pi_pid !== null && (await latestTurn())?.type === 'node.turn.started';
+    // Held on the row before the broker is signaled, so its exit is not recovered before `after` decides the row.
+    const hold = await holdRecovery(nodeId);
+    if (hold === null)
+        return await stopHeldElsewhere(nodeId, reason, options);
+    const teardown = requestBrokerTeardown(nodeId, { excludePid: options.excludePid, ...(options.startAfter ? { startAfter: options.startAfter } : {}) });
+    const completion = (async () => {
+        const result = await teardown;
+        if (!result.confirmed)
+            return result;
+        try {
+            // A stop that lost its hold (stalled past expiry; another stop took the node) does nothing more: the taker runs the whole stop.
+            const lost = () => ({ confirmed: false, error: new Error(`the recovery hold on ${nodeId} lapsed during its stop`) });
+            if (!await hold.renew())
+                return lost();
+            // Every unfinished job: the supervisor's own files name its process even before the row has a mirrored identity,
+            // and a foreground command or a job whose record never landed has no row at all.
+            const rows = new Map((await runningJobs(await openDb(), nodeId)).map((job) => [job.jobId, job]));
+            if (await ownerRunsRemotely(await openDb(), nodeId)) {
+                // A sandbox's jobs died with its broker's sandbox: there is no process or supervisor file here to signal.
+                if (!options.deleting)
+                    for (const jobId of rows.keys())
+                        await killBashJobObject(jobId, async () => null, reason);
+            }
+            else {
+                const dir = await contextDir(nodeId);
+                for (const jobId of new Set([...rows.keys(), ...unfinishedBashJobIds(dir)])) {
+                    const state = readJobSupervisorState(dir, jobId);
+                    const pgid = state.pgid ?? rows.get(jobId)?.pgid ?? null;
+                    const identity = state.pgidIdentity ?? rows.get(jobId)?.pgidIdentity ?? null;
+                    if (pgid === null || identity === null)
+                        throw new Error(`bash job ${jobId} could not be stopped`);
+                    await signalBashJob(pgid, identity, nodeId);
+                    if (!options.deleting && rows.has(jobId))
+                        await killBashJobObject(jobId, async () => null, reason);
+                }
+            }
+            if (!await hold.renew())
+                return lost();
+            if (pendingTurn && session && !options.deleting) {
+                const lastTurn = await latestTurn();
+                // A turn a completed abort already closed needs nothing more: an entry
+                // written after it would surface outside any turn.
+                if (lastTurn?.type !== 'node.turn.started') {
+                    if (!await hold.renew())
+                        return lost();
+                    await options.after?.();
+                    return result;
+                }
+                const store = conversationStore();
+                const { entries } = await store.read(session);
+                const last = entries.at(-1);
+                const timestamp = new Date().toISOString();
+                // A revoked permission is an error the runtime ended the turn with. A
+                // cancel or close is the caller's own stop: the turn ends aborted.
+                const failed = reason === 'permission_revoked';
+                const ending = { type: 'message', id: randomUUID(), parentId: last?.id ?? null, timestamp,
+                    message: { role: 'assistant', content: [], api: 'openai-completions', provider: 'crouter', model: '',
+                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                        stopReason: failed ? 'error' : 'aborted', errorMessage: reason, timestamp: Date.now() } };
+                await store.append(session, [ending, { type: 'custom', id: randomUUID(), parentId: ending.id, timestamp, customType: 'crtr-turn-end',
+                        data: failed ? { stop_reason: 'error', error: { code: 'model_error', message: reason } } : { stop_reason: 'aborted' } }]);
+            }
+            if (!await hold.renew())
+                return lost();
+            await options.after?.();
+            return result;
+        }
+        catch (error) {
+            return { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+        }
+    })();
+    stopping.set(nodeId, completion);
+    void completion.finally(() => { void hold.release().catch(() => undefined); if (stopping.get(nodeId) === completion)
+        stopping.delete(nodeId); });
+    return completion;
+}

package/dist/core/spaces/users.d.ts

@@ -0,0 +1,20 @@
+export interface AppUser {
+    app: string;
+    uid: number;
+    created: string;
+    status: 'active' | 'removed';
+}
+/** The launcher is absent on macOS; there is no app uid on that host. */
+export declare function uidForApp(app: string): Promise<number>;
+/** An app has at most one active row. A removed app that reconnects gets a new
+ *  row above every uid ever allocated, so a uid is never reused. The lock makes the
+ *  read-then-insert safe when two first starts for one app, or two apps, race. */
+export declare function allocateAppUser(app: string): Promise<AppUser>;
+export declare function activeAppUsers(): Promise<Array<{
+    app: string;
+    uid: number;
+}>>;
+/** The app's OS-user row not yet marked removed, if any. */
+export declare function activeAppUser(app: string): Promise<AppUser | null>;
+/** The removal cascade's last write (runtime spec, "On removal"). */
+export declare function markAppUserRemoved(uid: number): Promise<void>;

package/dist/core/spaces/users.js

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs';
+import { withCanvasWrite, openDb } from '../canvas/db.js';
+import { APP_UID_MAX, APP_UID_MIN, LAUNCHER_SOCKET } from '../../launcher/spec.js';
+/** The launcher is absent on macOS; there is no app uid on that host. */
+export async function uidForApp(app) {
+    if (process.platform !== 'linux' || !existsSync(LAUNCHER_SOCKET))
+        return process.getuid?.() ?? 0;
+    return (await allocateAppUser(app)).uid;
+}
+/** Fixed key for the transaction-scoped lock that serializes app uid allocation across processes. */
+const APP_USER_ALLOCATION_LOCK_KEY = 7_340_002;
+/** An app has at most one active row. A removed app that reconnects gets a new
+ *  row above every uid ever allocated, so a uid is never reused. The lock makes the
+ *  read-then-insert safe when two first starts for one app, or two apps, race. */
+export async function allocateAppUser(app) {
+    if (process.platform !== 'linux')
+        throw new Error('app OS users exist only on Linux');
+    return await withCanvasWrite(async (db) => {
+        await db.prepare(`SELECT pg_advisory_xact_lock(${APP_USER_ALLOCATION_LOCK_KEY})`).get();
+        const existing = await db.prepare("SELECT app, uid, created, status FROM app_users WHERE app = ? AND status = 'active'").get(app);
+        if (existing)
+            return existing;
+        const max = (await db.prepare('SELECT MAX(uid) AS uid FROM app_users').get()).uid;
+        const uid = Math.max(APP_UID_MIN, (max ?? APP_UID_MIN - 1) + 1);
+        if (uid > APP_UID_MAX)
+            throw new Error('app OS user range exhausted');
+        const created = new Date().toISOString();
+        await db.prepare('INSERT INTO app_users (app, uid, created, status) VALUES (?, ?, ?, ?)').run(app, uid, created, 'active');
+        return { app, uid, created, status: 'active' };
+    });
+}
+export async function activeAppUsers() {
+    const rows = await (await openDb()).prepare("SELECT app, uid FROM app_users WHERE status = 'active'").all();
+    return rows.map(row => ({ app: row.app.startsWith('app:') ? row.app.slice(4) : row.app, uid: row.uid }));
+}
+/** The app's OS-user row not yet marked removed, if any. */
+export async function activeAppUser(app) {
+    return await (await openDb()).prepare("SELECT app, uid, created, status FROM app_users WHERE app = ? AND status = 'active'").get(app) ?? null;
+}
+/** The removal cascade's last write (runtime spec, "On removal"). */
+export async function markAppUserRemoved(uid) {
+    await (await openDb()).prepare("UPDATE app_users SET status = 'removed', removed_at = ? WHERE uid = ? AND status = 'active'").run(new Date().toISOString(), uid);
+}

package/dist/core/sqlite-statements.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync, StatementSync } from 'node:sqlite';
+export declare function prepared(db: DatabaseSync, sql: string): StatementSync;
+/** Explicitly release compiled statements before closing or migrating a connection. */
+export declare function forgetPrepared(db: DatabaseSync): void;

package/dist/core/sqlite-statements.js

@@ -0,0 +1,17 @@
+/** Statements belong to a connection, not a database path. Cache only fixed SQL:
+ * generated IN lists and schema-dependent SQL remain uncached at their call sites.
+ */
+const statements = new WeakMap();
+export function prepared(db, sql) {
+    let byDb = statements.get(db);
+    if (!byDb)
+        statements.set(db, byDb = new Map());
+    let statement = byDb.get(sql);
+    if (!statement)
+        byDb.set(sql, statement = db.prepare(sql));
+    return statement;
+}
+/** Explicitly release compiled statements before closing or migrating a connection. */
+export function forgetPrepared(db) {
+    statements.delete(db);
+}

package/dist/core/statements.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Placeholder translation for the Postgres engine. Call sites keep SQLite's `?` / `?N` spelling; this turns it into
+ * `$n`. Slot semantics follow SQLite: `?N` is always slot N (so one value can be bound to several `?1`), and a bare
+ * `?` takes the slot after the highest one used so far. `?` inside single-quoted literals, double-quoted identifiers,
+ * dollar-quoted bodies and comments is left alone. Identifiers are never rewritten.
+ */
+export interface TranslatedStatement {
+    /** SQL with `$n` placeholders. */
+    text: string;
+    /** Number of parameter slots (the highest slot used). */
+    slots: number;
+    /** Prepared-statement name on the connection: a hash of the original SQL. */
+    name: string;
+}
+export declare function translatePlaceholders(sql: string): TranslatedStatement;
+/** Translation without caching, for generated SQL that is run once. */
+export declare function translateOnce(sql: string): Omit<TranslatedStatement, 'name'>;

package/dist/core/statements.js

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+const cache = new Map();
+export function translatePlaceholders(sql) {
+    const hit = cache.get(sql);
+    if (hit !== undefined)
+        return hit;
+    const translated = translate(sql);
+    cache.set(sql, translated);
+    return translated;
+}
+/** Translation without caching, for generated SQL that is run once. */
+export function translateOnce(sql) {
+    const { text, slots } = translate(sql);
+    return { text, slots };
+}
+function translate(sql) {
+    let out = '';
+    let highest = 0;
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const c = sql[i];
+        if (c === "'" || c === '"') {
+            let j = i + 1;
+            for (; j < n; j++) {
+                if (sql[j] === c) {
+                    if (sql[j + 1] === c) {
+                        j++;
+                        continue;
+                    }
+                    break;
+                }
+            }
+            out += sql.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (c === '-' && sql[i + 1] === '-') {
+            let j = sql.indexOf('\n', i);
+            if (j === -1)
+                j = n;
+            out += sql.slice(i, j);
+            i = j;
+        }
+        else if (c === '/' && sql[i + 1] === '*') {
+            let j = sql.indexOf('*/', i + 2);
+            j = j === -1 ? n : j + 2;
+            out += sql.slice(i, j);
+            i = j;
+        }
+        else if (c === '$' && /[A-Za-z_$]/.test(sql[i + 1] ?? '')) {
+            // $tag$ ... $tag$ (or $$ ... $$)
+            const tag = /^\$[A-Za-z_]*\$/.exec(sql.slice(i))?.[0];
+            if (tag === undefined) {
+                out += c;
+                i++;
+                continue;
+            }
+            let j = sql.indexOf(tag, i + tag.length);
+            j = j === -1 ? n : j + tag.length;
+            out += sql.slice(i, j);
+            i = j;
+        }
+        else if (c === '?') {
+            let j = i + 1;
+            while (j < n && sql[j] >= '0' && sql[j] <= '9')
+                j++;
+            const slot = j > i + 1 ? Number(sql.slice(i + 1, j)) : highest + 1;
+            if (slot < 1)
+                throw new Error(`invalid placeholder ?${slot} in: ${sql}`);
+            if (slot > highest)
+                highest = slot;
+            out += `$${slot}`;
+            i = j;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return { text: out, slots: highest, name: `s${createHash('sha1').update(sql).digest('hex')}` };
+}

package/dist/core/storage/attachments.d.ts

@@ -0,0 +1,36 @@
+import { type BlobStore } from '../blobs/index.js';
+import { type StorageClient, type StorageConfig } from './client.js';
+import type { CanvasDb } from '../canvas/db.js';
+/** The fetch step of one `run.start` or `run.message` is bounded to 110 s in
+ *  total (the hosting router waits 120 s for its headers). */
+export declare const ATTACHMENT_FETCH_BUDGET_MS = 110000;
+/** One fetched upload; `url` is the storage URL the text named (for refusals). `path` is where the node's broker puts
+ *  the file; `blob_key` (`attachments/<run root node>/<sha256>`) is where its bytes are in the blob store. */
+export interface AttachmentUse {
+    upload_id: string;
+    path: string;
+    url: string;
+    blob_key: string;
+}
+export interface ResolvedAttachments {
+    /** The text with each storage URL replaced by its runtime path. */
+    text: string;
+    uses: AttachmentUse[];
+}
+export interface ResolveOptions {
+    config?: () => StorageConfig | null;
+    client?: () => StorageClient;
+    budgetMs?: number;
+    blobs?: () => Promise<BlobStore>;
+    /** Paths another call of the same request has already chosen, which no file of this call may take. */
+    taken?: readonly string[];
+}
+/** Re-check, inside the accepting write, that every used upload is still this
+ *  grantee's and not pending delete (the due-work tick or an app removal may
+ *  have released it while its bytes were fetched). */
+export declare function assertUploadsUsable(grantee: string, uses: readonly AttachmentUse[], db: CanvasDb): Promise<void>;
+/** Fetch every upload a storage URL in `text` names into the blob store at `attachments/<rootId>/<sha256>` and replace
+ *  exactly each URL's span with the path the node's broker downloads that file to (`<app space>/nodes/<rootId>/attachments/<name>`).
+ *  The control plane writes no file there. Without configured storage the text passes through unchanged. A failure leaves
+ *  at most content-keyed blobs, which are harmless and are deleted with the node (D100). */
+export declare function resolveStorageUrls(grantee: string, rootId: string, text: string, options?: ResolveOptions): Promise<ResolvedAttachments>;

package/dist/core/storage/attachments.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { extname, join } from 'node:path';
+import { Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { blobStore } from '../blobs/index.js';
+import { appSpace } from '../layout.js';
+import { RunError } from '../runs/operations.js';
+import { storageClient, storageConfig, StorageRefused } from './client.js';
+import { getUpload, runUsesPath } from './tables.js';
+/** The fetch step of one `run.start` or `run.message` is bounded to 110 s in
+ *  total (the hosting router waits 120 s for its headers). */
+export const ATTACHMENT_FETCH_BUDGET_MS = 110_000;
+const refused = (url, message) => new RunError(400, 'invalid_request', message, undefined, { url });
+const unavailable = (message) => new RunError(503, 'storage_unavailable', message, undefined, undefined, undefined, true);
+/** The URL as a reader sees it, for `details.url`: up to whitespace or a
+ *  delimiter, without sentence punctuation at its end. */
+function shownUrl(text, at) {
+    return /^[^\s<>"'`)\]]*/.exec(text.slice(at))[0].replace(/[.,;:!?]+$/, '');
+}
+/** Match every `<base_url>/<runtime id>/<upload id>/<encoded name>` in `text`
+ *  against the uploads table. Any occurrence of `<base_url>/` that is not this
+ *  runtime's usable upload of `grantee` refuses the call. */
+async function matchStorageUrls(text, base, runtime, grantee, db) {
+    const prefix = `${base}/`;
+    const matches = [];
+    let from = 0;
+    for (let at = text.indexOf(prefix, from); at !== -1; at = text.indexOf(prefix, from)) {
+        const url = shownUrl(text, at);
+        const segments = /^([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\//.exec(text.slice(at + prefix.length));
+        if (!segments)
+            throw refused(url, `storage URL ${url} does not name an upload`);
+        if (segments[1] !== runtime)
+            throw refused(url, `storage URL ${url} names another runtime`);
+        const upload = await getUpload(segments[2], db);
+        if (!upload || upload.grantee !== grantee)
+            throw refused(url, `storage URL ${url} names an unknown upload`);
+        if (upload.delete_pending_since)
+            throw refused(url, `storage URL ${url} names a deleted upload`);
+        const nameAt = at + prefix.length + segments[0].length;
+        const encoded = encodeURIComponent(upload.name);
+        if (!text.startsWith(encoded, nameAt))
+            throw refused(url, `storage URL ${url} does not match the upload's name`);
+        matches.push({ start: at, end: nameAt + encoded.length, upload });
+        from = nameAt + encoded.length;
+    }
+    return matches;
+}
+/** Re-check, inside the accepting write, that every used upload is still this
+ *  grantee's and not pending delete (the due-work tick or an app removal may
+ *  have released it while its bytes were fetched). */
+export async function assertUploadsUsable(grantee, uses, db) {
+    for (const use of uses) {
+        const upload = await getUpload(use.upload_id, db);
+        if (!upload || upload.grantee !== grantee || upload.delete_pending_since)
+            throw refused(use.url, `storage URL ${use.url} names an upload deleted while it was fetched`);
+    }
+}
+/** `photo.png`, `photo-2.png`, `photo-3.png`, … */
+function candidate(name, n) {
+    if (n === 1)
+        return name;
+    const ext = extname(name);
+    return ext && ext !== name ? `${name.slice(0, -ext.length)}-${n}${ext}` : `${name}-${n}`;
+}
+/** Fetch every upload a storage URL in `text` names into the blob store at `attachments/<rootId>/<sha256>` and replace
+ *  exactly each URL's span with the path the node's broker downloads that file to (`<app space>/nodes/<rootId>/attachments/<name>`).
+ *  The control plane writes no file there. Without configured storage the text passes through unchanged. A failure leaves
+ *  at most content-keyed blobs, which are harmless and are deleted with the node (D100). */
+export async function resolveStorageUrls(grantee, rootId, text, options = {}) {
+    const passThrough = { text, uses: [] };
+    const config = (options.config ?? storageConfig)();
+    if (!config || !text.includes(`${config.base_url}/`))
+        return passThrough;
+    const client = (options.client ?? storageClient)();
+    const matches = await matchStorageUrls(text, config.base_url, client.runtimeId, grantee);
+    if (!matches.length)
+        return passThrough;
+    const dir = join(appSpace(grantee).nodes, rootId, 'attachments');
+    const deadline = AbortSignal.timeout(options.budgetMs ?? ATTACHMENT_FETCH_BUDGET_MS);
+    const store = await (options.blobs ?? blobStore)();
+    const taken = new Set(options.taken);
+    const uses = new Map();
+    for (const { upload, start } of matches) {
+        if (uses.has(upload.upload_id))
+            continue;
+        const url = shownUrl(text, start);
+        let fetched;
+        try {
+            fetched = await client.fetchUpload(upload.upload_id, deadline);
+        }
+        catch (error) {
+            if (error instanceof StorageRefused)
+                throw refused(url, error.status === 409 ? `storage URL ${url} names an upload that was never finished` : `storage URL ${url} names an unknown upload`);
+            if (deadline.aborted)
+                throw unavailable('attachments could not be fetched within 110 s');
+            throw error;
+        }
+        const chunks = [];
+        const hash = createHash('sha256');
+        try {
+            await pipeline(fetched.body, new Writable({ write(chunk, _encoding, done) { hash.update(chunk); chunks.push(chunk); done(); } }), { signal: deadline });
+        }
+        catch (error) {
+            if (deadline.aborted)
+                throw unavailable('attachments could not be fetched within 110 s');
+            throw unavailable(`storage stopped sending ${upload.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const bytes = Buffer.concat(chunks);
+        if (bytes.length !== upload.size)
+            throw unavailable(`storage sent ${bytes.length} of ${upload.size} bytes of ${upload.name}`);
+        const blob_key = `attachments/${rootId}/${hash.digest('hex')}`;
+        try {
+            await store.put(blob_key, bytes);
+        }
+        catch (error) {
+            throw unavailable(`the attachment ${upload.name} could not be stored: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let path = '';
+        for (let n = 1;; n++) {
+            path = join(dir, candidate(upload.name, n));
+            if (!taken.has(path) && !await runUsesPath(rootId, path))
+                break;
+        }
+        taken.add(path);
+        uses.set(upload.upload_id, { upload_id: upload.upload_id, path, url, blob_key });
+    }
+    let out = '';
+    let last = 0;
+    for (const match of matches) {
+        out += text.slice(last, match.start) + uses.get(match.upload.upload_id).path;
+        last = match.end;
+    }
+    out += text.slice(last);
+    return { text: out, uses: [...uses.values()] };
+}

package/dist/core/storage/client.d.ts

@@ -0,0 +1,109 @@
+import { Readable } from 'node:stream';
+import { type DirectoryToken } from '../grants/sync.js';
+/** The size limit of one uploaded or shared file: 100 MiB. */
+export declare const UPLOAD_MAX_BYTES = 104857600;
+/** Storage answered 404 (unknown, or another runtime's object) or 409 (not uploaded). */
+export declare class StorageRefused extends Error {
+    readonly status: 404 | 409;
+    readonly code: string;
+    constructor(status: 404 | 409, code: string, message: string);
+}
+export interface StorageConfig {
+    service_url: string;
+    base_url: string;
+}
+export interface CreatedUpload {
+    upload_id: string;
+    url: string;
+    upload_link: string;
+    expires_at: string;
+}
+export interface CreatedShare {
+    share_id: string;
+    url: string;
+    upload_link: string;
+    expires_at: string | null;
+}
+export interface SignedLink {
+    url: string;
+    expires_at: string;
+}
+/** An `outbound` object (a provider file argument's copy): `upload_link` is the
+ *  signed PUT, `url` a signed GET valid 15 minutes from creation; storage
+ *  deletes the object 24 hours after creation (`expires_at`). */
+export interface CreatedOutbound {
+    object_id: string;
+    upload_link: string;
+    url: string;
+    link_expires_at: string;
+    expires_at: string;
+}
+export interface SignedOutbound {
+    url: string;
+    link_expires_at: string;
+    expires_at: string;
+}
+export interface SignedUploadLink {
+    upload_link: string;
+    expires_at: string;
+}
+export interface StorageClient {
+    readonly config: StorageConfig;
+    /** This runtime's id, the second segment of every storage URL it owns. */
+    readonly runtimeId: string;
+    createUpload(input: {
+        name: string;
+        media_type: string;
+        size: number;
+    }): Promise<CreatedUpload>;
+    /** The upload's bytes; `size` is storage's `Content-Length`. */
+    fetchUpload(uploadId: string, signal?: AbortSignal): Promise<{
+        body: Readable;
+        size: number | null;
+        media_type: string | null;
+    }>;
+    signDownload(uploadId: string): Promise<SignedLink>;
+    deleteUpload(uploadId: string): Promise<void>;
+    createShare(input: {
+        name: string;
+        media_type: string;
+        size: number;
+        expires_at?: string;
+    }): Promise<CreatedShare>;
+    putShareBytes(uploadLink: string, file: string, size: number, mediaType: string): Promise<void>;
+    deleteShare(shareId: string): Promise<void>;
+    /** A provider file result's upload: the PUT accepts any length up to
+     *  `max_size` and storage records the size stored (the one call to change if
+     *  storage's field differs). */
+    createResultUpload(input: {
+        name: string;
+        media_type: string;
+        max_size: number;
+    }): Promise<CreatedUpload>;
+    /** A fresh signed PUT link for an upload with nothing stored yet (409 once
+     *  bytes are stored, 404 once it is gone). */
+    signUploadLink(uploadId: string): Promise<SignedUploadLink>;
+    createOutbound(input: {
+        name: string;
+        size: number;
+        media_type?: string;
+    }): Promise<CreatedOutbound>;
+    /** A fresh signed GET URL for an uploaded outbound object (409 before its
+     *  PUT, 404 once gone). */
+    signOutbound(objectId: string): Promise<SignedOutbound>;
+    /** PUT exactly `size` bytes of the open descriptor `fd` from offset 0 to a
+     *  signed link. Reads the descriptor, never the pathname, so a file swapped
+     *  after it was checked cannot be copied; the caller closes `fd`. */
+    putFileBytes(uploadLink: string, fd: number, size: number, mediaType: string): Promise<void>;
+}
+/** The configured storage, or null when this runtime has none. */
+export declare function storageConfig(): StorageConfig | null;
+/** The storage client for the configured runtime. Refuses with
+ *  `storage_unavailable` when no storage is configured. */
+export declare function storageClient(): StorageClient;
+/** Test seam: reset the cached client (and its token). */
+export declare function resetStorageClient(): void;
+export declare function createStorageClient(config: StorageConfig, mint: () => Promise<DirectoryToken>, runtime: string): StorageClient;
+/** Storage's name rule (plan Overview): 1–255 bytes UTF-8, no `/`, `\`, NUL or
+ *  control characters, not `.` or `..`. Returns a reason, or null when valid. */
+export declare function invalidStorageName(name: string): string | null;