@north-light/api 0.3.580 → 0.3.587

package/dist/core/session-model/session-state.d.ts

@@ -0,0 +1,53 @@
+import type { BrokerToClient, ClientRole, RpcExtensionUIRequest, RpcSessionState, WelcomeFrame } from '../runtime/broker-protocol.js';
+/** A retained `ctx.ui.setWidget` entry. */
+export interface DisplayWidget {
+    lines: string[];
+    placement: 'aboveEditor' | 'belowEditor';
+}
+/** The broker-owned display levels (`ctx.ui.setStatus/setWidget/setTitle`),
+ *  insertion-ordered per key exactly as the broker retains them. */
+export interface DisplayState {
+    statuses: Record<string, string>;
+    widgets: Record<string, DisplayWidget>;
+    title: string | undefined;
+}
+export interface SessionState {
+    /** This viewer's fixed role, stated by the broker in `welcome`. `controller`
+     *  means writable and `observer` means read-only; the broker never reassigns
+     *  it, so nothing after `welcome` can change this field. */
+    role: ClientRole;
+    /** The broker process's pi agent dir, from `welcome` — lets a viewer point an
+     *  AuthStorage/ModelRegistry at the SAME auth.json. */
+    agentDir: string | undefined;
+    /** pi's own `get_state` payload. `undefined` until the first welcome. */
+    engine: RpcSessionState | undefined;
+    /** Live context occupancy in prompt tokens: seeded from the snapshot's
+     *  contextUsage, then tracked off each assistant `message_end`. */
+    contextTokens: number | undefined;
+    /** Queued steering + follow-up messages: seeded from `welcome.snapshot.queued`
+     *  and tracked off `queue_update`. Every welcome REPLACES this — the attaching
+     *  broker's own queue is the whole truth, so a dead broker's rows never survive
+     *  and a client attaching mid-queue still sees what is waiting. */
+    queued: Array<{
+        text: string;
+    }>;
+    display: DisplayState;
+    /** The blocking dialog awaiting an answer, or null. Only a writable client is
+     *  ever sent one, and every writable client is sent the SAME one — the first
+     *  answer wins and the broker dismisses the rest by id.
+     *  `welcome.pending_dialog` carries one in flight at attach time, and
+     *  a welcome is a COMPLETE catch-up, so a welcome naming none clears it.
+     *  (The terminal viewer does not read this field: its overlay is owned by
+     *  `InputController`, which holds a live TUI handle rather than data. The field
+     *  remains session state because it is derived solely from broker frames.) */
+    dialog: RpcExtensionUIRequest | null;
+}
+export declare function initialSessionState(role?: ClientRole): SessionState;
+/** The whole session state a `welcome` determines, in ONE step. This is why D1
+ *  had to land first: before the broker carried its retained display levels in
+ *  `snapshot.display`, catch-up was `welcome` plus N replayed edges and this
+ *  function could not be total. */
+export declare function applySnapshot(frame: WelcomeFrame): SessionState;
+/** Fold one broker frame into the session state. Pure and total: a frame that
+ *  carries no session state returns `state` UNCHANGED (same reference). */
+export declare function reduce(state: SessionState, frame: BrokerToClient): SessionState;

package/dist/core/session-model/session-state.js

