@roj-ai/sdk 0.1.35 → 0.2.1

package/dist/bun-platform/shell.js

@@ -0,0 +1,322 @@
+/**
+ * Bun/Node ShellRunner — spawns one command line and buffers what it prints.
+ *
+ * Confinement is `paths`: bubblewrap mounts exactly the paths the caller
+ * granted, at the location the caller says the command sees them.
+ */
+import { resolve } from 'node:path';
+import { createBunProcessRunner } from './process.js';
+/** Maximum output size per stream in bytes (1 MB) */
+const MAX_OUTPUT_BYTES = 1_048_576;
+/** Default cap on what a confined command may write (200 MB). */
+const DEFAULT_FILE_SIZE_BYTES = 209_715_200;
+/** Default process cap. Namespace-local only on Linux 5.14+; older kernels count per host uid. */
+const DEFAULT_PROCESSES = 64;
+/** POSIX counts `ulimit -f` in 512-byte blocks; a shell counting 1024 caps at twice the request. */
+const FILE_SIZE_BLOCK_BYTES = 512;
+/** Marks a limit the shell refused, so the host hears about it and the agent's stderr stays clean */
+const LIMIT_NOTICE_PREFIX = 'roj-shell: limit unavailable:';
+const reportedLimits = new Set();
+/** Grace period before SIGKILL after SIGTERM (ms) */
+const GRACEFUL_KILL_DELAY_MS = 5000;
+/** Host environment a command inherits; everything else stays out of it. */
+const SAFE_ENV_VARS = ['PATH', 'HOME', 'USER', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ'];
+function getSafeEnv() {
+    return Object.fromEntries(SAFE_ENV_VARS
+        .filter(key => process.env[key])
+        .map(key => [key, process.env[key]]));
+}
+/** A command the host could not run, carrying whatever it managed to observe. */
+class ShellRunFailure extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'ShellRunFailure';
+    }
+}
+export function buildBwrapArgs(opts) {
+    const args = [
+        '--ro-bind',
+        '/',
+        '/',
+        '--dev',
+        '/dev',
+        '--proc',
+        '/proc',
+        '--tmpfs',
+        '/tmp',
+    ];
+    // Overrides --ro-bind / / for these paths, keeping user home dirs and root out of reach
+    args.push('--tmpfs', '/home');
+    args.push('--tmpfs', '/root');
+    for (const grant of opts.grants ?? []) {
+        args.push(grant.mode === 'ro' ? '--ro-bind' : '--bind', resolve(grant.source ?? grant.path), grant.path);
+    }
+    args.push('--unshare-all');
+    if (opts.network) {
+        args.push('--share-net');
+    }
+    args.push('--die-with-parent');
+    // Set working directory inside the namespace
+    args.push('--chdir', opts.cwd);
+    args.push('/bin/sh', '-c', opts.command);
+    return args;
+}
+/**
+ * Resource limits for a confined command, one statement at a time: dash fails a single
+ * `ulimit` call carrying several flags, and spells the process cap `-p`, not `-u`.
+ * `-v` and `-t` stay unset; the shell port documents why.
+ */
+export function buildLimitPrefix(limits = {}) {
+    const fileSizeBytes = limits.fileSizeBytes === undefined ? DEFAULT_FILE_SIZE_BYTES : limits.fileSizeBytes;
+    const processes = limits.processes === undefined ? DEFAULT_PROCESSES : limits.processes;
+    const statements = [];
+    if (fileSizeBytes !== null) {
+        statements.push(['file size', `ulimit -f ${Math.ceil(fileSizeBytes / FILE_SIZE_BLOCK_BYTES)}`]);
+    }
+    if (processes !== null) {
+        statements.push(['process count', `{ ulimit -u ${processes} 2>/dev/null || ulimit -p ${processes} 2>/dev/null; }`]);
+    }
+    return statements
+        .map(([name, attempt]) => `${attempt} || echo '${LIMIT_NOTICE_PREFIX} ${name}' >&2`)
+        .join('\n');
+}
+/** Every limit turned off leaves no prefix, and the command must not gain a blank first line. */
+function prefixCommand(prefix, command) {
+    return prefix === '' ? command : `${prefix}\n${command}`;
+}
+/** Split the notices the prefix wrote from the command's own stderr. */
+export function splitLimitNotices(stderr) {
+    const unavailable = [];
+    const lines = stderr.split('\n');
+    let index = 0;
+    while (index < lines.length && lines[index].startsWith(LIMIT_NOTICE_PREFIX)) {
+        unavailable.push(lines[index].slice(LIMIT_NOTICE_PREFIX.length).trim());
+        index++;
+    }
+    return { stderr: lines.slice(index).join('\n'), unavailable };
+}
+function reportUnavailableLimits(names, warn) {
+    for (const name of names) {
+        if (reportedLimits.has(name))
+            continue;
+        reportedLimits.add(name);
+        warn(`shell: this shell applies no ${name} limit; commands run without it`);
+    }
+}
+/** Host directory the bwrap process itself starts from; the namespace has its own cwd. */
+function hostStartDir(options) {
+    const first = options.grants?.[0];
+    return first ? first.source ?? first.path : undefined;
+}
+function runCommand(processRunner, options, warn) {
+    // The grants are the confinement request: without them the command runs unconfined.
+    const confined = options.grants !== undefined;
+    const startTime = Date.now();
+    return new Promise((settleResult, failResult) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let processClosed = false;
+        let processError;
+        let exitCode = null;
+        let exitSignal = null;
+        let stdinSettled = options.stdin === undefined;
+        let stdinError;
+        let settled = false;
+        const env = { ...getSafeEnv(), ...options.env };
+        let child;
+        if (confined) {
+            // The prefix runs in the command's own shell: wrap it in a subshell and it limits nothing.
+            const bwrapArgs = buildBwrapArgs({
+                command: prefixCommand(buildLimitPrefix(options.limits), options.command),
+                cwd: options.cwd,
+                grants: options.grants,
+                network: options.network,
+            });
+            child = processRunner.spawn('bwrap', bwrapArgs, {
+                cwd: hostStartDir(options),
+                env,
+                detached: true,
+            });
+        }
+        else {
+            const shell = options.shell ?? (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh');
+            const shellFlag = process.platform === 'win32' ? '/c' : '-c';
+            child = processRunner.spawn(shell, [shellFlag, options.command], {
+                cwd: options.cwd,
+                env,
+                detached: true,
+            });
+        }
+        // Collect stdout with size cap
+        let stdoutBytes = 0;
+        let stdoutTruncated = false;
+        child.stdout?.on('data', (data) => {
+            if (stdoutTruncated)
+                return;
+            const remaining = MAX_OUTPUT_BYTES - stdoutBytes;
+            if (data.length > remaining) {
+                stdout += data.toString('utf-8', 0, remaining);
+                stdoutBytes = MAX_OUTPUT_BYTES;
+                stdoutTruncated = true;
+                stdout += '\n[stdout truncated at 1 MB]';
+            }
+            else {
+                stdout += data.toString();
+                stdoutBytes += data.length;
+            }
+        });
+        // Collect stderr with size cap
+        let stderrBytes = 0;
+        let stderrTruncated = false;
+        child.stderr?.on('data', (data) => {
+            if (stderrTruncated)
+                return;
+            const remaining = MAX_OUTPUT_BYTES - stderrBytes;
+            if (data.length > remaining) {
+                stderr += data.toString('utf-8', 0, remaining);
+                stderrBytes = MAX_OUTPUT_BYTES;
+                stderrTruncated = true;
+                stderr += '\n[stderr truncated at 1 MB]';
+            }
+            else {
+                stderr += data.toString();
+                stderrBytes += data.length;
+            }
+        });
+        // Timeout handler — SIGTERM first, then SIGKILL after grace period
+        let killTimeoutId;
+        const clearTimers = () => {
+            clearTimeout(timeoutId);
+            if (killTimeoutId)
+                clearTimeout(killTimeoutId);
+        };
+        const finishExecution = () => {
+            if (settled)
+                return;
+            if (!processClosed)
+                return;
+            const durationMs = Date.now() - startTime;
+            if (processError) {
+                settled = true;
+                clearTimers();
+                failResult(new ShellRunFailure(`Failed to execute command: ${processError.message}`, { durationMs }));
+                return;
+            }
+            if (!stdinSettled)
+                return;
+            settled = true;
+            clearTimers();
+            const notices = splitLimitNotices(stderr);
+            reportUnavailableLimits(notices.unavailable, warn);
+            const commandStderr = notices.stderr.trim();
+            if (stdinError) {
+                failResult(new ShellRunFailure(`Failed to deliver command stdin: ${stdinError.message}`, {
+                    stdout: stdout.trim(),
+                    stderr: commandStderr,
+                    durationMs,
+                    exitCode: exitCode ?? -1,
+                    signal: exitSignal ?? undefined,
+                    timedOut,
+                }));
+                return;
+            }
+            settleResult({
+                stdout: stdout.trim(),
+                stderr: commandStderr,
+                exitCode: exitCode ?? -1,
+                signal: exitSignal ?? undefined,
+                timedOut,
+                truncated: stdoutTruncated || stderrTruncated,
+            });
+        };
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                child.kill('SIGTERM');
+            }
+            killTimeoutId = setTimeout(() => {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch { /* already dead */ }
+                }
+            }, GRACEFUL_KILL_DELAY_MS);
+        }, options.timeoutMs);
+        // Process exit
+        child.on('close', (code, signal) => {
+            processClosed = true;
+            exitCode = code;
+            exitSignal = signal;
+            if (options.stdin !== undefined && !stdinSettled) {
+                if (child.stdin?.writableFinished) {
+                    stdinSettled = true;
+                }
+                else {
+                    stdinError = new Error('child process closed before accepting all stdin input');
+                    stdinSettled = true;
+                }
+            }
+            finishExecution();
+        });
+        // Process error
+        child.on('error', (error) => {
+            processError = error;
+            finishExecution();
+        });
+        // A failed stdin write must not be hidden by a successful process exit.
+        if (options.stdin !== undefined) {
+            if (!child.stdin) {
+                stdinError = new Error('child process stdin is unavailable');
+                stdinSettled = true;
+            }
+            else {
+                child.stdin.once('finish', () => {
+                    if (stdinSettled)
+                        return;
+                    stdinSettled = true;
+                    finishExecution();
+                });
+                child.stdin.on('error', (error) => {
+                    if (stdinSettled)
+                        return;
+                    stdinError = error;
+                    stdinSettled = true;
+                    finishExecution();
+                });
+                child.stdin.once('close', () => {
+                    if (stdinSettled)
+                        return;
+                    stdinError = new Error('child process stdin closed before accepting all input');
+                    stdinSettled = true;
+                    finishExecution();
+                });
+                child.stdin.end(options.stdin);
+            }
+        }
+        else {
+            // Keep late pipe errors contained when no input delivery was requested.
+            child.stdin?.on('error', () => { });
+            child.stdin?.end();
+        }
+        finishExecution();
+    });
+}
+export function createBunShellRunner(processRunner = createBunProcessRunner(), 
+/** Where a limit this shell refused is reported; the command's own stderr never carries it. */
+warn = (message) => console.warn(message)) {
+    return {
+        confinement: 'paths',
+        run: (options) => runCommand(processRunner, options, warn),
+    };
+}
+//# sourceMappingURL=shell.js.map

