@vornrun/connector-sdk 0.7.1-beta.1 → 0.7.1-beta.3

package/README.md

@@ -1,8 +1,9 @@
 # @vornrun/connector-sdk
 
 Build a Vorn pull connector in TypeScript and share it as an ordinary npm
-package. A connector built with this SDK runs as an MCP stdio server, and
-Vorn's generic MCP connector already knows how to talk to one.
+package. A connector built with this SDK runs as a child process that speaks
+Vorn's connector protocol — JSON-RPC, one message per line, over stdio — so
+Vorn needs no code of its own to run it.
 
 ```bash
 npm install @vornrun/connector-sdk
@@ -84,6 +85,10 @@ await serveConnector(connector)
 
 Publish it like any other package (`"bin": { "acme-connector": "dist/bin.js" }`).
 
+stdout carries only replies to Vorn. Once `serveConnector` has started,
+anything else written to stdout goes to stderr, so call it before printing
+anything.
+
 `vorn-connector new acme` writes all of the above — package, entry, definition,
 a test that needs no network — already building, checking and packing.
 
@@ -127,10 +132,10 @@ a live connection names a set the connector serves.
 
 Choices are **suggestions, not a closed set**. Vorn draws a picker while the
 value is one of them and its template-aware input whenever it is not, because a
-step is entitled to compute the value from an earlier one — so the served tool
-schema keeps the argument a plain string and lists the choices in its
-description. Your action still receives whatever was finally sent, and it is
-the connector's job to refuse a value it cannot use.
+step is entitled to compute the value from an earlier one — so the manifest
+carries the choices as suggestions and nothing refuses a value outside them.
+Your action still receives whatever was finally sent, and it is the
+connector's job to refuse a value it cannot use.
 
 ```ts
 options: { channels: async ({ config, fetch }) => ['general', 'random'] },