@@ -0,0 +1,180 @@
+// session-state.ts — the ONE model of "what the broker has told this viewer".
+//
+// Terminal attach folds every broker-derived fact through this reducer instead
+// of patching mutable state in individual frame handlers. One reducer keeps the
+// protocol projection coherent across every terminal consumer.
+//
+// The cut line is mechanical:
+//
+//   SESSION state = anything derived SOLELY from what the broker sent.
+//   VIEWER  state = anything derived from local input or this terminal viewer.
+//
+// So `role` belongs here even though it differs per viewer (the broker fixes it
+// from this viewer's `hello` and never changes it — "identical across viewers"
+// would get it wrong), while a transient notice, a connection phase, a
+// correlation id this viewer minted, and the transcript
+// RENDERING all stay with the viewer. The transcript itself is deliberately out
+// of scope because the terminal accumulates it into scrollback.
+//
+// `reduce` is pure and total over `BrokerToClient`: unknown/irrelevant frames
+// return the SAME object reference, so a viewer can drive its repaints off
+// slice-identity (`next.display !== prev.display`) instead of repainting
+// everything on every frame.
+const EMPTY_DISPLAY = { statuses: {}, widgets: {}, title: undefined };
+export function initialSessionState(role = 'observer') {
+    return {
+        role,
+        agentDir: undefined,
+        engine: undefined,
+        contextTokens: undefined,
+        queued: [],
+        display: EMPTY_DISPLAY,
+        dialog: null,
+    };
+}
+/** The whole session state a `welcome` determines, in ONE step. This is why D1
+ *  had to land first: before the broker carried its retained display levels in
+ *  `snapshot.display`, catch-up was `welcome` plus N replayed edges and this
+ *  function could not be total. */
+export function applySnapshot(frame) {
+    const snapshot = frame.snapshot;
+    // A broker pinned to a pre-`display` runtime generation is still live and sends
+    // no `display` key. It replays nothing either, so the empty floor is correct
+    // for it — and a re-welcome must never leave a dead broker's keys behind.
+    const display = snapshot.display ?? EMPTY_DISPLAY;
+    const contextUsage = snapshot.stats.contextUsage;
+    return {
+        role: frame.role,
+        agentDir: frame.agentDir,
+        engine: snapshot.state,
+        contextTokens: contextUsage?.tokens ?? undefined,
+        queued: snapshotQueued(snapshot),
+        display: {
+            statuses: { ...display.statuses },
+            widgets: Object.fromEntries(Object.entries(display.widgets).map(([k, w]) => [k, { lines: [...w.lines], placement: w.placement }])),
+            title: display.title,
+        },
+        dialog: frame.pending_dialog ?? null,
+    };
+}
+/** Fold one broker frame into the session state. Pure and total: a frame that
+ *  carries no session state returns `state` UNCHANGED (same reference). */
+export function reduce(state, frame) {
+    switch (frame.type) {
+        case 'welcome':
+            return applySnapshot(frame);
+        case 'model_changed':
+            return patchEngine(state, { model: frame.model });
+        case 'extension_ui_request': {
+            // pi's uniform envelope: the three display METHODS are levels this model
+            // retains; every other method is a dialog (a new one supersedes any
+            // showing one).
+            switch (frame.method) {
+                case 'setStatus': {
+                    const current = state.display.statuses[frame.statusKey];
+                    if (frame.statusText === undefined ? current === undefined : current === frame.statusText)
+                        return state;
+                    const statuses = { ...state.display.statuses };
+                    // Delete-then-set so an update moves the key to the end, matching the
+                    // broker's (and pi's) insertion-ordered widget/status behavior.
+                    delete statuses[frame.statusKey];
+                    if (frame.statusText !== undefined)
+                        statuses[frame.statusKey] = frame.statusText;
+                    return { ...state, display: { ...state.display, statuses } };
+                }
+                case 'setWidget': {
+                    const next = frame.widgetLines === undefined
+                        ? undefined
+                        : { lines: [...frame.widgetLines], placement: frame.widgetPlacement ?? 'aboveEditor' };
+                    if (widgetEqual(state.display.widgets[frame.widgetKey], next))
+                        return state;
+                    const widgets = { ...state.display.widgets };
+                    delete widgets[frame.widgetKey];
+                    if (next !== undefined)
+                        widgets[frame.widgetKey] = next;
+                    return { ...state, display: { ...state.display, widgets } };
+                }
+                case 'setTitle':
+                    if (state.display.title === frame.title)
+                        return state;
+                    return { ...state, display: { ...state.display, title: frame.title } };
+                case 'notify':
+                    // A notice line — viewer-local presentation, no session state, and
+                    // emphatically NOT a dialog: it must never supersede a blocking
+                    // request whose answer the broker is still waiting for.
+                    return state;
+                default:
+                    return { ...state, dialog: frame };
+            }
+        }
+        case 'extension_ui_dismiss':
+            // Correlated cleanup: the broker resolved this request itself. Clear ONLY
+            // the dialog whose id matches.
+            return state.dialog !== null && state.dialog.id === frame.id ? { ...state, dialog: null } : state;
+        case 'message_end':
+            // The most recent assistant turn's prompt tokens ARE the live context
+            // size — read straight off the relayed message, no broker round-trip.
+            if (frame.message.role !== 'assistant')
+                return state;
+            return patchContextTokens(state, frame.message.usage.input + frame.message.usage.cacheRead + frame.message.usage.cacheWrite);
+        case 'agent_start':
+            return patchEngine(state, { isStreaming: true });
+        // `agent_end` is the normal turn-over signal; `agent_settled` is the
+        // canonical WHOLE-RUN settle the broker always relays (and uses to clear its
+        // own busy marker). Clear on BOTH so an abnormal/missed agent_end cannot
+        // strand `isStreaming: true` — which is what kept a dormant, between-wakes
+        // orchestrator showing a frozen `Working…` spinner.
+        case 'agent_end':
+        case 'agent_settled':
+            return patchEngine(state, { isStreaming: false });
+        case 'session_info_changed':
+            return patchEngine(state, { sessionName: frame.name });
+        case 'thinking_level_changed':
+            return patchEngine(state, { thinkingLevel: frame.level });
+        case 'queue_update': {
+            const queued = [...frame.steering, ...frame.followUp].map((text) => ({ text }));
+            const next = patchEngine(state, { pendingMessageCount: queued.length });
+            return { ...next, queued };
+        }
+        default:
+            return state;
+    }
+}
+/** The queue a `welcome` reports, composed exactly as `queue_update` composes
+ *  it. Absent on a snapshot from a broker generation older than the field, and
+ *  on an offline node (no engine, so no queue) — both mean nothing is waiting. */
+function snapshotQueued(snapshot) {
+    const queued = snapshot.queued;
+    if (typeof queued !== 'object' || queued === null)
+        return [];
+    const { steering, followUp } = queued;
+    return [...texts(steering), ...texts(followUp)].map((text) => ({ text }));
+}
+function texts(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+/** Apply a partial patch to pi's state, preserving reference identity when the
+ *  patch changes nothing (and when no welcome has seeded `engine` yet). */
+function patchEngine(state, patch) {
+    const engine = state.engine;
+    if (engine === undefined)
+        return state;
+    let changed = false;
+    for (const [k, v] of Object.entries(patch)) {
+        if (engine[k] !== v) {
+            changed = true;
+            break;
+        }
+    }
+    if (!changed)
+        return state;
+    return { ...state, engine: { ...engine, ...patch } };
+}
+function patchContextTokens(state, tokens) {
+    return state.contextTokens === tokens ? state : { ...state, contextTokens: tokens };
+}
+function widgetEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return (a.placement === b.placement && a.lines.length === b.lines.length && a.lines.every((l, i) => l === b.lines[i]));
+}

