@sema-agent/connectors 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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

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,22 @@ 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. `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.js

@@ -7,9 +7,7 @@ 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`),

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.js

@@ -118,7 +118,7 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.4.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",