@cotal-ai/linear 0.0.0-bootstrap.0 → 0.76.0

package/dist/serve.js

@@ -0,0 +1,214 @@
+/**
+ * Serving one Linear account as a registered Cotal endpoint.
+ *
+ * Two layers. {@link runLinearEndpoint} is the generic runner: it takes an already-authorized,
+ * scoped serve bundle (the `authorizeServeGrant` artifact plus a serve credential source) and serves
+ * the fixed Linear contract on it. A hosted embedder that issues serve credentials its own way uses
+ * it directly. {@link registerLinearEndpoint} is the local operator setup for a static-auth mesh: it
+ * walks the same registration path every ordinary endpoint walks (contract-store publish, issuance
+ * gate, registration barrier, serve grant, ready status, fenced `endpoint-serve` mint) over one-shot
+ * `endpoint-serve-executor` connections, and keeps the space signer inside the operator process for
+ * renewal. The signer is never returned, logged, or passed to the runner.
+ *
+ * The endpoint name comes from operator configuration and must be a reverse-DNS name in a namespace
+ * the operator owns. The name authority authorizes exactly that name for the local owner, nothing
+ * else. A per-user-auth mesh is refused: its serve credentials come from the remote issuer, which
+ * this package has no client for.
+ */
+import { credsAuthenticator } from "@nats-io/transport-node";
+import { Kvm } from "@nats-io/kv";
+import { authorizeServeGrant, contractArtifactCanonicalBytes, contractStoreContext, CotalEndpoint, deregisterServiceInstance, DEV_OWNER, dialerFor, endpointRegistrationBarrier, epAuthBucket, inspectCredHealth, mintCreds, mintLifecycleUid, newIdentity, principalKey, provisionAgent, provisionEndpointGateOpen, publishContractArtifact, readEndpointGateGeneration, recordsBucket, registerServiceInstance, serveEndpoint, serveIssuanceGateKv, SERVICE_READY, standaloneConnectOpts, writeServiceStatus, } from "@cotal-ai/core";
+import { linearClusterArtifacts, linearCommandDefs, linearContractArtifactValues, LINEAR_COMMANDS } from "./contract.js";
+/** A reverse-DNS endpoint name: at least two lowercase labels, as the operator configured it. */
+export function assertLinearEndpointName(name) {
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/.test(name) || name.length > 200)
+        throw new Error(`"${name}" is not a reverse-DNS endpoint name (for example com.example.linear); use a namespace you own`);
+    return name;
+}
+function within(p, ms) {
+    return Promise.race([p, new Promise((r) => setTimeout(() => r(undefined), ms).unref())]);
+}
+/** Serve the fixed Linear contract on an authorized bundle. Command names, schemas and the
+ *  `linear.mcp` capability are fixed; the upstream result is returned as data and never parsed. */
+export async function runLinearEndpoint(bundle, upstream) {
+    const enc = new TextEncoder();
+    const nc = await dialerFor(bundle.servers)({
+        servers: bundle.servers,
+        ...(bundle.tls ? { tls: {} } : {}),
+        authenticator: (nonce) => credsAuthenticator(enc.encode(bundle.creds()))(nonce),
+        inboxPrefix: `_INBOX_${bundle.identity.id}`,
+        maxReconnectAttempts: -1,
+    });
+    let handle;
+    try {
+        handle = serveEndpoint(nc, bundle.space, bundle.grant, linearCommandDefs(upstream), { public: true });
+    }
+    catch (e) {
+        await nc.drain().catch(() => nc.close());
+        throw e;
+    }
+    return {
+        endpoint: bundle.grant.endpoint,
+        instanceId: bundle.grant.instanceId,
+        epoch: bundle.grant.epoch,
+        closed: nc.closed().then((e) => e ?? undefined),
+        async stop(graceMs = 10_000) {
+            await within(handle.stop(), graceMs);
+            await within(nc.drain().catch(() => nc.close()), graceMs);
+            if (!nc.isClosed())
+                await nc.close().catch(() => { });
+            await upstream.close(graceMs);
+        },
+    };
+}
+/**
+ * Register `endpoint` as a fresh instance on a static-auth mesh and mint its serve credential.
+ * `auth` is the operator's own space authority; it stays in this closure for renewal and
+ * deregistration and is never placed in the returned bundle.
+ */
+export async function registerLinearEndpoint(opts) {
+    const { auth, servers, space, tls } = opts;
+    if (auth.space !== space)
+        throw new Error(`the space authority is for "${auth.space}", not "${space}"`);
+    const endpoint = assertLinearEndpointName(opts.endpoint);
+    const instanceId = mintLifecycleUid();
+    const opId = mintLifecycleUid();
+    const identity = newIdentity();
+    const artifacts = linearClusterArtifacts();
+    const store = new Map([[artifacts.rootDigest, artifacts.document], [artifacts.closureDigest, artifacts.manifest]]);
+    const readClusterArtifact = (digest) => store.get(digest);
+    // Operator configuration is the trusted source: this name, for the local owner, and nothing else.
+    const authority = {
+        authorize: (name, owner) => ({ authorized: name === endpoint && owner === DEV_OWNER, revision: 0 }),
+    };
+    const withExecutor = async (fn) => {
+        const creds = await mintCreds(auth, newIdentity(), "endpoint-serve-executor", { endpointServeExecutor: { endpoint, instanceId } });
+        const nc = await dialerFor(servers)({ servers, ...standaloneConnectOpts({ creds, tls }), maxReconnectAttempts: 0 });
+        try {
+            const kvm = new Kvm(nc);
+            return await fn({ recordsKv: await kvm.open(recordsBucket(space)), authKv: await kvm.open(epAuthBucket(space)), nc });
+        }
+        finally {
+            await nc.drain().catch(() => nc.close());
+        }
+    };
+    const fenceOf = (authKv) => serveIssuanceGateKv(authKv, space, { endpoint, instanceId });
+    const epochOf = (authKv) => async () => {
+        const g = await fenceOf(authKv).observe();
+        if (g === null)
+            throw new Error(`no issuance gate for ${endpoint}/${instanceId}`);
+        return g.processEpoch;
+    };
+    const { grant, creds: first } = await withExecutor(async ({ recordsKv, authKv, nc }) => {
+        const storeCtx = await contractStoreContext(nc, space);
+        for (const value of [...linearContractArtifactValues(), artifacts.document, artifacts.manifest])
+            await publishContractArtifact(storeCtx, contractArtifactCanonicalBytes(value));
+        await provisionEndpointGateOpen(authKv, { endpoint, instanceId, principal: principalKey(DEV_OWNER, identity.id).key });
+        // A fresh instance has an empty credential family, so the barrier has nothing to evict.
+        const barrier = endpointRegistrationBarrier(authKv, space, { endpoint, instanceId, opId });
+        const spec = { endpoint, owner: DEV_OWNER, clusterDigests: [artifacts.closureDigest], protocol: { v: 1 } };
+        const { registrationRevision } = await registerServiceInstance(recordsKv, {
+            space, spec, instanceId, registrant: { owner: DEV_OWNER }, authority, barrier, readClusterArtifact,
+            observeHolderGeneration: (holder) => readEndpointGateGeneration(authKv, { endpoint, instanceId: holder }),
+        });
+        // The record exists from here on. A failure in any later step takes it back down before the
+        // error is reported, so a start that never reaches serving leaves no advertised instance; when
+        // the rollback itself fails, the error says so instead of claiming a clean refusal.
+        try {
+            const fence = fenceOf(authKv);
+            const observed = await fence.observe();
+            if (observed === null)
+                throw new Error(`the issuance gate for ${endpoint}/${instanceId} vanished after registration`);
+            const grant = await authorizeServeGrant(recordsKv, {
+                space, endpoint, instanceId, epoch: observed.processEpoch, holder: { owner: DEV_OWNER }, authority, readClusterArtifact,
+                readProcessEpoch: epochOf(authKv),
+            });
+            await writeServiceStatus(recordsKv, {
+                endpoint, instanceId, epoch: observed.processEpoch,
+                status: { state: SERVICE_READY, epoch: observed.processEpoch, observedSpecRevision: registrationRevision },
+                readProcessEpoch: epochOf(authKv),
+            });
+            const creds = await mintCreds(auth, identity, "endpoint-serve", { serveIssuance: fence, endpointServe: grant });
+            return { grant, creds };
+        }
+        catch (e) {
+            const why = e.message;
+            try {
+                await deregisterServiceInstance(recordsKv, { endpoint, instanceId, observeGeneration: () => readEndpointGateGeneration(authKv, { endpoint, instanceId }) });
+            }
+            catch (d) {
+                throw new Error(`${why}; the service record for ${endpoint}/${instanceId} could not be removed afterwards (${d.message}) and still advertises an instance nobody serves`);
+            }
+            throw new Error(`${why}; the service record for ${endpoint}/${instanceId} was removed again`);
+        }
+    });
+    let current = first;
+    const renew = async () => {
+        current = await withExecutor(({ authKv }) => mintCreds(auth, identity, "endpoint-serve", { serveIssuance: fenceOf(authKv), endpointServe: grant }));
+        return current;
+    };
+    const deregister = async () => {
+        await withExecutor(async ({ recordsKv, authKv }) => {
+            await deregisterServiceInstance(recordsKv, { endpoint, instanceId, observeGeneration: () => readEndpointGateGeneration(authKv, { endpoint, instanceId }) });
+        });
+    };
+    return { bundle: { servers, space, tls, identity, grant, creds: () => current }, renew, deregister };
+}
+/** Milliseconds until a credential reaches 75% of its remaining lifetime, or undefined when it is
+ *  unbounded. */
+export function renewalDelayMs(creds, nowMs = Date.now()) {
+    const exp = inspectCredHealth(creds).exp;
+    if (exp === undefined)
+        return undefined;
+    return Math.max(1_000, Math.floor((exp * 1000 - nowMs) * 0.75));
+}
+/** The caller rows for every Linear command on `endpoint`: what a least-privilege caller
+ *  credential carries, and nothing more. */
+export function linearCallerCapabilities(endpoint) {
+    assertLinearEndpointName(endpoint);
+    return LINEAR_COMMANDS.map((command) => ({ endpoint, command }));
+}
+/**
+ * Provision and mint a standalone caller for a static-auth mesh: the ordinary `agent` profile, its
+ * lifecycle-keyed mailboxes, and the exact request rows for the Linear commands on `endpoint`. It
+ * carries no spawn, run, admin or provisioner capability. The caller is an isolated, hand-launched
+ * seat the operator starts with this credential and lifecycle UID; managed spawns still refuse
+ * endpoint capabilities in static mode, which this does not change. The provisioner connection is
+ * minted for this call and stopped before it returns.
+ */
+export async function provisionLinearCaller(auth, target, endpoint, opts = {}) {
+    if (auth.space !== target.space)
+        throw new Error(`the space authority is for "${auth.space}", not "${target.space}"`);
+    const identity = newIdentity();
+    const lifecycleUid = mintLifecycleUid();
+    const channels = opts.channels ?? [];
+    const prov = new CotalEndpoint({
+        space: target.space,
+        servers: target.servers,
+        tls: target.tls,
+        creds: await mintCreds(auth, newIdentity(), "provisioner"),
+        channels: [],
+        consume: false,
+        registerPresence: false,
+        watchPresence: false,
+        watchChannels: false,
+        card: { name: "linear-caller-provisioner", role: "provisioner", kind: "endpoint" },
+    });
+    prov.on("error", () => { });
+    try {
+        await prov.start();
+        const creds = await provisionAgent(prov, auth, identity, {
+            lifecycleUid,
+            endpointCapabilities: linearCallerCapabilities(endpoint),
+            allowSubscribe: channels,
+            allowPublish: channels,
+            subscribe: channels,
+            ...(opts.expiresInSeconds !== undefined ? { expiresInSeconds: opts.expiresInSeconds } : {}),
+        });
+        return { creds, identity: identity.id, lifecycleUid };
+    }
+    finally {
+        await prov.stop().catch(() => { });
+    }
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/dist/upstream.d.ts

@@ -0,0 +1,148 @@
+import type { LinearAccount } from "./account.js";
+export interface LinearLimits {
+    /** Cap on one HTTP response body, checked before it is accumulated. */
+    maxResponseBytes: number;
+    /** Cap on the summed bytes of every discovery page. */
+    maxInventoryBytes: number;
+    /** Cap on the number of discovery pages across all lists. */
+    maxInventoryPages: number;
+    /** Cap on one inventory entry (a tool, resource, template or prompt) and on the initialize head
+     *  (server, instructions, capabilities), measured as an agent tool prints them
+     *  ({@link renderedBytes}), so every accepted entry and the first page fit the reply that tool
+     *  can carry. One over it refuses the whole inventory, named. */
+    maxInventoryEntryBytes: number;
+    /** Upstream requests in flight at once. */
+    maxConcurrent: number;
+    /** Requests allowed to wait for a slot; one more is refused before dispatch. */
+    maxQueued: number;
+    /** Default and ceiling for one request's deadline. */
+    defaultTimeoutMs: number;
+    maxTimeoutMs: number;
+    /** An inventory older than this is read again before the next request, for servers that do not
+     *  send list-changed notifications. */
+    maxInventoryAgeMs: number;
+}
+/** Bytes of `value` as an agent tool prints it: pretty JSON, nested where an inventory page nests an
+ *  entry. Indentation grows with depth, so a compact entry of a few kilobytes can print to hundreds;
+ *  this measure is never smaller than the wire form, so one bound covers both. */
+export declare function renderedBytes(value: unknown): number;
+export declare const DEFAULT_LIMITS: LinearLimits;
+type Json = Record<string, unknown>;
+export interface LinearInventory {
+    endpoint: string;
+    mode: LinearAccount["mode"];
+    server: {
+        name?: string;
+        version?: string;
+    };
+    instructions?: string;
+    /** The server's capabilities object, verbatim. */
+    capabilities: Json;
+    tools: Json[];
+    resources?: Json[];
+    resourceTemplates?: Json[];
+    prompts?: Json[];
+    /** Capability paths the server advertised that this package does not represent. */
+    unsupported: string[];
+    pages: number;
+    bytes: number;
+    fetchedAt: string;
+    /** Digest over everything above except `pages`, `bytes` and `fetchedAt`. */
+    digest: string;
+}
+export type Outcome = "not-executed" | "unknown";
+/** The result of one forwarded request. `result` covers tool results whose `isError` is true. */
+export type UpstreamReply = {
+    kind: "result";
+    result: Json;
+    inventoryDigest: string;
+} | {
+    kind: "protocol-error";
+    code: number;
+    message: string;
+    data?: unknown;
+    outcome: Outcome;
+} | {
+    kind: "refused";
+    reason: "queue-full" | "unknown-tool" | "not-advertised" | "stale-inventory" | "discovery-failed" | "deadline" | "closed";
+    detail: string;
+    outcome: "not-executed";
+} | {
+    kind: "failed";
+    reason: "timeout" | "cancelled" | "output-too-large" | "session-expired" | "unauthenticated" | "permission-denied" | "rate-limited" | "transport";
+    detail: string;
+    outcome: Outcome;
+};
+export declare class LinearUpstream {
+    readonly account: LinearAccount;
+    readonly limits: LinearLimits;
+    private client?;
+    private transport?;
+    /** The server's `initialize` result, verbatim. */
+    private initialized?;
+    private connecting?;
+    private current?;
+    private stale;
+    private closed;
+    /** Aborts every queued or in-flight operation on {@link close}. */
+    private readonly closing;
+    private readonly slots;
+    private readonly url;
+    private readonly credential;
+    constructor(account: LinearAccount, limits?: LinearLimits);
+    /** The session, or the connect in flight shared by every caller waiting on it. `signal` is this
+     *  caller's own deadline: when the last waiting caller leaves, the connect is ended with it, so an
+     *  operation's deadline never leaves an initialize running behind nobody. */
+    private session;
+    private connect;
+    /** Forget a session the server ended or that failed. Its in-flight requests reject. */
+    private drop;
+    /** One SDK request in its own dispatch context: the schema still validates the shape, and the
+     *  server's `result` is returned verbatim. */
+    private raw;
+    /** Complete discovery. Refuses on any cap rather than returning a partial inventory. `signal`
+     *  bounds the whole read, including the slot wait and connect. */
+    inventory(opts?: {
+        refresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<LinearInventory>;
+    /** Forward `tools/call`. `inventoryDigest`, when given, must match the live inventory. */
+    callTool(req: {
+        name: string;
+        arguments?: Json;
+        inventoryDigest?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<UpstreamReply>;
+    readResource(req: {
+        uri: string;
+        inventoryDigest?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<UpstreamReply>;
+    getPrompt(req: {
+        name: string;
+        arguments?: Record<string, string>;
+        inventoryDigest?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<UpstreamReply>;
+    complete(req: {
+        params: Json;
+        inventoryDigest?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<UpstreamReply>;
+    private forward;
+    /** A failure as a status or class, with the bearer scrubbed. Response bodies are never kept. */
+    private describeError;
+    /** Remove the current bearer from text the server or a library produced. */
+    private scrub;
+    private scrubValue;
+    private classify;
+    /** Close the session and end it upstream, within `graceMs`. Queued requests refuse before
+     *  dispatch; in-flight ones are cancelled and report `unknown`. */
+    close(graceMs?: number): Promise<void>;
+}
+export {};
+//# sourceMappingURL=upstream.d.ts.map

package/dist/upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.d.ts","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"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"}