package/dist/core/shell-segments.d.ts

@@ -0,0 +1,42 @@
+/** One shell word. `opaque` marks a token whose text came from inside quotes:
+ *  it is data, so it must never be treated as an executable or a matched
+ *  command word. */
+export type CommandToken = {
+    text: string;
+    opaque: boolean;
+};
+/** One shell segment: the raw text as the author wrote it, its leading
+ *  `VAR=value` assignments, and the remaining words — so `tokens[0]` is the
+ *  executable. An assignment-only segment (`export`-less `FOO=bar`) has
+ *  assignments and no tokens; the distinction matters, because a leading
+ *  assignment applies ONLY to the command in its own segment.
+ *
+ *  `background` marks a segment ended by a single `&`. It runs in a subshell,
+ *  so nothing it assigns or `cd`s reaches the commands after it. */
+export type CommandSegment = {
+    text: string;
+    assignments: string[];
+    tokens: CommandToken[];
+    background: boolean;
+};
+/** One raw segment and whether a single `&` — not `&&` — ended it. */
+export type RawSegment = {
+    text: string;
+    background: boolean;
+};
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  `|`, and a single `&`. Subshell parentheses and backticks are left inside
+ *  their segment. Heredoc bodies are a separate pre-read concern (see
+ *  `stripHeredocs`). */
+export declare function splitCommandSegments(command: string): RawSegment[];
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
+export declare function tokenizeCommandSegment(segment: string): CommandToken[];
+/** Every non-empty command segment, paired with its raw text. */
+export declare function commandSegments(command: string): CommandSegment[];
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is read. The opening line is kept —
+ *  `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this, a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held or refused. */
+export declare function stripHeredocs(command: string): string;

package/dist/core/shell-segments.js

@@ -0,0 +1,169 @@
+// shell-segments.ts — best-effort shell text reading, shared by everything in
+// crtr that has to reason about a command string it did not execute: the doc
+// substrate's `command`/`pre-command` surface matching and the bash valve's
+// refusals. Pure text in, structure out; no execution, no expansion.
+//
+// This is deliberately NOT a shell parser. Subshells, backticks, process
+// substitution, and path-prefixed binaries stay unhandled. Every caller must
+// treat a miss as "this text did not obviously do X", never as "this text
+// cannot do X".
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  `|`, and a single `&`. Subshell parentheses and backticks are left inside
+ *  their segment. Heredoc bodies are a separate pre-read concern (see
+ *  `stripHeredocs`). */
+export function splitCommandSegments(command) {
+    const segments = [];
+    let current = '';
+    let quote = null;
+    let escaped = false;
+    const finish = (background = false) => {
+        segments.push({ text: current, background });
+        current = '';
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            current += ch;
+            escaped = true;
+            continue;
+        }
+        if (quote !== null) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            current += ch;
+            quote = ch;
+            continue;
+        }
+        if (ch === '\n' || ch === ';') {
+            finish();
+            continue;
+        }
+        if ((ch === '&' || ch === '|') && command[i + 1] === ch) {
+            finish();
+            i += 1;
+            continue;
+        }
+        if (ch === '|') {
+            finish();
+            continue;
+        }
+        if (ch === '&') {
+            finish(true);
+            continue;
+        }
+        current += ch;
+    }
+    finish();
+    return segments;
+}
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
+export function tokenizeCommandSegment(segment) {
+    const tokens = [];
+    let text = '';
+    let opaque = false;
+    let started = false;
+    let quote = null;
+    let escaped = false;
+    const finish = () => {
+        if (started)
+            tokens.push({ text, opaque });
+        text = '';
+        opaque = false;
+        started = false;
+    };
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i];
+        if (escaped) {
+            text += ch;
+            started = true;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            escaped = true;
+            started = true;
+            continue;
+        }
+        if (quote !== null) {
+            started = true;
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                text += ch;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            opaque = true;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            finish();
+            continue;
+        }
+        text += ch;
+        started = true;
+    }
+    if (escaped)
+        text += '\\';
+    finish();
+    return tokens;
+}
+/** Every non-empty command segment, paired with its raw text. */
+export function commandSegments(command) {
+    return splitCommandSegments(command)
+        .map(({ text, background }) => {
+        const tokens = tokenizeCommandSegment(text);
+        let first = 0;
+        while (first < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[first].text))
+            first += 1;
+        return { text: text.trim(), assignments: tokens.slice(0, first).map((t) => t.text), tokens: tokens.slice(first), background };
+    })
+        .filter((segment) => segment.assignments.length > 0 || segment.tokens.length > 0);
+}
+const HEREDOC_OPEN = /<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g;
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is read. The opening line is kept —
+ *  `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this, a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held or refused. */
+export function stripHeredocs(command) {
+    const lines = command.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        out.push(line);
+        i += 1;
+        // Every heredoc opened on this line, left to right; their bodies stack and
+        // are consumed in that order.
+        const delims = [];
+        HEREDOC_OPEN.lastIndex = 0;
+        let m;
+        while ((m = HEREDOC_OPEN.exec(line)) !== null)
+            delims.push({ name: m[3], dash: m[1] === '-' });
+        for (const d of delims) {
+            while (i < lines.length) {
+                // `<<-` strips leading TABS from the body and the closing delimiter.
+                const probe = d.dash ? lines[i].replace(/^\t+/, '') : lines[i];
+                i += 1;
+                if (probe === d.name)
+                    break; // closing delimiter line — drop it, stop
+            }
+        }
+    }
+    return out.join('\n');
+}