package/dist/bun-platform/shell.js.map

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

package/dist/config.d.ts

@@ -2,6 +2,7 @@
  * Configuration for the Agent Server
  */
 import type { MockInferenceHandler } from './core/llm/mock.js';
+import type { ArchiveLimitOverrides } from './lib/archive/index.js';
 import type { LogLevel } from './lib/logger/logger.js';
 /**
  * Server configuration
@@ -20,6 +21,25 @@ export interface Config {
     llmLoggingEnabled?: boolean;
     /** Max concurrent vision LLM calls when classifying uploaded images. Default 10. */
     imageClassifierConcurrency?: number;
+    /**
+     * Hosts that `upload-from-url` and `inject-resource` may reach even though
+     * they land in a range the fetch guard blocks (loopback, RFC1918,
+     * link-local) — e.g. an internal object store. Absent blocks all of them.
+     *
+     * Entries are `host` or `host:port` (`[::1]` / `[::1]:9000` for IPv6). A
+     * bare host opens every port on it, so pin the port unless you mean that.
+     */
+    remoteFetchAllowedHosts?: readonly string[];
+    /** Aggregate limits across every ZIP nested in one attachment upload. */
+    uploadArchiveLimits?: ArchiveLimitOverrides;
+    /** Per-archive limits for resource ZIP injection. */
+    resourceArchiveLimits?: ArchiveLimitOverrides;
+    /**
+     * Resident session idle timeout. Zero or absent disables runtime eviction.
+     * `loadConfig()` leaves this unset unless SESSION_IDLE_TIMEOUT_MS is given —
+     * each runtime picks its own default (standalone-server uses 10 minutes).
+     */
+    sessionIdleTimeoutMs?: number;
     /**
      * Identity of the application embedding this SDK. Reported via `/status`
      * so platform health-checks can surface "what's actually running" in debug
@@ -49,4 +69,18 @@ export declare const loadConfig: () => Config;
  * Validate configuration and return errors if any.
  */
 export declare const validateConfig: (config: Config) => string[];
