@sema-agent/connectors 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog: @sema-agent/connectors
+
+All notable changes to this package are documented here. Released sections are
+frozen: once a version is published its section is never edited again; new text
+goes into the next version's section.
+
+## 0.2.0 (2026-10-15)
+
+### Added
+
+- Handles that are not secrets (CN-038). `<handle>.meta.json` may say
+  `"secret": false`; such a handle is delivered to the connector like every
+  handle (a per-launch 0600 copy named by `<NAME>_FILE`), but the launcher
+  does not withhold its value and the status does not count it. Every other
+  handle is a secret, as before. `openFileSecrets().put(name, value,
+  { secret: false })` writes it, `SecretHandle.secret` reports it, and a
+  later `put` without it makes the handle a secret again.
+- `CONNECTOR_DIR` (CN-038): the launcher gives its connector the absolute path
+  of the connector's directory, `<configuration directory>/connectors/<name>`
+  (standalone; it may not exist), so a connector no longer infers it from the
+  path of a handle copy. A hosted connector, which has no configuration
+  directory and no handles in this release, gets a fresh path of its own that
+  does not exist. A `CONNECTOR_DIR` set for the launcher never reaches the
+  connector.
+- The lock of a connector's directory (CN-038), `.auth.lock`: every write of
+  the secrets backend and every launch's listing and copy of the handles hold
+  it, so a launch copies a group of writes before or after the group, never in
+  between. `openFileSecrets().withLock(fn)` holds it across several writes. A
+  taker waits up to 5 seconds for another holder, then refuses (the launcher
+  with exit 2 and `connector.internal`); only the holder removes the lock, and
+  one left by a process that died is removed by hand. `FileSecrets.directory`
+  names the connector's directory.
+- The connector CLI kit (CN-039): `connectorCli` runs a connector package's
+  bin (no arguments: the connector's server; `install`, `auth`, `mount`,
+  `status` without arguments on the configuration directory of
+  `resolveConfigDir`), `cliOutput`, `readStdinLine`, `readStdinJson` (one line
+  holding a JSON object with exactly the given keys, each named once, every
+  value a string), `mountCommand`, `statusCommand` (the status resource read
+  through the launcher within 10 seconds) and `isLoopbackHttpOrHttps`, the
+  one rule for an address a connector sends requests to (the rule of a key set
+  URL).
+- `writeAll(fd, data)` (CN-042): the one whole write. It writes every byte of
+  `data` into the empty file open at `fd` (a write that writes nothing or fails
+  ends it with an error), syncs the file and checks that its size is the number
+  of bytes, or throws. Every file this package writes goes through it, and a
+  connector package writes its own files with it.
+
+### Changed
+
+- The status counts secret handles only: a connector whose only handles are
+  not secrets is `unauthorized`, and the expiry of a handle that is not a
+  secret changes nothing (CN-038).
+- `<handle>.meta.json` must be a JSON object whose only keys are `expiresAt`
+  and `secret`, each named once; another key, a key named twice or a `secret`
+  that is not `true` or `false` makes the directory refused (another key used
+  to be ignored, and an object without `expiresAt` refused) (CN-038).
+
+### Fixed
+
+- A write cut short is no longer taken as done (CN-042). A write can stop short
+  without an error (a file size limit, a full disk); `mount` used to rename the
+  cut-short text over `mcp.json` and report it written, losing the other
+  entries, and `put` stored a cut-short value and reported success. Now nothing
+  is put in place before it is written whole: `mount` refuses with the new
+  reason `write_failed` and `put` throws, the temporary file is removed and the
+  old file (or its absence) stays as it was. The lock files and the per-launch
+  copies of the handles are written the same way.
+- The scope judge never grants the empty tool name (CN-036): a `tools/call`
+  whose name is `""` is refused with `connector.forbidden_scope` also under
+  `tool:*` (or a bare `tool:`), and a listed tool whose name is `""` is not
+  listed.
+
+## 0.1.0 (2026-10-14)
+
+### Added
+
+- Package entry point and the `sema-connector` bin. The entry exports
+  `resolveConfigDir`, `openFileSecrets`, `verifyAssertion`, `standaloneResolver`,
+  `hostedResolver`, `ASSERTION_HEADER`, `mount` and their types; it exports
+  nothing that turns a secret handle into a value.
+- The launcher behind the `sema-connector` bin (CN-003):
+  `sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]`.
+  Structural guards exit with code 2: a missing `run`, an unknown or repeated
+  argument, a missing or unknown `--mode` or `--transport`, standalone with
+  anything but stdio, hosted without http, without a `--listen <IPv4 or [IPv6]>:<port>`,
+  without `CONNECTOR_ASSERTION_ISSUER` or `CONNECTOR_ASSERTION_AUDIENCE` (CN-008),
+  with both key-set overrides, or with a key set URL that is neither `https://`
+  nor `http://` on `127.0.0.1` or `localhost`, or that carries credentials,
+  standalone without `--config-dir` or with one that is not an absolute path,
+  and hosted with `--config-dir` (CN-028). Standalone reads its configuration
+  directory from `--config-dir` only, never from an environment variable, so a
+  launcher started from a catalog entry with the engine's minimal environment
+  finds it (CN-028). A
+  connector `<name>` must be lowercase letters and digits in hyphen-separated
+  words, so that it can only name `@sema-agent/connector-<name>`. Error messages
+  never repeat argument or environment values.
+- Hosted http face (CN-008): hosted mode that passes the guards obtains its key
+  set once (inline `CONNECTOR_ASSERTION_JWKS`, `CONNECTOR_ASSERTION_JWKS_URL`, or
+  `<issuer>/.well-known/jwks.json`; one GET, no redirect, never refreshed; exit
+  2 when it cannot), resolves its connector (exit 4) and serves the subset of MCP
+  Streamable HTTP the MCP SDK client needs on `--listen`: every request needs a
+  verifiable assertion in `connector-assertion` (HTTP 401 with
+  `connector.bad_assertion` otherwise, a bare name header included); `POST /mcp`
+  carries one message answered as one JSON body (notifications and replies 202);
+  one session at a time, each with its own connector process, named by
+  `mcp-session-id` (400 without it, 404 for another, 409 for a second
+  `initialize`); `mcp-protocol-version` must match the version the connector
+  chose; `GET /mcp` answers 405 (no stream); `DELETE /mcp` ends the session's
+  connector down the teardown ladder and answers 204 once it is gone; requests
+  still waiting when a connector ends are answered with `connector.internal`;
+  `GET /status` serves the status value under the request's own principal. An
+  id stays taken until the connector answers it (409 meanwhile), a message or a
+  status read for a connector that has not read its earlier input answers 503,
+  and connector
+  stderr a stalled log has not taken one step after the connector exited is
+  dropped; only a JSON-RPC answer (result or error) ends a request's wait. A stop
+  signal ends the open session and exits 0, abandoning output a stalled log has
+  not taken one step later. Exit code 3 is gone.
+- An upstream message with a line break inside (a CR other than CRLF framing,
+  or an LF in an http body) is refused like an unreadable one: the connector
+  could read its parts as other messages than the one judged.
+- The message session judges every upstream message under the principal of the
+  request that carried it (the stdio path passes the anonymous principal), and
+  a `tools/list` reply or a status read under the principal of the request it
+  answers.
+- Resolution of `@sema-agent/connector-<name>` from the launcher's own
+  `package.json`; a package that cannot be resolved, or whose `bin` is not a
+  single name, exits with code 4 and `connector.not_installed`.
+- MCP stdio path of newline-delimited messages in both directions, with no
+  runtime dependencies. The connector's stdout and stderr and the upstream
+  input all go through one pump with flow control, so a slow reader holds the
+  writer back instead of growing the launcher's memory, whether or not the
+  output contains newlines. The connector's stderr passes as it arrives; the
+  two message streams are read whole line by line, up to 4 MiB per line,
+  through the stages below, and nothing is forwarded unread; messages no stage
+  concerns are forwarded byte for byte. From upstream, a line that is not a
+  single JSON-RPC message within 4 MiB, that repeats a key in any object, or
+  whose id is neither a string nor a number gets one error with `id` null and
+  `data.code` `connector.forbidden_scope` (CN-004). From the connector, a
+  reply is forwarded only for a request the launcher forwarded and has not seen
+  answered; a longer line, a batch or a message with a repeated key is dropped,
+  and every pending request gets a `connector.internal` error instead (CN-005),
+  so a tool result over 4 MiB arrives as that error; their ids stay taken until
+  the connector answers them (a request with one is refused meanwhile), so a
+  late reply never answers another request (CN-008). An id is also taken while
+  its request is pending, so a request reusing it is refused, not forwarded
+  (CN-031). Upstream input is also held
+  back while upstream does not read the launcher's own replies. Once a reader has gone
+  away, what can no longer be delivered to it is dropped instead of waited for;
+  after a stop signal has run the teardown below to its end, undelivered output
+  is abandoned. When the connector process ends, every request it left
+  unanswered gets a JSON-RPC error with `data.code` `connector.internal` naming
+  how it ended. The connector exiting with code 0 on its own exits the launcher
+  with code 0. A non-zero exit, a signal or stalled input (below) exits with
+  code 5 (with one error with `id` null when no request was pending).
+- The connector never outlives the launcher. It runs as its own process group,
+  so helper processes it starts (for example an upstream binary sharing its
+  stdio) go down with it. One teardown ladder, one second per step: end the
+  connector's input, then `SIGTERM` to the group, then `SIGKILL` to the group.
+  The end of upstream input enters the ladder at its first step; `SIGTERM`,
+  `SIGINT` or `SIGHUP` sent to the launcher enters it at the second, passing that
+  signal on; the connector's own exit enters it at the second for whatever is
+  left of its group. The ladder finishes inside an MCP stdio client's own
+  shutdown (2 seconds after closing input before `SIGTERM`, 2 seconds after
+  `SIGTERM` before `SIGKILL`). The exit code follows the connector process.
+- Stalled input (CN-025): input reaches the connector one piece of at most
+  1 KiB at a time; a connector that takes none of its waiting input for ten
+  teardown steps (10 seconds) has stopped reading and enters the ladder at its
+  second step, on both transports. Its unanswered requests get
+  `connector.internal` naming the stalled input, and the run is abnormal
+  (stdio: exit 5). A client that only closes its pipe while input waits behind a
+  connector that stopped reading no longer leaves the launcher and the connector
+  running.
+- Receipts (CN-031): one `connector-receipt-v1` receipt per `tools/call` that
+  names its tool, on both transports, minted by the launcher's session once the
+  call is settled and written as the stderr line `sema-connector: receipt <JSON>`:
+  `refused` when the launcher refused it, `ok` for a result, `failed` for a
+  result with `isError`, a connector error (with its `data.code` only when that
+  is a code of the closed set) or a `connector.internal` answer of the launcher.
+  It holds the connector and tool names, the start time, the duration, the
+  outcome and the error code, nothing of the call's arguments; a tool name that
+  carries a secret value is written as `[redacted]`. A connector
+  stderr line that would start a line of the launcher's stderr with
+  `sema-connector:` gets `connector: ` in front, so such lines are always the
+  launcher's own.
+- The connector process gets a fixed environment instead of the launcher's:
+  `HOME`, `LOGNAME`, `USER`, `PATH`, `SHELL`, `TERM`, `LANG`, `LC_ALL` and `TZ`
+  when present, and `<NAME>_FILE` with the path of each of its secret files
+  (CN-005).
+- `resolveConfigDir(env)`, for connector CLI subcommands: the configuration
+  directory is `CONFIG_LOCAL_DIR`, which must be an absolute path; not set or
+  empty is refused, and no other variable or default is read (CN-028).
+- Secrets (CN-004): `openFileSecrets({ configDir, connector })` lists handles
+  (name, connector, source, optional expiry; never the value) and stores values
+  atomically. Layout: `<configuration directory>/connectors/<name>/` with mode
+  0700, one 0600 file per handle, optional `<handle>.meta.json` with
+  `expiresAt`. Listing refuses wider modes, symbolic links and unreadable
+  expiry data; the launcher then exits with code 2 and `connector.internal`
+  before the connector starts. The launcher reads each value once, through a
+  function the entry does not export, into a per-launch 0600 copy that the
+  connector receives and that is removed when the launcher ends, and keeps
+  exactly those values out of what it forwards, looking for them also behind
+  JSON escapes: a connector stdout line carrying one is withheld, a reply
+  becoming a `connector.internal` error, and the connector's stderr is
+  scrubbed, also across writes. A line that fails to be judged is not
+  forwarded.
+- Principal (CN-004): `verifyAssertion(compactJws, { issuer, audience, keys, now })`
+  checks a JWS compact assertion with Node's crypto in the contract's order
+  (algorithm allow-list `EdDSA` / `ES256`, key by `kid` with matching key type
+  and no other `alg`, signature, presence of every required claim with `iat` a
+  non-negative integer and `jti` a non-empty string (CN-029), `iss`, `aud`,
+  `exp` with 30 seconds of tolerance, non-empty `sub` and `space`, `scope`
+  pattern); every refusal is
+  `connector.bad_assertion` with the name of the failed step and nothing of the
+  token. `hostedResolver` takes a principal only from a verifiable assertion in
+  the `connector-assertion` request header (`ASSERTION_HEADER`: the header
+  name is the engine's standard to define; this value is the proposal the
+  launcher reads until the engine exports its constant, CN-034; a hosted
+  catalog entry names it with the settings schema's `assertionHeader` key,
+  CN-020), so a bare name header is
+  refused; `standaloneResolver` is anonymous with scope
+  `tool:*`.
+- Scope (CN-004): one judge for `tools/list` and `tools/call`: a tool is
+  granted by `tool:*` or `tool:<name>` in the principal's scope. Tools outside
+  the grant are not listed, and calls to them are answered with JSON-RPC error
+  `-32602` and `connector.forbidden_scope` without reaching the connector.
+- Normalize (CN-005): listed tool annotations keep `title` and the hints at
+  their MCP default (`destructiveHint: true`, `idempotentHint: false`,
+  `openWorldHint: true`); `readOnlyHint`, other hint values and unknown keys
+  are removed.
+- Status (CN-005): the launcher serves `sema-connector://<name>/status`, a
+  `connector-status-v1` value with state `unauthorized`, `authorized` or
+  `expired` from the handles read at start and their expiry, and the tools
+  the reading request's principal sees; hosted, also at `GET /status`
+  (CN-008). Reads never reach the connector; `resources/list` gains the
+  status entry (merged with the connector's own resources, never repeated), and
+  `initialize` gains the resources capability when the connector has none.
+- `mount({ name, configDir })` (CN-005, CN-028): writes the standalone entry
+  into `<configDir>/config.d/mcp.json`, and the entry's arguments end with
+  `--config-dir <configDir>`, the same directory. `configDir` must be an
+  absolute path (used normalized); mount reads no environment variable and has
+  no default. The same entry again changes nothing, another entry under the
+  same name (also one naming another configuration directory, or none) is
+  refused as a conflict, every other byte of the file is kept, and the file is
+  replaced atomically with its mode kept, under a lock file that excludes
+  concurrent mount writers and that only its holder removes. Refusals are
+  returned as reasons.

package/bin/sema-connector.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// sema-connector: the launcher executable (CN-003). Command line, exit codes and resolution rule:
+// docs/ARCHITECTURE.md. Implementation: src/launcher.ts, built to dist/launcher.js.
+import { main } from '../dist/launcher.js'
+
+process.exit(await main(process.argv.slice(2), process.env))

package/dist/cli-kit.d.ts

@@ -0,0 +1,33 @@
+import { type Env } from './config-dir.js';
+export interface CliOutput {
+    readonly program: string;
+    say(line: string): void;
+    complain(line: string): void;
+}
+export declare function cliOutput(name: string): CliOutput;
+export interface ConnectorCommands {
+    readonly name: string;
+    readonly serve: (env: Env) => void | number | Promise<number>;
+    readonly install: (configDir: string) => number | Promise<number>;
+    readonly auth: (configDir: string) => number | Promise<number>;
+    readonly authReads: string;
+}
+export declare function connectorCli(commands: ConnectorCommands, argv: readonly string[], env: Env): Promise<number | undefined>;
+export type StdinLine = {
+    readonly ok: true;
+    readonly line: string;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function readStdinLine(limit: number): Promise<StdinLine>;
+export type StdinJson = {
+    readonly ok: true;
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function readStdinJson(limit: number, keys: readonly string[]): Promise<StdinJson>;
+export declare function mountCommand(name: string, configDir: string): number;
+export declare function statusCommand(name: string, configDir: string): Promise<number>;

package/dist/cli-kit.js

@@ -0,0 +1,223 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveConfigDir } from './config-dir.js';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { hasRepeatedKey } from './json-text.js';
+import { mount } from './mount.js';
+export function cliOutput(name) {
+    if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
+        throw new Error('a connector name is lowercase letters and digits in hyphen-separated words');
+    const program = `sema-connector-${name}`;
+    return {
+        program,
+        say: (line) => void process.stdout.write(`${line}\n`),
+        complain: (line) => void process.stderr.write(`${program}: ${line}\n`),
+    };
+}
+const SUBCOMMANDS = ['install', 'auth', 'mount', 'status'];
+export async function connectorCli(commands, argv, env) {
+    const { complain, program } = cliOutput(commands.name);
+    const [command, ...rest] = argv;
+    if (command === undefined) {
+        const code = await commands.serve(env);
+        return typeof code === 'number' ? code : undefined;
+    }
+    const usage = `usage: ${program} [${SUBCOMMANDS.join(' | ')}]   (no argument: the connector's MCP stdio server; auth reads ${commands.authReads} from standard input)`;
+    if (!SUBCOMMANDS.includes(command)) {
+        complain(`unknown subcommand\n${usage}`);
+        return 2;
+    }
+    if (rest.length > 0) {
+        complain(`${command} takes no arguments${command === 'auth' ? ` (it reads ${commands.authReads} from standard input, never from an argument)` : ''}\n${usage}`);
+        return 2;
+    }
+    const config = resolveConfigDir(env);
+    if (!config.ok) {
+        complain(config.reason);
+        return 2;
+    }
+    if (command === 'install')
+        return commands.install(config.dir);
+    if (command === 'auth')
+        return commands.auth(config.dir);
+    if (command === 'mount')
+        return mountCommand(commands.name, config.dir);
+    return statusCommand(commands.name, config.dir);
+}
+export async function readStdinLine(limit) {
+    if (process.stdin.isTTY)
+        return { ok: false, problem: 'standard input is a terminal here; pipe the input in instead (a token typed on a terminal would be shown)' };
+    const parts = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += b.length;
+        if (size > limit)
+            return { ok: false, problem: `standard input holds more than ${limit} bytes; one line is read` };
+        parts.push(b);
+    }
+    const line = Buffer.concat(parts).toString('utf8').replace(/\r?\n$/, '');
+    if (/[\r\n]/.test(line))
+        return { ok: false, problem: 'standard input must hold exactly one line' };
+    return { ok: true, line };
+}
+const listed = (keys) => (keys.length < 2 ? keys.join('') : `${keys.slice(0, -1).join(', ')} and ${keys[keys.length - 1]}`);
+export async function readStdinJson(limit, keys) {
+    const read = await readStdinLine(limit);
+    if (!read.ok)
+        return read;
+    const shape = `standard input must be one JSON object with exactly the keys ${listed(keys)}, each a string, on one line`;
+    let value;
+    try {
+        value = JSON.parse(read.line);
+    }
+    catch {
+        return { ok: false, problem: shape };
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return { ok: false, problem: shape };
+    if (hasRepeatedKey(read.line))
+        return { ok: false, problem: 'the object names a key more than once' };
+    const object = value;
+    const own = Object.keys(object);
+    if (own.length !== keys.length || !keys.every((k) => own.includes(k)))
+        return { ok: false, problem: `the object must have exactly the keys ${listed(keys)}` };
+    if (!keys.every((k) => typeof object[k] === 'string'))
+        return { ok: false, problem: shape };
+    return { ok: true, values: Object.fromEntries(keys.map((k) => [k, object[k]])) };
+}
+export function mountCommand(name, configDir) {
+    const { say, complain } = cliOutput(name);
+    let r;
+    try {
+        r = mount({ name, configDir });
+    }
+    catch (e) {
+        complain(`mount failed: ${e instanceof Error ? e.message : 'unknown error'}`);
+        return 1;
+    }
+    if (!r.ok) {
+        complain(`mount refused (${r.reason}): ${r.message}`);
+        return 1;
+    }
+    say(r.changed ? `mounted connector ${name} in ${r.file}; restart the engine to apply` : `connector ${name} is already mounted in ${r.file}`);
+    return 0;
+}
+const PROTOCOL_VERSION = '2025-11-25';
+const STATUS_TIMEOUT_MS = 10_000;
+const KILL_GRACE_MS = 2_000;
+const SHOWN_LINES = 5;
+const RECEIPT_PREFIX = 'sema-connector: receipt ';
+function ownManifest() {
+    const url = new URL('../package.json', import.meta.url);
+    const manifest = JSON.parse(readFileSync(url, 'utf8'));
+    return { version: manifest.version, launcher: join(dirname(fileURLToPath(url)), manifest.bin['sema-connector'] ?? '') };
+}
+function lineReader(stream) {
+    const lines = [];
+    const waiters = [];
+    let rest = '';
+    let ended = false;
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        rest += chunk;
+        let at;
+        while ((at = rest.indexOf('\n')) !== -1) {
+            const line = rest.slice(0, at);
+            rest = rest.slice(at + 1);
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                lines.push(line);
+        }
+    });
+    stream.on('close', () => {
+        ended = true;
+        for (const waiter of waiters.splice(0))
+            waiter(null);
+    });
+    return () => {
+        const line = lines.shift();
+        if (line !== undefined)
+            return Promise.resolve(line);
+        if (ended)
+            return Promise.resolve(null);
+        return new Promise((resolve) => waiters.push(resolve));
+    };
+}
+export async function statusCommand(name, configDir) {
+    const { program, say, complain } = cliOutput(name);
+    const own = ownManifest();
+    const child = spawn(process.execPath, [own.launcher, 'run', name, '--mode', 'standalone', '--transport', 'stdio', '--config-dir', configDir], { stdio: ['pipe', 'pipe', 'pipe'] });
+    const exited = new Promise((resolve) => child.on('exit', (code) => resolve(code)));
+    const errors = [];
+    child.stderr.on('data', (d) => errors.push(d));
+    child.stdin.on('error', () => undefined);
+    const nextLine = lineReader(child.stdout);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.stdout.destroy();
+        child.stderr.destroy();
+        child.kill('SIGTERM');
+        setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS).unref();
+    }, STATUS_TIMEOUT_MS);
+    const write = (message) => void child.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n');
+    const reply = async (id, method, params) => {
+        write({ id, method, ...(params === undefined ? {} : { params }) });
+        for (;;) {
+            const line = await nextLine();
+            if (line === null)
+                return null;
+            try {
+                const m = JSON.parse(line);
+                if (m?.id === id)
+                    return m;
+            }
+            catch { }
+        }
+    };
+    let found = null;
+    let problem = null;
+    try {
+        const init = await reply(1, 'initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: program, version: own.version } });
+        if (init?.result === undefined)
+            problem = 'the launcher did not complete initialize';
+        else {
+            write({ method: 'notifications/initialized' });
+            const list = await reply(2, 'resources/list');
+            const entries = list?.result?.resources;
+            const uri = Array.isArray(entries) && entries.length === 1 ? entries[0]?.uri : undefined;
+            if (typeof uri !== 'string')
+                problem = 'the launcher did not list exactly one resource, its status';
+            else {
+                const read = await reply(3, 'resources/read', { uri });
+                const text = read?.result?.contents?.[0]?.text;
+                if (typeof text !== 'string')
+                    problem = `the status could not be read${typeof read?.error?.message === 'string' ? `: ${read.error.message}` : ''}`;
+                else
+                    found = JSON.parse(text);
+            }
+        }
+    }
+    catch {
+        problem = 'the launcher answered with something that is not JSON';
+    }
+    finally {
+        child.stdin.end();
+    }
+    const code = await exited;
+    clearTimeout(timer);
+    if (found !== null && !timedOut) {
+        say(JSON.stringify(found));
+        return 0;
+    }
+    complain(timedOut ? `the launcher did not answer within ${STATUS_TIMEOUT_MS} ms` : (problem ?? `the launcher exited with code ${String(code)}`));
+    const said = Buffer.concat(errors).toString('utf8').split('\n').filter((l) => l.trim() !== '' && !l.startsWith(RECEIPT_PREFIX));
+    for (const line of said.slice(-SHOWN_LINES))
+        complain(`the launcher said: ${line}`);
+    return 1;
+}