package/dist/core/spaces/cache-env.d.ts

@@ -0,0 +1,2 @@
+/** TMPDIR is the sandbox's own /tmp: the host's value names a folder the sandbox does not mount. Package-manager caches and Python settings for a sandboxed run. Downloads land in the app's purgeable `cache/` folder, which the cache pass empties when the app nears its disk quota; the guest's own Python is used so no run downloads an interpreter. */
+export declare function sandboxCacheEnv(app: string): Record<string, string>;

package/dist/core/spaces/cache-env.js

@@ -0,0 +1,15 @@
+import { appSpace } from '../layout.js';
+/** TMPDIR is the sandbox's own /tmp: the host's value names a folder the sandbox does not mount. Package-manager caches and Python settings for a sandboxed run. Downloads land in the app's purgeable `cache/` folder, which the cache pass empties when the app nears its disk quota; the guest's own Python is used so no run downloads an interpreter. */
+export function sandboxCacheEnv(app) {
+    const cache = appSpace(app).cache;
+    return {
+        TMPDIR: '/tmp',
+        XDG_CACHE_HOME: cache,
+        npm_config_cache: `${cache}/npm`,
+        UV_CACHE_DIR: `${cache}/uv`,
+        PIP_CACHE_DIR: `${cache}/pip`,
+        PLAYWRIGHT_BROWSERS_PATH: `${cache}/playwright`,
+        UV_PYTHON: '/usr/bin/python3',
+        UV_PYTHON_DOWNLOADS: 'never',
+    };
+}

