@withbuddi/buddi 0.1.0-pre.21 → 0.1.0-pre.23

package/packages/tools/mcp/dist/service.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Connections, the service (docs/connections.md; buddi-planning/specs/mcp-client.md).
+ *
+ * The four screens of the flow — address, consent, review, grant — are this
+ * service's methods (grant is the gateway's: it writes agent files through the
+ * same path Agent Father uses). It also owns what happens while buddi runs:
+ * every reviewed connection's tools registered as `mcp.<connection>.<tool>`,
+ * one MCP session per connection, and the connection's state.
+ *
+ * What a server may reach before the owner has read its review: an
+ * `initialize` and a tool list. No token exists until the owner signed in on
+ * the service's own consent page, and no tool is registered until the review
+ * is saved.
+ */
+import type { Pool } from 'pg';
+import { type JSONSchema7, type NetworkArea, type ToolsArea } from '@buddi/core/plugin';
+import type { HttpTransport, OAuthPort, VaultPort } from './ports.js';
+import { Sessions } from './session.js';
+import { type ConnectionRow, type ConnectionState, type ToolRow } from './store.js';
+import { type ToolTier } from './tiers.js';
+import { TokenKeeper } from './tokens.js';
+/** A refusal a route answers with its status and sentence. */
+export declare class ConnectionError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly name = "ConnectionError";
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export interface ConnectionsDeps {
+    pool: Pool;
+    vault: VaultPort | undefined;
+    /** The shared outbound transport (`@buddi/runtime`). A test hands a fake. */
+    transport: HttpTransport;
+    /** The shared OAuth module over the same transport (`createOAuthPort`). */
+    oauth: OAuthPort;
+    /**
+     * Compile a server's input schema the way the registry will, throwing a
+     * sentence when it cannot (core's `compileJsonSchema`). Without one, only
+     * the shape is checked here and the registry has the last word.
+     */
+    compileSchema?: (schema: JSONSchema7) => void;
+    /** A connection's tokens were saved or removed (the output scrubber rebuilds). */
+    tokensChanged?: () => void;
+    now?: () => Date;
+    /** `http://127.0.0.1` servers and authorization servers: tests only. */
+    allowLoopbackHttp?: boolean;
+    log?: (line: string) => void;
+    idleMs?: number;
+    /** How often a connection's tool list is compared with its review, at most. An hour. */
+    recheckMs?: number;
+}
+export interface ConnectionView {
+    id: string;
+    slug: string | null;
+    name: string;
+    url: string;
+    host: string;
+    state: ConnectionState;
+    authKind: 'none' | 'oauth';
+    /** OAuth: tokens are in the vault. Always true for a server that wants none. */
+    signedIn: boolean;
+    /** Tools registered for agents (enabled, reviewed). */
+    toolCount: number;
+    /** `mcp.<slug>.*`, what an agent's `tools:` line grants; null before review. */
+    grant: string | null;
+    serverName: string | null;
+    serverVersion: string | null;
+    reviewedAt: string | null;
+    /** When it stopped answering, while it is `unreachable` (buddi retries it in the background). */
+    unreachableSince: string | null;
+    /** Reviewed tools the server changed or dropped since: they wait for another review. */
+    heldTools: number;
+}
+/** What changed in a server's list since the owner's review, by the server's names. */
+export interface ReviewChanges {
+    added: string[];
+    changed: string[];
+    removed: string[];
+}
+export interface ReviewTool {
+    /** The server's name for it. */
+    name: string;
+    /** What buddi will call it: `mcp.<slug>.<tool>`. */
+    fullName: string;
+    description: string;
+    tier: ToolTier;
+    destructive: boolean;
+    /** The server said something about the tool's effect. */
+    annotated: boolean;
+    /** Why it cannot be used, when it cannot. */
+    problem: string | null;
+    /** Against the last review: new, or changed since. Null when it is as reviewed (or on a first review). */
+    change: 'added' | 'changed' | null;
+}
+export interface ReviewView {
+    connection: ConnectionView;
+    slug: string;
+    /** Only the first review chooses the slug; after that agent files name it. */
+    slugEditable: boolean;
+    host: string;
+    hash: string;
+    tools: ReviewTool[];
+    /** The server annotates none of its tools: every one is gated. */
+    annotatedNothing: boolean;
+    /** Against the last review; null on the first one. */
+    changes: ReviewChanges | null;
+}
+/** A line for Home and the rail: a connection that needs the owner. */
+export interface ConnectionSignal {
+    id: string;
+    name: string;
+    state: 'needs-reconnect' | 'needs-review';
+    sentence: string;
+}
+export type SignIn = 'none' | 'dynamic' | 'manual';
+/** Spec §2: the escape hatch, one sentence. */
+export declare const NEEDS_CLIENT_ID = "This service does not let buddi register itself, so it needs a client id you create in the service's developer settings, with the address below as its redirect.";
+/** After a failure, the next try is this many minutes on; the last one repeats (spec: 1, 5, 15, 60, then hourly). */
+export declare const RETRY_MINUTES: readonly [1, 5, 15, 60];
+export declare const RECHECK_MS: number;
+export declare function changedSentence(name: string, tool: string): string;
+export declare function reconnectSentence(name: string): string;
+export declare class ConnectionsService {
+    #private;
+    readonly deps: ConnectionsDeps;
+    readonly sessions: Sessions;
+    readonly tokens: TokenKeeper;
+    constructor(deps: ConnectionsDeps);
+    /**
+     * Where runtime tools go (the plugin's `ctx.buddi.tools`) and where its
+     * hosts are declared (`ctx.buddi.network`), handed over at register.
+     */
+    attachTools(area: ToolsArea, network?: NetworkArea): void;
+    view(row: ConnectionRow, tools: readonly ToolRow[]): ConnectionView;
+    list(): Promise<ConnectionView[]>;
+    get(id: string): Promise<ConnectionView>;
+    /** The connections that need the owner, in a sentence each: Home's line and the rail's dot. */
+    signals(): Promise<ConnectionSignal[]>;
+    /** The grant prefix of a connection: `mcp.<slug>.`, what agent files name. */
+    static grantPrefix(slug: string): string;
+    /**
+     * Open the server (`initialize`), read its name, and find out whether it
+     * wants a sign-in. The connection is recorded, pending review.
+     */
+    add(input: {
+        url: string;
+        name?: string;
+    }): Promise<{
+        connection: ConnectionView;
+        signIn: SignIn;
+    }>;
+    /**
+     * Register buddi with the service's authorization server (or take the
+     * client id the owner typed), and hand back the consent page's address,
+     * with PKCE and a state bound to this dashboard session. Reconnect is this,
+     * on a connection that keeps its tools.
+     */
+    beginConsent(id: string, input: {
+        sessionId: string;
+        redirectUri: string;
+        clientId?: string;
+    }): Promise<{
+        authorizeUrl: string;
+    }>;
+    /**
+     * The consent page came back to `/connections/callback`: check the state
+     * (this session's, unexpired, used once), exchange the code, keep the tokens
+     * in the vault. A connection that was reviewed before is connected again
+     * with its tools as they were.
+     */
+    finishConsent(input: {
+        sessionId: string;
+        state: string;
+        code?: string;
+        error?: string;
+    }): Promise<{
+        id: string;
+        reconnected: boolean;
+        name: string;
+    }>;
+    /** Every tool the server lists, as buddi would take it. Nothing is registered. */
+    review(id: string): Promise<ReviewView>;
+    /**
+     * The owner read the review: keep the list as it was read, name the
+     * connection, and register its tools. The server's list is read again, and
+     * a list that changed since the owner read it is refused.
+     */
+    saveReview(id: string, input: {
+        slug?: string;
+        hash: string;
+    }): Promise<ConnectionView>;
+    /**
+     * Take the tokens out of the vault, the tools out of the registry, the
+     * connection out of the store. The gateway removes the grants from agent
+     * files first, while the tools still resolve.
+     */
+    disconnect(id: string): Promise<{
+        id: string;
+        name: string;
+        slug: string | null;
+    }>;
+    /** Register every reviewed connection's tools. Once at start. */
+    boot(): Promise<void>;
+    /** The full names registered for a connection. */
+    registeredNames(id: string): string[];
+    /**
+     * Try every unreachable connection whose time has come: open it and read
+     * its list. It answers: connected again (or needs review, when the list
+     * changed). A 401: needs reconnect. Nothing: the next try is further off
+     * (1, 5, 15, 60 minutes, then hourly).
+     */
+    retryDue(): Promise<void>;
+    /** When an unreachable connection is tried next (tests, the page). */
+    nextRetryAt(id: string): Date | null;
+    /** Retry unreachable connections on a timer that never keeps the process alive. */
+    startBackground(everyMs?: number): void;
+    static envelope(row: Pick<ConnectionRow, 'name' | 'host' | 'slug'>, tool: string, input: unknown): Record<string, unknown>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/packages/tools/mcp/dist/service.d.ts.map

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