@naswerks/periscope 1.0.0

package/dist/identity/pkce.js

@@ -0,0 +1,94 @@
+/**
+ * PKCE (RFC 7636) and the callback's `state` — the two random values that make an authorization-code
+ * exchange safe to run on a machine somebody else is also running code on.
+ *
+ * They defend different things and neither substitutes for the other. This is the sentence worth
+ * reading twice, because "it does PKCE" is routinely taken to mean the whole callback is covered:
+ *
+ *   - The code verifier proves that whoever redeems the authorization code is the same party
+ *     that requested it. It protects the code exchange.
+ *   - The state proves that the callback this host received is the answer to the request this
+ *     host made. It protects the callback itself.
+ *
+ * Why that matters acutely here, rather than as boilerplate. This host's whole premise is that
+ * the agent runs as the same OS user as the host — it is why an 0600 token file is not a boundary
+ * and why the gate has a credential-path denial. That same fact means any local process can
+ * connect to the loopback listener this flow opens. Without `state`, such a process could hand this
+ * host an authorization code of its own obtaining and have the host redeem it and cache the
+ * resulting token. `state` is what makes that a named refusal instead of a silent substitution.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { ok, refuse } from '../core/result.js';
+/**
+ * The only challenge method this host will use.
+ *
+ * RFC 7636 also defines `plain`, where the challenge is the verifier. This host refuses it rather
+ * than merely not offering it — an unused branch is one a later reader restores on a compatibility
+ * report, and `plain` gives away the whole property to anyone who can observe the authorization
+ * request.
+ */
+export const CODE_CHALLENGE_METHOD = 'S256';
+/** 32 bytes, which is 43 base64url characters — the RFC's floor is 43 and its ceiling is 128. */
+const ENTROPY_BYTES = 32;
+/**
+ * base64url, per RFC 4648 §5 — no padding, URL-safe alphabet.
+ *
+ * Hand-rolled from base64 rather than reached for by name: `Buffer`'s `base64url` encoding is
+ * equivalent, but the transform is one line and stating it keeps this readable next to the RFC.
+ */
+function base64Url(bytes) {
+    return bytes.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * A cryptographically random, URL-safe string.
+ *
+ * `randomBytes`, never `Math.random`. `Math.random` is seeded, predictable and explicitly not for
+ * this; a predictable verifier or state defeats the property entirely while looking identical in
+ * every test.
+ */
+export function randomUrlSafe(bytes = ENTROPY_BYTES) {
+    return base64Url(randomBytes(bytes));
+}
+/** A fresh verifier and its S256 challenge. */
+export function createPkce() {
+    const verifier = randomUrlSafe();
+    return { verifier, challenge: challengeFor(verifier), method: CODE_CHALLENGE_METHOD };
+}
+/** The S256 challenge for a verifier: base64url(SHA-256(ascii(verifier))). */
+export function challengeFor(verifier) {
+    return base64Url(createHash('sha256').update(verifier, 'ascii').digest());
+}
+/**
+ * The `state` value for one authorization request.
+ *
+ * Same entropy source as the verifier and deliberately a separate value — reusing the verifier as
+ * state would put it in a URL the browser and the provider both log, and the verifier is the one
+ * that must never leave this process until the token exchange.
+ */
+export function createState() {
+    return randomUrlSafe();
+}
+/**
+ * Refuse a challenge method this host will not use.
+ *
+ * Exported so the refusal is reachable and testable, rather than being an `if` nobody can drive.
+ */
+export function requireS256(method) {
+    if (method !== CODE_CHALLENGE_METHOD) {
+        return refuse('pkce-method-unsupported', `code challenge method ${method} is refused; this host uses ${CODE_CHALLENGE_METHOD} only, and "plain" would put the verifier itself in the authorization request`);
+    }
+    return ok(CODE_CHALLENGE_METHOD);
+}
+/**
+ * Compare two `state` values without leaking their contents through timing.
+ *
+ * The length check is separate and deliberate: `timingSafeEqual` throws on unequal lengths, so
+ * comparing lengths first is required rather than an optimisation. It leaks the length and nothing
+ * else, which is the standard accepted residual.
+ */
+export function stateMatches(expected, received) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(received, 'utf8');
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+//# sourceMappingURL=pkce.js.map

package/dist/identity/store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What is persisted, and the port that persists it.
+ *
+ * The shape and its validation live here, not with the filesystem, and the dependency direction
+ * is the reason: `host/` may import this, and this may never import `host/`. Reading a cache is two
+ * jobs — getting bytes off a disk, and deciding whether what they say is usable — and only the
+ * first needs a machine. Keeping the second here means every malformed-cache branch is drivable
+ * without writing a file.
+ */
+import type { Result } from '../core/result.js';
+import type { AuthProtocol } from './device-code.js';
+import type { TokenSet } from './token.js';
+/**
+ * The persisted record.
+ *
+ * `authority` and `clientId` ride along so a cache minted against one provider is never presented
+ * to another — a re-pointed host discards rather than replays, which matters because the token
+ * would otherwise be sent to an audience it was not issued for. `protocol` exists for the
+ * protocol-mismatch guard: material minted by one flow is discarded rather than refreshed when the
+ * host is configured for the other.
+ */
+export interface CachedTokens {
+    readonly tokens: TokenSet;
+    readonly protocol: AuthProtocol;
+    readonly authority: string;
+    readonly clientId: string;
+}
+/**
+ * The port the credential holds.
+ *
+ * An interface rather than the concrete file cache so the credential's whole decision surface —
+ * expired, re-pointed, wrong protocol, corrupt — is testable with an in-memory double, and so an
+ * embedder with its own secret storage can supply one without this package growing an opinion
+ * about keychains.
+ */
+export interface TokenStore {
+    read(): Result<CachedTokens>;
+    write(cached: CachedTokens): Result<unknown>;
+    clear(): void;
+}
+/** Validate a parsed cache into the shape the rest of the host relies on. */
+export declare function readCachedTokens(parsed: unknown): Result<CachedTokens>;
+//# sourceMappingURL=store.d.ts.map

package/dist/identity/store.js

@@ -0,0 +1,43 @@
+import { ok, refuse } from '../core/result.js';
+/** Validate a parsed cache into the shape the rest of the host relies on. */
+export function readCachedTokens(parsed) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        return refuse('credential-cache-unreadable', 'the token cache is not a JSON object');
+    }
+    const record = parsed;
+    const tokens = record['tokens'];
+    const protocol = record['protocol'];
+    const authority = record['authority'];
+    const clientId = record['clientId'];
+    if (typeof tokens !== 'object' || tokens === null) {
+        return refuse('credential-cache-unreadable', 'the token cache carries no tokens object');
+    }
+    const tokenRecord = tokens;
+    const accessToken = tokenRecord['accessToken'];
+    const expiresAt = tokenRecord['expiresAt'];
+    if (typeof accessToken !== 'string' || accessToken === '' || typeof expiresAt !== 'number') {
+        return refuse('credential-cache-unreadable', 'the cached token has no accessToken or no numeric expiresAt');
+    }
+    if (protocol !== 'loopback' && protocol !== 'device-code') {
+        return refuse('credential-cache-unreadable', 'the token cache does not say which flow minted it, so it cannot be safely refreshed');
+    }
+    if (typeof authority !== 'string' || authority === '' || typeof clientId !== 'string' || clientId === '') {
+        return refuse('credential-cache-unreadable', 'the token cache does not record the authority and client it was minted for');
+    }
+    const refreshToken = tokenRecord['refreshToken'];
+    const tokenType = tokenRecord['tokenType'];
+    const scope = tokenRecord['scope'];
+    return ok({
+        tokens: {
+            accessToken,
+            refreshToken: typeof refreshToken === 'string' && refreshToken !== '' ? refreshToken : null,
+            expiresAt,
+            tokenType: typeof tokenType === 'string' && tokenType !== '' ? tokenType : 'Bearer',
+            scope: typeof scope === 'string' ? scope : null,
+        },
+        protocol,
+        authority,
+        clientId,
+    });
+}
+//# sourceMappingURL=store.js.map

