@sema-agent/connectors 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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.6.0 (2026-10-16)
+
+### Changed (breaking)
+
+- `binaries.lock.json`, which `pinnedUpstream` reads (CN-027): an upstream is now
+  any number of archives and one program, `{"<upstream>": {"version",
+  "archives": [{"platform", "file", "source", "sha256", "unpack"}],
+  "program"}}`. An archive names one platform or `"*"` (every platform the lock
+  pins); its file name gives its format (`.tar.gz` or `.tgz`, `.zip`); `unpack`
+  is `{"entry": <name>}` (the one file of the archive, as before) or
+  `{"directory": <top directory>, "to": <path below bin>}` (every entry below
+  that directory). `program` is `{"binary": <path>}` or `{"node": <path>}`, a
+  Node.js script run by the Node.js that runs the connector. The lock of the
+  earlier shape (`source` and `platforms`) is refused; connector packages move
+  to the new shape with this version.
+- `install` fetches every archive of the platform into the bin directory and
+  compares each with its sha256, and checks what it unpacks, before anything is
+  unpacked: an archive that does not match, or cannot be unpacked as the lock
+  says, installs nothing. Archives are streamed to disk instead of held in
+  memory; an archive is kept in the bin directory only once what it unpacks is
+  in place. The start check reads every archive's sha256, compares each tree
+  with its archive's listing (paths, kinds, sizes, modes, link targets; a tree
+  that differs is reinstalled by `install`) and the program with its entry.
+
+### Added
+
+- `readHostUrl(value)` (CN-045): the one rule for an address a connector stores as a non-secret host handle and hands
+  its upstream program (an `https` URL, or an `http` URL on `127.0.0.1` or `localhost`, without credentials, a query
+  or a fragment, stored as the URL's origin and path without a trailing slash); moved here from the Gitea connector's
+  own `readHost` (CN-037), so a second connector that needs a host does not carry a second copy of the rule.
+- `readStdinJson(limit, keys, optional?)` takes a third, optional list of keys a caller's JSON object may also carry
+  besides `keys` (CN-045): the same refusal shape (exactly `keys`, at most `optional` besides them, no other key, a
+  key named twice refused, every value a string). Omitted, behaviour is exactly as before.
+- `pinnedUpstream({ ..., optionalHandles })` (CN-045): handles a connector's server may use when stored, but starts
+  without; given, an optional handle's `<NAME>_FILE` is checked the same way a required one's is (a regular file
+  inside the connector's directory) and named in `UpstreamStart.files`; absent, `start()` does not wait for it. A
+  required or an optional handle's `<NAME>_FILE` is kept from the program either way.
+- Zip archives and archive trees (CN-027): a tree is checked whole before the
+  first byte is written (no entry outside its directory, no `..`, empty or `.`
+  segment, no absolute path, no name twice, nothing below a file or a link, no
+  hard link, device or pipe, a symbolic link only to a relative path below its
+  own directory), written with modes 0644 and 0755 only, zip entries streamed
+  through inflate with their size and CRC-32 checked; at most 1 GiB per
+  archive. Split, ZIP64 and encrypted zip archives are refused.
+- `UpstreamStart.binDir`, the bin directory holding the pinned build.
+
+### Fixed
+
+- The CLI kit's program name follows mount's whole name rule (CN-053): a
+  reserved name such as `sema-connector` is refused with the launcher's own
+  prefix, `sema-connector: mount refused (reserved_name): ...`, as `INTEGRATION.md`
+  says, instead of `sema-connector-sema-connector:`. A copy of the package whose
+  own manifest is out of reach (bundled, KL-14) refuses `statusCommand` in one
+  line with exit 1 instead of failing with a thrown error.
+
+## 0.5.0 (2026-10-15)
+
+### Added
+
+- `FileSecrets.remove(name)` (CN-048): removes a handle's value file and its
+  metadata file together, inside the lock of the connector's directory
+  (unless `withLock` already holds it); returns whether the handle existed
+  before. Absent is a no-op.
+
+### Changed
+
+- `FileSecrets.put` refuses the empty string (CN-048): a handle always has a
+  value, so `put(name, '')` throws a `TypeError` instead of writing one.
+  Nothing is written; an existing handle's value and metadata are untouched
+  byte for byte. A connector that needs to take a handle away uses `remove`.
+
+### Fixed
+
+- A `tools/call` outside the granted scope, sent as a notification (no
+  `id`): the launcher no longer answers it with an id-null
+  `connector.forbidden_scope` error and no longer writes its receipt (CN-047).
+  Nothing answers a notification, whatever refuses it; this already held for
+  a parked session's refusal (CN-046) and now holds for the scope judge's
+  too, the same form (`id === null ? [] : ...`).
+- `mountCommand` (and every CLI kit command) with a connector name `mount`
+  refuses no longer throws before `mount` is called: the refusal arrives as the
+  documented one line on standard error, `mount refused (invalid_name): ...`,
+  with exit 1 (CN-050). `cliOutput` gives such a name the launcher's own program
+  name instead of refusing it itself; the name rule is judged once, by `mount`.
+
 ## 0.4.0 (2026-10-15)
 
 ### Added

package/INTEGRATION.md

@@ -39,7 +39,10 @@ const result = mount({ name: 'gitea', configDir: dir })
 - `mountCommand(name, configDir): number` is the same call with the CLI's output: on success one line on
   standard output (`mounted connector <name> in <file>; restart the engine to apply`, or
   `connector <name> is already mounted in <file>`) and exit 0; on a refusal one line on standard error,
-  `mount refused (<reason>): <message>`, and exit 1. A thin wrapper returns its number as its exit code.
+  `sema-connector-<name>: mount refused (<reason>): <message>`, and exit 1. The prefix is the program name
+  of the connector's own CLI; a name `mount` refuses (`invalid_name`, `reserved_name`) gets the launcher's own,
+  `sema-connector: `, since no connector program exists for it. A thin wrapper returns its number as its
+  exit code and passes both streams through.
 - `mount` does not check that the connector package is installed: an entry for a connector that is not
   installed makes the launcher exit 4 (`connector.not_installed`) when the engine starts it. A tool that
   wants only installed connectors mounted uses the seed.
@@ -58,6 +61,23 @@ const result = mount({ name: 'gitea', configDir: dir })
   command line). A tool that offers "mount the defaults" runs the seed; a tool that offers "mount this one"
   calls `mount`.
 
+## Installing the pieces
+
+`@sema-agent/connectors` is consumed as an installed package, not bundled: `statusCommand` starts the
+`sema-connector` launcher of the very copy it belongs to, and `seed` resolves connector packages from that
+copy's place in `node_modules`, both through the package's own `package.json` (`import.meta.url`), so a copy
+inlined into another program's bundle finds neither and refuses in one line (KL-14 in the repository's
+`docs/KNOWN-LIMITS.md`). `mount` and `mountCommand` have no such dependency.
+
+The entry `mount` writes names the command `sema-connector`; the engine runs it from its `PATH`. The
+launcher is the `bin` of `@sema-agent/connectors`, and a connector is the `bin` of
+`@sema-agent/connector-<name>`, installed where that launcher resolves it (the same `node_modules`, a global
+install, or `NODE_PATH`). A tool that mounts a connector does not install either; it tells the person what to
+install (`npm install -g @sema-agent/connectors @sema-agent/connector-<name>`, then the connector's `install`
+and `auth` with the same `CONFIG_LOCAL_DIR`). An entry whose launcher is not on the engine's `PATH`, or whose
+connector package is not installed, fails at the engine's next start (exit 4, `connector.not_installed`);
+`seed` mounts only connectors the launcher that runs it finds.
+
 ## What the engine sees
 
 Entries are read by the engine from `config.d/mcp.json` through the server's local file configuration

