@vornrun/connector-sdk 0.7.0-beta.7 → 0.7.0

package/dist/check-62s2GvcO.d.ts

@@ -0,0 +1,1137 @@
+/**
+ * Author-facing types for Vorn connectors.
+ *
+ * A connector written with this SDK runs as an ordinary MCP stdio server, so
+ * it is shared as a normal npm package and installed by pointing a Vorn
+ * connection at `npx -y <package>`. Nothing about the host app has to change
+ * to accept a new connector.
+ */
+/** A raw item as the author's code returns it. Only id and title are required. */
+interface ConnectorItem {
+    /** Stable upstream identity. Vorn dedupes on this, so it must not change. */
+    externalId: string | number;
+    title: string;
+    url?: string;
+    description?: string;
+    /** Raw upstream status (`open`, `Active`, `In Progress`, …). */
+    status?: string;
+    labels?: string[];
+    assignee?: string;
+    /**
+     * When the item last changed. Vorn advances its poll cursor from this field,
+     * so it must be monotonic per item and comparable as an ISO 8601 string.
+     * Defaults to poll time when omitted.
+     */
+    updatedAt?: string | Date;
+    /** Extra fields to expose to workflow templates as `{{trigger.item.<key>}}`. */
+    data?: Record<string, unknown>;
+}
+/** A connector item after normalization. This is the exact JSON Vorn sees. */
+interface NormalizedItem extends Record<string, unknown> {
+    externalId: string;
+    title: string;
+    url: string;
+    description: string;
+    status: string;
+    labels: string[];
+    updatedAt: string;
+    assignee?: string;
+}
+/** Declares a value the connector needs at runtime, read from the environment. */
+interface ConnectorConfigField {
+    key: string;
+    label: string;
+    /** Environment variable the value is read from. Defaults to CONSTANT_CASE(key). */
+    env?: string;
+    required?: boolean;
+    /** Secrets are stored encrypted by Vorn and never printed by the CLI. */
+    secret?: boolean;
+    description?: string;
+    default?: string;
+    /**
+     * A note for whoever is building this connector rather than using it: where
+     * the value is found, what a good one looks like. The factory's agent reads
+     * these, so a field that is easy to get wrong can say so once here instead of
+     * being got wrong in every connector that copies it.
+     */
+    builderHint?: string;
+}
+type ConnectorConfig = Record<string, string | undefined>;
+interface PollContext {
+    config: ConnectorConfig;
+    /**
+     * Lower bound the host asked for, when it was able to supply one. Treat it
+     * as a hint: returning older items is safe because Vorn dedupes, but
+     * returning fewer than everything after `since` loses events.
+     */
+    since?: string;
+    /** Opaque cursor previously returned by this trigger, when supplied. */
+    cursor?: string;
+    /** Upper bound on items to return in one page. */
+    limit?: number;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+    /** Fetch with the SDK's retry and backoff applied. A poll is always a read. */
+    fetch: typeof fetch;
+    /** Present only when the connector signs in through a Vorn window. */
+    session?: SessionContext;
+}
+interface PollOutcome {
+    items: ConnectorItem[];
+    nextCursor?: string;
+    hasMore?: boolean;
+}
+/**
+ * How the SDK decides which fetched items are new.
+ *
+ * - `timestamp` — for sources that expose a reliable "last changed" field and
+ *   can filter on it. Handles the boundary case where several items share the
+ *   newest timestamp, which is the classic source of both duplicates and
+ *   silently dropped items.
+ * - `lastItem` — for feeds that return newest-first with no dependable
+ *   timestamp. The cursor is the newest id already delivered.
+ */
+type DedupeStrategy = 'timestamp' | 'lastItem';
+/**
+ * What a declarative trigger's `fetch` receives. Deliberately smaller than
+ * {@link PollContext}: cursor encoding, ordering, windowing and de-duplication
+ * are the SDK's job, so the author only has to answer "what is there now?".
+ */
+interface FetchContext {
+    config: ConnectorConfig;
+    /**
+     * With `dedupe: 'timestamp'`, everything changed at or after this instant is
+     * worth returning. Absent on the very first poll. Returning a little too
+     * much is safe — the SDK drops what was already delivered.
+     */
+    since?: string;
+    /**
+     * With `dedupe: 'lastItem'`, the newest id already delivered. Absent on the
+     * very first poll. Return the feed newest-first and the SDK will stop there.
+     */
+    lastItemId?: string;
+    /** Upper bound on items worth returning in one call. */
+    limit?: number;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+    /** Fetch with the SDK's retry and backoff applied. A fetch is always a read. */
+    fetch: typeof fetch;
+    /** Present only when the connector signs in through a Vorn window. */
+    session?: SessionContext;
+}
+/**
+ * What an upstream state should become when an item is imported as a task.
+ *
+ * A suggestion, not a rule: it seeds the connection form, and the person
+ * setting it up can change it. Without any, everything a connector imports
+ * lands as `todo` regardless of whether it was closed a year ago.
+ */
+interface StatusSuggestion {
+    /** The value the connector reports in `ConnectorItem.status`. */
+    upstream: string;
+    suggestedLocal: 'todo' | 'in_progress' | 'in_review' | 'done' | 'cancelled';
+}
+/**
+ * The workflow to create when a connection is made.
+ *
+ * A connector that fires on a schedule is useless until something polls it, and
+ * expecting every person to build that workflow by hand is how a connection
+ * ends up configured and silent. Seeded workflows are ordinary, visible and
+ * editable — the schedule is a starting point, not a fixed rule.
+ */
+interface DefaultWorkflow {
+    name: string;
+    defaultCronFromMinutes: number;
+}
+interface TriggerBase {
+    /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
+    type: string;
+    label: string;
+    description?: string;
+    /** Seeds the connection's status mapping; the person setting it up owns it. */
+    statusMapping?: StatusSuggestion[];
+    /** Seeds a polling workflow when a connection is created. */
+    defaultWorkflow?: DefaultWorkflow;
+    /**
+     * Representative items. `vorn-connector check` replays these through the
+     * real dedupe pipeline, so a connector can be verified before anyone has
+     * credentials for it.
+     */
+    sample?: ConnectorItem[];
+}
+/**
+ * A trigger is either declarative or hand-written, never both — expressed as a
+ * union so the invalid combinations are a type error at authoring time rather
+ * than a throw when the connector is first loaded.
+ */
+type TriggerDefinition = TriggerBase & ({
+    /**
+     * Declarative polling: return what the source has and let the SDK
+     * handle cursors and de-duplication.
+     */
+    dedupe: DedupeStrategy;
+    fetch(context: FetchContext): Promise<ConnectorItem[]> | ConnectorItem[];
+    poll?: never;
+} | {
+    /**
+     * Full control over cursors and paging. Use only when the source's
+     * paging cannot be expressed as "give me everything since X".
+     */
+    poll(context: PollContext): Promise<PollOutcome> | PollOutcome;
+    dedupe?: never;
+    fetch?: never;
+});
+/**
+ * What kind of value an action argument takes.
+ *
+ * Every argument still arrives as a string — Vorn renders them from templates —
+ * so this says how to read one, and how to draw its field. `select` is a
+ * string with known choices; `json` is a string holding a structured value.
+ */
+type ActionInputType = 'string' | 'number' | 'boolean' | 'select' | 'json';
+/** One choice a `select` argument offers. */
+interface ActionInputOption {
+    value: string;
+    /** Shown instead of the value where the raw value would not read well. */
+    label?: string;
+}
+interface ActionInputField {
+    key: string;
+    label: string;
+    type?: ActionInputType;
+    required?: boolean;
+    description?: string;
+    /** Fixed choices, for a `select` whose options are known when it is written. */
+    options?: ActionInputOption[];
+    /**
+     * Names an options set the connector serves, for a `select` whose choices
+     * are only knowable against a live connection — the channels in a workspace,
+     * the projects in an account.
+     */
+    loadOptions?: string;
+    /** A note for whoever is building the connector, not for whoever runs it. */
+    builderHint?: string;
+}
+/**
+ * A field the action is known to return. Declaring these is optional — extra
+ * keys always pass through — but declared fields show up in Vorn's variable
+ * autocomplete as `{{steps.<action>.<key>}}`.
+ */
+interface ActionOutputField {
+    key: string;
+    type?: 'string' | 'number' | 'boolean';
+    description?: string;
+}
+interface ActionContext {
+    config: ConnectorConfig;
+    now(): string;
+    /**
+     * Fetch, with the SDK's retry, backoff and rate-limit handling already
+     * applied. Prefer it over the global one: a hand-written action gets the
+     * same resilience a declared request does, and tests can replace it.
+     */
+    fetch: typeof fetch;
+    /** Present only when the connector signs in through a Vorn window. */
+    session?: SessionContext;
+}
+/**
+ * One step of reshaping a response.
+ *
+ * Each op reads the whole value, or just what lives at its dotted `path`, and
+ * leaves the rest alone. They compose left to right, which is enough to turn
+ * most envelopes into the record a workflow step wants.
+ */
+type PostReceiveOp = 
+/** Keep only these keys, of the object or of every object in the list. */
+{
+    op: 'pick';
+    keys: string[];
+    path?: string;
+}
+/** Give a key a better name, of the object or of every object in the list. */
+ | {
+    op: 'rename';
+    from: string;
+    to: string;
+    path?: string;
+}
+/** Replace the whole value with what is at this path — unwrap the envelope. */
+ | {
+    op: 'flatten';
+    path: string;
+}
+/** Keep the list entries whose `key` equals this value. */
+ | {
+    op: 'filter';
+    key: string;
+    equals: unknown;
+    path?: string;
+}
+/** Run these ops against every entry of the list. */
+ | {
+    op: 'map';
+    ops: PostReceiveOp[];
+    path?: string;
+};
+/**
+ * How to ask for the page after this one.
+ *
+ * Declared rather than written because every source does the same three things
+ * — hand back a cursor, count pages, or put a link in a header — and following
+ * them by hand is where "only the first 100 items ever arrive" comes from.
+ */
+type PaginationStrategy = 
+/** The response carries a cursor at `cursorPath`; send it back as `param`. */
+{
+    kind: 'cursor';
+    cursorPath: string;
+    param: string;
+    itemsPath?: string;
+}
+/** Ask for page 1, 2, 3 … under `param`, until a page comes back short. */
+ | {
+    kind: 'page';
+    param: string;
+    startPage?: number;
+    itemsPath?: string;
+}
+/** Follow the `Link` header's `rel="next"`, as paged HTTP APIs do. */
+ | {
+    kind: 'link';
+    itemsPath?: string;
+};
+/** An HTTP call an action makes, with `{{args.x}}` and `{{config.y}}` filled in. */
+interface ActionRequest {
+    /** Defaults to GET. */
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    headers?: Record<string, string>;
+    /** Query parameters. An argument that resolves to nothing is left out. */
+    query?: Record<string, string>;
+    /** Sent as JSON unless it is already a string, or a content type says otherwise. */
+    body?: unknown;
+    /** Follow every page rather than returning only the first. */
+    paginate?: PaginationStrategy;
+}
+interface ActionBase {
+    /** Action key, e.g. `closeWorkItem`. Becomes an MCP tool of the same name. */
+    type: string;
+    label: string;
+    description?: string;
+    /**
+     * Whether repeating the call with the same arguments is safe. Surfaced in
+     * the MCP tool description, because an agent retrying a failed step has no
+     * other way to know whether it is about to create a second issue — and it is
+     * what decides whether the SDK may retry the call itself.
+     */
+    idempotent?: boolean;
+    inputs?: ActionInputField[];
+    outputs?: ActionOutputField[];
+    sample?: Record<string, string>;
+}
+/**
+ * An action is either declared or hand-written, never both — the same union
+ * shape triggers use, so the invalid combination is a type error while the
+ * connector is being written rather than a throw once it is installed.
+ */
+type ActionDefinition = ActionBase & ({
+    run(args: Record<string, unknown>, context: ActionContext): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+    request?: never;
+    postReceive?: never;
+} | {
+    /** The call to make. The SDK sends it and keeps the response. */
+    request: ActionRequest;
+    /** How to reshape what came back, before the step sees it. */
+    postReceive?: PostReceiveOp[];
+    run?: never;
+});
+/**
+ * A connector's own glyph, so an installed connector is recognizable in a list
+ * rather than sharing one generic icon with every other one.
+ *
+ * Path data only — deliberately not markup. Vorn draws these itself as
+ * `<path d="...">` inside an `<svg>` it owns, so a connector cannot inject
+ * elements, scripts or external references into the app rendering it.
+ */
+interface ConnectorIcon {
+    /** Defaults to `0 0 24 24`. */
+    viewBox?: string;
+    /** SVG path `d` data, drawn with `fill="currentColor"` so it inherits color. */
+    paths: string[];
+}
+/**
+ * What a connector reports about its own readiness.
+ *
+ * `message` is shown to the user verbatim, so it should say what to do rather
+ * than what went wrong — "run `gh auth login`" beats "not authenticated".
+ */
+interface PreflightResult {
+    ok: boolean;
+    message?: string;
+}
+/**
+ * How a connector signs in, lowest rung first.
+ *
+ * `none` needs nothing — installing it is the whole setup. `cli` borrows a
+ * login that already works on the machine, which is the rung to prefer
+ * whenever a mature tool is signed in anyway. `key` asks for a credential.
+ * `browser` signs in through a Vorn window for a service with no API to key.
+ * `oauth` is declared but not yet carried by the host.
+ */
+type AuthRung = 'none' | 'cli' | 'key' | 'browser' | 'oauth';
+/** How a `browser` connector signs in, and the only origins its calls may reach. */
+interface BrowserSignIn {
+    /** The page the Vorn window opens for signing in. */
+    signInUrl: string;
+    /** `https://host` or `https://*.host`; the sign-in page and the check must sit inside them. */
+    origins: string[];
+    /** Answers 2xx only when signed in; `identity` names the fields of its JSON that say who. */
+    check: {
+        url: string;
+        identity: string[];
+    };
+}
+/** The signed-in window, offered to a `browser` connector's code. */
+interface SessionContext {
+    /** Runs the request inside the connection's signed-in window; cookies never reach the connector. */
+    fetch: typeof fetch;
+}
+/**
+ * What a connector needs before it can talk to anything.
+ *
+ * Declaring this is what lets the app say how a connector signs in *before*
+ * anyone installs it, and lets a `cli` connector show who you already are
+ * instead of a token field. The credential itself is never described here —
+ * only where it comes from.
+ */
+interface ConnectorAuth {
+    rung: AuthRung;
+    /**
+     * Asks the borrowed tool whether it is signed in, e.g. `glab auth status`.
+     * Required for `cli`: without it the app has nothing to ask.
+     */
+    probe?: {
+        command: string;
+        args?: string[];
+    };
+    /**
+     * What to take from the signed-in tool.
+     *
+     * `env` names variables to pass through, and every one of them must also
+     * appear in this connector's own `config` — the host refuses to borrow a
+     * name the connector does not openly read. `tokenArgs` is a command that
+     * prints a token, run fresh at spawn so nothing is ever stored, and
+     * `tokenEnv` names the one variable that receives it (the first of `env` by
+     * default). The rest are pass-throughs: a host or an account id filled with
+     * a token would authenticate against nothing.
+     */
+    borrow?: {
+        env?: string[];
+        tokenArgs?: string[];
+        tokenEnv?: string;
+    };
+    /** Config field keys holding the credential. Required for `key`. */
+    keys?: string[];
+    /** Required for `browser`. */
+    browser?: BrowserSignIn;
+}
+/** What an options set is given to work out its choices. */
+interface OptionsContext {
+    config: ConnectorConfig;
+    now(): string;
+    /** Fetch with the SDK's retry and backoff applied. Listing choices is a read. */
+    fetch: typeof fetch;
+    /** Present only when the connector signs in through a Vorn window. */
+    session?: SessionContext;
+}
+/**
+ * Answers the question "what can this field be?" against a live connection.
+ *
+ * A bare string is taken as a choice that shows itself; return the object form
+ * when the value a step should send and the words a person should read differ.
+ */
+type OptionsLoader = (context: OptionsContext) => Promise<Array<ActionInputOption | string>> | Array<ActionInputOption | string>;
+interface ConnectorDefinition {
+    /** Stable connector id, e.g. `azure-devops`. */
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    icon?: ConnectorIcon;
+    config?: ConnectorConfigField[];
+    /**
+     * Named sets of choices an input can point at with `loadOptions`, for fields
+     * whose values only exist against a live connection — the channels in a
+     * workspace, the projects in an account.
+     */
+    options?: Record<string, OptionsLoader>;
+    /**
+     * How this connector signs in. Absent means the app cannot say, which reads
+     * as "a key, probably" — declare it rather than leave that to be guessed.
+     */
+    auth?: ConnectorAuth;
+    triggers?: TriggerDefinition[];
+    actions?: ActionDefinition[];
+    /**
+     * Whether this connector could work right now, asked before anyone waits on
+     * a poll.
+     *
+     * A connector whose credentials come from config fields does not need this:
+     * a missing field is already a visible, nameable error. One that borrows an
+     * external tool's login — `gh auth login`, `az login` — has no field to be
+     * missing, so without this the first sign that the tool is absent or signed
+     * out is a poll failing some minutes after the connection was saved.
+     *
+     * Answer `ok: false` with a message saying what to do about it. Throwing is
+     * equivalent — the server catches it and reports the same shape with the
+     * error's message — so there is one result for a caller to read and no
+     * behaviour riding on which you choose. Prefer returning when the state is
+     * one you recognise, because then you get to write the sentence.
+     *
+     * Absent means there is nothing to check, which is not the same answer as a
+     * check that passed.
+     */
+    preflight?(): Promise<PreflightResult> | PreflightResult;
+}
+/** What a pack is: a connector polls a service, an extension contributes to a session card. */
+type ConnectorKind = 'connector' | 'extension';
+/** A validated definition. Every accessor below is guaranteed non-null. */
+interface Connector extends ConnectorDefinition {
+    readonly version: string;
+    readonly config: ConnectorConfigField[];
+    readonly triggers: TriggerDefinition[];
+    readonly actions: ActionDefinition[];
+    readonly kind: ConnectorKind;
+    /** What an extension adds to a card. Absent on a connector. */
+    readonly contributes?: ExtensionContributions;
+    /** What an extension may ask the host for. Absent on a connector. */
+    readonly permissions?: ExtensionPermission[];
+    /** Where an extension shows at all. Absent on a connector. */
+    readonly activates?: ActivationPredicate;
+}
+/**
+ * What an extension may ask the host for, named by what it grants rather than
+ * by the method that spends it.
+ *
+ * A closed set on purpose: a permission is shown to a person before they
+ * install, so every one of them has to be a sentence someone can weigh.
+ */
+type ExtensionPermission = 'git.read' | 'terminal.read' | 'terminal.selection' | 'terminal.send' | 'card.rename' | 'agent.usage';
+/** Session types an extension can name; `shell` is a plain terminal. */
+type ExtensionAgent = 'claude' | 'copilot' | 'codex' | 'opencode' | 'gemini' | 'shell';
+type ExtensionPlatform = 'darwin' | 'linux' | 'win32';
+/**
+ * Where a contribution shows.
+ *
+ * Every declared field must hold for it to show, and each is satisfied by any
+ * one of its values: a Rust footer says `workspaceContains: ['Cargo.toml']`
+ * and is simply absent everywhere else, rather than reporting nothing.
+ */
+interface ActivationPredicate {
+    /** Paths relative to the session's worktree; any one of them existing is enough. */
+    workspaceContains?: string[];
+    /** Host of the worktree's git remote, e.g. `github.com`. */
+    remoteHost?: string[];
+    agent?: ExtensionAgent[];
+    platform?: ExtensionPlatform[];
+}
+interface ContributionBase {
+    /** Stable within the extension; the host addresses the contribution by it. */
+    id: string;
+    title: string;
+    description?: string;
+    /** Narrows where this one shows, inside where the extension is active at all. */
+    when?: ActivationPredicate;
+}
+/**
+ * A pane the extension adds beside the terminal: either a page it ships or a
+ * program it runs, never both — a union, so the invalid pair is a type error
+ * while the extension is being written.
+ */
+type PaneContribution = ContributionBase & {
+    /** Glyph for the menu row and the pane's own bar; the extension's is used when absent. */
+    icon?: ConnectorIcon;
+} & ({
+    /** Page inside the pack, under `web/`, rendered in a pane. */
+    web: string;
+    command?: never;
+} | {
+    /** Argv run in the session's worktree, drawn as a terminal. */
+    command: string[];
+    web?: never;
+});
+/** One reading in a footer band: a label, its value, and how the value reads. */
+interface FooterItem {
+    label: string;
+    value: string;
+    /** `ok` and `danger` colour the value; anything else is ordinary text. */
+    tone?: 'default' | 'ok' | 'danger';
+    /** Opened when the item is clicked, for a reading that points somewhere. */
+    href?: string;
+}
+/** What the agent's provider says is left, for the windows it publishes. */
+interface ExtensionUsageWindow {
+    /** The window's own name, e.g. `5h`. */
+    window: string;
+    /** How much of the allowance is left, 0 to 1. */
+    remaining: number;
+    resetsAt?: string;
+}
+interface ExtensionUsage {
+    contextTokens?: number;
+    contextWindow?: number;
+    /** Session-cumulative prompt-cache hit rate, 0 to 1. */
+    cacheHitRate?: number;
+    limits?: ExtensionUsageWindow[];
+}
+/**
+ * The host, as an extension sees it.
+ *
+ * Every method costs exactly one permission — `HOST_PERMISSIONS` says which —
+ * and calling one the manifest did not declare is refused rather than ignored,
+ * so an extension cannot quietly reach past what a person agreed to.
+ */
+interface ExtensionHost {
+    /** The worktree's diff against its base. */
+    diff(): Promise<string>;
+    /** Porcelain status of the worktree. */
+    status(): Promise<string>;
+    /** The session's recent terminal output, newest last. */
+    output(options?: {
+        lines?: number;
+    }): Promise<string>;
+    /** The text selected in the terminal, empty when nothing is selected. */
+    selection(): Promise<string>;
+    /** Type text into the session's terminal, as a person would. */
+    send(text: string): Promise<void>;
+    /** Name the session card, until a person names it themselves. */
+    rename(name: string): Promise<void>;
+    /** Context and provider allowance for the session's agent. */
+    usage(): Promise<ExtensionUsage>;
+}
+/** Every method of the host, so the table naming what each one costs stays complete. */
+type ExtensionHostMethod = keyof ExtensionHost;
+/** What a contribution is told about the session it is running for. */
+interface ExtensionContext {
+    sessionId: string;
+    /** Where the session's work is, so a contribution reads the tree it is about. */
+    worktreePath: string;
+    agent: ExtensionAgent;
+    host: ExtensionHost;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+}
+/** What a link handler is told, on top of the session it was clicked in. */
+interface LinkContext extends ExtensionContext {
+    /** The clicked text, which matched this handler's pattern. */
+    url: string;
+}
+/** What a link handler asks the app to do once it has run. */
+interface LinkHandled {
+    /** Id of one of this extension's panes, opened for the session. */
+    openPane?: string;
+}
+/** A band under the card's status bar, recomputed on its own interval. */
+interface FooterContribution extends ContributionBase {
+    /** Seconds between calls; the host polls no faster than this. */
+    every: number;
+    run(context: ExtensionContext): Promise<FooterItem[]> | FooterItem[];
+}
+/** Offers this extension when the clicked text in a terminal matches. */
+interface LinkHandlerContribution extends ContributionBase {
+    /** Matched as a regular expression against clicked text, under a bound the app sets. */
+    pattern: string;
+    /** A link this handler is for, which its pattern must match; `check` runs the handler on it. */
+    example: string;
+    run(context: LinkContext): Promise<LinkHandled | void> | LinkHandled | void;
+}
+interface ExtensionContributions {
+    panes?: PaneContribution[];
+    footers?: FooterContribution[];
+    linkHandlers?: LinkHandlerContribution[];
+}
+interface ExtensionDefinition {
+    /** Stable extension id, e.g. `review`. */
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    icon?: ConnectorIcon;
+    /** Everything this extension may ask the host for, declared rather than inferred. */
+    permissions: ExtensionPermission[];
+    /** Where the extension shows at all; absent means every session. */
+    activates?: ActivationPredicate;
+    panes?: PaneContribution[];
+    footers?: FooterContribution[];
+    linkHandlers?: LinkHandlerContribution[];
+}
+
+/**
+ * What a connector must be true of as a *package*, rather than as a definition.
+ *
+ * Both `check` and `pack` ask these questions — check to fail a pull request
+ * early, pack to refuse an artifact — so they live here rather than in either,
+ * and neither imports the other.
+ */
+/** Largest pack Vorn will install, matched by the server's own verification. */
+declare const MAX_PACK_BYTES: number;
+interface BundleRequest {
+    contents: string;
+    resolveDir: string;
+}
+interface BundleOutput {
+    code: string;
+    /** Specifiers the bundler left for the runtime to resolve. */
+    external: string[];
+}
+/** Reject a source package whose install would run code on the user's machine. */
+declare function lifecycleScriptFindings(pkg: unknown): CheckFinding[];
+/** Specifiers left outside a bundle, which would need a registry at launch. */
+declare function bundleDependencyFindings(external: string[]): CheckFinding[];
+declare function bundledRequireFindings(code: string): CheckFinding[];
+/** Nearest package.json at or above a directory, or undefined when there is none. */
+declare function readNearestPackageJson(fromDir: string): Record<string, unknown> | undefined;
+/** The bundler `pack` uses, shared so `check` gates on the same answer. */
+declare function esbuildBundle(request: BundleRequest): Promise<BundleOutput>;
+
+/**
+ * Surviving an upstream's bad minute.
+ *
+ * Every connector eventually meets the same three answers — a rate limit, a
+ * gateway that briefly forgot how to work, a socket that died mid-call — and
+ * every author writes the same retry loop for them, usually without the one
+ * part that matters: only repeating calls that are safe to repeat. Doing it
+ * here means a connector gets it by saying nothing at all.
+ */
+interface RetryPolicy {
+    /** Total tries, including the first. Defaults to 3. */
+    attempts?: number;
+    /** First backoff step; each retry doubles it. Defaults to 250ms. */
+    baseDelayMs?: number;
+    /** Ceiling for any single wait, including one the server asked for. */
+    maxDelayMs?: number;
+}
+interface ResilientFetchOptions {
+    fetchImpl: typeof fetch;
+    /**
+     * Whether repeating the call is safe. A read always is; a write is only when
+     * the action said so, because retrying a `create` invents a second one.
+     */
+    retryable: boolean;
+    retry?: RetryPolicy;
+    /** Replaced in tests so backoff costs no real time. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long the server asked us to wait, in milliseconds.
+ *
+ * `Retry-After` is either a count of seconds or an HTTP date; both are common
+ * enough that reading only one of them is how a connector ends up hammering a
+ * rate limiter it was politely asked to back off from.
+ */
+declare function retryAfterMs(header: string | null, now: number): number | undefined;
+/** The wait before try number `attempt`, counting the first try as zero. */
+declare function backoffMs(attempt: number, policy?: RetryPolicy): number;
+/**
+ * Wrap a fetch so it retries what is worth retrying.
+ *
+ * The wrapper is the value handed to actions as `context.fetch`, so a
+ * hand-written action and a declared request are equally protected.
+ */
+declare function resilientFetch(options: ResilientFetchOptions): typeof fetch;
+
+interface PollPage {
+    items: NormalizedItem[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+interface RunPollOptions {
+    config?: ConnectorConfig;
+    since?: string;
+    cursor?: string;
+    limit?: number;
+    now?: () => string;
+    /** Replaced by the harness and by tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Replaced by the harness and by tests; defaults to the signed-in window Vorn serves. */
+    sessionFetchImpl?: typeof fetch;
+    /** The key Vorn gave this tool call, carried on each request through the window. */
+    sessionCall?: string;
+    retry?: RetryPolicy;
+    /** Replaced in tests so backoff costs no real time. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Longest chain of pages `drainPoll` will follow before calling it a bug. */
+declare const MAX_POLL_PAGES = 1000;
+/**
+ * Run one poll page and normalize it. Shared by the MCP server, the CLI and
+ * the test harness so all three observe exactly what Vorn will observe.
+ */
+declare function runPoll(connector: Connector, triggerType: string, options?: RunPollOptions): Promise<PollPage>;
+/**
+ * Follow `hasMore` to the end of a trigger's backlog. Mirrors how Vorn drains
+ * a connector, including its refusal to follow a cursor that does not move —
+ * so an author sees the infinite loop in a unit test instead of in the app.
+ */
+declare function drainPoll(connector: Connector, triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
+interface RunActionOptions {
+    config?: ConnectorConfig;
+    now?: () => string;
+    /** Replaced by the harness and by tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Replaced by the harness and by tests; defaults to the signed-in window Vorn serves. */
+    sessionFetchImpl?: typeof fetch;
+    /** The key Vorn gave this tool call, carried on each request through the window. */
+    sessionCall?: string;
+    retry?: RetryPolicy;
+    /** Replaced in tests so backoff costs no real time. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Ask a connector what one of its dynamic fields can be.
+ *
+ * Listing choices only reads, so it retries like a poll does. A bare string is
+ * taken as a choice that shows itself, which is the common case.
+ */
+declare function runOptions(connector: Connector, name: string, options?: RunActionOptions): Promise<ActionInputOption[]>;
+/**
+ * Run an action with its declared inputs validated and coerced. Vorn renders
+ * every action argument as a template string, so numbers and booleans arrive
+ * as text and have to be converted back here.
+ */
+declare function runAction(connector: Connector, actionType: string, args: Record<string, unknown>, options?: RunActionOptions): Promise<Record<string, unknown>>;
+
+/** MCP tool name a trigger is served under. */
+declare function pollToolName(triggerType: string): string;
+/** MCP tool name a footer is recomputed under. */
+declare function footerToolName(footerId: string): string;
+/** MCP tool name a link handler is run under. */
+declare function handlerToolName(handlerId: string): string;
+/** Tool that reports the connector's manifest and setup hints. */
+declare const MANIFEST_TOOL = "vorn_connector_manifest";
+/**
+ * Tool that reports whether the connector can run right now. Present only when
+ * the connector declares a `preflight`, so its absence means "nothing to
+ * check" rather than "check passed".
+ */
+declare const PREFLIGHT_TOOL = "vorn_connector_preflight";
+/**
+ * Tool that lists the choices for one dynamic field. Present only when the
+ * connector serves an options set, for the same reason preflight is.
+ */
+declare const OPTIONS_TOOL = "vorn_connector_options";
+interface ConnectionSetup {
+    connectorId: string;
+    triggerType: string;
+    /** Values to paste into Vorn's MCP connection form. */
+    filters: {
+        pollTool: string;
+        itemsPath: 'items';
+        idField: 'externalId';
+        timestampField: 'updatedAt';
+        titleField: 'title';
+        urlField: 'url';
+        cursorArg: 'cursor';
+        cursorPath: 'nextCursor';
+    };
+    /** Environment variable names the connector reads. */
+    env: Array<{
+        name: string;
+        required: boolean;
+        secret: boolean;
+        description?: string;
+        /** For whoever is building a connector like this one, not for whoever runs it. */
+        builderHint?: string;
+    }>;
+}
+/**
+ * Describe how to wire one trigger into a Vorn MCP connection.
+ *
+ * Every SDK connector normalizes to the same field names, so this mapping is
+ * fixed; it is generated rather than documented so a rename in the SDK cannot
+ * drift away from the setup instructions users copy. `cursorArg` hands the
+ * connector back its own cursor each poll, which is what lets its dedupe
+ * strategy — rather than Vorn's timestamp comparison — decide what is new.
+ */
+declare function connectionSetup(connector: Connector, triggerType: string): ConnectionSetup;
+/** A contribution as the manifest carries it: everything but the code that runs it. */
+interface ManifestContribution {
+    id: string;
+    title: string;
+    description?: string;
+    when?: ActivationPredicate;
+}
+interface ManifestContributions {
+    panes?: Array<ManifestContribution & {
+        icon?: ConnectorIcon;
+        web?: string;
+        command?: string[];
+    }>;
+    footers?: Array<ManifestContribution & {
+        every: number;
+    }>;
+    linkHandlers?: Array<ManifestContribution & {
+        pattern: string;
+        example: string;
+    }>;
+}
+interface ConnectorManifest {
+    id: string;
+    name: string;
+    version: string;
+    /** Absent on a manifest written before extensions, which reads as a connector. */
+    kind?: ConnectorKind;
+    description?: string;
+    icon?: ConnectorIcon;
+    /** How the connector signs in, so the app can say so before installing it. */
+    auth?: ConnectorAuth;
+    /** What an extension adds to a card. Present only on an extension. */
+    contributes?: ManifestContributions;
+    /** What an extension may ask the host for. Present only on an extension. */
+    permissions?: ExtensionPermission[];
+    /** Where an extension shows at all. Present only on an extension. */
+    activates?: ActivationPredicate;
+    triggers: Array<{
+        type: string;
+        label: string;
+        description?: string;
+        /** Seeds a connection's status mapping; absent when the connector was silent. */
+        statusMapping?: StatusSuggestion[];
+        /** Seeds the polling workflow created with the connection. */
+        defaultWorkflow?: DefaultWorkflow;
+        setup: ConnectionSetup;
+    }>;
+    actions: Array<{
+        type: string;
+        label: string;
+        description?: string;
+        inputs: Array<{
+            key: string;
+            label: string;
+            type: string;
+            required: boolean;
+            options?: ActionInputOption[];
+            /** An options set the connector serves, resolved against a live connection. */
+            loadOptions?: string;
+            /** For whoever is building a connector like this one, not for whoever runs it. */
+            builderHint?: string;
+        }>;
+        /**
+         * Fields the action is known to return. Absent when the connector declared
+         * none, which is not the same as saying it returns nothing.
+         */
+        outputs?: Array<{
+            key: string;
+            type?: string;
+            description?: string;
+        }>;
+        /** Arguments a live check may call it with, when the author named some. */
+        sample?: Record<string, string>;
+    }>;
+}
+/** Full machine-readable description of a connector, served over MCP and printed by the CLI. */
+declare function connectorManifest(connector: Connector): ConnectorManifest;
+
+interface HarnessOptions {
+    config?: ConnectorConfig;
+    /** Fixed clock, so `updatedAt` defaults and cursors are deterministic. */
+    now?: () => string;
+    /** Answer the connector's calls from the test rather than the network. */
+    fetchImpl?: typeof fetch;
+    /** Answer its signed-in calls; defaults to `fetchImpl`, so one stub serves both. */
+    sessionFetchImpl?: typeof fetch;
+    /** Fake clock for backoff, so a retry test costs no real time. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One reply the stub will serve, matched in the order the routes were given. */
+interface MockRoute {
+    /**
+     * A string names a path: `/api/messages` matches that path and nothing else,
+     * and a trailing slash makes it a prefix — `/api/` matches everything under
+     * it. A pattern is tested against the whole URL, for the times host or query
+     * is what tells two calls apart.
+     */
+    url: string | RegExp;
+    /** Matched case-insensitively; absent matches any method. */
+    method?: string;
+    /** Defaults to 200. */
+    status?: number;
+    /** Serialized as JSON unless it is already a string. */
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** What the connector asked for, in the order it asked. */
+interface MockCall {
+    method: string;
+    url: string;
+    body?: string;
+}
+interface MockRun<T> {
+    result: T;
+    calls: MockCall[];
+}
+interface ConnectorHarness {
+    poll(triggerType: string, options?: RunPollOptions): Promise<PollPage>;
+    drain(triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
+    execute(actionType: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    manifest(): ConnectorManifest;
+    /**
+     * Poll repeatedly the way Vorn does — carrying the newest `updatedAt`
+     * forward as the watermark — and return only items a real installation
+     * would treat as new. Catches the classic connector bug where a poll
+     * ignores its lower bound and re-delivers the same backlog forever.
+     */
+    pollTwice(triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
+    /**
+     * Run something with every HTTP request answered from `routes` instead of
+     * the network. A request no route matches is refused rather than served, so
+     * a test says which call escaped rather than reaching a real service.
+     */
+    withMockHttp<T>(routes: MockRoute[], body: () => Promise<T> | T): Promise<MockRun<T>>;
+}
+/**
+ * A call the routes did not offer.
+ *
+ * Its own class because callers wrap it: a declarative action rethrows with
+ * the action's name in front, so recognising an escape by reading the message
+ * would stop working the moment anything added a prefix.
+ */
+declare class MockRouteMissError extends Error {
+    constructor(method: string, url: string);
+}
+/** Whether a call escaped the stub, however many times it was rethrown. */
+declare function escapedMockHttp(error: unknown): boolean;
+/**
+ * Serve a connector's HTTP from a list of replies, in-process.
+ *
+ * Swapping `fetch` rather than opening a socket keeps a conformance run
+ * hermetic: no port, no ordering between tests, and the same code path the
+ * connector uses against the real service.
+ *
+ * One at a time, deliberately. Two overlapping installs share one global: the
+ * first to finish restores the real `fetch` under the second — whose calls
+ * then reach the network — and the second restores the first's dead stub
+ * permanently. Refusing is the only outcome that cannot corrupt the process.
+ */
+declare function withMockHttp<T>(routes: MockRoute[], body: () => Promise<T> | T): Promise<MockRun<T>>;
+/**
+ * Run a connector in-process, exactly as the MCP server would, without
+ * spawning anything. Authors get real assertions in a plain unit test.
+ */
+declare function createConnectorHarness(connector: Connector, harnessOptions?: HarnessOptions): ConnectorHarness;
+/** Answers a footer or handler from fixtures, and refuses what the manifest never asked for. */
+interface MockHostRun {
+    host: ExtensionHost;
+    /** Permissions the run actually spent, so a declared-but-unused one can be named. */
+    used: Set<ExtensionPermission>;
+}
+/** Replaces what the stub answers, for a test whose subject is the reading rather than the plumbing. */
+type MockHostAnswers = Partial<{
+    [K in ExtensionHostMethod]: ExtensionHost[K];
+}>;
+/**
+ * A host that answers from fixtures and enforces the manifest.
+ *
+ * The check runs every footer and handler against this rather than a real
+ * session, which is what lets a conformance run catch an extension reaching
+ * for something it never declared — before a person is asked to grant it.
+ */
+declare function mockExtensionHost(granted: readonly ExtensionPermission[], answers?: MockHostAnswers): MockHostRun;
+
+/**
+ * Every finding this SDK can report.
+ *
+ * A closed set, so `CHECK_OWNERS` cannot fall behind it: a new code that no
+ * named check owns is a compile error rather than a receipt quietly vouching
+ * for a check whose failure nothing was watching.
+ */
+type CheckCode = 'missing-description' | 'auth-undeclared' | 'auth-probe-missing' | 'secret-not-marked' | 'action-no-outputs' | 'input-type-unsupported' | 'missing-idempotent' | 'unverifiable' | 'sample-unusable' | 'poll-failed' | 'no-items' | 'no-cursor' | 'cursor-rejected' | 'redelivers-items' | 'stuck-cursor' | 'lifecycle-scripts' | 'keywords-missing' | 'runtime-dependencies' | 'mock-action-failed' | 'mock-network-escape' | 'mock-not-observed' | 'preflight-failed' | 'live-action-failed' | 'pack-launch' | 'pack-too-large' | 'web-entry-missing' | 'web-entry-outside-package' | 'footer-failed' | 'footer-items-invalid' | 'handler-failed' | 'permission-undeclared' | 'permission-unused';
+interface CheckFinding {
+    /** `error` means the connector will misbehave in Vorn; `warn` is advisory. */
+    level: 'error' | 'warn';
+    code: CheckCode;
+    /** Which part of the connector the finding is about. */
+    target: string;
+    message: string;
+}
+interface CheckOptions {
+    /**
+     * Poll every trigger against the real source. Off by default, so a check
+     * runs on declared `sample` items and the definition alone.
+     */
+    live?: boolean;
+    /** Credentials, required by `live`. */
+    config?: ConnectorConfig;
+    now?: () => string;
+    /**
+     * Directory whose nearest package.json says how the connector ships. Given,
+     * the checks that are about the package rather than the definition run too.
+     */
+    packageDir?: string;
+    /**
+     * Bundles the connector so the check can see what would stay outside it.
+     * Given, a pack's no-install-step promise is verified before packing.
+     */
+    bundle?(request: BundleRequest): Promise<BundleOutput>;
+    /** Module specifier the bundle starts from; required by `bundle`. */
+    entry?: string;
+    /**
+     * Run every action against served HTTP rather than the network. Without
+     * routes each request is answered `{}`, which proves an action runs and
+     * escapes nowhere; with them, that it does the right thing.
+     */
+    mock?: boolean;
+    mockRoutes?: MockRoute[];
+}
+/**
+ * Check a connector against the contract Vorn relies on.
+ *
+ * The point is a feedback loop: a connector — hand-written or generated — can
+ * be verified before it is ever installed, catching the failures that are
+ * otherwise invisible until duplicate tasks show up in someone's inbox days
+ * later.
+ */
+declare function checkConnector(connector: Connector, options?: CheckOptions): Promise<CheckFinding[]>;
+/**
+ * What the factory checked, and when.
+ *
+ * Mirrors the receipt the catalog carries. "Verified" is not a word here but a
+ * list: the checks that ran and came back with nothing to say. A check that
+ * could not run — no sample to replay, no credentials to go live with — is
+ * absent rather than passed, because absent is the true answer.
+ */
+interface ConnectorVerification {
+    /** Which receipt format this is, so a later one is not read as this one. */
+    schema: 1;
+    version: string;
+    checkedAt: string;
+    checks: string[];
+}
+/**
+ * Which named check each finding belongs to, so one failure clears one name.
+ *
+ * `null` means the code belongs to no check a receipt can carry — `pack` has
+ * its own gates, and a receipt speaks only for the conformance run.
+ */
+declare const CHECK_OWNERS: Record<CheckCode, string | null>;
+interface ConformanceRun {
+    findings: CheckFinding[];
+    /** Named checks that ran and had nothing to say. */
+    passed: string[];
+    /**
+     * The receipt to publish, or nothing when an error means there is no claim
+     * to make. Warnings do not void it — they are advice, not a failure.
+     */
+    receipt?: ConnectorVerification;
+}
+/**
+ * Check a connector and say what can be vouched for.
+ *
+ * `checkConnector` answers "what is wrong"; this answers the catalog's
+ * question, "what did you check", which is what a verified badge shows.
+ */
+declare function runConformance(connector: Connector, options?: CheckOptions): Promise<ConformanceRun>;
+/** Render findings for a terminal. Returns an empty string when all clear. */
+declare function formatFindings(findings: CheckFinding[]): string;
+
+export { MANIFEST_TOOL as $, type ActionRequest as A, type BundleRequest as B, type CheckFinding as C, type ConnectorHarness as D, type ExtensionPermission as E, type ConnectorIcon as F, type ConnectorKind as G, type ConnectorManifest as H, type ConnectorVerification as I, type DedupeStrategy as J, type DefaultWorkflow as K, type ExtensionAgent as L, type ExtensionContext as M, type NormalizedItem as N, type ExtensionContributions as O, type PollContext as P, type ExtensionPlatform as Q, type ExtensionUsage as R, type ExtensionUsageWindow as S, type TriggerDefinition as T, type FetchContext as U, type FooterContribution as V, type FooterItem as W, type HarnessOptions as X, type LinkContext as Y, type LinkHandled as Z, type LinkHandlerContribution as _, type BundleOutput as a, MAX_PACK_BYTES as a0, MAX_POLL_PAGES as a1, type ManifestContributions as a2, type MockCall as a3, type MockHostAnswers as a4, type MockHostRun as a5, type MockRoute as a6, MockRouteMissError as a7, type MockRun as a8, OPTIONS_TOOL as a9, lifecycleScriptFindings as aA, mockExtensionHost as aB, pollToolName as aC, readNearestPackageJson as aD, resilientFetch as aE, retryAfterMs as aF, runAction as aG, runConformance as aH, runOptions as aI, runPoll as aJ, withMockHttp as aK, type OptionsContext as aa, type OptionsLoader as ab, PREFLIGHT_TOOL as ac, type PaginationStrategy as ad, type PaneContribution as ae, type PollPage as af, type PreflightResult as ag, type ResilientFetchOptions as ah, type RetryPolicy as ai, type RunActionOptions as aj, type RunPollOptions as ak, type SessionContext as al, type StatusSuggestion as am, backoffMs as an, bundleDependencyFindings as ao, bundledRequireFindings as ap, checkConnector as aq, connectionSetup as ar, connectorManifest as as, createConnectorHarness as at, drainPoll as au, esbuildBundle as av, escapedMockHttp as aw, footerToolName as ax, formatFindings as ay, handlerToolName as az, type ExtensionHostMethod as b, type ConnectorDefinition as c, type Connector as d, type ExtensionDefinition as e, type ConnectorConfig as f, type ExtensionHost as g, type PollOutcome as h, type ConnectorItem as i, type PostReceiveOp as j, type ActionContext as k, type ActionDefinition as l, type ActionInputField as m, type ActionInputOption as n, type ActionInputType as o, type ActionOutputField as p, type ActivationPredicate as q, type AuthRung as r, type BrowserSignIn as s, CHECK_OWNERS as t, type CheckCode as u, type CheckOptions as v, type ConformanceRun as w, type ConnectionSetup as x, type ConnectorAuth as y, type ConnectorConfigField as z };