package/dist/identity/token.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The token exchange — building the requests, reading the responses, and deciding when what the
+ * host holds is still usable. Pure: no network here, so every branch including the ugly ones is
+ * drivable.
+ *
+ * The redaction in this file is load-bearing, not hygiene. Mapping a provider's error response
+ * into a readable message is the single most likely place a token ends up in a log, because the
+ * natural implementation — echo the body so the operator can see what happened — is also the one
+ * that writes credential material to disk. Everything a provider says passes through
+ * `redactSecrets` before it becomes a refusal `detail`, and `token.test.ts` drives a failure path
+ * carrying a token and asserts the token appears nowhere in the output.
+ */
+import type { Result } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+/** What this host holds after a successful exchange. */
+export interface TokenSet {
+    readonly accessToken: string;
+    /** Null when the provider issued none — then expiry means an interactive sign-in. */
+    readonly refreshToken: string | null;
+    /** Epoch milliseconds. */
+    readonly expiresAt: number;
+    readonly tokenType: string;
+    readonly scope: string | null;
+}
+/**
+ * How long before expiry a token is treated as already expired.
+ *
+ * A token that expires in four seconds is not usable for a request that takes five. The skew also
+ * covers clock drift between this host and the provider, which is why it is generous.
+ */
+export declare const EXPIRY_SKEW_MS = 60000;
+/**
+ * Collect every credential-shaped value in a parsed body.
+ *
+ * Recursive because providers nest error payloads, and a token one level down is exactly as
+ * damaging as one at the top.
+ */
+export declare function secretsIn(body: unknown): string[];
+/** Replace every known secret with a marker. Longest first, so a prefix cannot leave a tail behind. */
+export declare function redactSecrets(text: string, secrets: readonly string[]): string;
+/** The authorization-code redemption body. */
+export declare function codeExchangeBody(config: IdentityConfig, code: string, codeVerifier: string, redirectUri: string): string;
+/** The refresh body. */
+export declare function refreshBody(config: IdentityConfig, refreshToken: string): string;
+/**
+ * Turn a token-endpoint response into a `TokenSet`, or into the right kind of refusal.
+ *
+ * Two failure reasons, and they must not be collapsed — the same discipline the permission gate
+ * uses. A non-2xx is the provider refusing or an outage: the fix is a credential, a tenant policy,
+ * or a retry. A 2xx whose body cannot be used is version skew or a misconfigured endpoint: the fix
+ * is code or configuration. One is the provider's problem and one is this host's.
+ */
+export declare function readTokenResponse(status: number, body: unknown, nowMs: number): Result<TokenSet>;
+/** Is this token still usable, allowing for the skew? */
+export declare function isFresh(tokens: TokenSet, nowMs: number): boolean;
+/** The header a fresh token is presented as. */
+export declare function authorizationValue(tokens: TokenSet): string;
+//# sourceMappingURL=token.d.ts.map

