@sema-agent/connectors 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.3.0 (2026-10-15)
+
+### Added
+
+- The default catalog seed (CN-009): `sema-connector seed --config-dir
+  <absolute path>`, the launcher's second command, and `seed({ configDir })`
+  mount every installed connector of the default catalog into
+  `config.d/mcp.json`. The catalog is `DEFAULT_CONNECTORS` (today `gitea` and
+  `github`, CN-044),
+  the one list of default connectors; `SEED_VERSION` is the newest version
+  that added a name. Each connector is resolved with the launcher's own rule
+  first (one that is not installed gets no entry) and mounted only through
+  `mount`, so another entry under its name is never overwritten.
+  `config.d/.sema-connector-seed.json` records what each name came to
+  (mounted, present, not installed): a name recorded as mounted or present is
+  never mounted again, so an entry a person removed stays removed; a conflict
+  or a refusal is not recorded and is tried again. Seeds on one directory
+  exclude each other with `config.d/.sema-connector-seed.json.lock` (a second
+  seed refuses as `locked`). One line per connector on stdout; exit 0 when
+  every connector is mounted, present or not installed, 1 otherwise. A marker
+  the seed cannot read refuses it before any mount; a marker write that fails
+  leaves the old marker as it was and the mounted entries in place.
+- `pinnedUpstream({ connector, upstream, lockFile, handles })` (CN-044): what
+  a connector that runs a third-party MCP server takes from the shared layer,
+  so that no connector package carries its own copy. `install(configDir)` is
+  the install subcommand: this platform's release archive from the source the
+  package's `binaries.lock.json` gives (`https`, redirects followed only to
+  `https`, or `file` for a local copy of the releases), its sha256 compared
+  with the lock before anything is written, then the archive and its
+  `upstream` entry kept in `<configuration directory>/connectors/<name>/bin/`
+  (directory 0700, program 0755), each file written whole before it replaces
+  the old one; nothing changes when the pinned build is there. `start(env)`
+  checks `CONNECTOR_DIR`, one `<NAME>_FILE` per handle naming a regular file
+  (not a symbolic link) inside it, and the pinned build in the bin directory
+  (the same check as install's), and refuses with a sentence naming what to
+  run; its `run(args, extra)` starts the program as the connector's child on
+  the same standard input, output and error, with the connector's environment
+  minus `CONNECTOR_DIR` and the handle paths plus `extra`, passes `SIGTERM`,
+  `SIGINT` and `SIGHUP` on, and ends as the program ends. The Gitea connector
+  is its first user (moved from its own package) and the GitHub connector its
+  second.
+
+### Changed
+
+- A launcher command line that starts with neither `run` nor `seed` is
+  refused with `expected the command "run" or "seed"` (exit 2, as before).
+- `readStdinJson` with one key names it as "the key" in its refusals
+  (`the object must have exactly the key token`); with two or more keys the
+  wording is as before.
+
 ## 0.2.0 (2026-10-15)
 
 ### Added

package/dist/cli-kit.d.ts

@@ -28,6 +28,7 @@ export type StdinJson = {
     readonly ok: false;
     readonly problem: string;
 };
+export declare const listed: (keys: readonly string[]) => 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

@@ -63,12 +63,13 @@ export async function readStdinLine(limit) {
         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 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`;
+    const exactly = keys.length === 1 ? `exactly the key ${listed(keys)}` : `exactly the keys ${listed(keys)}`;
+    const shape = `standard input must be one JSON object with ${exactly}, ${keys.length === 1 ? 'a string' : 'each a string'}, on one line`;
     let value;
     try {
         value = JSON.parse(read.line);
@@ -83,7 +84,7 @@ export async function readStdinJson(limit, keys) {
     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)}` };
+        return { ok: false, problem: `the object must have ${exactly}` };
     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]])) };

package/dist/index.d.ts

@@ -6,7 +6,11 @@ export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion }
 export type { AnonymousPrincipal, AssertionPrincipal, AssertionStep, Principal, PrincipalResolver, PrincipalResult, RequestContext, VerifyOptions, VerifyResult, } from './principal.js';
 export { mount } from './mount.js';
 export type { MountOptions, MountRefusal, MountResult } from './mount.js';
+export { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
+export type { DefaultConnector, SeedOptions, SeedReading, SeedRefusal, SeedResult } from './seed.js';
 export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
 export type { CliOutput, ConnectorCommands, StdinJson, StdinLine } from './cli-kit.js';
 export { isLoopbackHttpOrHttps } from './jwks.js';
+export { pinnedUpstream } from './pinned-upstream.js';
+export type { PinnedUpstream, PinnedUpstreamOptions, UpstreamStart } from './pinned-upstream.js';
 export { writeAll } from './write-all.js';

package/dist/index.js

@@ -2,6 +2,8 @@ export { resolveConfigDir } from './config-dir.js';
 export { openFileSecrets } from './secrets.js';
 export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion } from './principal.js';
 export { mount } from './mount.js';