package/dist/config-dir.d.ts

@@ -0,0 +1,11 @@
+export type Env = Readonly<Record<string, string | undefined>>;
+export declare const given: (v: string | undefined) => v is string;
+export declare function absoluteDir(value: unknown): string | null;
+export type ConfigDirResolution = {
+    readonly ok: true;
+    readonly dir: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function resolveConfigDir(env: Env): ConfigDirResolution;

package/dist/config-dir.js

@@ -0,0 +1,12 @@
+import { isAbsolute, resolve } from 'node:path';
+export const given = (v) => v !== undefined && v !== '';
+export function absoluteDir(value) {
+    return typeof value === 'string' && isAbsolute(value) ? resolve(value) : null;
+}
+export function resolveConfigDir(env) {
+    const value = env.CONFIG_LOCAL_DIR;
+    if (value === undefined || value === '')
+        return { ok: false, reason: 'CONFIG_LOCAL_DIR is not set: it names the configuration directory as an absolute path, and there is no default' };
+    const dir = absoluteDir(value);
+    return dir === null ? { ok: false, reason: 'CONFIG_LOCAL_DIR must be an absolute path' } : { ok: true, dir };
+}

package/dist/connector-name.d.ts

@@ -0,0 +1 @@
+export declare const CONNECTOR_NAME: RegExp;

package/dist/connector-name.js

@@ -0,0 +1 @@
+export const CONNECTOR_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+import type { Principal, PrincipalResolver } from './principal.js';
+import { type JsonRpcId } from './session.js';
+export declare const MCP_PATH = "/mcp";
+export declare const STATUS_PATH = "/status";
+export interface ConnectorLink {
+    send(raw: Buffer, principal: Principal): void;
+    readStatus(id: JsonRpcId, principal: Principal): void;
+    busy(): boolean;
+    end(signal?: NodeJS.Signals): void;
+    readonly gone: Promise<void>;
+}
+export type StartConnector = (deliver: (line: string) => void) => ConnectorLink;
+export interface HttpFaceOptions {
+    readonly host: string;
+    readonly port: number;
+    readonly resolver: PrincipalResolver;
+    readonly start: StartConnector;
+}
+export type HttpFace = {
+    readonly ok: true;
+    close(signal: NodeJS.Signals): Promise<void>;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+export declare function serveHttp(options: HttpFaceOptions): Promise<HttpFace>;