@@ -142,14 +147,17 @@ actions: [{
 }]
 ```
 
-`loadOptions` is served today but not yet consumed: the SDK registers a
-`vorn_connector_options` tool and answers it, and the manifest carries the set's
-name, but the app does not fetch the list yet — such a field is edited as text
-until it does. Declaring it now is what makes it work then; a field whose
-choices are already known should use `options` instead.
+`loadOptions` is served today but not yet consumed: the SDK answers
+`connector/options` for the set, and the manifest carries the set's name, but
+the app does not fetch the list yet — such a field is edited as text until it
+does. Declaring it now is what makes it work then; a field whose choices are
+already known should use `options` instead.
 
-A `json` argument arrives parsed. `builderHint` on a field is a note for whoever
-writes the next connector, not for whoever runs this one.
+Arguments arrive as JSON values. One that already has its declared type is
+taken as it is, text a template rendered is read as that type, and a `json`
+argument arrives parsed. A value that cannot be read fails the step with an
+error naming the field. `builderHint` on a field is a note for whoever writes
+the next connector, not for whoever runs this one.
 
 ## Poll a database instead of an API
 
@@ -326,7 +334,9 @@ call escaped instead of quietly reaching a real service.
 The stub replaces `fetch`, and only `fetch`. A connector that shells out to a
 CLI or opens its own socket is not intercepted by it, so `--mock` reports any
 action the stub never heard from as `mock-not-observed` and leaves `mock` out
-of the receipt rather than vouching for a run it did not see.
+of the receipt rather than vouching for a run it did not see. An action that
+returns a declared output as another type than it declares is reported as
+`mock-output-type`: Vorn keeps what came back, but a later step reads the type.
 
 ```ts
 {
@@ -365,23 +375,28 @@ test('does not redeliver the same backlog forever', async () => {
 
 ## Install it in Vorn
 
-**Settings → Connectors → MCP → From a package**, then type the package name.
+In **Settings → Connectors**, add a connection **From a package** and type the
+package name, or use **Install from file** for a pack.
 
-Vorn starts the connector once, asks it to describe itself, and fills in the
-connection settings from the answer. All that is left on screen is the
-connector's own name, its triggers, and the config it declared.
+Vorn starts the connector, says `vorn/hello`, asks for `connector/manifest`,
+and fills in the connection settings from the answer. All that is left on
+screen is the connector's own name, its triggers, and the config it declared.
+Polls are `trigger/poll` and actions are `action/run`, each carrying typed
+arguments; a failure comes back with a kind (`validation`, `app-offline`,
+`signed-out`, `upstream` or `internal`) that decides what Vorn tells you. A
+declared request sorts its own failures; a `run()` that reads a failing status
+can `throw new UpstreamStatusError(status, message, viaSession)`, where
+`viaSession` says the call went through `ctx.session.fetch`, so a 401 or 403
+reads as signed out.
 
-Nothing needs transcribing: `pollTool`, `itemsPath`, `idField`,
-`timestampField`, `titleField`, `urlField`, `cursorArg` and `cursorPath` all
-come from the manifest. `cursorArg` is what makes the dedupe strategy
-load-bearing — Vorn hands the connector back its own cursor on every poll and
-fires for whatever it returns, rather than re-filtering by timestamp itself.
+Vorn hands the connector back its own cursor on every poll and fires for
+whatever it returns, rather than re-filtering by timestamp itself — which is
+what makes the dedupe strategy load-bearing.
 
 Because the connector is a normal npm package, versions are pinned by the
 package spec and upgrades are a version bump — no separate registry.
 
-To see the same values on the command line, or to wire a connection up by
-hand:
+To see a connector's triggers and the environment each reads:
 
 ```bash
 npx vorn-connector setup ./dist/index.js
@@ -421,7 +436,7 @@ it on **Settings → Connectors** and Vorn launches it from disk.
 
 ### Ship an icon
 
-Without one, a connector shows the generic MCP glyph and is hard to pick out
+Without one, a connector shows a generic glyph and is hard to pick out
 of a list of connections.
 
 ```ts
@@ -565,7 +580,7 @@ linkHandlers: [
 ```
 vorn-connector new <id>                   Scaffold a new connector, ready to build
 vorn-connector manifest <module>          Print the manifest as JSON
-vorn-connector setup <module> [trigger]   Print the Vorn connection settings
+vorn-connector setup <module> [trigger]   Print each trigger and the environment it reads
 vorn-connector poll <module> <trigger>    Run one poll against the environment
 vorn-connector check <module>             Verify the connector against the contract
 vorn-connector pack <module>              Build an installable .vorn.tgz pack

package/dist/{check-CzSTEQD8.d.ts → check-DQttwqgl.d.ts}

@@ -1,11 +1,4 @@
-/**
- * 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.
- */
+/** Author-facing types for Vorn connectors: npm packages Vorn starts and speaks its connector protocol to. */
 /** 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. */
@@ -144,7 +137,7 @@ interface DefaultWorkflow {
     defaultCronFromMinutes: number;
 }
 interface TriggerBase {
-    /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
+    /** Event key, e.g. `workItemCreated`; the name Vorn polls the trigger by. */
     type: string;
     label: string;
     description?: string;
@@ -181,13 +174,7 @@ type TriggerDefinition = TriggerBase & ({
     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.
- */
+/** How to read an argument, often template text, and draw its field; `select` has choices, `json` holds structure. */
 type ActionInputType = 'string' | 'number' | 'boolean' | 'select' | 'json';
 /** One choice a `select` argument offers. */
 interface ActionInputOption {
@@ -219,7 +206,7 @@ interface ActionInputField {
  */
 interface ActionOutputField {
     key: string;
-    type?: 'string' | 'number' | 'boolean';
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
     description?: string;
 }
 interface ActionContext {
@@ -314,16 +301,11 @@ interface ActionRequest {
     paginate?: PaginationStrategy;
 }
 interface ActionBase {
-    /** Action key, e.g. `closeWorkItem`. Becomes an MCP tool of the same name. */
+    /** Action key, e.g. `closeWorkItem`; the name Vorn runs the action by. */
     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.
-     */
+    /** Whether repeating the call with the same arguments is safe; decides whether the SDK or an agent may retry it. */
     idempotent?: boolean;
     inputs?: ActionInputField[];
     outputs?: ActionOutputField[];
@@ -696,15 +678,6 @@ declare function readNearestPackageJson(fromDir: string): Record<string, unknown
 /** 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;
@@ -757,7 +730,7 @@ interface RunPollOptions {
     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. */
+    /** The key Vorn gave this call, carried on each request through the window. */
     sessionCall?: string;
     retry?: RetryPolicy;
     /** Replaced in tests so backoff costs no real time. */
@@ -766,7 +739,7 @@ interface RunPollOptions {
 /** 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
+ * Run one poll page and normalize it. Shared by the stdio 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>;
@@ -783,7 +756,7 @@ interface RunActionOptions {
     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. */
+    /** The key Vorn gave this call, carried on each request through the window. */
     sessionCall?: string;
     retry?: RetryPolicy;
     /** Replaced in tests so backoff costs no real time. */
@@ -796,46 +769,12 @@ interface RunActionOptions {
  * 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.
- */
+/** Run an action with its declared inputs validated and read as their declared types. */
 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;
@@ -846,15 +785,7 @@ interface ConnectionSetup {
         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.
- */
+/** What a Vorn connection needs for one trigger: which trigger, and the environment the connector reads. */
 declare function connectionSetup(connector: Connector, triggerType: string): ConnectionSetup;
 /** A contribution as the manifest carries it: everything but the code that runs it. */
 interface ManifestContribution {
@@ -878,6 +809,8 @@ interface ManifestContributions {
     }>;
 }
 interface ConnectorManifest {
+    /** The connector protocol the pack speaks; Vorn refuses a pack without one. */
+    protocol: number;
     id: string;
     name: string;
     version: string;
@@ -907,11 +840,14 @@ interface ConnectorManifest {
         type: string;
         label: string;
         description?: string;
+        /** Whether repeating a call with the same arguments has no further effect; absent when unsaid. */
+        idempotent?: boolean;
         inputs: Array<{
             key: string;
             label: string;
             type: string;
             required: boolean;
+            description?: string;
             options?: ActionInputOption[];
             /** An options set the connector serves, resolved against a live connection. */
             loadOptions?: string;
@@ -931,7 +867,7 @@ interface ConnectorManifest {
         sample?: Record<string, string>;
     }>;
 }
-/** Full machine-readable description of a connector, served over MCP and printed by the CLI. */
+/** Full machine-readable description of a connector, served over stdio, written into a pack and printed by the CLI. */
 declare function connectorManifest(connector: Connector): ConnectorManifest;
 
 interface HarnessOptions {
@@ -1016,10 +952,7 @@ declare function escapedMockHttp(error: unknown): boolean;
  * 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.
- */
+/** Run a connector in-process through the runtime the stdio server uses, so a plain unit test can assert on it. */
 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 {
@@ -1047,7 +980,7 @@ declare function mockExtensionHost(granted: readonly ExtensionPermission[], answ
  * 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';
+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' | 'mock-output-type' | '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';
@@ -1136,4 +1069,4 @@ declare function runConformance(connector: Connector, options?: CheckOptions): P
 /** 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 };
+export { MAX_PACK_BYTES 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_POLL_PAGES as a0, type ManifestContributions as a1, type MockCall as a2, type MockHostAnswers as a3, type MockHostRun as a4, type MockRoute as a5, MockRouteMissError as a6, type MockRun as a7, type OptionsContext as a8, type OptionsLoader as a9, runAction as aA, runConformance as aB, runOptions as aC, runPoll as aD, withMockHttp as aE, type PaginationStrategy as aa, type PaneContribution as ab, type PollPage as ac, type PreflightResult as ad, type ResilientFetchOptions as ae, type RetryPolicy as af, type RunActionOptions as ag, type RunPollOptions as ah, type SessionContext as ai, type StatusSuggestion as aj, backoffMs as ak, bundleDependencyFindings as al, bundledRequireFindings as am, checkConnector as an, connectionSetup as ao, connectorManifest as ap, createConnectorHarness as aq, drainPoll as ar, esbuildBundle as as, escapedMockHttp as at, formatFindings as au, lifecycleScriptFindings as av, mockExtensionHost as aw, readNearestPackageJson as ax, resilientFetch as ay, retryAfterMs 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 };