@sema-agent/connectors 0.0.0-stage → 0.1.0

package/dist/jwks.js

@@ -0,0 +1,78 @@
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import { given } from './config-dir.js';
+const INLINE = 'CONNECTOR_ASSERTION_JWKS';
+const OVERRIDE = 'CONNECTOR_ASSERTION_JWKS_URL';
+const WELL_KNOWN = '/.well-known/jwks.json';
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost'];
+const FETCH_LIMIT_BYTES = 1024 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+export function keySetSource(env, issuer) {
+    const inline = env[INLINE];
+    const override = env[OVERRIDE];
+    if (given(override) && given(inline))
+        return `both ${OVERRIDE} and ${INLINE} are set; the key set must have one source`;
+    if (given(inline))
+        return { kind: 'inline', text: inline };
+    const from = given(override) ? OVERRIDE : `the default key set location (CONNECTOR_ASSERTION_ISSUER followed by ${WELL_KNOWN})`;
+    let url;
+    try {
+        url = new URL(given(override) ? override : issuer.replace(/\/+$/, '') + WELL_KNOWN);
+    }
+    catch {
+        return `${from} is not a URL`;
+    }
+    if (url.username !== '' || url.password !== '')
+        return `${from} carries credentials; a key set URL never does`;
+    if (url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK_HOSTS.includes(url.hostname)))
+        return { kind: 'url', from, url };
+    return `${from} must be an https URL, or an http URL on 127.0.0.1 or localhost`;
+}
+const isKeySet = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && Array.isArray(v.keys);
+export async function obtainKeySet(source) {
+    const what = source.kind === 'inline' ? INLINE : `the key set from ${source.from}`;
+    let text;
+    if (source.kind === 'inline')
+        text = source.text;
+    else {
+        const fetched = await fetchOnce(source.url);
+        if (!fetched.ok)
+            return { ok: false, problem: `${what} could not be fetched: ${fetched.why}` };
+        text = fetched.text;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, problem: `${what} is not JSON` };
+    }
+    return isKeySet(value) ? { ok: true, keys: value } : { ok: false, problem: `${what} is not a JSON Web Key Set (an object with a keys list)` };
+}
+function fetchOnce(url) {
+    return new Promise((resolve) => {
+        const get = url.protocol === 'https:' ? httpsGet : httpGet;
+        const req = get(url, { agent: false, headers: { accept: 'application/json' } }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve({ ok: false, why: `it answered HTTP ${String(res.statusCode)}` });
+                return;
+            }
+            const parts = [];
+            let size = 0;
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > FETCH_LIMIT_BYTES) {
+                    req.destroy();
+                    resolve({ ok: false, why: `its answer is over ${FETCH_LIMIT_BYTES / (1024 * 1024)} MiB` });
+                }
+                else
+                    parts.push(chunk);
+            });
+            res.on('end', () => resolve({ ok: true, text: Buffer.concat(parts).toString('utf8') }));
+            res.on('error', () => resolve({ ok: false, why: 'its answer broke off' }));
+        });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => req.destroy(Object.assign(new Error('timeout'), { code: 'ETIMEDOUT' })));
+        req.on('error', (e) => resolve({ ok: false, why: `the request failed (${e.code ?? 'no answer'})` }));
+    });
+}

package/dist/launcher.d.ts

@@ -0,0 +1,2 @@
+import { type Env } from './config-dir.js';
+export declare function main(argv: readonly string[], env: Env): Promise<number>;

package/dist/launcher.js

