@vornrun/connector-sdk 0.5.2

package/README.md

@@ -0,0 +1,213 @@
+# @vornrun/connector-sdk
+
+Build a Vorn pull connector in TypeScript and share it as an ordinary npm
+package. No marketplace, no plugin host, no changes to Vorn itself: 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.
+
+```bash
+npm install @vornrun/connector-sdk
+```
+
+## Write a connector
+
+```ts
+// src/index.ts
+import { defineConnector } from '@vornrun/connector-sdk'
+
+export default defineConnector({
+  id: 'acme',
+  name: 'Acme Tickets',
+  version: '1.0.0',
+  config: [
+    { key: 'apiToken', label: 'API token', required: true, secret: true },
+    { key: 'baseUrl', label: 'Base URL', default: 'https://api.acme.test' }
+  ],
+  triggers: [
+    {
+      type: 'newTicket',
+      label: 'New ticket',
+      async poll({ config, since, limit }) {
+        const url = new URL('/tickets', config.baseUrl)
+        if (since) url.searchParams.set('updated_after', since)
+        url.searchParams.set('per_page', String(limit ?? 100))
+
+        const response = await fetch(url, {
+          headers: { authorization: `Bearer ${config.apiToken}` }
+        })
+        if (!response.ok) throw new Error(`Acme returned ${response.status}`)
+        const tickets = (await response.json()) as AcmeTicket[]
+
+        return {
+          items: tickets.map((ticket) => ({
+            externalId: ticket.id,
+            title: ticket.subject,
+            url: ticket.html_url,
+            description: ticket.body,
+            status: ticket.state,
+            updatedAt: ticket.updated_at,
+            data: { priority: ticket.priority }
+          }))
+        }
+      }
+    }
+  ],
+  actions: [
+    {
+      type: 'closeTicket',
+      label: 'Close ticket',
+      inputs: [{ key: 'id', label: 'Ticket id', required: true }],
+      // Optional: declared outputs show up in Vorn's `{{steps.…}}` autocomplete.
+      // Undeclared fields are still returned.
+      outputs: [{ key: 'closed' }],
+      async run({ id }, { config }) {
+        await fetch(`${config.baseUrl}/tickets/${id}/close`, {
+          method: 'POST',
+          headers: { authorization: `Bearer ${config.apiToken}` }
+        })
+        return { closed: id }
+      }
+    }
+  ]
+})
+```
+
+Then a two-line bin:
+
+```ts
+// src/bin.ts
+import { serveConnector } from '@vornrun/connector-sdk'
+import connector from './index'
+
+await serveConnector(connector)
+```
+
+Publish it like any other package (`"bin": { "acme-connector": "dist/bin.js" }`).
+
+## Poll a database instead of an API
+
+Nothing about a trigger is HTTP-specific — it just returns items. A SQL pull
+connector is the same shape:
+
+```ts
+import { defineConnector } from '@vornrun/connector-sdk'
+import postgres from 'postgres'
+
+export default defineConnector({
+  id: 'orders-db',
+  name: 'Orders database',
+  config: [{ key: 'databaseUrl', label: 'Database URL', required: true, secret: true }],
+  triggers: [
+    {
+      type: 'newOrder',
+      label: 'New order',
+      async poll({ config, since, limit }) {
+        const sql = postgres(config.databaseUrl!)
+        try {
+          const rows = await sql`
+            SELECT id, reference, status, updated_at
+            FROM orders
+            WHERE updated_at > ${since ?? '1970-01-01'}
+            ORDER BY updated_at ASC
+            LIMIT ${limit ?? 200}
+          `
+          return {
+            items: rows.map((row) => ({
+              externalId: row.id,
+              title: `Order ${row.reference}`,
+              status: row.status,
+              updatedAt: row.updated_at
+            }))
+          }
+        } finally {
+          await sql.end()
+        }
+      }
+    }
+  ]
+})
+```
+
+Two rules make a pull trigger reliable, and the SDK enforces both:
+
+1. `externalId` must be stable — Vorn dedupes on it, so a changing id means
+   duplicate work items.
+2. `updatedAt` must be monotonic and ISO-comparable — Vorn advances its poll
+   cursor from it. Sort ascending by that column and honor `since`.
+
+## Paging a backlog
+
+Return `hasMore: true` with a `nextCursor`, and Vorn (or `drainPoll` in tests)
+will keep pulling bounded pages until the backlog is drained:
+
+```ts
+async poll({ cursor, config }) {
+  const page = Number(cursor ?? '1')
+  const { items, totalPages } = await fetchPage(config, page)
+  return {
+    items: items.map(toItem),
+    nextCursor: String(page + 1),
+    hasMore: page < totalPages
+  }
+}
+```
+
+A cursor that does not advance is rejected rather than looped on.
+
+## Test it without running the app
+
+```ts
+import { createConnectorHarness } from '@vornrun/connector-sdk'
+import connector from '../src/index'
+
+const harness = createConnectorHarness(connector, {
+  config: { apiToken: 'test' },
+  now: () => '2026-08-05T00:00:00.000Z'
+})
+
+test('emits normalized tickets', async () => {
+  const page = await harness.poll('newTicket')
+  expect(page.items[0]).toMatchObject({ externalId: '1', status: 'open' })
+})
+
+test('does not redeliver the same backlog forever', async () => {
+  // Polls twice, carrying the watermark forward exactly as Vorn does.
+  expect(await harness.pollTwice('newTicket')).toEqual([])
+})
+```
+
+`harness.drain()` walks every page, `harness.execute()` runs an action, and
+`harness.manifest()` returns what Vorn will see.
+
+## Install it in Vorn
+
+Run the CLI to get the exact connection settings:
+
+```bash
+npx vorn-connector setup ./dist/index.js
+```
+
+It prints the values for **Settings → Connectors → MCP → New connection**:
+
+| Field      | Value                                                                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Command    | `npx`                                                                                                                                    |
+| Arguments  | `["-y", "@your-scope/acme-connector"]`                                                                                                   |
+| Secret env | `{"API_TOKEN": "…"}`                                                                                                                     |
+| Filters    | `pollTool: poll_newTicket`, `itemsPath: items`, `idField: externalId`, `timestampField: updatedAt`, `titleField: title`, `urlField: url` |
+
+Because the connector is a normal npm package, versions are pinned by the
+`npx` argument and upgrades are a version bump — no separate registry.
+
+## CLI
+
+```
+vorn-connector manifest <module>          Print the manifest as JSON
+vorn-connector setup <module> [trigger]   Print the Vorn connection settings
+vorn-connector poll <module> <trigger>    Run one poll against the environment
+vorn-connector serve <module>             Serve on stdio (what Vorn runs)
+```
+
+`poll` accepts `--since <iso>` and `--limit <n>`, and reads the connector's
+declared config from your shell environment — the fastest way to confirm
+credentials and field mapping before wiring anything up.