package/dist/identity/token.js

@@ -0,0 +1,149 @@
+import { ok, refuse } from '../core/result.js';
+/**
+ * How long before expiry a token is treated as already expired.
+ *
+ * A token that expires in four seconds is not usable for a request that takes five. The skew also
+ * covers clock drift between this host and the provider, which is why it is generous.
+ */
+export const EXPIRY_SKEW_MS = 60_000;
+/** The field names whose values must never reach a log, at any nesting depth. */
+const SECRET_FIELDS = ['access_token', 'refresh_token', 'id_token', 'code', 'code_verifier', 'client_secret'];
+/**
+ * Collect every credential-shaped value in a parsed body.
+ *
+ * Recursive because providers nest error payloads, and a token one level down is exactly as
+ * damaging as one at the top.
+ */
+export function secretsIn(body) {
+    const found = [];
+    const visit = (node, depth) => {
+        if (depth > 8 || typeof node !== 'object' || node === null)
+            return;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item, depth + 1);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (SECRET_FIELDS.includes(key) && typeof value === 'string' && value !== '')
+                found.push(value);
+            else
+                visit(value, depth + 1);
+        }
+    };
+    visit(body, 0);
+    return found;
+}
+/** Replace every known secret with a marker. Longest first, so a prefix cannot leave a tail behind. */
+export function redactSecrets(text, secrets) {
+    let out = text;
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+        if (secret === '')
+            continue;
+        out = out.split(secret).join('[redacted]');
+    }
+    return out;
+}
+/** Bound a provider-supplied string before it becomes a message. */
+function bounded(value, max = 200) {
+    return value.length <= max ? value : `${value.slice(0, max)}… (${value.length} chars)`;
+}
+function form(pairs) {
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(pairs))
+        body.set(key, value);
+    return body.toString();
+}
+/** The authorization-code redemption body. */
+export function codeExchangeBody(config, code, codeVerifier, redirectUri) {
+    return form({
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+        scope: config.scopes.join(' '),
+    });
+}
+/** The refresh body. */
+export function refreshBody(config, refreshToken) {
+    return form({
+        grant_type: 'refresh_token',
+        client_id: config.clientId,
+        refresh_token: refreshToken,
+        scope: config.scopes.join(' '),
+    });
+}
+/**
+ * Turn a token-endpoint response into a `TokenSet`, or into the right kind of refusal.
+ *
+ * Two failure reasons, and they must not be collapsed — the same discipline the permission gate
+ * uses. A non-2xx is the provider refusing or an outage: the fix is a credential, a tenant policy,
+ * or a retry. A 2xx whose body cannot be used is version skew or a misconfigured endpoint: the fix
+ * is code or configuration. One is the provider's problem and one is this host's.
+ */
+export function readTokenResponse(status, body, nowMs) {
+    const secrets = secretsIn(body);
+    if (status < 200 || status >= 300) {
+        const record = typeof body === 'object' && body !== null ? body : {};
+        const error = typeof record['error'] === 'string' ? record['error'] : `HTTP ${status}`;
+        const description = typeof record['error_description'] === 'string' ? record['error_description'] : null;
+        // Only the two named fields are quoted — the body is never dumped. That is the first of two
+        // defences here, and it is the one that is easy to lose: "echo what the provider said so the
+        // operator can see it" is the natural implementation and it writes tokens to a log.
+        const message = description === null ? error : `${error}: ${description}`;
+        // `invalid_grant` is a different answer from every other non-2xx, and conflating them hides a
+        // dead grant behind retries. RFC 6749 section 5.2 defines it as the grant being expired, revoked,
+        // or issued to another client - none of which the next attempt improves. Everything else here is
+        // something a retry may well survive: a gateway hiccup, a throttle, a provider blip.
+        //
+        // This reader serves both grant exchanges, and the conclusion holds for each. On a refresh the
+        // refresh token has lapsed; on the initial code exchange the authorization code has expired or
+        // been replayed. Either way the material presented is spent and the next attempt with the same
+        // material fails identically - what differs is only which sign-in a person has to redo.
+        //
+        // The name is the RFC's, not a provider's. Providers append their own diagnostic codes to
+        // `error_description` and no one provider's is canonical; branching on the standard name is
+        // what keeps the rule true for a host pointed somewhere else.
+        if (error === 'invalid_grant') {
+            return refuse('token-grant-rejected', redactSecrets(bounded(`${message} - this grant is no longer valid; a new sign-in is required`), secrets));
+        }
+        return refuse('token-request-failed', redactSecrets(bounded(message), secrets));
+    }
+    if (typeof body !== 'object' || body === null) {
+        return refuse('token-response-invalid', 'the token endpoint returned 2xx with a body that is not a JSON object');
+    }
+    const record = body;
+    const accessToken = record['access_token'];
+    if (typeof accessToken !== 'string' || accessToken === '') {
+        return refuse('token-response-invalid', 'the token endpoint returned 2xx with no access_token');
+    }
+    // `expires_in` is only recommended by RFC 6749, and this host refuses without it anyway. An
+    // unattended host that does not know when its token dies cannot decide when to refresh — it would
+    // either refresh on every single call or discover expiry as a 401 in the middle of doing
+    // something. Neither is acceptable, and guessing a lifetime would be inventing a fact.
+    const expiresIn = record['expires_in'];
+    const seconds = typeof expiresIn === 'number' ? expiresIn : Number(expiresIn);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return refuse('token-response-invalid', 'the token endpoint returned 2xx with no usable expires_in; an unattended host cannot decide when to refresh a token whose lifetime it does not know');
+    }
+    const refreshToken = record['refresh_token'];
+    const scope = record['scope'];
+    const tokenType = record['token_type'];
+    return ok({
+        accessToken,
+        refreshToken: typeof refreshToken === 'string' && refreshToken !== '' ? refreshToken : null,
+        expiresAt: nowMs + seconds * 1000,
+        tokenType: typeof tokenType === 'string' && tokenType !== '' ? tokenType : 'Bearer',
+        scope: typeof scope === 'string' ? scope : null,
+    });
+}
+/** Is this token still usable, allowing for the skew? */
+export function isFresh(tokens, nowMs) {
+    return tokens.expiresAt - EXPIRY_SKEW_MS > nowMs;
+}
+/** The header a fresh token is presented as. */
+export function authorizationValue(tokens) {
+    return `${tokens.tokenType} ${tokens.accessToken}`;
+}
+//# sourceMappingURL=token.js.map

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The public surface of the package.
+ *
+ * Everything a consumer may depend on is named here or on the `./protocol` subpath. A module not
+ * re-exported from one of the two is internal, whatever its file path suggests.
+ */
+export * from './protocol.js';
+export type { LinkHandlers, LinkOptions } from './control/link.js';
+export { ControllerLink } from './control/link.js';
+export type { ForwardSessionOptions, FrameSink } from './control/stream.js';
+export { forwardSession } from './control/stream.js';
+export type { RoutingRow, StreamLane } from './control/stream-routing.js';
+export { MESSAGE_ROUTING, discriminatorsOn, laneFor } from './control/stream-routing.js';
+export type { LinkCause, LinkState, LinkTransition } from './control/link-state.js';
+export { LINK_CAUSES, LinkStateMachine } from './control/link-state.js';
+export type { BackoffOptions } from './control/backoff.js';
+export { DEFAULT_BACKOFF, nextDelayMs } from './control/backoff.js';
+export type { QueueStats } from './control/queue.js';
+export { BoundedFrameQueue } from './control/queue.js';
+export type { Authorization, ControllerCredential } from './control/credential.js';
+export { UnconfiguredCredential } from './control/credential.js';
+export { HOST_NOUNS, SDK_NOUNS, isAbsolutePath, isContainedBy, isDeclaredNoun, isOk, nounOf, normalizePath, ok, refuse, refusal, requireAbsolute, systemClock, systemTicker, valueOr, } from './core/index.js';
+export type { Clock, HostNoun, SdkNoun, Ticker } from './core/index.js';
+export * from './state/index.js';
+export * from './sessions/index.js';
+export type { BulkPostReceipt, BulkPostRequest, MachineFacts } from './host/index.js';
+export { credentialPaths, nodePathResolver, periscopeCredentialDir, postBulk, readMachineFacts, tokenCachePath, } from './host/index.js';
+export type { BulkResolver, ComposeSessionOptions, ComposedSession, GateTimings, HostEvent, PeriscopeHostOptions, } from './host/index.js';
+export { PeriscopeHost, composeSession } from './host/index.js';
+export * from './identity/index.js';
+export type { DeviceCodeInstruction, LoopbackListener, SignInDeps, TokenCacheWrite } from './host/index.js';
+export { DEFAULT_SIGN_IN_TIMEOUT_MS, FileTokenCache, LOOPBACK_HOST, openLoopbackListener, probeModeEnforcement, protocolFor, refresherFor, resolveEndpoints, signIn, signInWithDeviceCode, } from './host/index.js';
+export type { HookFailureListener, ObservationHookOptions } from './host/hooks.js';
+export { mergeHooks, observationHooks, wiredHookEvents } from './host/hooks.js';
+export { readWhere } from './host/git-facts.js';
+export * from './gate/index.js';
+export * from './workspace/index.js';
+export { nodeCommandEffects, nodeWorkspaceEffects } from './host/workspace-fs.js';
+export * from './mcp/index.js';
+export { createToolServer } from './host/mcp-server.js';
+export * from './persistence/index.js';
+export { asSessionStore, nodeStoreEffects, readMirrorDrop, toSessionKey, toTranscriptKey, } from './host/index.js';
+export * from './telemetry/index.js';
+export { readRateLimit, readTaskSpend, readTurnSpend } from './host/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * The public surface of the package.
+ *
+ * Everything a consumer may depend on is named here or on the `./protocol` subpath. A module not
+ * re-exported from one of the two is internal, whatever its file path suggests.
+ */
+// The wire contract, re-exported so `@naswerks/periscope` alone is enough for a host-side consumer. A
+// controller that wants only the wire should import `@naswerks/periscope/protocol` instead — that path
+// cannot reach the privileged module.
+export * from './protocol.js';
+export { ControllerLink } from './control/link.js';
+export { forwardSession } from './control/stream.js';
+export { MESSAGE_ROUTING, discriminatorsOn, laneFor } from './control/stream-routing.js';
+export { LINK_CAUSES, LinkStateMachine } from './control/link-state.js';
+export { DEFAULT_BACKOFF, nextDelayMs } from './control/backoff.js';
+export { BoundedFrameQueue } from './control/queue.js';
+export { UnconfiguredCredential } from './control/credential.js';
+// The pure core.
+export { HOST_NOUNS, SDK_NOUNS, isAbsolutePath, isContainedBy, isDeclaredNoun, isOk, nounOf, normalizePath, ok, refuse, refusal, requireAbsolute, systemClock, systemTicker, valueOr, } from './core/index.js';
+// The declared state model, its machine, its store and the coverage table.
+export * from './state/index.js';
+// The agent session lifecycle and the registry of live sessions.
+export * from './sessions/index.js';
+export { credentialPaths, nodePathResolver, periscopeCredentialDir, postBulk, readMachineFacts, tokenCachePath, } from './host/index.js';
+export { PeriscopeHost, composeSession } from './host/index.js';
+// Identity — the pure flows, plus the two impure halves that live in `host/` by the same rule as
+// everything else that touches the machine.
+export * from './identity/index.js';
+export { DEFAULT_SIGN_IN_TIMEOUT_MS, FileTokenCache, LOOPBACK_HOST, openLoopbackListener, probeModeEnforcement, protocolFor, refresherFor, resolveEndpoints, signIn, signInWithDeviceCode, } from './host/index.js';
+export { mergeHooks, observationHooks, wiredHookEvents } from './host/hooks.js';
+export { readWhere } from './host/git-facts.js';
+// The permission gate. Registered after observationHooks — see permissionHooks' own note on why the
+// order is load-bearing.
+export * from './gate/index.js';
+// Workspace provisioning — the directory a session runs in. The two providers ship; the interesting
+// policies (a shared directory per task, a branch naming rule, a cleanup schedule) are the
+// embedder's and are written against `WorkspaceProvider` rather than added here.
+export * from './workspace/index.js';
+export { nodeCommandEffects, nodeWorkspaceEffects } from './host/workspace-fs.js';
+// The generic tool mechanism: descriptors in, an in-process MCP server out. The host validates a
+// call against the schema it was handed, attaches session identity, forwards, and returns — it never
+// learns what any tool means. `createToolServer` sits in `host/` because it names the SDK.
+export * from './mcp/index.js';
+export { createToolServer } from './host/mcp-server.js';
+// Durability. The pure half — the store contract, the receipt read path, the transition log's
+// encoding and the retention policy — plus the two impure halves in `host/`: the local JSONL
+// effects, and the bridge that presents a store to the SDK.
+export * from './persistence/index.js';
+export { asSessionStore, nodeStoreEffects, readMirrorDrop, toSessionKey, toTranscriptKey, } from './host/index.js';
+// Cost, usage and rate limits — read from the agent's own result, never computed from a price table.
+export * from './telemetry/index.js';
+export { readRateLimit, readTaskSpend, readTurnSpend } from './host/index.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/descriptor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The descriptor contract — what an embedder supplies so this host can register an in-process tool.
+ *
+ * The descriptor is deliberately language-neutral. An embedder composing this host from another
+ * language, or a controller whose descriptors an embedder forwards,
+ * cannot express a TypeScript schema library's types, and asking it to would put a TypeScript
+ * dependency on the wire — which is precisely the leak this package is built to avoid. So a
+ * descriptor is JSON: a name, a description, and a JSON-Schema object. The host converts it
+ * (schema.ts) into what the SDK needs.
+ *
+ * The host never learns what a tool means. It validates the descriptor's shape, converts the
+ * schema it was handed, checks a call's arguments against that schema, attaches session identity,
+ * forwards, and returns the answer. There is no branch anywhere on a tool's name — pinned by
+ * pins/mcp-generic.test.ts, which registers the same descriptors under permuted names and requires
+ * the results to be identical.
+ *
+ * The subset is declared, not inferred. Only the constructs below are convertible. A descriptor
+ * carrying anything else is refused at registration rather than converted to something permissive —
+ * see schema.ts, where that rule is the most consequential line in this directory.
+ */
+import type { JsonValue } from '../control/frames.js';
+/** The JSON-Schema types this host converts. Anything else is refused by name. */
+export declare const SUPPORTED_SCHEMA_TYPES: readonly ["string", "number", "integer", "boolean", "array", "object"];
+export type SupportedSchemaType = (typeof SUPPORTED_SCHEMA_TYPES)[number];
+/**
+ * One node of a tool's input schema.
+ *
+ * Everything is optional because this is what ARRIVES — an untrusted object off the wire, not a
+ * shape this package constructs. Validation happens in schema.ts and reports what was wrong.
+ */
+export interface JsonSchemaNode {
+    readonly type?: string;
+    readonly description?: string;
+    /** A closed set of literal values. Takes precedence over `type`. */
+    readonly enum?: readonly JsonValue[];
+    /** For `array`. */
+    readonly items?: JsonSchemaNode;
+    /** For `object`. */
+    readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+    readonly required?: readonly string[];
+    /** JSON-Schema draft-4 style, and the spelling most emitters produce. */
+    readonly nullable?: boolean;
+}
+/** A tool's input schema. Always an object at the top level — `tool()` takes a shape, not a type. */
+export interface JsonSchemaObject extends JsonSchemaNode {
+    readonly type?: 'object';
+    readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+    readonly required?: readonly string[];
+}
+/** One tool, as the embedder describes it. */
+export interface ToolDescriptor {
+    /** What the agent calls. Reaches the model as `mcp__{server}__{name}`. */
+    readonly name: string;
+    /** What the tool does, in the model's terms. The only thing that makes it usable. */
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+}
+export declare function isUsableToolName(name: string): boolean;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/mcp/descriptor.js