package/dist/core/spaces/file-root.d.ts

@@ -0,0 +1,23 @@
+export declare function contains(parent: string, path: string): boolean;
+export interface FileCaller {
+    app: string;
+    resolved: readonly string[];
+    launched: readonly string[] | null;
+    /** Run confinement for a node caller (Silas, 2026-09-30): `isolated` when the caller's
+     *  run is isolated; `reaches` answers whether a node folder of its own app is visible. */
+    run?: {
+        isolated: boolean;
+        reaches: (nodeId: string) => boolean;
+    };
+}
+/** The directory a caller's permission names for `path`: the daemon opens
+ *  `path` beneath it. `missing` is the scope the caller lacks (null when no
+ *  scope names the path). The person (`null`) and a Mac terminal node keep a
+ *  Mac's whole filesystem; on Linux the person reaches /user and /apps. */
+export declare function fileRoot(caller: FileCaller | null, target: string, access: 'read' | 'rw'): {
+    root: string;
+} | {
+    missing: string | null;
+} | {
+    hidden: true;
+};

package/dist/core/spaces/file-root.js

@@ -0,0 +1,68 @@
+// Which directory a caller's file permissions name for a path. It depends only on
+// the layout and scope coverage, so access checks in core/graph can import it
+// without pulling the grant mirror and the canvas database into their import graph.
+import { covers } from '@north-light/identity';
+import { join, relative, resolve, sep } from 'node:path';
+import { appSpace, appsRoot, userFilesRoot, userRoot } from '../layout.js';
+export function contains(parent, path) {
+    const rel = relative(parent, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+/** The directory a caller's permission names for `path`: the daemon opens
+ *  `path` beneath it. `missing` is the scope the caller lacks (null when no
+ *  scope names the path). The person (`null`) and a Mac terminal node keep a
+ *  Mac's whole filesystem; on Linux the person reaches /user and /apps. */
+export function fileRoot(caller, target, access) {
+    const path = resolve(target);
+    if (caller === null || (process.platform !== 'linux' && caller.app === 'app:terminal')) {
+        if (process.platform !== 'linux')
+            return { root: '/' };
+        const root = [userRoot(), appsRoot()].find((dir) => contains(dir, path));
+        return root ? { root } : { missing: null };
+    }
+    const own = appSpace(caller.app);
+    if (caller.run && contains(own.root, path)) {
+        // A node folder of another run it may not see is absent; a node of an isolated
+        // run reaches only its own run's node folders, not the app's shared files.
+        const [area, id] = relative(own.root, path).split(sep);
+        if (area === 'nodes' && id)
+            return caller.run.reaches(id) ? { root: join(own.nodes, id) } : { hidden: true };
+        if (caller.run.isolated)
+            return { hidden: true };
+    }
+    for (const root of [own.files, own.nodes])
+        if (contains(root, path))
+            return { root };
+    const held = (scope) => caller.resolved.some((s) => covers(s, scope)) && (caller.launched === null || caller.launched.some((s) => covers(s, scope)));
+    // A file name need not be valid scope grammar, so coverage is decided on the parsed held scope.
+    const files = (holder, base) => {
+        const rel = relative(base, path) || '.';
+        const dirs = (scopes) => scopes.flatMap((s) => {
+            const m = /^crtr:files:(read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(s);
+            if (!m || m[2] !== holder || (access === 'rw' && m[1] !== 'rw'))
+                return [];
+            return m[3] === '.' || m[3] === rel || rel.startsWith(`${m[3]}/`) ? [join(base, m[3] === '.' ? '' : m[3])] : [];
+        });
+        const granted = dirs(caller.resolved);
+        const run = caller.launched === null ? granted : dirs(caller.launched);
+        if (!granted.length || !run.length)
+            return { missing: `crtr:files:${access}:${holder}:${rel}` };
+        // The narrowest covering scope of the grant and of the run.
+        return { root: [...granted, ...run].reduce((a, b) => (b.length > a.length ? b : a)) };
+    };
+    if (contains(userFilesRoot(), path))
+        return files('user', userFilesRoot());
+    const [app, area, id, folder] = relative(appsRoot(), path).split(sep);
+    if (!contains(appsRoot(), path) || !app || !/^[A-Za-z0-9_-]{1,64}$/.test(app))
+        return { missing: null };
+    const space = appSpace(`app:${app}`);
+    if (area === 'files')
+        return files(`app:${app}`, space.files);
+    if (area !== 'nodes' || access !== 'read')
+        return { missing: null };
+    if (held(`crtr:objects:read:app:${app}`))
+        return { root: space.nodes };
+    if (id && folder === 'attachments' && held(`crtr:conversations:read:app:${app}`))
+        return { root: join(space.nodes, id, folder) };
+    return { missing: `crtr:objects:read:app:${app}` };
+}

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

@@ -0,0 +1,41 @@
+import { type RunPermissions } from './permissions.js';
+import type { LaunchSpec } from '../../launcher/spec.js';
+export interface LaunchNode {
+    nodeId: string;
+    app: string;
+    sub: string;
+    grantId: string | null;
+    scopes: string[] | null;
+    command: string[];
+    env: Record<string, string>;
+    /** No node exists for this app process (e.g. an unanchored cron). */
+    withoutNode?: boolean;
+    /** A node in an isolated run has no own working-files mount or network. */
+    isolated?: boolean;
+    /** The folder of a process that has no node but owns one (an isolated cron's `<app space>/crons/<id>`): it takes the place of the node agent folder. */
+    folder?: string;
+    cwd?: string;
+    /** A cron execution (launch id `cron-<execution_id>`): its only daemon path is `cli.sock` in its own run folder
+     *  `nodeRunDir(nodeId)`, so `api.sock` is not mounted. `anchorDir` is an anchored cron's anchor agent folder. */
+    cron?: {
+        anchorDir?: string;
+    };
+    /** Hook code alone may be mounted from the installed plugin root, read-only. */
+    pluginRoot?: string;
+    /** Missing granted directories are omitted and reported to the daemon. */
+    auditMissing: (source: string) => void;
+}
+/** The mounts a run's grant adds beyond its own app space (other apps' files
+ *  and nodes, and the person's files). */
+export declare function grantedMounts(permissions: RunPermissions): LaunchSpec['mounts'];
+/** Whether a launched mount came from a grant: it lies under the person's files
+ *  or under another app's space. Own-space and system mounts never do. */
+export declare function isGrantedSource(app: string, source: string): boolean;
+/** A launched mount the current permissions still give: the same or a broader
+ *  granted directory, writable if the mount is. */
+export declare function mountAllowed(mount: LaunchSpec['mounts'][number], allowed: LaunchSpec['mounts']): boolean;
+/** Whether a spec compiled earlier is still within the node's current
+ *  permissions. A launch whose grant generation moved while the launcher was
+ *  starting it checks this before registering the sandbox (runtime spec §15). */
+export declare function launchStillGranted(node: Pick<LaunchNode, 'app' | 'sub' | 'grantId' | 'scopes'>, spec: Pick<LaunchSpec, 'mounts'>): Promise<boolean>;
+export declare function compileLaunch(node: LaunchNode): Promise<LaunchSpec>;