@sema-agent/connectors 0.2.0 → 0.4.0

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/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]);
@@ -91,6 +119,8 @@ export class Session {
             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)];
+                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/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.4.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"