package/dist/chunk-UANUTYUV.js

@@ -0,0 +1,421 @@
+// src/define.ts
+var KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+function assertUnique(kind, keys) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (seen.has(key)) throw new Error(`Duplicate ${kind} "${key}"`);
+    seen.add(key);
+  }
+}
+function envNameFor(key, explicit) {
+  if (explicit) return explicit;
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toUpperCase();
+}
+function defineConnector(definition) {
+  if (!KEY_PATTERN.test(definition.id ?? "")) {
+    throw new Error(`Connector id "${definition.id}" must start with a letter and be url-safe`);
+  }
+  if (!definition.name?.trim()) {
+    throw new Error(`Connector ${definition.id} is missing a name`);
+  }
+  const triggers = definition.triggers ?? [];
+  const actions = definition.actions ?? [];
+  if (triggers.length === 0 && actions.length === 0) {
+    throw new Error(`Connector ${definition.id} declares no triggers and no actions`);
+  }
+  for (const trigger of triggers) {
+    if (!KEY_PATTERN.test(trigger.type ?? "")) {
+      throw new Error(`Trigger type "${trigger.type}" must start with a letter and be url-safe`);
+    }
+    if (typeof trigger.poll !== "function") {
+      throw new Error(`Trigger ${trigger.type} is missing a poll() implementation`);
+    }
+  }
+  for (const action of actions) {
+    if (!KEY_PATTERN.test(action.type ?? "")) {
+      throw new Error(`Action type "${action.type}" must start with a letter and be url-safe`);
+    }
+    if (typeof action.run !== "function") {
+      throw new Error(`Action ${action.type} is missing a run() implementation`);
+    }
+  }
+  assertUnique(
+    "trigger",
+    triggers.map((trigger) => trigger.type)
+  );
+  assertUnique(
+    "action",
+    actions.map((action) => action.type)
+  );
+  assertUnique(
+    "config field",
+    (definition.config ?? []).map((field) => field.key)
+  );
+  return {
+    ...definition,
+    version: definition.version ?? "0.0.0",
+    config: definition.config ?? [],
+    triggers,
+    actions
+  };
+}
+function resolveConfig(connector, env = process.env) {
+  const config = {};
+  const missing = [];
+  for (const field of connector.config) {
+    const name = envNameFor(field.key, field.env);
+    const value = env[name] ?? field.default;
+    if (value === void 0 || value === "") {
+      if (field.required) missing.push(`${field.key} (${name})`);
+      continue;
+    }
+    config[field.key] = value;
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `Connector ${connector.id} is missing required configuration: ${missing.join(", ")}`
+    );
+  }
+  return config;
+}
+
+// src/normalize.ts
+var RESERVED_KEYS = [
+  "externalId",
+  "title",
+  "url",
+  "description",
+  "status",
+  "labels",
+  "assignee",
+  "updatedAt"
+];
+var UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+function isoTimestamp(value, fallback) {
+  if (value === void 0) return fallback;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid updatedAt: ${String(value)}`);
+  }
+  return date.toISOString();
+}
+function normalizeItem(item, polledAt) {
+  const externalId = String(item.externalId ?? "").trim();
+  if (!externalId) {
+    throw new Error("Connector item is missing externalId");
+  }
+  if (!item.title || !item.title.trim()) {
+    throw new Error(`Connector item ${externalId} is missing title`);
+  }
+  const extra = {};
+  for (const [key, value] of Object.entries(item.data ?? {})) {
+    if (RESERVED_KEYS.includes(key)) continue;
+    if (UNSAFE_KEYS.includes(key)) continue;
+    extra[key] = value;
+  }
+  return {
+    ...extra,
+    externalId,
+    title: item.title,
+    url: item.url ?? "",
+    description: item.description ?? "",
+    status: item.status ?? "open",
+    labels: item.labels ?? [],
+    ...item.assignee !== void 0 && { assignee: item.assignee },
+    updatedAt: isoTimestamp(item.updatedAt, polledAt)
+  };
+}
+function normalizeItems(items, polledAt) {
+  const seen = /* @__PURE__ */ new Set();
+  return items.map((item) => {
+    const normalized = normalizeItem(item, polledAt);
+    if (seen.has(normalized.externalId)) {
+      throw new Error(`Duplicate externalId "${normalized.externalId}" in one poll page`);
+    }
+    seen.add(normalized.externalId);
+    return normalized;
+  });
+}
+
+// src/runtime.ts
+var MAX_POLL_PAGES = 1e3;
+async function runPoll(connector, triggerType, options = {}) {
+  const trigger = connector.triggers.find((entry) => entry.type === triggerType);
+  if (!trigger) {
+    throw new Error(`Connector ${connector.id} has no trigger "${triggerType}"`);
+  }
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const polledAt = now();
+  const context = {
+    config: options.config ?? {},
+    ...options.since !== void 0 && { since: options.since },
+    ...options.cursor !== void 0 && { cursor: options.cursor },
+    ...options.limit !== void 0 && { limit: options.limit },
+    now
+  };
+  const outcome = await trigger.poll(context);
+  if (!outcome || !Array.isArray(outcome.items)) {
+    throw new Error(`Trigger ${triggerType} did not return an items array`);
+  }
+  if (outcome.hasMore && !outcome.nextCursor) {
+    throw new Error(`Trigger ${triggerType} reported more pages without a nextCursor`);
+  }
+  return {
+    items: normalizeItems(outcome.items, polledAt),
+    ...outcome.nextCursor !== void 0 && { nextCursor: outcome.nextCursor },
+    hasMore: outcome.hasMore === true
+  };
+}
+async function drainPoll(connector, triggerType, options = {}) {
+  const collected = [];
+  let cursor = options.cursor;
+  for (let page = 0; page < MAX_POLL_PAGES; page++) {
+    const result = await runPoll(connector, triggerType, {
+      ...options,
+      ...cursor !== void 0 && { cursor }
+    });
+    collected.push(...result.items);
+    if (!result.hasMore) return collected;
+    if (result.nextCursor === cursor) {
+      throw new Error(`Trigger ${triggerType} did not advance its cursor`);
+    }
+    cursor = result.nextCursor;
+  }
+  throw new Error(`Trigger ${triggerType} exceeded ${MAX_POLL_PAGES} pages`);
+}
+function coerceArg(value, type) {
+  if (typeof value !== "string") return value;
+  if (type === "number") {
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) throw new Error(`Expected a number, got "${value}"`);
+    return parsed;
+  }
+  if (type === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new Error(`Expected a boolean, got "${value}"`);
+  }
+  return value;
+}
+async function runAction(connector, actionType, args, options = {}) {
+  const action = connector.actions.find((entry) => entry.type === actionType);
+  if (!action) {
+    throw new Error(`Connector ${connector.id} has no action "${actionType}"`);
+  }
+  const coerced = { ...args };
+  for (const input of action.inputs ?? []) {
+    const value = coerced[input.key];
+    if (value === void 0 || value === "") {
+      if (input.required) throw new Error(`Action ${actionType} requires "${input.key}"`);
+      delete coerced[input.key];
+      continue;
+    }
+    try {
+      coerced[input.key] = coerceArg(value, input.type);
+    } catch (error) {
+      throw new Error(
+        `Action ${actionType} argument "${input.key}": ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  const output = await action.run(coerced, {
+    config: options.config ?? {},
+    now: options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString())
+  });
+  return output ?? {};
+}
+
+// src/setup.ts
+function pollToolName(triggerType) {
+  return `poll_${triggerType}`;
+}
+var MANIFEST_TOOL = "vorn_connector_manifest";
+function connectionSetup(connector, triggerType) {
+  const trigger = connector.triggers.find((entry) => entry.type === triggerType);
+  if (!trigger) {
+    throw new Error(`Connector ${connector.id} has no trigger "${triggerType}"`);
+  }
+  return {
+    connectorId: connector.id,
+    triggerType,
+    filters: {
+      pollTool: pollToolName(triggerType),
+      itemsPath: "items",
+      idField: "externalId",
+      timestampField: "updatedAt",
+      titleField: "title",
+      urlField: "url"
+    },
+    env: connector.config.map((field) => ({
+      name: envNameFor(field.key, field.env),
+      required: field.required === true,
+      secret: field.secret === true,
+      ...field.description !== void 0 && { description: field.description }
+    }))
+  };
+}
+function connectorManifest(connector) {
+  return {
+    id: connector.id,
+    name: connector.name,
+    version: connector.version,
+    ...connector.description !== void 0 && { description: connector.description },
+    triggers: connector.triggers.map((trigger) => ({
+      type: trigger.type,
+      label: trigger.label,
+      ...trigger.description !== void 0 && { description: trigger.description },
+      setup: connectionSetup(connector, trigger.type)
+    })),
+    actions: connector.actions.map((action) => ({
+      type: action.type,
+      label: action.label,
+      ...action.description !== void 0 && { description: action.description },
+      inputs: (action.inputs ?? []).map((input) => ({
+        key: input.key,
+        label: input.label,
+        type: input.type ?? "string",
+        required: input.required === true
+      }))
+    }))
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function json(value) {
+  return {
+    // Vorn reads `structuredContent` to build step output and to find the
+    // `items` array a poll returned; the text block keeps the result readable
+    // in any generic MCP client.
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    structuredContent: value
+  };
+}
+function failure(error) {
+  return {
+    content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+    isError: true
+  };
+}
+function inputShape(inputs) {
+  const shape = {};
+  for (const input of inputs) {
+    const base = z.string().describe(input.description ?? input.label);
+    shape[input.key] = input.required ? base : base.optional();
+  }
+  return shape;
+}
+function scalar(type) {
+  if (type === "number") return z.number();
+  if (type === "boolean") return z.boolean();
+  return z.string();
+}
+function outputSchema(outputs) {
+  const shape = {};
+  for (const output of outputs) {
+    shape[output.key] = scalar(output.type).optional().describe(output.description ?? output.key);
+  }
+  return z.looseObject(shape);
+}
+function createConnectorServer(connector, options = {}) {
+  const server = new McpServer(
+    { name: connector.id, version: connector.version },
+    { capabilities: { tools: {} } }
+  );
+  let cached = options.config;
+  const config = () => cached ??= resolveConfig(connector);
+  server.registerTool(
+    MANIFEST_TOOL,
+    {
+      description: `Describe the ${connector.name} connector and how to configure it`,
+      inputSchema: {},
+      outputSchema: z.looseObject({})
+    },
+    () => json(connectorManifest(connector))
+  );
+  for (const trigger of connector.triggers) {
+    server.registerTool(
+      pollToolName(trigger.type),
+      {
+        description: trigger.description ?? `Poll ${connector.name} for ${trigger.label}`,
+        inputSchema: {
+          since: z.string().optional().describe("Only return items changed after this ISO timestamp"),
+          cursor: z.string().optional().describe("Opaque cursor from a previous page"),
+          limit: z.string().optional().describe("Maximum number of items to return")
+        },
+        outputSchema: z.looseObject({
+          items: z.array(z.looseObject({})).describe("Normalized items"),
+          nextCursor: z.string().optional().describe("Cursor for the next page"),
+          hasMore: z.boolean().describe("Whether another page is immediately available")
+        })
+      },
+      async (args) => {
+        try {
+          const limit = args.limit === void 0 ? void 0 : Number(args.limit);
+          if (limit !== void 0 && !Number.isFinite(limit)) {
+            throw new Error(`Invalid limit "${args.limit}"`);
+          }
+          return json(
+            await runPoll(connector, trigger.type, {
+              config: config(),
+              ...args.since !== void 0 && { since: args.since },
+              ...args.cursor !== void 0 && { cursor: args.cursor },
+              ...limit !== void 0 && { limit },
+              ...options.now && { now: options.now }
+            })
+          );
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  for (const action of connector.actions) {
+    server.registerTool(
+      action.type,
+      {
+        description: action.description ?? `${action.label} in ${connector.name}`,
+        inputSchema: inputShape(action.inputs ?? []),
+        outputSchema: outputSchema(action.outputs ?? [])
+      },
+      async (args) => {
+        try {
+          return json(
+            await runAction(connector, action.type, args, {
+              config: config(),
+              ...options.now && { now: options.now }
+            })
+          );
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  return server;
+}
+async function serveConnector(connector, options = {}) {
+  const server = createConnectorServer(connector, options);
+  await server.connect(new StdioServerTransport());
+}
+
+export {
+  envNameFor,
+  defineConnector,
+  resolveConfig,
+  normalizeItem,
+  normalizeItems,
+  MAX_POLL_PAGES,
+  runPoll,
+  drainPoll,
+  runAction,
+  pollToolName,
+  MANIFEST_TOOL,
+  connectionSetup,
+  connectorManifest,
+  createConnectorServer,
+  serveConnector
+};

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+interface CliDeps {
+    load(modulePath: string): Promise<unknown>;
+    write(line: string): void;
+    env?: NodeJS.ProcessEnv;
+}
+declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
+
+export { type CliDeps, runCli };

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import {
+  connectionSetup,
+  connectorManifest,
+  resolveConfig,
+  runPoll,
+  serveConnector
+} from "./chunk-UANUTYUV.js";
+
+// src/cli.ts
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+var USAGE = `vorn-connector <command> <module> [options]
+
+Commands:
+  manifest <module>             Print the connector manifest as JSON
+  setup <module> [trigger]      Print the Vorn connection settings to paste
+  poll <module> <trigger>       Run one poll against the current environment
+  serve <module>                Serve the connector on stdio (what Vorn runs)
+
+Options:
+  --since <iso>                 Lower bound passed to poll
+  --limit <n>                   Maximum items to request`;
+function parseFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) continue;
+    const value = args[index + 1];
+    if (value === void 0 || value.startsWith("--")) {
+      throw new Error(`Missing value for ${arg}`);
+    }
+    flags[arg.slice(2)] = value;
+    index++;
+  }
+  return flags;
+}
+function pickConnector(loaded, modulePath) {
+  const module = loaded;
+  const candidate = module?.default ?? module?.connector;
+  const connector = candidate;
+  if (!connector || typeof connector !== "object" || !Array.isArray(connector.triggers)) {
+    throw new Error(
+      `${modulePath} does not export a connector built with defineConnector() (default or named "connector")`
+    );
+  }
+  return connector;
+}
+async function runCli(argv, deps) {
+  const [command, modulePath, ...rest] = argv;
+  if (!command || command === "help" || command === "--help") {
+    deps.write(USAGE);
+    return command ? 0 : 1;
+  }
+  if (!modulePath) {
+    deps.write(`Missing <module> argument
+
+${USAGE}`);
+    return 1;
+  }
+  const connector = pickConnector(await deps.load(modulePath), modulePath);
+  const positional = rest.filter((arg) => !arg.startsWith("--"));
+  const flags = parseFlags(rest);
+  switch (command) {
+    case "manifest":
+      deps.write(JSON.stringify(connectorManifest(connector), null, 2));
+      return 0;
+    case "setup": {
+      const triggers = positional[0] ? [positional[0]] : connector.triggers.map((t) => t.type);
+      for (const triggerType of triggers) {
+        const setup = connectionSetup(connector, triggerType);
+        deps.write(`# ${connector.name} \u2014 ${triggerType}`);
+        deps.write(`Command: npx`);
+        deps.write(`Arguments: ["-y", "<your-package>"]`);
+        deps.write(`Filters: ${JSON.stringify(setup.filters, null, 2)}`);
+        if (setup.env.length > 0) {
+          deps.write(
+            `Environment: ${setup.env.map((entry) => `${entry.name}${entry.required ? " (required)" : ""}`).join(", ")}`
+          );
+        }
+      }
+      return 0;
+    }
+    case "poll": {
+      const triggerType = positional[0];
+      if (!triggerType) {
+        deps.write(`Missing <trigger> argument
+
+${USAGE}`);
+        return 1;
+      }
+      const limit = flags.limit === void 0 ? void 0 : Number(flags.limit);
+      if (limit !== void 0 && !Number.isFinite(limit)) {
+        deps.write(`Invalid limit "${flags.limit}"`);
+        return 1;
+      }
+      const page = await runPoll(connector, triggerType, {
+        config: resolveConfig(connector, deps.env ?? process.env),
+        ...flags.since !== void 0 && { since: flags.since },
+        ...limit !== void 0 && { limit }
+      });
+      deps.write(JSON.stringify(page, null, 2));
+      return 0;
+    }
+    case "serve":
+      await serveConnector(connector);
+      return 0;
+    default:
+      deps.write(`Unknown command "${command}"
+
+${USAGE}`);
+      return 1;
+  }
+}
+var invokedDirectly = process.argv[1] !== void 0 && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+if (invokedDirectly) {
+  runCli(process.argv.slice(2), {
+    load: (modulePath) => modulePath.startsWith(".") || modulePath.startsWith("/") ? import(pathToFileURL(resolve(modulePath)).href) : import(modulePath),
+    write: (line) => process.stdout.write(`${line}
+`)
+  }).then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * 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;
+}
+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;
+}
+interface PollOutcome {
+    items: ConnectorItem[];
+    nextCursor?: string;
+    hasMore?: boolean;
+}
+interface TriggerDefinition {
+    /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
+    type: string;
+    label: string;
+    description?: string;
+    poll(context: PollContext): Promise<PollOutcome> | PollOutcome;
+}
+interface ActionInputField {
+    key: string;
+    label: string;
+    type?: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    description?: 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;
+}
+interface ActionDefinition {
+    /** Action key, e.g. `closeWorkItem`. Becomes an MCP tool of the same name. */
+    type: string;
+    label: string;
+    description?: string;
+    inputs?: ActionInputField[];
+    outputs?: ActionOutputField[];
+    run(args: Record<string, unknown>, context: ActionContext): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+}
+interface ConnectorDefinition {
+    /** Stable connector id, e.g. `azure-devops`. */
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    config?: ConnectorConfigField[];
+    triggers?: TriggerDefinition[];
+    actions?: ActionDefinition[];
+}
+/** 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[];
+}
+
+/** Environment variable a config field reads from, e.g. `apiToken` → `API_TOKEN`. */
+declare function envNameFor(key: string, explicit?: string): string;
+/**
+ * Validate a connector definition and fill in its defaults.
+ *
+ * Failing here — at import time — is the whole point: a typo in a trigger
+ * type or a duplicate action key otherwise surfaces as a silently missing
+ * MCP tool once the connector is already installed in someone's app.
+ */
+declare function defineConnector(definition: ConnectorDefinition): Connector;
+/**
+ * Read the connector's declared config out of the environment. Vorn supplies
+ * these through the connection's `env` / `secretEnv` maps, so a missing
+ * required value is a setup mistake worth reporting by name rather than
+ * letting the first API call fail with a confusing 401.
+ */
+declare function resolveConfig(connector: Connector, env?: NodeJS.ProcessEnv): ConnectorConfig;
+
+/**
+ * Turn an author-supplied item into the flat JSON shape Vorn consumes.
+ *
+ * Normalizing here rather than in each connector is what lets one host-side
+ * poll configuration (`idField: externalId`, `timestampField: updatedAt`, …)
+ * work for every SDK connector.
+ */
+declare function normalizeItem(item: ConnectorItem, polledAt: string): NormalizedItem;
+/**
+ * Normalize a page and reject duplicate ids within it. Two items sharing an
+ * id in one page means one of them would be silently dropped by Vorn's
+ * dedupe, which looks like data loss long after the fact.
+ */
+declare function normalizeItems(items: ConnectorItem[], polledAt: string): NormalizedItem[];
+
+interface PollPage {
+    items: NormalizedItem[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+interface RunPollOptions {
+    config?: ConnectorConfig;
+    since?: string;
+    cursor?: string;
+    limit?: number;
+    now?: () => string;
+}
+/** 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;
+}
+/**
+ * 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;
+/** Tool that reports the connector's manifest and setup hints. */
+declare const MANIFEST_TOOL = "vorn_connector_manifest";
+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';
+    };
+    /** Environment variable names the connector reads. */
+    env: Array<{
+        name: string;
+        required: boolean;
+        secret: boolean;
+        description?: 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.
+ */
+declare function connectionSetup(connector: Connector, triggerType: string): ConnectionSetup;
+interface ConnectorManifest {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    triggers: Array<{
+        type: string;
+        label: string;
+        description?: string;
+        setup: ConnectionSetup;
+    }>;
+    actions: Array<{
+        type: string;
+        label: string;
+        description?: string;
+        inputs: Array<{
+            key: string;
+            label: string;
+            type: string;
+            required: boolean;
+        }>;
+    }>;
+}
+/** Full machine-readable description of a connector, served over MCP and printed by the CLI. */
+declare function connectorManifest(connector: Connector): ConnectorManifest;
+
+interface ConnectorServerOptions {
+    /** Resolved connector configuration. Defaults to reading `process.env`. */
+    config?: ConnectorConfig;
+    now?: () => string;
+}
+/**
+ * Expose a connector as an MCP server.
+ *
+ * Each trigger becomes a `poll_<type>` tool returning the normalized page,
+ * each action becomes a tool of the same name, and `vorn_connector_manifest`
+ * reports everything needed to configure the connection. That is the entire
+ * contract — Vorn's generic MCP connector consumes it with no host changes.
+ */
+declare function createConnectorServer(connector: Connector, options?: ConnectorServerOptions): McpServer;
+/** Serve a connector on stdio. This is the one line a connector's bin needs. */
+declare function serveConnector(connector: Connector, options?: ConnectorServerOptions): Promise<void>;
+
+interface HarnessOptions {
+    config?: ConnectorConfig;
+    /** Fixed clock, so `updatedAt` defaults and cursors are deterministic. */
+    now?: () => string;
+}
+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 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;
+
+export { type ActionContext, type ActionDefinition, type ActionInputField, type ConnectionSetup, type Connector, type ConnectorConfig, type ConnectorConfigField, type ConnectorDefinition, type ConnectorHarness, type ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, type NormalizedItem, type PollContext, type PollOutcome, type PollPage, type RunActionOptions, type RunPollOptions, type TriggerDefinition, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, normalizeItem, normalizeItems, pollToolName, resolveConfig, runAction, runPoll, serveConnector };

package/dist/index.js

@@ -0,0 +1,66 @@
+import {
+  MANIFEST_TOOL,
+  MAX_POLL_PAGES,
+  connectionSetup,
+  connectorManifest,
+  createConnectorServer,
+  defineConnector,
+  drainPoll,
+  envNameFor,
+  normalizeItem,
+  normalizeItems,
+  pollToolName,
+  resolveConfig,
+  runAction,
+  runPoll,
+  serveConnector
+} from "./chunk-UANUTYUV.js";
+
+// src/harness.ts
+function createConnectorHarness(connector, harnessOptions = {}) {
+  const defaults = (options = {}) => ({
+    ...harnessOptions.config && { config: harnessOptions.config },
+    ...harnessOptions.now && { now: harnessOptions.now },
+    ...options
+  });
+  return {
+    poll: (triggerType, options) => runPoll(connector, triggerType, defaults(options)),
+    drain: (triggerType, options) => drainPoll(connector, triggerType, defaults(options)),
+    execute: (actionType, args = {}) => runAction(connector, actionType, args, {
+      ...harnessOptions.config && { config: harnessOptions.config },
+      ...harnessOptions.now && { now: harnessOptions.now }
+    }),
+    manifest: () => connectorManifest(connector),
+    async pollTwice(triggerType, options) {
+      const first = await drainPoll(connector, triggerType, defaults(options));
+      const watermark = first.reduce(
+        (newest, item) => newest === void 0 || item.updatedAt > newest ? item.updatedAt : newest,
+        options?.since
+      );
+      const second = await drainPoll(
+        connector,
+        triggerType,
+        defaults({ ...options, ...watermark !== void 0 && { since: watermark } })
+      );
+      return watermark === void 0 ? second : second.filter((item) => item.updatedAt > watermark);
+    }
+  };
+}
+export {
+  MANIFEST_TOOL,
+  MAX_POLL_PAGES,
+  connectionSetup,
+  connectorManifest,
+  createConnectorHarness,
+  createConnectorServer,
+  defineConnector,
+  drainPoll,
+  envNameFor,
+  normalizeItem,
+  normalizeItems,
+  pollToolName,
+  resolveConfig,
+  runAction,
+  runPoll,
+  serveConnector
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vornrun/connector-sdk",
+  "version": "0.5.2",
+  "description": "Build and share Vorn pull connectors as ordinary npm packages",
+  "type": "module",
+  "license": "MIT",
+  "author": "Javier Canizalez <javier-canizalez@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vorn-run/vorn.git",
+    "directory": "packages/connector-sdk"
+  },
+  "keywords": [
+    "vorn",
+    "connector",
+    "mcp",
+    "model-context-protocol",
+    "integration"
+  ],
+  "bin": {
+    "vorn-connector": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}