+export { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
 export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
 export { isLoopbackHttpOrHttps } from './jwks.js';
+export { pinnedUpstream } from './pinned-upstream.js';
 export { writeAll } from './write-all.js';

package/dist/launcher.js

@@ -1,20 +1,21 @@
 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 { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { 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 { resolveConnector } from './resolve-connector.js';
 import { NO_HANDLES, copyForLaunch, handleDirectory } from './secrets.js';
+import { seed } from './seed.js';
 import { INSPECT_LIMIT_BYTES, Session } from './session.js';
 import { mintStatus } from './status.js';
-const EXIT = { ok: 0, guard: 2, notInstalled: 4, connectorFailed: 5 };
+import { writeFailure } from './write-all.js';
+const EXIT = { ok: 0, notSeeded: 1, guard: 2, notInstalled: 4, connectorFailed: 5 };
 const NOT_INSTALLED = 'connector.not_installed';
 const INTERNAL = 'connector.internal';
 const STOP_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
@@ -22,21 +23,15 @@ 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 USAGE = 'usage: sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]\n       sema-connector seed --config-dir <absolute path>';
 const FLAGS = ['--mode', '--transport', '--listen', '--config-dir'];
+const SEED_FLAGS = ['--config-dir'];
 const CHILD_ENV = ['HOME', 'LOGNAME', 'USER', 'PATH', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ'];
 const CONNECTOR_DIR = 'CONNECTOR_DIR';
-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>)';
+function flagValues(argv, from, allowed) {
     const values = new Map();
-    for (let i = 2; i < argv.length; i += 2) {
-        const flag = FLAGS.find((f) => f === argv[i]);
+    for (let i = from; i < argv.length; i += 2) {
+        const flag = allowed.find((f) => f === argv[i]);
         if (flag === undefined)
             return `unknown argument at position ${i + 1}`;
         if (values.has(flag))
@@ -46,6 +41,31 @@ function guard(argv, env) {
             return `${flag} needs a value`;
         values.set(flag, value);
     }
+    return values;
+}
+function guard(argv, env) {
+    if (argv[0] === 'seed') {
+        const values = flagValues(argv, 1, SEED_FLAGS);
+        if (typeof values === 'string')
+            return values;
+        const configDirArgument = values.get('--config-dir');
+        if (configDirArgument === undefined)
+            return 'seed requires --config-dir <absolute path>, the configuration directory it seeds (there is no default)';
+        const configDir = absoluteDir(configDirArgument);
+        if (configDir === null)
+            return '--config-dir must be an absolute path';
+        return { command: 'seed', configDir };
+    }
+    if (argv[0] !== 'run')
+        return 'expected the command "run" or "seed"';
+    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 = flagValues(argv, 2, FLAGS);
+    if (typeof values === 'string')
+        return values;
     const mode = values.get('--mode');
     const transport = values.get('--transport');
     const listen = values.get('--listen');
@@ -68,7 +88,7 @@ function guard(argv, env) {
         const configDir = absoluteDir(configDirArgument);
         if (configDir === null)
             return '--config-dir must be an absolute path';
-        return { name, mode, configDir };
+        return { command: 'run', name, mode, configDir };
     }
     if (transport !== 'http')
         return 'hosted mode requires --transport http';
@@ -88,7 +108,7 @@ function guard(argv, env) {
     const keySet = keySetSource(env, issuer);
     if (typeof keySet === 'string')
         return keySet;
-    return { name, mode, listen: address, issuer, audience, keySet };
+    return { command: 'run', name, mode, listen: address, issuer, audience, keySet };
 }
 function listenAddress(value) {
     const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):([1-9][0-9]{0,4})$/.exec(value);
@@ -99,31 +119,6 @@ function listenAddress(value) {
     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 = [];
@@ -527,6 +522,24 @@ async function runHosted(plan, keys, packageName, binPath, env, log) {
     setTimeout(abandon, TEARDOWN_STEP_MS);
     return EXIT.ok;
 }
+const readingLine = (r) => `seed: ${r.name} ${r.outcome}${r.outcome === 'not_installed' ? ` (${r.message})` : r.outcome === 'refused' ? ` (${r.reason}: ${r.message})` : ''}\n`;
+function runSeed(configDir, stdout, log) {
+    let result;
+    try {
+        result = seed({ configDir });
+    }
+    catch (e) {
+        log.line(`sema-connector: seed: failed (${writeFailure(e)}); the marker was not written\n`);
+        return EXIT.notSeeded;
+    }
+    for (const r of result.readings)
+        stdout.write(readingLine(r));
+    if (!result.ok) {
+        log.line(`sema-connector: seed: ${result.reason}: ${result.message}\n`);
+        return EXIT.notSeeded;
+    }
+    return result.readings.every((r) => r.outcome === 'mounted' || r.outcome === 'present' || r.outcome === 'not_installed') ? EXIT.ok : EXIT.notSeeded;
+}
 export async function main(argv, env) {
     const stdout = new Out(process.stdout);
     const log = new Log(new Out(process.stderr));
@@ -539,6 +552,8 @@ export async function main(argv, env) {
         log.line(`sema-connector: ${plan}\n${USAGE}\n`);
         return finish(EXIT.guard);
     }
+    if (plan.command === 'seed')
+        return finish(runSeed(plan.configDir, stdout, log));
     if (plan.mode === 'hosted') {
         const keys = await obtainKeySet(plan.keySet);
         if (!keys.ok) {

package/dist/mount.d.ts

@@ -12,6 +12,10 @@ export type MountResult = {
     readonly reason: MountRefusal;
     readonly message: string;
 };
+export declare function nameRefusal(name: unknown): {
+    readonly reason: 'invalid_name' | 'reserved_name';
+    readonly message: string;
+} | null;
 export declare function standaloneEntry(name: string, configDir: string): {
     name: string;
     transport: {

package/dist/mount.js

@@ -5,8 +5,15 @@ import { absoluteDir } from './config-dir.js';
 import { CONNECTOR_NAME } from './connector-name.js';
 import { skipWhitespace, spansOf } from './json-text.js';
 import { takeLockFile } from './lock-file.js';
-import { writeAll } from './write-all.js';
+import { writeAll, writeFailure } from './write-all.js';
 const RESERVED_NAMES = ['sema-connector'];
+export function nameRefusal(name) {
+    if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
+        return { reason: 'invalid_name', message: 'a connector name is lowercase letters and digits in hyphen-separated words' };
+    if (RESERVED_NAMES.includes(name))
+        return { reason: 'reserved_name', message: `${name} is a reserved name` };
+    return null;
+}
 export function standaloneEntry(name, configDir) {
     return { name, transport: { kind: 'stdio', command: 'sema-connector', args: ['run', name, '--mode', 'standalone', '--transport', 'stdio', '--config-dir', configDir] } };
 }
@@ -71,10 +78,6 @@ function plan(before, entry) {
     return { text };
 }
 const LOCK_FILE = '.mcp.json.lock';
-const failure = (e) => {
-    const code = e?.code;
-    return typeof code === 'string' ? code : e instanceof Error ? e.message : 'unknown error';
-};
 const readOrNull = (file) => {
     try {
         return readFileSync(file, 'utf8');
@@ -88,10 +91,9 @@ const readOrNull = (file) => {
 export function mount(options) {
     const refuse = (reason, message) => ({ ok: false, reason, message });
     const name = options?.name;
-    if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
-        return refuse('invalid_name', 'a connector name is lowercase letters and digits in hyphen-separated words');
-    if (RESERVED_NAMES.includes(name))
-        return refuse('reserved_name', `${name} is a reserved name`);
+    const named = nameRefusal(name);
+    if (named !== null)
+        return refuse(named.reason, named.message);
     const configDir = absoluteDir(options.configDir);
     if (configDir === null)
         return refuse('config_dir', 'configDir must be the configuration directory as an absolute path; mount reads no environment variable and has no default');
@@ -103,7 +105,7 @@ export function mount(options) {
         unlock = takeLockFile(join(dir, LOCK_FILE));
     }
     catch (e) {
-        return refuse('write_failed', `config.d or its lock could not be written (${failure(e)}); config.d/mcp.json was left as it was`);
+        return refuse('write_failed', `config.d or its lock could not be written (${writeFailure(e)}); config.d/mcp.json was left as it was`);
     }
     if (unlock === null)
         return refuse('locked', `another mount is writing config.d/mcp.json; try again, and if no mount is running remove config.d/${LOCK_FILE}`);
@@ -154,7 +156,7 @@ function write(file, entry, refuse) {
     }
     catch (e) {
         rmSync(tmp, { force: true });
-        return refuse('write_failed', `config.d/mcp.json could not be written (${failure(e)}); it was left as it was and nothing else was written`);
+        return refuse('write_failed', `config.d/mcp.json could not be written (${writeFailure(e)}); it was left as it was and nothing else was written`);
     }
     return { ok: true, changed: true, file };
 }

package/dist/pinned-upstream.d.ts

@@ -0,0 +1,21 @@
+import { type Env } from './config-dir.js';
+export interface PinnedUpstreamOptions {
+    readonly connector: string;
+    readonly upstream: string;
+    readonly lockFile: URL;
+    readonly handles: readonly string[];
+}
+export type UpstreamStart = {
+    readonly ok: true;
+    readonly connectorDir: string;
+    readonly files: Readonly<Record<string, string>>;
+    run(args: readonly string[], extra: Readonly<Record<string, string>>): Promise<number>;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export interface PinnedUpstream {
+    install(configDir: string): Promise<number>;
+    start(env: Env): UpstreamStart;
+}
+export declare function pinnedUpstream(options: PinnedUpstreamOptions): PinnedUpstream;

package/dist/pinned-upstream.js

@@ -0,0 +1,347 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { get as httpsGet } from 'node:https';
+import { constants as osConstants } from 'node:os';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cliOutput, listed } from './cli-kit.js';
+import { given } from './config-dir.js';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { entryOf } from './release-archive.js';
+import { HANDLE_NAME, openFileSecrets } from './secrets.js';
+import { writeAll } from './write-all.js';
+const CONNECTOR_DIR = 'CONNECTOR_DIR';
+const BIN_DIR = 'bin';
+const DIRECTORY_MODE = 0o700;
+const BINARY_MODE = 0o755;
+const ARCHIVE_MODE = 0o644;
+const DOWNLOAD_LIMIT = 256 * 1024 * 1024;
+const DOWNLOAD_IDLE_MS = 120_000;
+const REDIRECT_LIMIT = 5;
+const SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+const PLATFORM = /^[a-z0-9]+-[a-z0-9]+$/;
+const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const platformKey = () => `${process.platform}-${process.arch}`;
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keysAre = (v, keys) => Object.keys(v).sort().join('\0') === [...keys].sort().join('\0');
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const below = (dir, file) => {
+    if (!isAbsolute(file))
+        return false;
+    const r = relative(dir, file);
+    return r !== '' && !isAbsolute(r) && r.split(sep)[0] !== '..';
+};
+const isRegularFile = (path) => {
+    try {
+        return lstatSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+function regularFile(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return null;
+    }
+    try {
+        return fstatSync(fd).isFile() ? readFileSync(fd) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function fetchHttps(url, redirects) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        const req = httpsGet(url, (res) => {
+            const status = res.statusCode ?? 0;
+            const location = res.headers.location;
+            if (status >= 300 && status < 400 && location !== undefined) {
+                res.resume();
+                let next;
+                try {
+                    next = new URL(location, url);
+                }
+                catch {
+                    return done({ ok: false, problem: 'the download was redirected to something that is not a URL' });
+                }
+                if (redirects === 0)
+                    return done({ ok: false, problem: `the download was redirected more than ${REDIRECT_LIMIT} times` });
+                if (next.protocol !== 'https:' || next.username !== '' || next.password !== '')
+                    return done({ ok: false, problem: 'the download was redirected away from https' });
+                return void fetchHttps(next, redirects - 1).then(done);
+            }
+            if (status !== 200) {
+                res.resume();
+                return done({ ok: false, problem: `the download answered HTTP ${status}` });
+            }
+            const parts = [];
+            let size = 0;
+            res.on('data', (d) => {
+                size += d.length;
+                if (size > DOWNLOAD_LIMIT) {
+                    req.destroy();
+                    done({ ok: false, problem: `the archive is larger than ${DOWNLOAD_LIMIT} bytes` });
+                }
+                else
+                    parts.push(d);
+            });
+            res.on('end', () => done({ ok: true, bytes: Buffer.concat(parts) }));
+            res.on('error', () => done({ ok: false, problem: 'the download broke off' }));
+        });
+        req.setTimeout(DOWNLOAD_IDLE_MS, () => req.destroy(new Error(`no data for ${DOWNLOAD_IDLE_MS / 1000} s`)));
+        req.on('error', (e) => done({ ok: false, problem: `the download failed (${e.message})` }));
+    });
+}
+async function fetchArchive(url) {
+    if (url.protocol === 'https:')
+        return fetchHttps(url, REDIRECT_LIMIT);
+    const path = fileURLToPath(url);
+    try {
+        const st = statSync(path);
+        if (!st.isFile())
+            return { ok: false, problem: `${path} is not a file` };
+        if (st.size > DOWNLOAD_LIMIT)
+            return { ok: false, problem: `the archive is larger than ${DOWNLOAD_LIMIT} bytes` };
+        return { ok: true, bytes: readFileSync(path) };
+    }
+    catch {
+        return { ok: false, problem: `${path} cannot be read` };
+    }
+}
+export function pinnedUpstream(options) {
+    const { connector, upstream, lockFile } = options ?? {};
+    if (typeof connector !== 'string' || !CONNECTOR_NAME.test(connector))
+        throw new Error('connector must be lowercase letters and digits in hyphen-separated words');
+    if (typeof upstream !== 'string' || !FILE.test(upstream))
+        throw new Error('upstream must be a file name: letters, digits, dots, underscores and hyphens, starting with a letter or digit');
+    if (!(lockFile instanceof URL) || lockFile.protocol !== 'file:')
+        throw new Error('lockFile must be a file URL');
+    const handles = options.handles;
+    if (!Array.isArray(handles) || !handles.every((h) => typeof h === 'string' && HANDLE_NAME.test(h)) || new Set(handles).size !== handles.length)
+        throw new Error('handles must list handle names, each once');
+    const { program, say, complain } = cliOutput(connector);
+    const fileVars = handles.map((h) => `${h}_FILE`);
+    const binaryOf = (connectorDir) => join(connectorDir, BIN_DIR, upstream);
+    function pinnedBuild() {
+        const refuse = (problem) => ({ ok: false, problem: `binaries.lock.json ${problem}` });
+        const isBuild = (v) => isObject(v) && keysAre(v, ['file', 'sha256']) && typeof v.file === 'string' && FILE.test(v.file) && v.file !== upstream && typeof v.sha256 === 'string' && SHA256.test(v.sha256);
+        let doc;
+        try {
+            doc = JSON.parse(readFileSync(lockFile, 'utf8'));
+        }
+        catch {
+            return refuse('cannot be read as JSON');
+        }
+        if (!isObject(doc) || !keysAre(doc, [upstream]))
+            return refuse(`must hold exactly one entry, "${upstream}"`);
+        const entry = doc[upstream];
+        if (!isObject(entry) || !keysAre(entry, ['version', 'source', 'platforms']))
+            return refuse('must give exactly version, source and platforms');
+        const { version, source, platforms } = entry;
+        if (typeof version !== 'string' || !VERSION.test(version))
+            return refuse('must give the version as <major>.<minor>.<patch>');
+        if (typeof source !== 'string' || !source.includes('{file}'))
+            return refuse('must give the source as a URL template naming {file}');
+        if (!isObject(platforms) || !Object.entries(platforms).every(([k, v]) => PLATFORM.test(k) && isBuild(v)))
+            return refuse('must map each platform to {"file": <archive name>, "sha256": <64 hex digits>}');
+        const key = platformKey();
+        const build = Object.hasOwn(platforms, key) ? platforms[key] : undefined;
+        if (!isBuild(build))
+            return refuse(`pins no ${upstream} build for ${key}`);
+        return { ok: true, lock: { version, source, platforms: platforms }, build };
+    }
+    function sourceOf(lock, build) {
+        let url;
+        try {
+            url = new URL(lock.source.replaceAll('{version}', lock.version).replaceAll('{file}', build.file));
+        }
+        catch {
+            return { ok: false, problem: 'the source in binaries.lock.json is not a URL' };
+        }
+        if (url.protocol === 'https:' && url.username === '' && url.password === '')
+            return { ok: true, url };
+        if (url.protocol === 'file:' && (url.host === '' || url.host === 'localhost'))
+            return { ok: true, url };
+        return { ok: false, problem: 'the source in binaries.lock.json must be an https or file URL (an https URL without credentials)' };
+    }
+    function installedProblem(connectorDir, build) {
+        const dir = join(connectorDir, BIN_DIR);
+        let st;
+        try {
+            st = lstatSync(dir);
+        }
+        catch {
+            return `${upstream} is not installed`;
+        }
+        if (!st.isDirectory() || (st.mode & 0o777) !== DIRECTORY_MODE)
+            return 'the bin directory of the connector is not a 0700 directory';
+        const archive = regularFile(join(dir, build.file));
+        if (archive === null)
+            return `${upstream} is not installed (the pinned archive is not there)`;
+        if (sha256(archive) !== build.sha256)
+            return 'the archive there is not the one binaries.lock.json pins';
+        const entry = entryOf(archive, upstream);
+        if (!entry.ok)
+            return `the pinned archive ${entry.problem}`;
+        const binary = binaryOf(connectorDir);
+        const bytes = regularFile(binary);
+        if (bytes === null || !bytes.equals(entry.bytes))
+            return `${upstream} there is not the entry of the pinned archive`;
+        if ((lstatSync(binary).mode & 0o777) !== BINARY_MODE)
+            return `${upstream} there is not mode 0755`;
+        return null;
+    }
+    function writeAtomically(path, bytes, mode) {
+        const tmp = join(dirname(path), `.${upstream}.${randomBytes(6).toString('hex')}.tmp`);
+        try {
+            const fd = openSync(tmp, 'wx', mode);
+            try {
+                fchmodSync(fd, mode);
+                writeAll(fd, bytes);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(tmp, path);
+        }
+        catch (e) {
+            rmSync(tmp, { force: true });
+            throw e;
+        }
+    }
+    async function install(configDir) {
+        const pinned = pinnedBuild();
+        if (!pinned.ok) {
+            complain(`${pinned.problem}; nothing was installed`);
+            return 1;
+        }
+        const { lock, build } = pinned;
+        const secrets = openFileSecrets({ configDir, connector });
+        const before = secrets.list();
+        if (!before.ok) {
+            complain(`${before.problem}; nothing was installed`);
+            return 1;
+        }
+        const connectorDir = secrets.directory;
+        const binDir = join(connectorDir, BIN_DIR);
+        if (installedProblem(connectorDir, build) === null) {
+            say(`${upstream} ${lock.version} is already installed in ${binDir}; nothing changed`);
+            return 0;
+        }
+        const source = sourceOf(lock, build);
+        if (!source.ok) {
+            complain(`${source.problem}; nothing was installed`);
+            return 1;
+        }
+        const fetched = await fetchArchive(source.url);
+        if (!fetched.ok) {
+            complain(`${build.file} could not be fetched: ${fetched.problem}; nothing was installed`);
+            return 1;
+        }
+        const actual = sha256(fetched.bytes);
+        if (actual !== build.sha256) {
+            complain(`the fetched ${build.file} does not match binaries.lock.json (sha256 ${actual}, pinned ${build.sha256}); nothing was installed`);
+            return 1;
+        }
+        const entry = entryOf(fetched.bytes, upstream);
+        if (!entry.ok) {
+            complain(`the pinned archive ${build.file} ${entry.problem}; nothing was installed`);
+            return 1;
+        }
+        try {
+            mkdirSync(binDir, { recursive: true, mode: DIRECTORY_MODE });
+            const after = secrets.list();
+            if (!after.ok)
+                throw new Error(after.problem);
+            const st = lstatSync(binDir);
+            if (!st.isDirectory())
+                throw new Error('the bin directory of the connector is not a directory');
+            chmodSync(binDir, DIRECTORY_MODE);
+            writeAtomically(join(binDir, build.file), fetched.bytes, ARCHIVE_MODE);
+            writeAtomically(binaryOf(connectorDir), entry.bytes, BINARY_MODE);
+        }
+        catch (e) {
+            complain(`${upstream} was not installed: ${e instanceof Error ? e.message : 'unknown error'}`);
+            return 1;
+        }
+        const problem = installedProblem(connectorDir, build);
+        if (problem !== null) {
+            complain(`${upstream} was written but does not read back as the pinned build: ${problem}`);
+            return 1;
+        }
+        say(`installed ${upstream} ${lock.version} (${build.file}, sha256 ${build.sha256}) in ${binDir}`);
+        return 0;
+    }
+    function run(binary, args, env) {
+        return new Promise((resolve) => {
+            const child = spawn(binary, [...args], { stdio: 'inherit', env });
+            const forwarders = SIGNALS.map((signal) => [signal, () => void child.kill(signal)]);
+            for (const [signal, forward] of forwarders)
+                process.on(signal, forward);
+            const stopForwarding = () => {
+                for (const [signal, forward] of forwarders)
+                    process.off(signal, forward);
+            };
+            child.on('error', (e) => {
+                stopForwarding();
+                complain(`${upstream} could not be started (${e.code ?? e.message})`);
+                resolve(1);
+            });
+            child.on('exit', (code, signal) => {
+                stopForwarding();
+                if (signal !== null) {
+                    process.kill(process.pid, signal);
+                    setTimeout(() => resolve(128 + (osConstants.signals[signal] ?? 0)), 1000);
+                    return;
+                }
+                resolve(code ?? 1);
+            });
+        });
+    }
+    function start(env) {
+        const refuse = (problem) => ({ ok: false, problem });
+        const connectorDir = env[CONNECTOR_DIR];
+        if (!given(connectorDir) || !isAbsolute(connectorDir))
+            return refuse(`${CONNECTOR_DIR} does not name the connector's directory: start the connector with sema-connector run ${connector}`);
+        const paths = fileVars.map((v) => env[v]);
+        if (!paths.every(given))
+            return refuse(`connector ${connector} has no ${listed(handles)} ${handles.length === 1 ? 'handle' : 'handles'} to start ${upstream} with: store ${handles.length === 1 ? 'it' : 'them'} with ${program} auth`);
+        if (!paths.every((p) => below(connectorDir, p) && isRegularFile(p)))
+            return refuse(`${listed(fileVars)} must name files in the connector's directory (${CONNECTOR_DIR}), as the launcher hands ${handles.length === 1 ? 'it' : 'them'}: start the connector with sema-connector run ${connector}`);
+        const pinned = pinnedBuild();
+        if (!pinned.ok)
+            return refuse(pinned.problem);
+        const problem = installedProblem(connectorDir, pinned.build);
+        if (problem !== null)
+            return refuse(`${problem}: run ${program} install`);
+        const own = {};
+        for (const [k, v] of Object.entries(env))
+            if (v !== undefined && k !== CONNECTOR_DIR && !fileVars.includes(k))
+                own[k] = v;
+        const binary = binaryOf(connectorDir);
+        return {
+            ok: true,
+            connectorDir,
+            files: Object.fromEntries(handles.map((h, i) => [h, paths[i]])),
+            run: (args, extra) => run(binary, args, { ...own, ...extra }),
+        };
+    }
+    return { install, start };
+}

package/dist/release-archive.d.ts

@@ -0,0 +1,8 @@
+export type Entry = {
+    readonly ok: true;
+    readonly bytes: Buffer;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function entryOf(archive: Buffer, wanted: string): Entry;

package/dist/release-archive.js

@@ -0,0 +1,96 @@
+import { gunzipSync } from 'node:zlib';
+const BLOCK = 512;
+const UNPACKED_LIMIT = 512 * 1024 * 1024;
+function text(h, at, length) {
+    const raw = h.subarray(at, at + length);
+    const end = raw.indexOf(0);
+    return raw.subarray(0, end === -1 ? length : end).toString('utf8');
+}
+function octal(h, at, length) {
+    const t = text(h, at, length).trim();
+    return /^[0-7]+$/.test(t) ? parseInt(t, 8) : null;
+}
+function pax(body) {
+    const out = {};
+    for (let at = 0; at < body.length;) {
+        const space = body.indexOf(0x20, at);
+        const length = space === -1 ? NaN : Number(body.subarray(at, space).toString('latin1'));
+        if (!Number.isInteger(length) || length <= space - at || at + length > body.length)
+            return null;
+        const record = body.subarray(space + 1, at + length - 1).toString('utf8');
+        const eq = record.indexOf('=');
+        if (eq === -1)
+            return null;
+        const key = record.slice(0, eq);
+        const value = record.slice(eq + 1);
+        if (key === 'path')
+            out.path = value;
+        if (key === 'size') {
+            if (!/^[0-9]+$/.test(value))
+                return null;
+            out.size = Number(value);
+        }
+        at += length;
+    }
+    return out;
+}
+export function entryOf(archive, wanted) {
+    const refuse = (problem) => ({ ok: false, problem });
+    let tar;
+    try {
+        tar = gunzipSync(archive, { maxOutputLength: UNPACKED_LIMIT });
+    }
+    catch {
+        return refuse('is not a gzip stream within the size limit');
+    }
+    const found = [];
+    let next = {};
+    for (let at = 0;;) {
+        if (at === tar.length)
+            break;
+        if (at + BLOCK > tar.length)
+            return refuse('ends inside a header');
+        const h = tar.subarray(at, at + BLOCK);
+        if (h.every((b) => b === 0))
+            break;
+        let sum = 0;
+        for (let i = 0; i < BLOCK; i++)
+            sum += i >= 148 && i < 156 ? 0x20 : (h[i] ?? 0);
+        if (octal(h, 148, 8) !== sum)
+            return refuse('has a damaged header');
+        const type = h[156] === 0 ? '0' : String.fromCharCode(h[156] ?? 0);
+        const meta = type === 'x' || type === 'g' || type === 'L';
+        const own = octal(h, 124, 12);
+        const size = meta ? own : (next.size ?? own);
+        if (size === null)
+            return refuse('has a damaged header');
+        const start = at + BLOCK;
+        if (start + size > tar.length)
+            return refuse('ends inside an entry');
+        const body = tar.subarray(start, start + size);
+        at = start + Math.ceil(size / BLOCK) * BLOCK;
+        if (type === 'x') {
+            const records = pax(body);
+            if (records === null)
+                return refuse('has a damaged extended header');
+            next = { ...next, ...records };
+            continue;
+        }
+        if (type === 'L') {
+            next = { ...next, path: body.toString('utf8').replace(/\0+$/, '') };
+            continue;
+        }
+        if (type === 'g')
+            continue;
+        const prefix = text(h, 257, 6).startsWith('ustar') ? text(h, 345, 155) : '';
+        const name = next.path ?? (prefix === '' ? text(h, 0, 100) : `${prefix}/${text(h, 0, 100)}`);
+        next = {};
+        if ((type === '0' || type === '7') && name.replace(/^\.\//, '') === wanted)
+            found.push(Buffer.from(body));
+    }
+    if (found.length === 0)
+        return refuse(`holds no ${wanted}`);
+    if (found.length > 1)
+        return refuse(`holds ${wanted} more than once`);
+    return { ok: true, bytes: found[0] };
+}

package/dist/resolve-connector.d.ts

@@ -0,0 +1,8 @@
+export type Resolution = {
+    readonly packageName: string;
+    readonly binPath: string;
+} | {
+    readonly packageName: string;
+    readonly reason: string;
+};
+export declare function resolveConnector(name: string): Resolution;

package/dist/resolve-connector.js

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+export 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) };
+}

package/dist/seed.d.ts

@@ -0,0 +1,35 @@
+import { type MountRefusal } from './mount.js';
+export interface DefaultConnector {
+    readonly name: string;
+    readonly since: number;
+}
+export declare const DEFAULT_CONNECTORS: readonly DefaultConnector[];
+export declare const SEED_VERSION: number;
+export interface SeedOptions {
+    readonly configDir: string;
+}
+export type SeedReading = {
+    readonly name: string;
+    readonly outcome: 'mounted' | 'present' | 'conflict';
+} | {
+    readonly name: string;
+    readonly outcome: 'not_installed';
+    readonly message: string;
+} | {
+    readonly name: string;
+    readonly outcome: 'refused';
+    readonly reason: MountRefusal;
+    readonly message: string;
+};
+export type SeedRefusal = 'config_dir' | 'locked' | 'unreadable' | 'unexpected_shape' | 'write_failed';
+export type SeedResult = {
+    readonly ok: true;
+    readonly readings: readonly SeedReading[];
+    readonly marker: string;
+} | {
+    readonly ok: false;
+    readonly reason: SeedRefusal;
+    readonly message: string;
+    readonly readings: readonly SeedReading[];
+};
+export declare function seed(options: SeedOptions): SeedResult;

package/dist/seed.js

@@ -0,0 +1,134 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { absoluteDir } from './config-dir.js';
+import { hasRepeatedKey } from './json-text.js';
+import { mount, nameRefusal } from './mount.js';
+import { takeLockFile } from './lock-file.js';
+import { resolveConnector } from './resolve-connector.js';
+import { writeFailure, writeAll } from './write-all.js';
+export const DEFAULT_CONNECTORS = Object.freeze([Object.freeze({ name: 'gitea', since: 1 }), Object.freeze({ name: 'github', since: 1 })]);
+export const SEED_VERSION = newestVersion(DEFAULT_CONNECTORS);
+function newestVersion(catalog) {
+    const names = new Set();
+    for (const c of catalog) {
+        const refusal = nameRefusal(c.name);
+        if (refusal !== null)
+            throw new Error(`the default catalog names a connector mount refuses (${refusal.reason})`);
+        if (names.has(c.name))
+            throw new Error(`the default catalog names ${c.name} twice`);
+        names.add(c.name);
+        if (!Number.isSafeInteger(c.since) || c.since < 1)
+            throw new Error(`the default catalog gives ${c.name} a since that is not a positive integer`);
+    }
+    if (catalog.length === 0)
+        throw new Error('the default catalog is empty');
+    return Math.max(...catalog.map((c) => c.since));
+}
+const MARKER_FILE = '.sema-connector-seed.json';
+const SEED_LOCK_FILE = `${MARKER_FILE}.lock`;
+const RECORDED = ['mounted', 'present', 'not_installed'];
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+function readMarker(file) {
+    const where = `config.d/${MARKER_FILE}`;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { marker: null };
+        return { refusal: 'unreadable', message: `${where} cannot be read` };
+    }
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        return { refusal: 'unreadable', message: `${where} is not valid JSON` };
+    }
+    const shape = `${where} must be one JSON object {"version": <a positive integer>, "entries": {"<name>": "mounted" | "present" | "not_installed"}}`;
+    if (!isObject(doc) || Object.keys(doc).sort().join() !== 'entries,version' || hasRepeatedKey(text))
+        return { refusal: 'unexpected_shape', message: shape };
+    const { version, entries } = doc;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1 || !isObject(entries))
+        return { refusal: 'unexpected_shape', message: shape };
+    for (const [name, value] of Object.entries(entries)) {
+        if (nameRefusal(name) !== null || typeof value !== 'string' || !RECORDED.includes(value))
+            return { refusal: 'unexpected_shape', message: shape };
+    }
+    return { marker: { version, entries: entries } };
+}
+export function seed(options) {
+    const configDir = absoluteDir(options?.configDir);
+    if (configDir === null)
+        return { ok: false, reason: 'config_dir', message: 'configDir must be the configuration directory as an absolute path; the seed reads no environment variable and has no default', readings: [] };
+    const dir = join(configDir, 'config.d');
+    let unlock;
+    try {
+        mkdirSync(dir, { recursive: true });
+        unlock = takeLockFile(join(dir, SEED_LOCK_FILE));
+    }
+    catch (e) {
+        return { ok: false, reason: 'write_failed', message: `config.d or the seed's lock could not be written (${writeFailure(e)}); nothing was mounted`, readings: [] };
+    }
+    if (unlock === null)
+        return { ok: false, reason: 'locked', message: `another seed is running on this directory; nothing was mounted: try again, and if no seed is running remove config.d/${SEED_LOCK_FILE}`, readings: [] };
+    try {
+        return seedLocked(configDir, dir);
+    }
+    finally {
+        unlock();
+    }
+}
+function seedLocked(configDir, dir) {
+    const file = join(dir, MARKER_FILE);
+    const read = readMarker(file);
+    if ('refusal' in read)
+        return { ok: false, reason: read.refusal, message: `${read.message}; nothing was mounted`, readings: [] };
+    const before = read.marker;
+    const entries = { ...before?.entries };
+    const readings = [];
+    for (const { name } of DEFAULT_CONNECTORS) {
+        const recorded = before !== null && Object.hasOwn(before.entries, name) ? before.entries[name] : undefined;
+        if (recorded === 'mounted' || recorded === 'present') {
+            readings.push({ name, outcome: 'present' });
+            continue;
+        }
+        const resolved = resolveConnector(name);
+        if ('reason' in resolved) {
+            readings.push({ name, outcome: 'not_installed', message: `package ${resolved.packageName} ${resolved.reason}` });
+            entries[name] = 'not_installed';
+            continue;
+        }
+        const r = mount({ name, configDir });
+        if (r.ok) {
+            const outcome = r.changed ? 'mounted' : 'present';
+            readings.push({ name, outcome });
+            entries[name] = outcome;
+        }
+        else if (r.reason === 'conflict')
+            readings.push({ name, outcome: 'conflict' });
+        else
+            readings.push({ name, outcome: 'refused', reason: r.reason, message: r.message });
+    }
+    const after = { version: SEED_VERSION, entries };
+    if (before === null || JSON.stringify(after) !== JSON.stringify(before)) {
+        const tmp = join(dir, `${MARKER_FILE}.${randomBytes(6).toString('hex')}.tmp`);
+        try {
+            const fd = openSync(tmp, 'wx', 0o666);
+            try {
+                writeAll(fd, JSON.stringify(after, null, 2) + '\n');
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(tmp, file);
+        }
+        catch (e) {
+            rmSync(tmp, { force: true });
+            return { ok: false, reason: 'write_failed', message: `config.d/${MARKER_FILE} could not be written (${writeFailure(e)}); it was left as it was, and the entries mounted stay mounted`, readings };
+        }
+    }
+    return { ok: true, readings, marker: file };
+}

package/dist/write-all.d.ts

@@ -1 +1,2 @@
 export declare function writeAll(fd: number, data: string | Uint8Array): void;
+export declare function writeFailure(e: unknown): string;

package/dist/write-all.js

@@ -13,3 +13,7 @@ export function writeAll(fd, data) {
     if (size !== bytes.length)
         throw new Error(`the file holds ${size} bytes after a write of ${bytes.length}`);
 }
+export function writeFailure(e) {
+    const code = e?.code;
+    return typeof code === 'string' ? code : e instanceof Error ? e.message : 'unknown error';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared connector layer and the sema-connector launcher (MCP stdio proxy with principal, scope, normalize, status and trace stages).",
   "license": "Apache-2.0",
   "type": "module",