@@ -0,0 +1,585 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isIPv4, isIPv6 } from 'node:net';
+import { dirname, join } from 'node:path';
+import { absoluteDir, given } from './config-dir.js';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { serveHttp } from './http.js';
+import { keySetSource, obtainKeySet } from './jwks.js';
+import { hostedResolver, standaloneResolver } from './principal.js';
+import { Scrubber, secretMatcher } from './redact.js';
+import { copyForLaunch, openFileSecrets } from './secrets.js';
+import { INSPECT_LIMIT_BYTES, Session } from './session.js';
+import { mintStatus } from './status.js';
+const EXIT = { ok: 0, guard: 2, notInstalled: 4, connectorFailed: 5 };
+const NOT_INSTALLED = 'connector.not_installed';
+const INTERNAL = 'connector.internal';
+const STOP_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+const TEARDOWN_STEP_MS = 1000;
+const STALL_STEPS = 10;
+const STALL_MS = STALL_STEPS * TEARDOWN_STEP_MS;
+const PIECE_BYTES = 1024;
+const USAGE = 'usage: sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]';
+const FLAGS = ['--mode', '--transport', '--listen', '--config-dir'];
+const CHILD_ENV = ['HOME', 'LOGNAME', 'USER', 'PATH', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ'];
+function guard(argv, env) {
+    if (argv[0] !== 'run')
+        return 'expected the command "run"';
+    const name = argv[1];
+    if (name === undefined || name.startsWith('-'))
+        return 'missing the connector <name> after "run"';
+    if (!CONNECTOR_NAME.test(name))
+        return '<name> must be lowercase letters and digits in hyphen-separated words (it names the package @sema-agent/connector-<name>)';
+    const values = new Map();
+    for (let i = 2; i < argv.length; i += 2) {
+        const flag = FLAGS.find((f) => f === argv[i]);
+        if (flag === undefined)
+            return `unknown argument at position ${i + 1}`;
+        if (values.has(flag))
+            return `${flag} is given more than once`;
+        const value = argv[i + 1];
+        if (value === undefined)
+            return `${flag} needs a value`;
+        values.set(flag, value);
+    }
+    const mode = values.get('--mode');
+    const transport = values.get('--transport');
+    const listen = values.get('--listen');
+    if (mode === undefined)
+        return '--mode is required (standalone or hosted); there is no default';
+    if (mode !== 'standalone' && mode !== 'hosted')
+        return '--mode must be standalone or hosted';
+    if (transport === undefined)
+        return '--transport is required (stdio or http); there is no default';
+    if (transport !== 'stdio' && transport !== 'http')
+        return '--transport must be stdio or http';
+    if (mode === 'standalone') {
+        if (transport !== 'stdio')
+            return 'standalone mode requires --transport stdio';
+        if (listen !== undefined)
+            return '--listen is only valid with --transport http';
+        const configDirArgument = values.get('--config-dir');
+        if (configDirArgument === undefined)
+            return 'standalone mode requires --config-dir <absolute path>, the configuration directory its secrets are read from (there is no default)';
+        const configDir = absoluteDir(configDirArgument);
+        if (configDir === null)
+            return '--config-dir must be an absolute path';
+        return { name, mode, configDir };
+    }
+    if (transport !== 'http')
+        return 'hosted mode requires --transport http';
+    if (values.has('--config-dir'))
+        return '--config-dir is only valid in standalone mode (hosted configuration comes from the deployment declaration)';
+    if (listen === undefined)
+        return 'hosted mode requires --listen <ip>:<port>';
+    const address = listenAddress(listen);
+    if (address === null)
+        return '--listen must be <IPv4 or [IPv6]>:<port> with a port from 1 to 65535';
+    const issuer = env.CONNECTOR_ASSERTION_ISSUER;
+    if (!given(issuer))
+        return 'hosted mode requires CONNECTOR_ASSERTION_ISSUER (an empty value counts as missing)';
+    const audience = env.CONNECTOR_ASSERTION_AUDIENCE;
+    if (!given(audience))
+        return 'hosted mode requires CONNECTOR_ASSERTION_AUDIENCE, the audience every assertion must name (an empty value counts as missing)';
+    const keySet = keySetSource(env, issuer);
+    if (typeof keySet === 'string')
+        return keySet;
+    return { name, mode, listen: address, issuer, audience, keySet };
+}
+function listenAddress(value) {
+    const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):([1-9][0-9]{0,4})$/.exec(value);
+    if (m === null)
+        return null;
+    const host = m[1] ?? m[2] ?? '';
+    const hostOk = m[1] !== undefined ? isIPv6(host) : isIPv4(host);
+    const port = Number(m[3]);
+    return hostOk && port <= 65535 ? { host, port } : null;
+}
+function resolveConnector(name) {
+    const packageName = `@sema-agent/connector-${name}`;
+    let manifestPath;
+    try {
+        manifestPath = createRequire(new URL('../package.json', import.meta.url)).resolve(`${packageName}/package.json`);
+    }
+    catch {
+        return { packageName, reason: 'is not installed where the launcher can resolve it' };
+    }
+    let bin;
+    try {
+        bin = JSON.parse(readFileSync(manifestPath, 'utf8')).bin;
+    }
+    catch {
+        return { packageName, reason: 'has a package.json that cannot be read' };
+    }
+    let rel;
+    if (typeof bin === 'string')
+        rel = bin;
+    else if (bin !== null && typeof bin === 'object' && !Array.isArray(bin) && Object.keys(bin).length === 1)
+        rel = Object.values(bin)[0];
+    if (typeof rel !== 'string' || rel === '')
+        return { packageName, reason: 'does not declare exactly one bin' };
+    return { packageName, binPath: join(dirname(manifestPath), rel) };
+}
+class Out {
+    stream;
+    held = [];
+    heldBytes = 0;
+    writing = false;
+    ending = false;
+    needDrain = false;
+    gone = false;
+    settled = [];
+    stall = null;
+    constructor(stream) {
+        this.stream = stream;
+        const lost = () => {
+            if (this.gone)
+                return;
+            this.gone = true;
+            this.held.length = 0;
+            this.heldBytes = 0;
+            this.idle();
+        };
+        stream.on('error', lost);
+        stream.once('close', lost);
+    }
+    behind() {
+        return !this.gone && this.needDrain;
+    }
+    whenCaughtUp(go) {
+        void this.flushed().then(go);
+    }
+    write(chunk) {
+        if (this.gone || this.ending)
+            return;
+        const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        for (let at = 0; at < bytes.length; at += PIECE_BYTES)
+            this.held.push(bytes.subarray(at, at + PIECE_BYTES));
+        this.heldBytes += bytes.length;
+        if (this.heldBytes >= this.stream.writableHighWaterMark)
+            this.needDrain = true;
+        this.next();
+    }
+    end() {
+        this.ending = true;
+        this.next();
+    }
+    flushed() {
+        if (this.gone || (!this.writing && this.held.length === 0))
+            return Promise.resolve();
+        return new Promise((resolve) => this.settled.push(resolve));
+    }
+    watchStall(ms, stalled) {
+        this.stall = { ms, stalled };
+    }
+    next() {
+        if (this.writing || this.gone)
+            return;
+        const piece = this.held.shift();
+        if (piece === undefined) {
+            if (this.ending && !this.stream.writableEnded)
+                this.stream.end();
+            this.idle();
+            return;
+        }
+        this.writing = true;
+        const stall = this.stall;
+        if (stall !== null) {
+            stall.timer ??= setTimeout(() => {
+                this.stall = null;
+                stall.stalled();
+            }, stall.ms).unref();
+            stall.timer.refresh();
+        }
+        this.stream.write(piece, () => {
+            this.writing = false;
+            this.heldBytes -= piece.length;
+            this.next();
+        });
+    }
+    idle() {
+        if (this.stall?.timer !== undefined) {
+            clearTimeout(this.stall.timer);
+            delete this.stall.timer;
+        }
+        this.needDrain = false;
+        const settled = this.settled;
+        this.settled = [];
+        for (const resolve of settled)
+            resolve();
+    }
+}
+const LINE_FEED = 0x0a;
+const OWN_PREFIX = Buffer.from('sema-connector:');
+const MARK = Buffer.from('connector: ');
+const RECEIPT_PREFIX = 'sema-connector: receipt ';
+const LINE_BREAK = /\n|\r|\x0b|\x0c|[\x1c-\x1e]|\xc2\x85|\xe2\x80[\xa8\xa9]/g;
+const LONGEST_BREAK = 3;
+const lineStarts = (text) => [...text.matchAll(LINE_BREAK)].map((m) => m.index + m[0].length);
+const asciiJson = (value) => JSON.stringify(value).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+class Log {
+    out;
+    tail = Buffer.from([LINE_FEED]);
+    constructor(out) {
+        this.out = out;
+    }
+    line(text) {
+        if (this.tail[this.tail.length - 1] !== LINE_FEED)
+            this.write(Buffer.from('\n'));
+        this.write(Buffer.from(text, 'utf8'));
+    }
+    connector(scrubber) {
+        let held = Buffer.alloc(0);
+        const pass = (bytes, final) => {
+            const data = held.length > 0 ? Buffer.concat([held, bytes]) : bytes;
+            held = Buffer.alloc(0);
+            const before = this.tail.length;
+            const starts = lineStarts(this.tail.toString('latin1')).includes(before) ? [0] : [];
+            for (const end of lineStarts(Buffer.concat([this.tail, data]).toString('latin1')))
+                if (end > before)
+                    starts.push(end - before);
+            const parts = [];
+            let at = 0;
+            for (const start of starts) {
+                const rest = data.length - start;
+                if (rest < OWN_PREFIX.length && !final && data.subarray(start).equals(OWN_PREFIX.subarray(0, rest))) {
+                    held = Buffer.from(data.subarray(start));
+                    break;
+                }
+                if (rest >= OWN_PREFIX.length && data.subarray(start, start + OWN_PREFIX.length).equals(OWN_PREFIX)) {
+                    parts.push(data.subarray(at, start), MARK);
+                    at = start;
+                }
+            }
+            parts.push(data.subarray(at, data.length - held.length));
+            this.write(Buffer.concat(parts));
+        };
+        return {
+            chunk: (bytes) => pass(scrubber.feed(bytes), false),
+            end: () => {
+                pass(scrubber.flush(), true);
+                if (this.tail[this.tail.length - 1] !== LINE_FEED)
+                    this.write(Buffer.from('\n'));
+            },
+        };
+    }
+    write(bytes) {
+        if (bytes.length === 0)
+            return;
+        this.out.write(bytes);
+        const both = Buffer.concat([this.tail, bytes]);
+        this.tail = Buffer.from(both.subarray(Math.max(0, both.length - LONGEST_BREAK)));
+    }
+}
+const onAbandon = new Set();
+let isAbandoned = false;
+let abandon = () => undefined;
+const abandoned = new Promise((resolve) => {
+    abandon = () => {
+        isAbandoned = true;
+        for (const release of onAbandon)
+            release();
+        onAbandon.clear();
+        resolve();
+    };
+});
+function pump(src, dst, framing, also = [], passing, giveUp) {
+    return new Promise((resolve) => {
+        let gone = false;
+        let parts = [];
+        let size = 0;
+        let dropping = false;
+        const release = () => {
+            if (gone)
+                return;
+            gone = true;
+            parts = [];
+            src.resume();
+        };
+        dst?.stream.once('error', release);
+        dst?.stream.once('close', release);
+        if (isAbandoned)
+            release();
+        else
+            onAbandon.add(release);
+        void giveUp?.then(release);
+        const append = (piece) => {
+            if (piece.length === 0 || framing === undefined || dropping)
+                return;
+            if (size + piece.length > INSPECT_LIMIT_BYTES) {
+                dropping = true;
+                parts = [];
+                size = 0;
+                framing.oversized();
+                return;
+            }
+            parts.push(Buffer.from(piece));
+            size += piece.length;
+        };
+        const endLine = () => {
+            if (!dropping)
+                framing?.line(Buffer.concat(parts));
+            parts = [];
+            size = 0;
+            dropping = false;
+        };
+        src.on('data', (chunk) => {
+            if (gone)
+                return;
+            if (framing === undefined)
+                passing?.chunk(chunk);
+            else {
+                let start = 0;
+                let at;
+                while ((at = chunk.indexOf(LINE_FEED, start)) !== -1) {
+                    append(chunk.subarray(start, at));
+                    endLine();
+                    start = at + 1;
+                }
+                if (start < chunk.length)
+                    append(chunk.subarray(start));
+            }
+            const slow = gone ? undefined : [...(dst === null ? [] : [dst]), ...also].find((o) => o.behind());
+            if (slow !== undefined) {
+                src.pause();
+                slow.whenCaughtUp(() => src.resume());
+            }
+        });
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            if (!gone) {
+                if (framing === undefined)
+                    passing?.end();
+                else if (size > 0)
+                    endLine();
+            }
+            parts = [];
+            dst?.stream.off('error', release);
+            dst?.stream.off('close', release);
+            onAbandon.delete(release);
+            resolve();
+        };
+        src.on('end', finish);
+        src.on('error', finish);
+        src.on('close', finish);
+    });
+}
+function childEnvironment(env, secrets) {
+    const out = {};
+    for (const name of CHILD_ENV) {
+        const value = env[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    for (const [name, path] of secrets.files)
+        out[`${name}_FILE`] = path;
+    return out;
+}
+const describe = (o) => `connector process ${o.stalled ? `stopped reading its input (stalled input: none of it taken for ${STALL_MS / 1000} s) and ` : ''}${o.error ? `could not be started (${o.error.message})` : o.signal !== null ? `was terminated by signal ${o.signal}` : `exited with code ${String(o.code)}`}`;
+const abnormal = (o) => o.code !== 0 || o.stalled === true;
+function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
+    const child = spawn(process.execPath, [binPath], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env: childEnv });
+    const toGroup = (signal) => {
+        if (child.pid === undefined)
+            return false;
+        try {
+            process.kill(-child.pid, signal);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const toChild = new Out(child.stdin);
+    const perform = (actions) => {
+        for (const a of actions) {
+            if (a.to === 'receipt')
+                log.line(`${RECEIPT_PREFIX}${asciiJson(a.receipt)}\n`);
+            else if (a.to === 'upstream')
+                toUpstream(a.data);
+            else
+                toChild.write(a.data);
+        }
+    };
+    const judged = (judge, unreadable) => {
+        let actions;
+        try {
+            actions = judge();
+        }
+        catch {
+            actions = unreadable();
+        }
+        perform(actions);
+    };
+    let rung = 0;
+    let stopped = false;
+    const climb = (to, signal = 'SIGTERM') => {
+        if (to <= rung)
+            return;
+        rung = to;
+        if (to === 1)
+            toChild.end();
+        else
+            toGroup(to === 2 ? signal : 'SIGKILL');
+        if (to < 3)
+            setTimeout(() => climb(to + 1), TEARDOWN_STEP_MS).unref();
+        else if (stopped)
+            abandon();
+    };
+    let stalled = false;
+    toChild.watchStall(STALL_MS, () => {
+        if (rung >= 2)
+            return;
+        stalled = true;
+        climb(2);
+    });
+    const fromChild = pump(child.stdout, upstreamOut, {
+        line: (line) => judged(() => session.fromConnector(line), () => session.connectorOversized()),
+        oversized: () => perform(session.connectorOversized()),
+    });
+    const exited = new Promise((resolve) => {
+        child.on('error', (error) => resolve({ code: null, signal: null, error }));
+        child.on('exit', (code, signal) => resolve({ code, signal }));
+    });
+    const stderrGiveUp = stderrAfterExitMs === undefined ? undefined : exited.then(() => new Promise((resolve) => setTimeout(resolve, stderrAfterExitMs).unref()));
+    const fromChildErr = pump(child.stderr, log.out, undefined, [], log.connector(scrubber), stderrGiveUp);
+    const outcome = (async () => {
+        const exit = await exited;
+        climb(2);
+        await Promise.all([fromChild, fromChildErr]);
+        const ended = stalled ? { ...exit, stalled } : exit;
+        perform(session.connectorGone(describe(ended), abnormal(ended)));
+        while (rung < 3 && toGroup(0))
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        return ended;
+    })();
+    return {
+        toChild,
+        perform,
+        fromUpstream: (line, principal) => judged(() => session.fromUpstream(line, principal), () => session.upstreamOversized()),
+        endInput: () => climb(1),
+        stop: (signal) => {
+            stopped = true;
+            if (rung >= 3)
+                abandon();
+            else
+                climb(2, signal);
+        },
+        outcome,
+    };
+}
+async function runStdio(packageName, binPath, childEnv, session, scrubber, stdout, log) {
+    const resolution = standaloneResolver().resolve({ headers: {} });
+    if (!resolution.ok)
+        throw new Error('the standalone principal cannot be refused');
+    const anonymous = resolution.principal;
+    const run = startConnector(binPath, childEnv, session, scrubber, (data) => stdout.write(data), stdout, log);
+    const upstream = pump(process.stdin, run.toChild, { line: (line) => run.fromUpstream(line, anonymous), oversized: () => run.perform(session.upstreamOversized()) }, [stdout]);
+    void upstream.then(() => run.endInput());
+    for (const s of STOP_SIGNALS)
+        process.on(s, (signal) => run.stop(signal));
+    const outcome = await run.outcome;
+    process.stdin.destroy();
+    if (!abnormal(outcome))
+        return EXIT.ok;
+    log.line(`sema-connector: ${INTERNAL}: ${packageName}: ${describe(outcome)}\n`);
+    return EXIT.connectorFailed;
+}
+async function runHosted(plan, keys, packageName, binPath, env, log) {
+    const childEnv = childEnvironment(env, NO_SECRETS);
+    const start = (deliver) => {
+        const session = new Session({
+            connector: plan.name,
+            status: (tools) => mintStatus({ handles: [], nowMs: Date.now(), tools }),
+            ownIdPrefix: `sema-connector/${randomUUID()}`,
+            withheld: secretMatcher(NO_SECRETS.values),
+        });
+        const run = startConnector(binPath, childEnv, session, new Scrubber(NO_SECRETS.values), (data) => deliver(String(data)), null, log, TEARDOWN_STEP_MS);
+        return {
+            send: (raw, principal) => run.fromUpstream(raw, principal),
+            busy: () => run.toChild.behind(),
+            readStatus: (id, principal) => run.perform(session.statusFor(id, principal)),
+            end: (signal) => (signal === undefined ? run.endInput() : run.stop(signal)),
+            gone: run.outcome.then((o) => {
+                if (abnormal(o))
+                    log.line(`sema-connector: ${INTERNAL}: ${packageName}: ${describe(o)}\n`);
+            }),
+        };
+    };
+    const face = await serveHttp({ host: plan.listen.host, port: plan.listen.port, resolver: hostedResolver({ issuer: plan.issuer, audience: plan.audience, keys }), start });
+    if (!face.ok) {
+        log.line(`sema-connector: cannot listen on the address given with --listen (${face.code})\n`);
+        return EXIT.guard;
+    }
+    const signal = await new Promise((resolve) => {
+        for (const s of STOP_SIGNALS)
+            process.on(s, resolve);
+    });
+    await face.close(signal);
+    setTimeout(abandon, TEARDOWN_STEP_MS);
+    return EXIT.ok;
+}
+const NO_SECRETS = { files: new Map(), values: [], remove: () => undefined };
+export async function main(argv, env) {
+    const stdout = new Out(process.stdout);
+    const log = new Log(new Out(process.stderr));
+    const finish = async (code) => {
+        await Promise.race([Promise.all([stdout.flushed(), log.out.flushed()]), abandoned]);
+        return code;
+    };
+    const plan = guard(argv, env);
+    if (typeof plan === 'string') {
+        log.line(`sema-connector: ${plan}\n${USAGE}\n`);
+        return finish(EXIT.guard);
+    }
+    if (plan.mode === 'hosted') {
+        const keys = await obtainKeySet(plan.keySet);
+        if (!keys.ok) {
+            log.line(`sema-connector: ${keys.problem}\n`);
+            return finish(EXIT.guard);
+        }
+        const resolved = resolveConnector(plan.name);
+        if ('reason' in resolved) {
+            log.line(`sema-connector: ${NOT_INSTALLED}: package ${resolved.packageName} ${resolved.reason}\n`);
+            return finish(EXIT.notInstalled);
+        }
+        return finish(await runHosted(plan, keys.keys, resolved.packageName, resolved.binPath, env, log));
+    }
+    const listing = openFileSecrets({ configDir: plan.configDir, connector: plan.name }).list();
+    if (!listing.ok) {
+        log.line(`sema-connector: ${INTERNAL}: ${listing.problem}\n`);
+        return finish(EXIT.guard);
+    }
+    const { handles } = listing;
+    let secrets;
+    try {
+        secrets = copyForLaunch(plan.configDir, plan.name, handles);
+    }
+    catch {
+        log.line(`sema-connector: ${INTERNAL}: connector ${plan.name}: its secrets cannot be read for this launch\n`);
+        return finish(EXIT.guard);
+    }
+    const resolved = resolveConnector(plan.name);
+    if ('reason' in resolved) {
+        secrets.remove();
+        log.line(`sema-connector: ${NOT_INSTALLED}: package ${resolved.packageName} ${resolved.reason}\n`);
+        return finish(EXIT.notInstalled);
+    }
+    const session = new Session({
+        connector: plan.name,
+        status: (tools) => mintStatus({ handles, nowMs: Date.now(), tools }),
+        ownIdPrefix: `sema-connector/${randomUUID()}`,
+        withheld: secretMatcher(secrets.values),
+    });
+    try {
+        return finish(await runStdio(resolved.packageName, resolved.binPath, childEnvironment(env, secrets), session, new Scrubber(secrets.values), stdout, log));
+    }
+    finally {
+        secrets.remove();
+    }
+}

package/dist/mount.d.ts

@@ -0,0 +1,23 @@
+export interface MountOptions {
+    readonly name: string;
+    readonly configDir: string;
+}
+export type MountRefusal = 'config_dir' | 'invalid_name' | 'reserved_name' | 'unreadable' | 'unexpected_shape' | 'conflict' | 'locked' | 'changed_during_write';
+export type MountResult = {
+    readonly ok: true;
+    readonly changed: boolean;
+    readonly file: string;
+} | {
+    readonly ok: false;
+    readonly reason: MountRefusal;
+    readonly message: string;
+};
+export declare function standaloneEntry(name: string, configDir: string): {
+    name: string;
+    transport: {
+        kind: 'stdio';
+        command: string;
+        args: string[];
+    };
+};
+export declare function mount(options: MountOptions): MountResult;