@sema-agent/connectors 0.0.0-stage → 0.2.0

package/dist/secrets.js

@@ -0,0 +1,264 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants, fchmodSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { hasRepeatedKey } from './json-text.js';
+import { takeLockFile } from './lock-file.js';
+import { writeAll } from './write-all.js';
+export const isSecret = (handle) => handle.secret !== false;
+export const HANDLE_NAME = /^[A-Z][A-Z0-9_]*$/;
+const META_SUFFIX = '.meta.json';
+const META_KEYS = ['expiresAt', 'secret'];
+const TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$/;
+const FILE_MODE = 0o600;
+const DIRECTORY_MODE = 0o700;
+export const LOCK_FILE = '.auth.lock';
+export const LOCK_WAIT_MS = 5000;
+const LOCK_POLL_MS = 25;
+export function handleDirectory(configDir, connector) {
+    return join(configDir, 'connectors', connector);
+}
+export function handleFilePath(configDir, handle) {
+    return join(handleDirectory(configDir, handle.connector), handle.name);
+}
+export function readSecretValue(configDir, handle) {
+    const fd = openSync(handleFilePath(configDir, handle), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const held = new Set();
+const pause = (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function locked(dir, connector, fn) {
+    const path = join(dir, LOCK_FILE);
+    if (held.has(path))
+        return { ok: true, value: fn() };
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let release = takeLockFile(path);
+    while (release === null) {
+        if (Date.now() >= deadline)
+            return { ok: false, problem: `connector ${connector}: another process held connectors/${connector}/${LOCK_FILE} for ${LOCK_WAIT_MS / 1000} s (an auth writing the handles, or a launch copying them); a lock left by a process that died is removed by hand` };
+        pause(LOCK_POLL_MS);
+        release = takeLockFile(path);
+    }
+    held.add(path);
+    try {
+        const value = fn();
+        if (typeof value?.then === 'function')
+            throw new Error('withLock runs a synchronous function: the lock is released as soon as it returns');
+        return { ok: true, value };
+    }
+    finally {
+        held.delete(path);
+        release();
+    }
+}
+export const NO_HANDLES = { handles: [], files: new Map(), values: [], remove: () => undefined };
+export function copyForLaunch(configDir, connector) {
+    const dir = handleDirectory(configDir, connector);
+    try {
+        lstatSync(dir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ok: true, ...NO_HANDLES };
+        return { ok: false, problem: `connector ${connector}: the secrets directory cannot be read` };
+    }
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        return { ok: false, problem: `connector ${connector}: ${dirProblem}` };
+    const r = locked(dir, connector, () => copyHandles(configDir, dir, connector));
+    return r.ok ? r.value : r;
+}
+function copyHandles(configDir, dir, connector) {
+    const listing = listHandles(dir, connector);
+    if (!listing.ok)
+        return listing;
+    if (listing.handles.length === 0)
+        return { ok: true, ...NO_HANDLES };
+    const copies = mkdtempSync(join(dir, '.launch-'));
+    const remove = () => rmSync(copies, { recursive: true, force: true });
+    try {
+        const files = new Map();
+        const values = [];
+        for (const handle of listing.handles) {
+            const bytes = readSecretValue(configDir, handle);
+            const path = join(copies, handle.name);
+            const fd = openSync(path, 'wx', FILE_MODE);
+            try {
+                writeAll(fd, bytes);
+            }
+            finally {
+                closeSync(fd);
+            }
+            files.set(handle.name, path);
+            if (isSecret(handle))
+                values.push(bytes.toString('utf8'));
+        }
+        return { ok: true, handles: listing.handles, files, values, remove };
+    }
+    catch (e) {
+        remove();
+        throw e;
+    }
+}
+const validExpiry = (v) => typeof v === 'string' && TIMESTAMP.test(v) && Number.isFinite(Date.parse(v));
+function readMeta(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (v === null || typeof v !== 'object' || Array.isArray(v) || hasRepeatedKey(text))
+        return null;
+    const meta = v;
+    if (!Object.keys(meta).every((k) => META_KEYS.includes(k)))
+        return null;
+    if (Object.hasOwn(meta, 'expiresAt') && !validExpiry(meta.expiresAt))
+        return null;
+    if (Object.hasOwn(meta, 'secret') && typeof meta.secret !== 'boolean')
+        return null;
+    return { ...(validExpiry(meta.expiresAt) ? { expiresAt: meta.expiresAt } : {}), secret: meta.secret !== false };
+}
+function entryProblem(path, kind, label) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        return `${label} cannot be read`;
+    }
+    if (st.isSymbolicLink())
+        return `${label} is a symbolic link`;
+    if (kind === 'directory' ? !st.isDirectory() : !st.isFile())
+        return `${label} is not a ${kind === 'directory' ? 'directory' : 'regular file'}`;
+    const allowed = kind === 'directory' ? DIRECTORY_MODE : FILE_MODE;
+    if ((st.mode & 0o777 & ~allowed) !== 0)
+        return `${label} has permissions wider than ${kind === 'directory' ? '0700' : '0600'}`;
+    return null;
+}
+function listHandles(dir, connector) {
+    const refuse = (problem) => ({ ok: false, problem: `connector ${connector}: ${problem}` });
+    try {
+        lstatSync(dir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ok: true, handles: [] };
+        return refuse('the secrets directory cannot be read');
+    }
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        return refuse(dirProblem);
+    let names;
+    try {
+        names = readdirSync(dir).sort();
+    }
+    catch {
+        return refuse('the secrets directory cannot be listed');
+    }
+    const handles = [];
+    for (const name of names) {
+        if (!HANDLE_NAME.test(name))
+            continue;
+        const problem = entryProblem(join(dir, name), 'file', `secret file ${name}`);
+        if (problem !== null)
+            return refuse(problem);
+        const metaFile = name + META_SUFFIX;
+        if (!names.includes(metaFile)) {
+            handles.push({ connector, name, source: 'file', secret: true });
+            continue;
+        }
+        const metaProblem = entryProblem(join(dir, metaFile), 'file', `metadata file ${metaFile}`);
+        if (metaProblem !== null)
+            return refuse(metaProblem);
+        let meta;
+        try {
+            meta = readMeta(readFileSync(join(dir, metaFile), 'utf8'));
+        }
+        catch {
+            meta = null;
+        }
+        if (meta === null)
+            return refuse(`metadata file ${metaFile} does not hold a JSON object whose only keys are "expiresAt" (an RFC 3339 UTC time) and "secret" (true or false), each named once`);
+        handles.push({ connector, name, source: 'file', ...meta });
+    }
+    return { ok: true, handles };
+}
+function writePrivately(path, text) {
+    const tmp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        const fd = openSync(tmp, 'wx', FILE_MODE);
+        try {
+            fchmodSync(fd, FILE_MODE);
+            writeAll(fd, text);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+function ensureDirectory(dir, connector) {
+    mkdirSync(dir, { recursive: true, mode: DIRECTORY_MODE });
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        throw new Error(`connector ${connector}: ${dirProblem}`);
+}
+function writeHandle(dir, connector, name, value, options) {
+    const secret = options.secret !== false;
+    const expiry = options.expiresAt === undefined ? {} : { expiresAt: options.expiresAt };
+    const meta = { ...expiry, ...(secret ? {} : { secret: false }) };
+    const metaFile = join(dir, name + META_SUFFIX);
+    const writeMeta = () => (Object.keys(meta).length === 0 ? rmSync(metaFile, { force: true }) : writePrivately(metaFile, JSON.stringify(meta) + '\n'));
+    if (secret)
+        writeMeta();
+    writePrivately(join(dir, name), value);
+    if (!secret)
+        writeMeta();
+    return { connector, name, source: 'file', secret, ...expiry };
+}
+function putHandle(dir, connector, name, value, options) {
+    if (!HANDLE_NAME.test(name))
+        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 (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')
+        throw new Error('secret must be true or false');
+    ensureDirectory(dir, connector);
+    const r = locked(dir, connector, () => writeHandle(dir, connector, name, value, options));
+    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');
+    if (typeof options.connector !== 'string' || !CONNECTOR_NAME.test(options.connector))
+        throw new Error('connector must be lowercase letters and digits in hyphen-separated words');
+    const { connector } = options;
+    const dir = handleDirectory(options.configDir, connector);
+    return {
+        directory: dir,
+        list: () => listHandles(dir, connector),
+        put: (name, value, putOptions = {}) => putHandle(dir, connector, name, value, putOptions),
+        withLock: (fn) => {
+            ensureDirectory(dir, connector);
+            const r = locked(dir, connector, fn);
+            if (!r.ok)
+                throw new Error(r.problem);
+            return r.value;
+        },
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,59 @@
+import type { ConnectorErrorCode, ConnectorMintedStatus, ConnectorReceipt } from '@sema-agent/connectors-contract';
+import type { Principal } from './principal.js';
+export type JsonRpcId = string | number;
+export type Action = {
+    readonly to: 'upstream' | 'connector';
+    readonly data: Buffer | string;
+} | {
+    readonly to: 'receipt';
+    readonly receipt: ConnectorReceipt;
+};
+export declare const INSPECT_LIMIT_BYTES: number;
+export declare const INVALID_REQUEST = -32600;
+export declare const INTERNAL_ERROR = -32603;
+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 {
+    readonly connector: string;
+    readonly status: (tools: readonly string[]) => ConnectorMintedStatus;
+    readonly ownIdPrefix: string;
+    readonly withheld: (line: Buffer, parsed: unknown) => boolean;
+}
+export declare const isId: (v: unknown) => v is JsonRpcId;
+export declare const idKey: (id: JsonRpcId) => string;
+export type Reading = {
+    readonly kind: 'message';
+    readonly m: Message;
+} | {
+    readonly kind: 'unreadable';
+} | {
+    readonly kind: 'other';
+    readonly value?: unknown;
+};
+export declare function read(raw: Buffer): Reading;
+export declare const errorLine: (id: JsonRpcId | null, code: number, message: string, dataCode: ConnectorErrorCode) => string;
+export declare class Session {
+    private readonly options;
+    private readonly uri;
+    private readonly pending;
+    private readonly own;
+    private readonly retired;
+    private capabilities;
+    private ownCount;
+    constructor(options: SessionOptions);
+    fromUpstream(raw: Buffer, principal: Principal): Action[];
+    statusFor(id: JsonRpcId, principal: Principal): Action[];
+    upstreamOversized(): Action[];
+    fromConnector(raw: Buffer): Action[];
+    connectorOversized(): Action[];
+    private connectorUnreadable;
+    connectorGone(how: string, abnormal: boolean): Action[];
+    private forward;
+    private settle;
+    private settleReply;
+    private visibleTools;
+    private rewrite;
+    private readStatus;
+    private askTools;
+    private statusReply;
+}

package/dist/session.js

@@ -0,0 +1,256 @@
+import { hasRepeatedKey } from './json-text.js';
+import { normalizeTool } from './normalize.js';
+import { REDACTED } from './redact.js';
+import { isGranted } from './scope.js';
+import { STATUS_MIME_TYPE, statusResource, statusUri } from './status.js';
+export const INSPECT_LIMIT_BYTES = 4 * 1024 * 1024;
+const LIMIT_TEXT = `${INSPECT_LIMIT_BYTES / (1024 * 1024)} MiB`;
+const MAX_STATUS_PAGES = 64;
+const FORBIDDEN_SCOPE = 'connector.forbidden_scope';
+const INTERNAL = 'connector.internal';
+export const INVALID_REQUEST = -32600;
+const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+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 ERROR_CODES = new Set(Object.keys({
+    'connector.auth_required': 0,
+    'connector.auth_expired': 0,
+    'connector.forbidden_scope': 0,
+    'connector.upstream_unreachable': 0,
+    'connector.bad_assertion': 0,
+    'connector.internal': 0,
+    'connector.not_installed': 0,
+}));
+const NEWLINE = Buffer.from('\n');
+const LINE_FEED = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+export const isId = (v) => typeof v === 'string' || typeof v === 'number';
+export const idKey = (id) => `${typeof id}:${String(id)}`;
+const asObject = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : null);
+export function read(raw) {
+    const text = raw.toString('utf8');
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'other' };
+    }
+    if (Array.isArray(value))
+        return { kind: 'unreadable' };
+    const m = asObject(value);
+    if (m === null)
+        return { kind: 'other', value };
+    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 up = (data) => ({ to: 'upstream', data });
+const down = (data) => ({ to: 'connector', data });
+const same = (raw) => Buffer.concat([raw, NEWLINE]);
+export class Session {
+    options;
+    uri;
+    pending = new Map();
+    own = new Map();
+    retired = new Set();
+    capabilities = null;
+    ownCount = 0;
+    constructor(options) {
+        this.options = options;
+        this.uri = statusUri(options.connector);
+    }
+    fromUpstream(raw, principal) {
+        const startedAt = new Date().toISOString();
+        const started = performance.now();
+        const grant = principal.scope;
+        const body = raw[raw.length - 1] === CARRIAGE_RETURN ? raw.subarray(0, -1) : raw;
+        if (body.includes(LINE_FEED) || body.includes(CARRIAGE_RETURN))
+            return [up(errorLine(null, INVALID_REQUEST, UNREADABLE_REQUEST, FORBIDDEN_SCOPE))];
+        const r = read(raw);
+        if (r.kind !== 'message')
+            return [up(errorLine(null, INVALID_REQUEST, UNREADABLE_REQUEST, FORBIDDEN_SCOPE))];
+        const m = r.m;
+        if (typeof m.method !== 'string')
+            return [down(same(raw))];
+        const params = asObject(m.params);
+        const name = params?.name;
+        const call = m.method === 'tools/call' && typeof name === 'string' && name !== '' ? { tool: name, startedAt, started } : undefined;
+        if ('id' in m && !isId(m.id))
+            return [up(errorLine(null, INVALID_REQUEST, NO_ID, FORBIDDEN_SCOPE)), ...this.settle(call, 'refused', FORBIDDEN_SCOPE)];
+        const id = isId(m.id) ? m.id : null;
+        if (id !== null && (this.pending.has(idKey(id)) || this.retired.has(idKey(id))))
+            return [up(errorLine(id, INVALID_REQUEST, TAKEN_ID, FORBIDDEN_SCOPE)), ...this.settle(call, 'refused', FORBIDDEN_SCOPE)];
+        const needsId = () => [up(errorLine(null, INVALID_REQUEST, NO_ID, FORBIDDEN_SCOPE))];
+        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 this.forward(raw, id, grant, undefined, undefined, call);
+            }
+            case 'resources/read':
+                if (params?.uri !== this.uri)
+                    return this.forward(raw, id, grant);
+                return id === null ? needsId() : this.readStatus(id, grant);
+            case 'resources/list': {
+                if (id === null)
+                    return needsId();
+                const firstPage = params?.cursor === undefined;
+                if (this.capabilities !== null && asObject(this.capabilities.resources) === null) {
+                    return [up(lineOf({ jsonrpc: '2.0', id, result: { resources: firstPage ? [statusResource(this.options.connector)] : [] } }))];
+                }
+                return this.forward(raw, id, grant, 'resources/list', firstPage);
+            }
+            case 'initialize':
+            case 'tools/list':
+                return id === null ? needsId() : this.forward(raw, id, grant, m.method);
+            default:
+                return this.forward(raw, id, grant);
+        }
+    }
+    statusFor(id, principal) {
+        return this.readStatus(id, principal.scope);
+    }
+    upstreamOversized() {
+        return [up(errorLine(null, INVALID_REQUEST, UNREADABLE_REQUEST, FORBIDDEN_SCOPE))];
+    }
+    fromConnector(raw) {
+        const r = read(raw);
+        if (r.kind === 'unreadable')
+            return this.connectorUnreadable();
+        const withheld = this.options.withheld(raw, r.kind === 'message' ? r.m : r.value);
+        const pass = () => (withheld ? [] : [up(same(raw))]);
+        if (r.kind === 'other')
+            return pass();
+        const m = r.m;
+        if (m.method !== undefined)
+            return pass();
+        if (!isId(m.id) || !('result' in m || 'error' in m))
+            return pass();
+        const key = idKey(m.id);
+        if (this.retired.delete(key))
+            return [];
+        const own = this.own.get(key);
+        if (own !== undefined) {
+            const actions = withheld ? [up(errorLine(own.upstreamId, INTERNAL_ERROR, WITHHELD, INTERNAL))] : own.handle(m);
+            this.own.delete(key);
+            return actions;
+        }
+        const p = this.pending.get(key);
+        if (p === undefined)
+            return [];
+        const data = withheld ? errorLine(p.id, INTERNAL_ERROR, WITHHELD, INTERNAL) : p.rewrite === undefined || !('result' in m) ? same(raw) : this.rewrite(p, m, raw);
+        this.pending.delete(key);
+        return [up(data), ...(withheld ? this.settle(p.call, 'failed', INTERNAL) : this.settleReply(p.call, m))];
+    }
+    connectorOversized() {
+        return this.connectorUnreadable();
+    }
+    connectorUnreadable() {
+        const actions = [
+            ...[...this.pending.values()].flatMap((p) => [up(errorLine(p.id, INTERNAL_ERROR, UNREADABLE_REPLY, INTERNAL)), ...this.settle(p.call, 'failed', INTERNAL)]),
+            ...[...this.own.values()].map((o) => up(errorLine(o.upstreamId, INTERNAL_ERROR, UNREADABLE_REPLY, INTERNAL))),
+        ];
+        for (const key of this.pending.keys())
+            this.retired.add(key);
+        this.pending.clear();
+        this.own.clear();
+        return actions;
+    }
+    connectorGone(how, abnormal) {
+        const actions = [
+            ...[...this.pending.values()].flatMap((p) => [up(errorLine(p.id, INTERNAL_ERROR, `${how} before it answered`, INTERNAL)), ...this.settle(p.call, 'failed', INTERNAL)]),
+            ...[...this.own.values()].map((o) => up(errorLine(o.upstreamId, INTERNAL_ERROR, 'the connector ended before it listed its tools for the status', INTERNAL))),
+        ];
+        if (abnormal && this.pending.size === 0)
+            actions.push(up(errorLine(null, INTERNAL_ERROR, how, INTERNAL)));
+        this.pending.clear();
+        this.own.clear();
+        return actions;
+    }
+    forward(raw, id, grant, rewrite, firstPage, call) {
+        if (id !== null)
+            this.pending.set(idKey(id), { id, grant, ...(rewrite !== undefined ? { rewrite } : {}), ...(firstPage !== undefined ? { firstPage } : {}), ...(call !== undefined ? { call } : {}) });
+        return [down(same(raw))];
+    }
+    settle(call, outcome, errorCode) {
+        if (call === undefined)
+            return [];
+        const durationMs = Math.max(0, Math.round(performance.now() - call.started));
+        const tool = this.options.withheld(Buffer.from(call.tool, 'utf8'), call.tool) ? REDACTED : call.tool;
+        return [{ to: 'receipt', receipt: { connector: this.options.connector, tool, startedAt: call.startedAt, durationMs, outcome, ...(errorCode !== undefined ? { errorCode } : {}) } }];
+    }
+    settleReply(call, m) {
+        if ('error' in m) {
+            const code = asObject(asObject(m.error)?.data)?.code;
+            return this.settle(call, 'failed', typeof code === 'string' && ERROR_CODES.has(code) ? code : undefined);
+        }
+        return this.settle(call, asObject(m.result)?.isError === true ? 'failed' : 'ok');
+    }
+    visibleTools(tools, grant) {
+        return tools.flatMap((t) => {
+            const tool = asObject(t);
+            return tool !== null && typeof tool.name === 'string' && isGranted(grant, tool.name) ? [normalizeTool(tool)] : [];
+        });
+    }
+    rewrite(p, m, raw) {
+        const result = asObject(m.result);
+        if (p.rewrite === 'initialize') {
+            const capabilities = result === null ? null : asObject(result.capabilities);
+            if (result === null || capabilities === null)
+                return errorLine(p.id, INTERNAL_ERROR, 'the connector answered initialize without capabilities', INTERNAL);
+            this.capabilities = capabilities;
+            if (asObject(capabilities.resources) !== null)
+                return same(raw);
+            return lineOf({ ...m, result: { ...result, capabilities: { ...capabilities, resources: {} } } });
+        }
+        if (p.rewrite === 'tools/list') {
+            const tools = result?.tools;
+            if (result === null || !Array.isArray(tools))
+                return errorLine(p.id, INTERNAL_ERROR, 'the connector answered tools/list without a list of tools', INTERNAL);
+            return lineOf({ ...m, result: { ...result, tools: this.visibleTools(tools, p.grant) } });
+        }
+        const resources = result?.resources;
+        if (result === null || !Array.isArray(resources))
+            return errorLine(p.id, INTERNAL_ERROR, 'the connector answered resources/list without a list of resources', INTERNAL);
+        const kept = resources.filter((r) => asObject(r)?.uri !== this.uri);
+        return lineOf({ ...m, result: { ...result, resources: p.firstPage ? [...kept, statusResource(this.options.connector)] : kept } });
+    }
+    readStatus(id, grant) {
+        if (this.capabilities === null)
+            return [up(errorLine(id, INTERNAL_ERROR, STATUS_BEFORE_INITIALIZE, INTERNAL))];
+        if (asObject(this.capabilities.tools) === null)
+            return [up(this.statusReply(id, []))];
+        return this.askTools(id, undefined, [], 1, grant);
+    }
+    askTools(upstreamId, cursor, names, page, grant) {
+        const ownId = `${this.options.ownIdPrefix}/${++this.ownCount}`;
+        this.own.set(idKey(ownId), {
+            upstreamId,
+            handle: (reply) => {
+                const result = asObject(reply.result);
+                const tools = result?.tools;
+                if (result === null || !Array.isArray(tools))
+                    return [up(this.statusReply(upstreamId, []))];
+                for (const t of this.visibleTools(tools, grant))
+                    names.push(t.name);
+                const next = result.nextCursor;
+                if (typeof next !== 'string' || next === '')
+                    return [up(this.statusReply(upstreamId, names))];
+                if (page >= MAX_STATUS_PAGES)
+                    return [up(errorLine(upstreamId, INTERNAL_ERROR, `the connector listed its tools in more than ${MAX_STATUS_PAGES} pages`, INTERNAL))];
+                return this.askTools(upstreamId, next, names, page + 1, grant);
+            },
+        });
+        return [down(lineOf({ jsonrpc: '2.0', id: ownId, method: 'tools/list', ...(cursor !== undefined ? { params: { cursor } } : {}) }))];
+    }
+    statusReply(id, tools) {
+        const text = JSON.stringify(this.options.status(tools));
+        return lineOf({ jsonrpc: '2.0', id, result: { contents: [{ uri: this.uri, mimeType: STATUS_MIME_TYPE, text }] } });
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,12 @@
+import type { 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 mintStatus(input: {
+    readonly handles: readonly SecretHandle[];
+    readonly nowMs: number;
+    readonly tools: readonly string[];
+    readonly authorizeUrl?: string;
+}): ConnectorMintedStatus;

package/dist/status.js

@@ -0,0 +1,21 @@
+import { isSecret } from './secrets.js';
+export const STATUS_MIME_TYPE = 'application/json';
+export const AUTHORIZE_URL_PATTERN = /^https?:\/\//;
+export function statusUri(connector) {
+    return `sema-connector://${connector}/status`;
+}
+export function statusResource(connector) {
+    return {
+        uri: statusUri(connector),
+        name: 'status',
+        title: 'Connector status',
+        description: 'Authorization state and visible tools of this connector, as connector-status-v1 JSON.',
+        mimeType: STATUS_MIME_TYPE,
+    };
+}
+export function mintStatus(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';
+    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

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

package/dist/write-all.js

@@ -0,0 +1,15 @@
+import { fstatSync, fsyncSync, writeSync } from 'node:fs';
+export function writeAll(fd, data) {
+    const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+    let written = 0;
+    while (written < bytes.length) {
+        const n = writeSync(fd, bytes, written, bytes.length - written, written);
+        if (n <= 0)
+            throw new Error(`a write stopped after ${written} of ${bytes.length} bytes`);
+        written += n;
+    }
+    fsyncSync(fd);
+    const size = fstatSync(fd).size;
+    if (size !== bytes.length)
+        throw new Error(`the file holds ${size} bytes after a write of ${bytes.length}`);
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "sema-connector": "bin/sema-connector.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sema-agent/sema-connectors.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}