@@ -0,0 +1,14 @@
+/** The JSON-Schema types this host converts. Anything else is refused by name. */
+export const SUPPORTED_SCHEMA_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'];
+/**
+ * A tool name both the MCP protocol and the agent CLI accept.
+ *
+ * Conservative on purpose: the name is concatenated into `mcp__{server}__{name}`, so a name carrying
+ * the separator would produce a tool the agent addresses ambiguously — and the failure would look
+ * like the wrong tool being called rather than like a bad name.
+ */
+const NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+export function isUsableToolName(name) {
+    return NAME_PATTERN.test(name) && !name.includes('__');
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-process MCP servers and the tool descriptors that build them.
+ *
+ * `createToolServer` is not here. It calls the SDK, so it lives in `host/mcp-server.ts` under the
+ * rule that one directory names the SDK — see that file. Everything in this directory is the
+ * decisions: the descriptor contract, the schema conversion, and the plan a server is built from.
+ */
+export type { JsonSchemaNode, JsonSchemaObject, SupportedSchemaType, ToolDescriptor } from './descriptor.js';
+export { SUPPORTED_SCHEMA_TYPES, isUsableToolName } from './descriptor.js';
+export type { ZodRawShape } from './schema.js';
+export { toRawShape, toZod } from './schema.js';
+export type { McpServerOptions, ToolCall, ToolCallIdentity, ToolInvoker, ToolPlan, ToolResponse, ToolResult, } from './server.js';
+export { planTools } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.js

@@ -0,0 +1,4 @@
+export { SUPPORTED_SCHEMA_TYPES, isUsableToolName } from './descriptor.js';
+export { toRawShape, toZod } from './schema.js';
+export { planTools } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * JSON-Schema to Zod raw shape, because that is the shape the SDK's `tool()` actually takes.
+ *
+ * Why a conversion exists at all. `SdkMcpToolDefinition<Schema extends AnyZodRawShape>` is generic
+ * over a Zod raw shape — a plain record of Zod types, not a schema object and not JSON Schema. A
+ * design in which descriptors carry `inputSchema: JsonSchema` and the host does
+ * `validate(input, d.inputSchema)` does not compile against the shipped types. A controller in
+ * another language cannot express Zod shapes, so the conversion happens here and the descriptor
+ * contract stays JSON.
+ *
+ * An unconvertible construct is refused. Never widened, never `z.any()`, never skipped.
+ * This is the most consequential line in the directory. A converter that met something it did not
+ * recognise and fell back to a permissive schema would register the tool successfully and validate
+ * nothing — so "a malformed call is rejected before it reaches the controller" would be silently
+ * false for exactly the tools nobody looked at, while every test stayed green and the tool appeared
+ * to work. That is a false green in the highest-consequence direction: the failure is invisible
+ * precisely where the checking was supposed to be. Refusing happens at registration, before any
+ * session exists, and names the construct that could not be converted.
+ *
+ * The subset is deliberately small — what a controller emits for a tool's arguments. Growing it is
+ * a normal change; growing it by accident is what the refusal prevents.
+ */
+import { z } from 'zod';
+import type { Result } from '../core/result.js';
+import type { JsonSchemaNode, JsonSchemaObject } from './descriptor.js';
+/** What `tool()` takes: a record of Zod types, one per top-level property. */
+export type ZodRawShape = Record<string, z.ZodType>;
+/**
+ * Convert a tool's input schema into a raw shape.
+ *
+ * An object with no properties converts to an empty shape rather than being refused — a tool that
+ * takes no arguments is ordinary, and refusing it would force every caller to invent a parameter.
+ */
+export declare function toRawShape(schema: JsonSchemaObject, at?: string): Result<ZodRawShape>;
+/** Convert one node. Recursive for `array` and `object`. */
+export declare function toZod(node: JsonSchemaNode, at: string): Result<z.ZodType>;
+//# sourceMappingURL=schema.d.ts.map