@sema-agent/connectors 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ 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.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
+
+- `INTEGRATION.md` ships with the package: how a command-line tool mounts a
+  connector of the default catalog through `mount`, `mountCommand` and `seed`,
+  what it reads back, and what the engine then sees.
+- The parked session (CN-046): in standalone mode the launcher never starts a
+  connector whose status would be `unauthorized` (no secret handle, the
+  status's own judgement); it answers the session itself, through the same
+  session and stages as a connector run. `initialize` is answered with the
+  requested protocol version, the tools and resources capabilities and
+  `serverInfo` `sema-connector` at this package's version; `tools/list` lists
+  no tools, `resources/list` the status entry alone, the status reads
+  `unauthorized` with no tools, and `ping` is answered. A tool call is refused
+  with `-32603`, another resource read with `-32602` and any other method with
+  `-32601`, each with `connector.auth_required` and the message
+  `connector <name> has no credentials; run its auth`; the refused call's
+  receipt is `refused` with `connector.auth_required`. The session ends with
+  exit 0 at the end of input or on a stop signal. So
+  `sema-connector-<name> status` before `auth` prints the `unauthorized`
+  status and exits 0, and an upstream program that would begin a login of its
+  own without a token never starts.
+
+### Changed
+
+- A standalone launcher starts a connector only when it has a secret handle
+  (CN-046). Before, it started every connector, and one that refuses to start
+  without its handles (as the Gitea and GitHub connectors do) ended the run
+  with exit 5 and `connector.internal`. A connector that needs no credential
+  at all is parked as well until a secret handle is stored for it. A connector
+  whose secret handle has expired, and every hosted connector, is started as
+  before.
+
+### Fixed
+
+- `sema-connector-<name> status` (CN-049) no longer discovers the status
+  resource's URI through `resources/list` and then insists on exactly one
+  entry there; it reads the status resource straight by its URI (the one
+  `statusUri` makes). Before, a started connector that lists resources of its
+  own made `resources/list` answer with more than the status entry the
+  launcher adds, so `status` always failed with "the launcher did not list
+  exactly one resource, its status" once authorized, even though the launcher
+  itself serves the status resource correctly. This affected the GitHub
+  connector once authorized (github-mcp-server lists 4 `ui://` resources of
+  its own); the Gitea connector, which lists none, was not affected.
+
 ## 0.3.0 (2026-10-15)
 
 ### Added

package/INTEGRATION.md

@@ -0,0 +1,87 @@
+# Integrating `@sema-agent/connectors` from a command-line tool
+
+How a tool outside this repository (the CLI's `connectors add`, for one) mounts a connector of the default
+catalog into the engine's local configuration and reads what happened, using this package only. The rules
+live in the repository's `docs/ARCHITECTURE.md` ("Mounting", "Seeding the default catalog", "Parked
+session"); this page states the surface a tool consumes and does not restate the rules.
+
+## The configuration directory
+
+One configuration directory per engine installation, the engine's local one: `CONFIG_LOCAL_DIR`, an
+absolute path. `resolveConfigDir(process.env)` turns the variable into `{ ok: true, dir }` or
+`{ ok: false, reason }` (not set, empty, or not absolute; the reason names the variable, never the value).
+It is the same root `sema-connector seed --config-dir <dir>` seeds and the same root every connector CLI
+(`sema-connector-<name> auth | mount | status`) reads from `CONFIG_LOCAL_DIR`. Entries land in
+`<dir>/config.d/mcp.json`; a connector's secrets live in `<dir>/connectors/<name>/`.
+
+## Mounting one connector
+
+```ts
+import { mount, mountCommand, resolveConfigDir, DEFAULT_CONNECTORS, SEED_VERSION, seed } from '@sema-agent/connectors'
+
+const result = mount({ name: 'gitea', configDir: dir })
+```
+
+- `mount(options: { name: string; configDir: string }): MountResult`. There is no `entry` argument: the entry
+  is fixed by the package and written as
+  `{"name": "<name>", "transport": {"kind": "stdio", "command": "sema-connector", "args": ["run", "<name>",
+  "--mode", "standalone", "--transport", "stdio", "--config-dir", "<configDir>"]}}`, never with environment
+  references or headers. A tool never composes an entry of its own.
+- `MountResult` is `{ ok: true, changed: boolean, file: string }` (`changed: false` when the same entry was
+  already there, byte for byte apart from key order; `file` is the catalog file written) or
+  `{ ok: false, reason: MountRefusal, message: string }` with `reason` one of the closed set
+  `config_dir | invalid_name | reserved_name | unreadable | unexpected_shape | conflict | locked |
+  changed_during_write | write_failed`. `mount` does not throw for a refusal.
+- Idempotence: a second `mount` of the same name changes nothing. Another entry under the same name (other
+  arguments, another `--config-dir`, `enabled: false`, environment references) is `conflict` and is never
+  overwritten; the tool reports it and leaves the person to remove the entry. `mount` keeps no marker of
+  its own.
+- `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,
+  `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.
+
+## The default catalog and the seed
+
+- `DEFAULT_CONNECTORS: readonly { name: string; since: number }[]`: the one list of default connectors, in
+  order; `name` is the connector (the package is `@sema-agent/connector-<name>`), `since` the seed version
+  that added it. `SEED_VERSION` is the newest `since`.
+- `seed({ configDir }): SeedResult` mounts every installed connector of the default catalog through `mount`,
+  resolving each with the launcher's own rule first, and remembers the outcome per name in
+  `<dir>/config.d/.sema-connector-seed.json`, so an entry a person removed is never brought back. Readings per
+  name: `mounted | present | conflict | not_installed | refused`; the whole seed is refused as `config_dir |
+  locked | unreadable | unexpected_shape | write_failed`. `sema-connector seed --config-dir <dir>` is the same
+  call as a command (exit 0 when every connector is mounted, present or not installed, 1 otherwise, 2 for a bad
+  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. `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
+(the same path that reads every other stdio entry there); an entry `mount` wrote is read at the engine's next
+start, and the launcher it names reads the connector's secrets under the same directory. Before `auth` has
+stored the connector's credential the launcher parks the session: the connector lists no tools, its status
+reads `unauthorized`, and a tool call is refused with `connector.auth_required`; after `auth`, the next start
+runs the connector.

package/dist/cli-kit.js

@@ -1,15 +1,13 @@
 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';
+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 = typeof name === 'string' && CONNECTOR_NAME.test(name) ? `sema-connector-${name}` : 'sema-connector';
     return {
         program,
         say: (line) => void process.stdout.write(`${line}\n`),
@@ -106,16 +104,10 @@ export function mountCommand(name, configDir) {
     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 = [];
@@ -184,24 +176,17 @@ export async function statusCommand(name, configDir) {
     let found = null;
     let problem = null;
     try {
-        const init = await reply(1, 'initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: program, version: own.version } });
+        const init = await reply(1, 'initialize', { protocolVersion: MCP_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);
-            }
+            const read = await reply(2, 'resources/read', { uri: statusUri(name) });
+            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 {

package/dist/launcher.js

@@ -7,13 +7,14 @@ 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 { ownManifest } from './own-package.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';
+import { INSPECT_LIMIT_BYTES, Session, parkedAnswer } from './session.js';
+import { mintState, mintStatus } from './status.js';
 import { writeFailure } from './write-all.js';
 const EXIT = { ok: 0, notSeeded: 1, guard: 2, notInstalled: 4, connectorFailed: 5 };
 const NOT_INSTALLED = 'connector.not_installed';
@@ -381,31 +382,20 @@ function childEnvironment(env, connectorDir, secrets) {
 const hostedConnectorDir = (name) => join(tmpdir(), `sema-connector-${randomUUID()}`, 'connectors', name);
 const describe = (o) => `connector process ${o.stalled ? `stopped reading its input (stalled input: none of it taken for ${STALL_MS / 1000} s) and ` : ''}${o.error ? `could not be started (${o.error.message})` : o.signal !== null ? `was terminated by signal ${o.signal}` : `exited with code ${String(o.code)}`}`;
 const abnormal = (o) => o.code !== 0 || o.stalled === true;
-function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
-    const child = spawn(process.execPath, [binPath], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env: childEnv });
-    const toGroup = (signal) => {
-        if (child.pid === undefined)
-            return false;
-        try {
-            process.kill(-child.pid, signal);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
-    const toChild = new Out(child.stdin);
-    const perform = (actions) => {
+function performer(log, toUpstream, toConnector) {
+    return (actions) => {
         for (const a of actions) {
             if (a.to === 'receipt')
                 log.line(`${RECEIPT_PREFIX}${asciiJson(a.receipt)}\n`);
             else if (a.to === 'upstream')
                 toUpstream(a.data);
             else
-                toChild.write(a.data);
+                toConnector(a.data);
         }
     };
-    const judged = (judge, unreadable) => {
+}
+function judging(perform) {
+    return (judge, unreadable) => {
         let actions;
         try {
             actions = judge();
@@ -415,6 +405,23 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         }
         perform(actions);
     };
+}
+function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
+    const child = spawn(process.execPath, [binPath], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env: childEnv });
+    const toGroup = (signal) => {
+        if (child.pid === undefined)
+            return false;
+        try {
+            process.kill(-child.pid, signal);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const toChild = new Out(child.stdin);
+    const perform = performer(log, toUpstream, (data) => toChild.write(data));
+    const judged = judging(perform);
     let rung = 0;
     let stopped = false;
     const climb = (to, signal = 'SIGTERM') => {
@@ -458,7 +465,7 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         return ended;
     })();
     return {
-        toChild,
+        input: toChild,
         perform,
         fromUpstream: (line, principal) => judged(() => session.fromUpstream(line, principal), () => session.upstreamOversized()),
         endInput: () => climb(1),
@@ -472,13 +479,37 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         outcome,
     };
 }
-async function runStdio(packageName, binPath, childEnv, session, scrubber, stdout, log) {
+function parkedRun(session, connector, stdout, log) {
+    const serverInfo = { name: 'sema-connector', version: ownManifest().version };
+    let end = () => undefined;
+    const ended = new Promise((resolve) => (end = () => resolve({ code: 0, signal: null })));
+    const perform = performer(log, (data) => stdout.write(data), (data) => {
+        const answer = parkedAnswer(data, connector, serverInfo);
+        if (answer !== null)
+            judged(() => session.fromConnector(Buffer.from(JSON.stringify(answer), 'utf8')), () => session.connectorOversized());
+    });
+    const judged = judging(perform);
+    return {
+        input: stdout,
+        perform,
+        fromUpstream: (line, principal) => judged(() => session.fromUpstream(line, principal), () => session.upstreamOversized()),
+        endInput: end,
+        stop: () => {
+            end();
+            setTimeout(abandon, TEARDOWN_STEP_MS).unref();
+        },
+        outcome: ended.then((outcome) => {
+            perform(session.connectorGone('the launcher ended the parked session', false));
+            return outcome;
+        }),
+    };
+}
+async function runStdio(packageName, run, session, stdout, log) {
     const resolution = standaloneResolver().resolve({ headers: {} });
     if (!resolution.ok)
         throw new Error('the standalone principal cannot be refused');
     const anonymous = resolution.principal;
-    const run = startConnector(binPath, childEnv, session, scrubber, (data) => stdout.write(data), stdout, log);
-    const upstream = pump(process.stdin, run.toChild, { line: (line) => run.fromUpstream(line, anonymous), oversized: () => run.perform(session.upstreamOversized()) }, [stdout]);
+    const upstream = pump(process.stdin, run.input, { line: (line) => run.fromUpstream(line, anonymous), oversized: () => run.perform(session.upstreamOversized()) }, [stdout]);
     void upstream.then(() => run.endInput());
     for (const s of STOP_SIGNALS)
         process.on(s, (signal) => run.stop(signal));
@@ -500,7 +531,7 @@ async function runHosted(plan, keys, packageName, binPath, env, log) {
         const run = startConnector(binPath, childEnvironment(env, hostedConnectorDir(plan.name), NO_HANDLES), session, new Scrubber(NO_HANDLES.values), (data) => deliver(String(data)), null, log, TEARDOWN_STEP_MS);
         return {
             send: (raw, principal) => run.fromUpstream(raw, principal),
-            busy: () => run.toChild.behind(),
+            busy: () => run.input.behind(),
             readStatus: (id, principal) => run.perform(session.statusFor(id, principal)),
             end: (signal) => (signal === undefined ? run.endInput() : run.stop(signal)),
             gone: run.outcome.then((o) => {
@@ -585,14 +616,19 @@ export async function main(argv, env) {
         log.line(`sema-connector: ${NOT_INSTALLED}: package ${resolved.packageName} ${resolved.reason}\n`);
         return finish(EXIT.notInstalled);
     }
+    const parked = mintState({ handles: secrets.handles, nowMs: Date.now() }) === 'unauthorized';
     const session = new Session({
         connector: plan.name,
         status: (tools) => mintStatus({ handles: secrets.handles, nowMs: Date.now(), tools }),
         ownIdPrefix: `sema-connector/${randomUUID()}`,
         withheld: secretMatcher(secrets.values),
+        ...(parked ? { parked: true } : {}),
     });
     try {
-        return finish(await runStdio(resolved.packageName, resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), stdout, log));
+        const run = parked
+            ? parkedRun(session, plan.name, stdout, log)
+            : startConnector(resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), (data) => stdout.write(data), stdout, log);
+        return finish(await runStdio(resolved.packageName, run, session, stdout, log));
     }
     finally {
         secrets.remove();

package/dist/own-package.d.ts

@@ -0,0 +1,4 @@
+export declare function ownManifest(): {
+    readonly version: string;
+    readonly launcher: string;
+};

package/dist/own-package.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export 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'] ?? '') };
+}

package/dist/secrets.d.ts

@@ -20,6 +20,7 @@ export interface FileSecrets {
     readonly directory: string;
     list(): SecretListing;
     put(name: string, value: string, options?: PutOptions): SecretHandle;
+    remove(name: string): boolean;
     withLock<T>(fn: () => T): T;
 }
 export declare const isSecret: (handle: SecretHandle) => boolean;

package/dist/secrets.js

@@ -232,6 +232,8 @@ function putHandle(dir, connector, name, value, options) {
         throw new Error('a handle name is upper-case letters, digits and underscores, starting with a letter');
     if (typeof value !== 'string')
         throw new Error('a secret value is a string');
+    if (value === '')
+        throw new TypeError('a secret value is never the empty string (use remove to take the handle away)');
     if (options.expiresAt !== undefined && !validExpiry(options.expiresAt))
         throw new Error('expiresAt must be an RFC 3339 UTC time ending in Z');
     if (options.secret !== undefined && typeof options.secret !== 'boolean')
@@ -242,6 +244,37 @@ function putHandle(dir, connector, name, value, options) {
         throw new Error(r.problem);
     return r.value;
 }
+function removeHandle(dir, connector, name) {
+    if (!HANDLE_NAME.test(name))
+        throw new Error('a handle name is upper-case letters, digits and underscores, starting with a letter');
+    try {
+        lstatSync(dir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        throw new Error(`connector ${connector}: the secrets directory cannot be read`);
+    }
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        throw new Error(`connector ${connector}: ${dirProblem}`);
+    const r = locked(dir, connector, () => {
+        let existed = true;
+        try {
+            rmSync(join(dir, name));
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            existed = false;
+        }
+        rmSync(join(dir, name + META_SUFFIX), { force: true });
+        return existed;
+    });
+    if (!r.ok)
+        throw new Error(r.problem);
+    return r.value;
+}
 export function openFileSecrets(options) {
     if (typeof options?.configDir !== 'string' || !isAbsolute(options.configDir))
         throw new Error('configDir must be an absolute path');
@@ -253,6 +286,7 @@ export function openFileSecrets(options) {
         directory: dir,
         list: () => listHandles(dir, connector),
         put: (name, value, putOptions = {}) => putHandle(dir, connector, name, value, putOptions),
+        remove: (name) => removeHandle(dir, connector, name),
         withLock: (fn) => {
             ensureDirectory(dir, connector);
             const r = locked(dir, connector, fn);

package/dist/session.d.ts

@@ -11,6 +11,7 @@ export type Action = {
 export declare const INSPECT_LIMIT_BYTES: number;
 export declare const INVALID_REQUEST = -32600;
 export declare const INTERNAL_ERROR = -32603;
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const STATUS_BEFORE_INITIALIZE = "the status is not available before the connector has answered initialize";
 export type Message = Record<string, unknown>;
 export interface SessionOptions {
@@ -18,6 +19,7 @@ export interface SessionOptions {
     readonly status: (tools: readonly string[]) => ConnectorMintedStatus;
     readonly ownIdPrefix: string;
     readonly withheld: (line: Buffer, parsed: unknown) => boolean;
+    readonly parked?: true;
 }
 export declare const isId: (v: unknown) => v is JsonRpcId;
 export declare const idKey: (id: JsonRpcId) => string;
@@ -32,6 +34,10 @@ export type Reading = {
 };
 export declare function read(raw: Buffer): Reading;
 export declare const errorLine: (id: JsonRpcId | null, code: number, message: string, dataCode: ConnectorErrorCode) => string;
+export declare function parkedAnswer(line: Buffer | string, connector: string, serverInfo: {
+    readonly name: string;
+    readonly version: string;
+}): Message | null;
 export declare class Session {
     private readonly options;
     private readonly uri;

package/dist/session.js

@@ -8,15 +8,19 @@ const LIMIT_TEXT = `${INSPECT_LIMIT_BYTES / (1024 * 1024)} MiB`;
 const MAX_STATUS_PAGES = 64;
 const FORBIDDEN_SCOPE = 'connector.forbidden_scope';
 const INTERNAL = 'connector.internal';
+const AUTH_REQUIRED = 'connector.auth_required';
 export const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
 export const INTERNAL_ERROR = -32603;
+export const MCP_PROTOCOL_VERSION = '2025-11-25';
 const UNREADABLE_REQUEST = `the launcher forwards only single JSON-RPC messages of at most ${LIMIT_TEXT}, on one line and without repeated keys, which it can check against the granted scope`;
 const WITHHELD = 'the connector wrote one of its secret values into this reply, so the launcher withheld it';
 const NO_ID = 'the launcher forwards a request only with a string or number id, and needs one on the requests whose replies it rewrites or answers';
 export const STATUS_BEFORE_INITIALIZE = 'the status is not available before the connector has answered initialize';
 const TAKEN_ID = 'the connector may still answer an earlier request with this id (it has not answered it yet, or the launcher answered it after a line it could not read); use another id';
 const UNREADABLE_REPLY = `the connector wrote a message the launcher cannot read (over ${LIMIT_TEXT}, a batch, or a repeated key), which may have been this reply`;
+const noCredentials = (connector) => `connector ${connector} has no credentials; run its auth`;
 const ERROR_CODES = new Set(Object.keys({
     'connector.auth_required': 0,
     'connector.auth_expired': 0,
@@ -49,7 +53,31 @@ export function read(raw) {
     return hasRepeatedKey(text) ? { kind: 'unreadable' } : { kind: 'message', m };
 }
 const lineOf = (m) => JSON.stringify(m) + '\n';
-export const errorLine = (id, code, message, dataCode) => lineOf({ jsonrpc: '2.0', id, error: { code, message, data: { code: dataCode } } });
+const errorOf = (id, code, message, dataCode) => ({ jsonrpc: '2.0', id, error: { code, message, data: { code: dataCode } } });
+export const errorLine = (id, code, message, dataCode) => lineOf(errorOf(id, code, message, dataCode));
+export function parkedAnswer(line, connector, serverInfo) {
+    const r = read(typeof line === 'string' ? Buffer.from(line, 'utf8') : line);
+    if (r.kind !== 'message' || typeof r.m.method !== 'string' || !isId(r.m.id))
+        return null;
+    const id = r.m.id;
+    const result = (value) => ({ jsonrpc: '2.0', id, result: value });
+    switch (r.m.method) {
+        case 'initialize': {
+            const requested = asObject(r.m.params)?.protocolVersion;
+            return result({ protocolVersion: typeof requested === 'string' ? requested : MCP_PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { ...serverInfo } });
+        }
+        case 'ping':
+            return result({});
+        case 'tools/list':
+            return result({ tools: [] });
+        case 'resources/list':
+            return result({ resources: [] });
+        case 'resources/read':
+            return errorOf(id, INVALID_PARAMS, noCredentials(connector), AUTH_REQUIRED);
+        default:
+            return errorOf(id, METHOD_NOT_FOUND, noCredentials(connector), AUTH_REQUIRED);
+    }
+}
 const up = (data) => ({ to: 'upstream', data });
 const down = (data) => ({ to: 'connector', data });
 const same = (raw) => Buffer.concat([raw, NEWLINE]);
@@ -90,7 +118,9 @@ export class Session {
         switch (m.method) {
             case 'tools/call': {
                 if (typeof name !== 'string' || !isGranted(grant, name))
-                    return [up(errorLine(id, INVALID_PARAMS, 'the requested tool is not in the granted scope', FORBIDDEN_SCOPE)), ...this.settle(call, 'refused', FORBIDDEN_SCOPE)];
+                    return id === null ? [] : [up(errorLine(id, INVALID_PARAMS, 'the requested tool is not in the granted scope', FORBIDDEN_SCOPE)), ...this.settle(call, 'refused', FORBIDDEN_SCOPE)];
+                if (this.options.parked === true)
+                    return id === null ? [] : [up(errorLine(id, INTERNAL_ERROR, noCredentials(this.options.connector), AUTH_REQUIRED)), ...this.settle(call, 'refused', AUTH_REQUIRED)];
                 return this.forward(raw, id, grant, undefined, undefined, call);
             }
             case 'resources/read':

package/dist/status.d.ts

@@ -1,9 +1,13 @@
-import type { ConnectorMintedStatus } from '@sema-agent/connectors-contract';
+import type { ConnectorMintedState, ConnectorMintedStatus } from '@sema-agent/connectors-contract';
 import { type SecretHandle } from './secrets.js';
 export declare const STATUS_MIME_TYPE = "application/json";
 export declare const AUTHORIZE_URL_PATTERN: RegExp;
 export declare function statusUri(connector: string): string;
 export declare function statusResource(connector: string): Record<string, string>;
+export declare function mintState(input: {
+    readonly handles: readonly SecretHandle[];
+    readonly nowMs: number;
+}): ConnectorMintedState;
 export declare function mintStatus(input: {
     readonly handles: readonly SecretHandle[];
     readonly nowMs: number;

package/dist/status.js

@@ -13,9 +13,12 @@ export function statusResource(connector) {
         mimeType: STATUS_MIME_TYPE,
     };
 }
-export function mintStatus(input) {
+export function mintState(input) {
     const secrets = input.handles.filter(isSecret);
-    const state = secrets.length === 0 ? 'unauthorized' : secrets.some((h) => h.expiresAt !== undefined && Date.parse(h.expiresAt) <= input.nowMs) ? 'expired' : 'authorized';
+    return secrets.length === 0 ? 'unauthorized' : secrets.some((h) => h.expiresAt !== undefined && Date.parse(h.expiresAt) <= input.nowMs) ? 'expired' : 'authorized';
+}
+export function mintStatus(input) {
+    const state = mintState(input);
     const link = state === 'unauthorized' && input.authorizeUrl !== undefined && AUTHORIZE_URL_PATTERN.test(input.authorizeUrl) ? { authorizeUrl: input.authorizeUrl } : {};
     return { state, tools: [...input.tools], ...link };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -19,7 +19,8 @@
   "files": [
     "dist",
     "bin",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "INTEGRATION.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json"