+/** One parsed `remoteFetchAllowedHosts` entry. `port` absent means the host is open on every port. */
+export interface AllowedHostEntry {
+    host: string;
+    port?: number;
+}
+/**
+ * Parse one `remoteFetchAllowedHosts` entry into the form the fetch guard matches.
+ *
+ * The guard compares against `URL.hostname`, so the entry is normalised the same
+ * way here — lowercased, IPv6 brackets dropped, trailing root dots stripped.
+ * Returns null for anything that could never match, which `validateConfig`
+ * reports rather than leaving as a silently dead entry.
+ */
+export declare const parseAllowedHostEntry: (raw: string) => AllowedHostEntry | null;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,MAAM;IAEtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IAGZ,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAA;IAI9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAA;IAGvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAA;IAEnC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KACf,CAAA;IAGD,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,GAAG,MAAM,CAAA;IAG7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IAGnB,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,QAAO,MAuB7B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAAM,EA2BrD,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,MAAM;IAEtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IAGZ,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAA;IAI9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAA;IAGvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAA;IAEnC;;;;;;;OAOG;IACH,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE3C,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,qBAAqB,CAAA;IAC3C,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KACf,CAAA;IAGD,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,GAAG,MAAM,CAAA;IAG7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IAGnB,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,QAAO,MAiC7B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAAM,EAwCrD,CAAA;AAED,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,gBAAgB,GAAG,IAoCtE,CAAA"}