package/dist/cli-kit.d.ts

@@ -29,6 +29,6 @@ export type StdinJson = {
     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 readStdinJson(limit: number, keys: readonly string[], optional?: 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

@@ -1,15 +1,12 @@
 import { spawn } from 'node:child_process';
 import { resolveConfigDir } from './config-dir.js';
-import { CONNECTOR_NAME } from './connector-name.js';
 import { hasRepeatedKey } from './json-text.js';
-import { mount } from './mount.js';
+import { mount, nameRefusal } from './mount.js';
 import { ownManifest } from './own-package.js';
 import { MCP_PROTOCOL_VERSION } from './session.js';
 import { statusUri } from './status.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}`;
+    const program = nameRefusal(name) === null ? `sema-connector-${name}` : 'sema-connector';
     return {
         program,
         say: (line) => void process.stdout.write(`${line}\n`),
@@ -64,12 +61,14 @@ export async function readStdinLine(limit) {
     return { ok: true, line };
 }
 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) {
+export async function readStdinJson(limit, keys, optional = []) {
     const read = await readStdinLine(limit);
     if (!read.ok)
         return read;
-    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`;
+    const all = [...keys, ...optional];
+    const phrase = (how, names) => `${how} the ${names.length === 1 ? 'key' : 'keys'} ${listed(names)}`;
+    const exactly = [...(keys.length > 0 ? [phrase('exactly', keys)] : []), ...(optional.length > 0 ? [phrase('at most', optional)] : [])].join(' and ') || 'no keys';
+    const shape = `standard input must be one JSON object with ${exactly}, ${all.length === 1 ? 'a string' : 'each a string'}, on one line`;
     let value;
     try {
         value = JSON.parse(read.line);
@@ -83,11 +82,11 @@ export async function readStdinJson(limit, keys) {
         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)))
+    if (!keys.every((k) => own.includes(k)) || !own.every((k) => all.includes(k)))
         return { ok: false, problem: `the object must have ${exactly}` };
-    if (!keys.every((k) => typeof object[k] === 'string'))
+    if (!own.every((k) => typeof object[k] === 'string'))
         return { ok: false, problem: shape };
-    return { ok: true, values: Object.fromEntries(keys.map((k) => [k, object[k]])) };
+    return { ok: true, values: Object.fromEntries(own.map((k) => [k, object[k]])) };
 }
 export function mountCommand(name, configDir) {
     const { say, complain } = cliOutput(name);
@@ -145,7 +144,14 @@ function lineReader(stream) {
 }
 export async function statusCommand(name, configDir) {
     const { program, say, complain } = cliOutput(name);
-    const own = ownManifest();
+    let own;
+    try {
+        own = ownManifest();
+    }
+    catch {
+        complain('the package\'s own manifest cannot be read, so its launcher cannot be found: this package is consumed installed, not bundled (INTEGRATION.md, KL-14)');
+        return 1;
+    }
     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 = [];

package/dist/host-url.d.ts

@@ -0,0 +1,8 @@
+export type HostReading = {
+    readonly ok: true;
+    readonly host: string;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function readHostUrl(value: string): HostReading;

package/dist/host-url.js

@@ -0,0 +1,19 @@
+import { isLoopbackHttpOrHttps } from './jwks.js';
+export function readHostUrl(value) {
+    if (/[\s\u0000-\u001f\u007f]/.test(value))
+        return { ok: false, problem: 'the host is not a URL (it holds whitespace or a control character)' };
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { ok: false, problem: 'the host is not a URL' };
+    }
+    if (url.username !== '' || url.password !== '')
+        return { ok: false, problem: 'the host carries credentials; a host URL never does (the token is stored on its own)' };
+    if (!isLoopbackHttpOrHttps(url))
+        return { ok: false, problem: 'the host must be an https URL, or an http URL on 127.0.0.1 or localhost' };
+    if (url.search !== '' || url.hash !== '')
+        return { ok: false, problem: 'the host URL takes no query and no fragment' };
+    return { ok: true, host: url.origin + url.pathname.replace(/\/+$/, '') };
+}

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { DefaultConnector, SeedOptions, SeedReading, SeedRefusal, SeedResul
 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 { readHostUrl } from './host-url.js';
+export type { HostReading } from './host-url.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

@@ -5,5 +5,6 @@ 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 { readHostUrl } from './host-url.js';
 export { pinnedUpstream } from './pinned-upstream.js';
 export { writeAll } from './write-all.js';

package/dist/pinned-upstream.d.ts

@@ -4,10 +4,12 @@ export interface PinnedUpstreamOptions {
     readonly upstream: string;
     readonly lockFile: URL;
     readonly handles: readonly string[];
+    readonly optionalHandles?: readonly string[];
 }
 export type UpstreamStart = {
     readonly ok: true;
     readonly connectorDir: string;
+    readonly binDir: string;
     readonly files: Readonly<Record<string, string>>;
     run(args: readonly string[], extra: Readonly<Record<string, string>>): Promise<number>;
 } | {