package/dist/config.js

@@ -6,6 +6,7 @@ import { resolve } from 'node:path';
  * Load configuration from environment variables.
  */
 export const loadConfig = () => {
+    const sessionIdleTimeout = process.env.SESSION_IDLE_TIMEOUT_MS;
     return {
         port: parseInt(process.env.PORT ?? '2486', 10),
         host: process.env.HOST ?? '0.0.0.0',
@@ -19,6 +20,15 @@ export const loadConfig = () => {
         imageClassifierConcurrency: process.env.IMAGE_CLASSIFIER_CONCURRENCY
             ? parseInt(process.env.IMAGE_CLASSIFIER_CONCURRENCY, 10)
             : undefined,
+        remoteFetchAllowedHosts: hostListFromEnv('REMOTE_FETCH_ALLOWED_HOSTS'),
+        uploadArchiveLimits: archiveLimitsFromEnv('UPLOAD_ARCHIVE'),
+        resourceArchiveLimits: archiveLimitsFromEnv('RESOURCE_ARCHIVE'),
+        // Left undefined when unset: loadConfig() is a public export, so baking a
+        // default here silently switches eviction on for every embedder that calls it
+        // (sandbox-runtime among them). Runtimes that want eviction opt in themselves.
+        sessionIdleTimeoutMs: sessionIdleTimeout === undefined
+            ? undefined
+            : sessionIdleTimeout.trim() === '' ? Number.NaN : Number(sessionIdleTimeout),
         logLevel: (process.env.LOG_LEVEL ?? 'info'),
         logFormat: (process.env.LOG_FORMAT ?? 'console'),
         workerUrl: process.env.WORKER_URL,
@@ -52,6 +62,93 @@ export const validateConfig = (config) => {
     if (!validPersistence.includes(config.persistence)) {
         errors.push(`Invalid persistence type: ${config.persistence}`);
     }
+    for (const host of config.remoteFetchAllowedHosts ?? []) {
+        // An entry the guard cannot parse silently never matches, leaving the fetch blocked.
+        if (parseAllowedHostEntry(host) === null) {
+            errors.push(`Invalid remoteFetchAllowedHosts entry: ${host}`);
+        }
+    }
+    validateArchiveLimitOverrides('uploadArchiveLimits', config.uploadArchiveLimits, errors);
+    validateArchiveLimitOverrides('resourceArchiveLimits', config.resourceArchiveLimits, errors);
+    if (config.sessionIdleTimeoutMs !== undefined && (!Number.isSafeInteger(config.sessionIdleTimeoutMs) || config.sessionIdleTimeoutMs < 0)) {
+        errors.push(`Invalid sessionIdleTimeoutMs: ${config.sessionIdleTimeoutMs}`);
+    }
     return errors;
 };
+/**
+ * Parse one `remoteFetchAllowedHosts` entry into the form the fetch guard matches.
+ *
+ * The guard compares against `URL.hostname`, so the entry is normalised the same
+ * way here — lowercased, IPv6 brackets dropped, trailing root dots stripped.
+ * Returns null for anything that could never match, which `validateConfig`
+ * reports rather than leaving as a silently dead entry.
+ */
+export const parseAllowedHostEntry = (raw) => {
+    const entry = raw.trim().toLowerCase();
+    if (entry === '' || /[\s/]/.test(entry))
+        return null;
+    const normalizeHostPart = (value) => {
+        const host = value.replace(/\.+$/, '');
+        return host === '' || host.includes('[') || host.includes(']') ? null : host;
+    };
+    const parsePort = (value) => {
+        if (!/^\d{1,5}$/.test(value))
+            return null;
+        const port = Number(value);
+        return port >= 1 && port <= 65535 ? port : null;
+    };
+    if (entry.startsWith('[')) {
+        const close = entry.indexOf(']');
+        if (close === -1)
+            return null;
+        const host = normalizeHostPart(entry.slice(1, close));
+        const rest = entry.slice(close + 1);
+        if (host === null)
+            return null;
+        if (rest === '')
+            return { host };
+        if (!rest.startsWith(':'))
+            return null;
+        const port = parsePort(rest.slice(1));
+        return port === null ? null : { host, port };
+    }
+    // An unbracketed IPv6 literal has several colons and carries no port.
+    const colon = entry.lastIndexOf(':');
+    if (colon !== -1 && entry.indexOf(':') === colon) {
+        const host = normalizeHostPart(entry.slice(0, colon));
+        const port = parsePort(entry.slice(colon + 1));
+        return host === null || port === null ? null : { host, port };
+    }
+    const host = normalizeHostPart(entry);
+    return host === null ? null : { host };
+};
+/** Split a comma-separated env var into entries, or undefined when it holds none. */
+function hostListFromEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return undefined;
+    const hosts = raw.split(',').map(entry => entry.trim()).filter(entry => entry !== '');
+    return hosts.length > 0 ? hosts : undefined;
+}
+function archiveLimitsFromEnv(prefix) {
+    const maxEntries = process.env[`${prefix}_MAX_ENTRIES`];
+    const maxTotalUncompressedSize = process.env[`${prefix}_MAX_UNCOMPRESSED_BYTES`];
+    if (maxEntries === undefined && maxTotalUncompressedSize === undefined)
+        return undefined;
+    return {
+        maxEntries: maxEntries === undefined ? undefined : parseInt(maxEntries, 10),
+        maxTotalUncompressedSize: maxTotalUncompressedSize === undefined
+            ? undefined
+            : parseInt(maxTotalUncompressedSize, 10),
+    };
+}
+function validateArchiveLimitOverrides(name, limits, errors) {
+    if (!limits)
+        return;
+    for (const [field, value] of Object.entries(limits)) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+            errors.push(`Invalid ${name}.${field}: ${value}`);
+        }
+    }
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAiFnC;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAW,EAAE;IACtC,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAA;IAC9D,OAAO;QACN,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,CAAC;QAC9C,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,SAAS;QACnC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,QAAQ,CAAC;QACnE,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,CAAsB;QACrE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAChD,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC9C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,4BAA4B;QACvE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;QACnG,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,OAAO;QAC9D,0BAA0B,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B;YACnE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,EAAE,CAAC;YACxD,CAAC,CAAC,SAAS;QACZ,uBAAuB,EAAE,eAAe,CAAC,4BAA4B,CAAC;QACtE,mBAAmB,EAAE,oBAAoB,CAAC,gBAAgB,CAAC;QAC3D,qBAAqB,EAAE,oBAAoB,CAAC,kBAAkB,CAAC;QAC/D,0EAA0E;QAC1E,8EAA8E;QAC9E,+EAA+E;QAC/E,oBAAoB,EAAE,kBAAkB,KAAK,SAAS;YACrD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC;QAC7E,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM,CAAa;QACvD,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,SAAS,CAAuB;QACtE,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU;QACjC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;QACnC,sBAAsB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,MAAM,EAAE,EAAE,CAAC;QACtF,qBAAqB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,OAAO,EAAE,EAAE,CAAC;QACrF,qBAAqB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,OAAO,EAAE,EAAE,CAAC;QACpF,oBAAoB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,OAAO,EAAE,EAAE,CAAC;KAClF,CAAA;AACF,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAY,EAAE;IAC1D,MAAM,MAAM,GAAa,EAAE,CAAA;IAE3B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAC5E,MAAM,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAA;IACnF,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IACnD,CAAC;IAED,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,sBAAsB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;IACrD,CAAC;IAED,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAC3C,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC,uBAAuB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAA;IACvD,CAAC;IAED,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC3C,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,6BAA6B,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,uBAAuB,IAAI,EAAE,EAAE,CAAC;QACzD,qFAAqF;QACrF,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,0CAA0C,IAAI,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;IAED,6BAA6B,CAAC,qBAAqB,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAA;IACxF,6BAA6B,CAAC,uBAAuB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;IAC5F,IAAI,MAAM,CAAC,oBAAoB,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,MAAM,CAAC,oBAAoB,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1I,MAAM,CAAC,IAAI,CAAC,iCAAiC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAA;IAC5E,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC,CAAA;AAQD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAW,EAA2B,EAAE;IAC7E,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACtC,IAAI,KAAK,KAAK,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEpD,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAiB,EAAE;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QACtC,OAAO,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;IAC7E,CAAC,CAAA;IACD,MAAM,SAAS,GAAG,CAAC,KAAa,EAAiB,EAAE;QAClD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1B,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;IAChD,CAAC,CAAA;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAChC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;QAC7B,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;QACnC,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAA;QAC9B,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAChC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QACtC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QACrC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC7C,CAAC;IAED,sEAAsE;IACtE,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;QACrD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;QAC9C,OAAO,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC9D,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACrC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;AACvC,CAAC,CAAA;AAED,qFAAqF;AACrF,SAAS,eAAe,CAAC,IAAY;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACvC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAA;IACrF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5C,CAAC;AAED,SAAS,oBAAoB,CAAC,MAA6C;IAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,cAAc,CAAC,CAAA;IACvD,MAAM,wBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,yBAAyB,CAAC,CAAA;IAChF,IAAI,UAAU,KAAK,SAAS,IAAI,wBAAwB,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxF,OAAO;QACN,UAAU,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;QAC3E,wBAAwB,EAAE,wBAAwB,KAAK,SAAS;YAC/D,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,QAAQ,CAAC,wBAAwB,EAAE,EAAE,CAAC;KACzC,CAAA;AACF,CAAC;AAED,SAAS,6BAA6B,CACrC,IAAqD,EACrD,MAAyC,EACzC,MAAgB;IAEhB,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACxE,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC,CAAA;QAClD,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/core/agents/agent.d.ts

@@ -8,7 +8,8 @@
  */
 import z from 'zod/v4';
 import { DebounceCallback } from '../../core/agents/debounce.js';
-import type { AgentId } from '../../core/agents/schema.js';
+import { AgentId } from '../../core/agents/schema.js';
+import { type AgentWakeKind } from '../../core/wake-key.js';
 import type { AgentState } from '../../core/agents/state.js';
 import type { FileStore } from '../../core/file-store/types.js';
 import { type CacheTtlConfig } from '../../core/llm/cache-breakpoints.js';
@@ -62,7 +63,7 @@ export interface AgentConfig<TInput = unknown> {
  */
 export interface AgentDependencies {
     id: AgentId;
-    sessionContext: SessionContext;
+    getSessionContext: () => SessionContext;
     store: SessionStore;
     llmProvider: LLMProvider;
     /** Named provider instances, passed to InferenceContext for middleware routing */
@@ -96,7 +97,7 @@ export interface AgentDependencies {
 export declare class Agent {
     readonly id: AgentId;
     private readonly config;
-    private readonly sessionContext;
+    private readonly getSessionContext;
     private readonly store;
     private readonly logger;
     private readonly llmProvider;
@@ -111,15 +112,25 @@ export declare class Agent {
     private readonly scheduleCallback?;
     /** Merged tools map: config tools + plugin tools (plugins override). Rebuilt each processing cycle. */
     private tools;
-    private debounceTimer?;
-    private errorRetryTimer?;
+    /** Poll timer for the debounceCallback path only — see scheduleProcessing(). */
+    private debounceCheckTimer?;
+    /** Whether a retry wake is armed. In-memory: a fresh process re-arms from replayed state. */
+    private errorRetryArmed;
+    private releaseScheduledLease?;
+    /** Host scheduler, resolved once — the platform never changes for a session. */
+    private scheduler?;
     private processing;
     private scheduled;
     private pendingReschedule;
+    /** In-flight continue() calls, so disposal can drain a turn instead of racing it. */
+    private readonly inFlightContinues;
     private readonly abortController;
-    /** Track conversation turn number for handler context */
-    private turnNumber;
     constructor(deps: AgentDependencies);
+    /**
+     * Turn the agent is working on: committed turns plus the one in flight.
+     * Read from persisted state so a reload or a compaction can't reset it.
+     */
+    private get turnNumber();
     /**
      * Get the current agent state from store.
      */
@@ -135,16 +146,32 @@ export declare class Agent {
      * mid-turn — abort controllers, debounce timers and mailbox state included.
      */
     private resolveModel;
+    /** Drop the scheduled lease. Idempotent — the release closure self-guards. */
+    private dropScheduledLease;
     /**
      * Unified processing entry point - decides what to do next.
      * Safe to call multiple times; skips if already processing.
      */
     continue(): Promise<void>;
+    /**
+     * Await the turn that is currently running, if any — including work it starts
+     * while draining. Never rejects: callers use it to drain before teardown, not
+     * to observe processing errors.
+     */
+    waitForIdle(): Promise<void>;
+    private runContinue;
     /**
      * Schedule processing with debounce.
      * Use this when receiving new messages or after tool execution.
      */
     scheduleProcessing(): void;
+    /**
+     * Run the continuation a due wake stands for — the one entry point for a host,
+     * whether this process armed the delay or an alarm held it across an eviction.
+     */
+    deliverWake(kind: AgentWakeKind): Promise<void>;
+    /** One debounce-callback check. Never rejects: on error it cancels the schedule. */
+    private runDebounceCheck;
     /**
      * Shutdown the agent - cancel any scheduled processing.
      */
@@ -203,6 +230,14 @@ export declare class Agent {
      * Cancel any scheduled processing.
      */
     private cancelSchedule;
+    /** The host scheduler, or null once the runtime is gone — a disposed session builds no context. */
+    private tryGetScheduler;
+    /**
+     * Arm a wake without awaiting the host: scheduleProcessing() and shutdown() are
+     * synchronous, while a host may persist the wake asynchronously.
+     */
+    private armWake;
+    private cancelWake;
     /**
      * Execute a single tool call.
      */