@vornrun/connector-sdk 0.5.2 → 0.5.4

package/README.md

@@ -1,9 +1,8 @@
 # @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.
+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.
 
 ```bash
 npm install @vornrun/connector-sdk
@@ -27,7 +26,10 @@ export default defineConnector({
     {
       type: 'newTicket',
       label: 'New ticket',
-      async poll({ config, since, limit }) {
+      description: 'Tickets created or updated since the last poll',
+      // Say how new items are recognized and the SDK owns the cursor for you.
+      dedupe: 'timestamp',
+      async fetch({ 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))
@@ -38,17 +40,15 @@ export default defineConnector({
         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 }
-          }))
-        }
+        return 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 }
+        }))
       }
     }
   ],
@@ -101,24 +101,23 @@ export default defineConnector({
     {
       type: 'newOrder',
       label: 'New order',
-      async poll({ config, since, limit }) {
+      dedupe: 'timestamp',
+      async fetch({ 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'}
+            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
-            }))
-          }
+          return rows.map((row) => ({
+            externalId: row.id,
+            title: `Order ${row.reference}`,
+            status: row.status,
+            updatedAt: row.updated_at
+          }))
         } finally {
           await sql.end()
         }
@@ -132,13 +131,39 @@ 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`.
+2. `updatedAt` must be monotonic and ISO-comparable — the cursor advances from
+   it. Use `>=` when filtering on `since` and sort ascending; returning a few
+   items again is free, because the SDK drops anything already delivered.
+
+## Dedupe strategies
+
+`dedupe` tells the SDK how to recognize new items, and it then owns the cursor
+— including the case that quietly breaks hand-written connectors, where several
+items share the newest timestamp and are either dropped forever (`>`) or
+redelivered on every poll (`>=`).
+
+| strategy    | your `fetch` receives | use it when                                      |
+| ----------- | --------------------- | ------------------------------------------------ |
+| `timestamp` | `since`               | the source has a reliable "last changed" field   |
+| `lastItem`  | `lastItemId`          | a newest-first feed with no dependable timestamp |
+
+```ts
+{
+  type: 'newPost',
+  label: 'New post',
+  dedupe: 'lastItem',
+  // Return the feed newest-first; the SDK stops at the last id it delivered.
+  fetch: ({ config }) => fetchFeed(config)
+}
+```
+
+A first poll never drains the whole history — it delivers one page and starts
+tracking from there.
 
-## Paging a backlog
+## Paging a backlog by hand
 
-Return `hasMore: true` with a `nextCursor`, and Vorn (or `drainPoll` in tests)
-will keep pulling bounded pages until the backlog is drained:
+When a source's paging cannot be expressed as "everything since X", implement
+`poll` instead of `fetch` and own the cursor yourself:
 
 ```ts
 async poll({ cursor, config }) {
@@ -154,6 +179,35 @@ async poll({ cursor, config }) {
 
 A cursor that does not advance is rejected rather than looped on.
 
+## Check it before shipping
+
+`vorn-connector check` verifies a connector against the contract Vorn relies
+on — most importantly that re-polling with its own cursor does not redeliver
+items it already handed over:
+
+```console
+$ npx vorn-connector check ./dist/index.js
+error  trigger newTicket: re-polling with its own nextCursor returned 3 already-delivered item(s), starting with "1042" [redelivers-items]
+warn   action closeTicket: does not declare `idempotent`, so an agent cannot tell whether retrying is safe [missing-idempotent]
+
+1 error(s), 1 warning(s)
+```
+
+It exits non-zero on errors, so it works as a CI gate. Add `sample` items to a
+trigger and they are replayed through the real dedupe pipeline, so a connector
+can be checked before anyone has credentials for it; pass `--live` to poll the
+real source instead.
+
+```ts
+{
+  type: 'newTicket',
+  label: 'New ticket',
+  dedupe: 'timestamp',
+  sample: [{ externalId: '1', title: 'Example ticket', updatedAt: '2026-01-01T00:00:00.000Z' }],
+  fetch: ({ config, since }) => fetchTickets(config, since)
+}
+```
+
 ## Test it without running the app
 
 ```ts
@@ -181,23 +235,53 @@ test('does not redeliver the same backlog forever', async () => {
 
 ## Install it in Vorn
 
-Run the CLI to get the exact connection settings:
+**Settings → Connectors → MCP → From a package**, then type the package name.
+
+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.
+
+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.
+
+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:
 
 ```bash
 npx vorn-connector setup ./dist/index.js
 ```
 
-It prints the values for **Settings → Connectors → MCP → New connection**:
+### Ship an icon
 
-| 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` |
+Without one, a connector shows the generic MCP glyph and is hard to pick out
+of a list of connections.
 
-Because the connector is a normal npm package, versions are pinned by the
-`npx` argument and upgrades are a version bump — no separate registry.
+```ts
+defineConnector({
+  id: 'acme',
+  name: 'Acme',
+  icon: {
+    viewBox: '0 0 24 24',
+    paths: ['M12 2 2 22h20L12 2z']
+  }
+  // ...
+})
+```
+
+Path data only — no markup, no `<svg>` wrapper, no external references. Vorn
+draws these as `<path d="...">` inside an element it owns, so an icon can
+never contribute markup to the app rendering it. Anything that is not path
+data is rejected by `defineConnector` at import time, and again when Vorn
+reads the manifest.
+
+Paths are filled with `currentColor`, so the icon picks up the surrounding
+text color instead of fighting the theme.
 
 ## CLI
 
@@ -205,9 +289,13 @@ Because the connector is a normal npm package, versions are pinned by the
 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 check <module>             Verify the connector against the contract
 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.
+
+`check` runs against declared `sample` data by default and takes `--live` to
+poll the real source instead.

package/dist/{chunk-UANUTYUV.js → chunk-W4GGTEUK.js}

@@ -1,84 +1,3 @@
-// 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",
@@ -91,6 +10,12 @@ var RESERVED_KEYS = [
   "updatedAt"
 ];
 var UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+function itemExternalId(item) {
+  return String(item.externalId ?? "").trim();
+}
+function itemTimestamp(item, fallback) {
+  return isoTimestamp(item.updatedAt, fallback);
+}
 function isoTimestamp(value, fallback) {
   if (value === void 0) return fallback;
   const date = value instanceof Date ? value : new Date(value);
@@ -100,7 +25,7 @@ function isoTimestamp(value, fallback) {
   return date.toISOString();
 }
 function normalizeItem(item, polledAt) {
-  const externalId = String(item.externalId ?? "").trim();
+  const externalId = itemExternalId(item);
   if (!externalId) {
     throw new Error("Connector item is missing externalId");
   }
@@ -137,6 +62,120 @@ function normalizeItems(items, polledAt) {
   });
 }
 
+// src/dedupe.ts
+var MAX_BOUNDARY_IDS = 500;
+function decodeCursor(cursor, strategy) {
+  if (!cursor) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(cursor);
+  } catch (error) {
+    throw new Error(`Cursor is not valid SDK cursor JSON: ${cursor}`, { cause: error });
+  }
+  const state = parsed;
+  if (!state || typeof state !== "object" || state.v !== 1 || state.s !== strategy) {
+    throw new Error(`Cursor does not belong to the "${strategy}" strategy: ${cursor}`);
+  }
+  const wellFormed = state.s === "timestamp" ? typeof state.t === "string" && Array.isArray(state.ids) && state.ids.every((id) => typeof id === "string") : typeof state.id === "string";
+  if (!wellFormed) {
+    throw new Error(`Cursor is missing the fields the "${strategy}" strategy needs: ${cursor}`);
+  }
+  return state;
+}
+function compare(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+function page(chronological, context, hadCursor, nextCursor) {
+  const delivered = context.limit === void 0 ? chronological : chronological.slice(0, context.limit);
+  if (delivered.length === 0) {
+    return { items: [], ...context.cursor !== void 0 && { nextCursor: context.cursor } };
+  }
+  return {
+    items: delivered.map((entry) => entry.item),
+    nextCursor: JSON.stringify(nextCursor(delivered)),
+    // Only drain a backlog we know we truncated, and only once a cursor
+    // exists — a first poll should not pull the source's entire history.
+    hasMore: chronological.length > delivered.length && hadCursor
+  };
+}
+function timestampPoll(fetched, state, context, polledAt) {
+  const boundary = state?.t ?? context.since;
+  const seen = new Set(state?.ids ?? []);
+  const fresh = [];
+  const pinnedAlreadySeen = [];
+  for (const item of fetched) {
+    const id = itemExternalId(item);
+    const pinned = item.updatedAt === void 0 && boundary !== void 0;
+    const at = pinned ? boundary : itemTimestamp(item, polledAt);
+    const isNew = boundary === void 0 || at > boundary || at === boundary && !seen.has(id);
+    if (isNew) fresh.push({ item, at, id, ...pinned && { pinned: true } });
+    else if (pinned) pinnedAlreadySeen.push(id);
+  }
+  fresh.sort((left, right) => compare(left.at, right.at) || compare(left.id, right.id));
+  return page(fresh, context, state !== void 0, (delivered) => {
+    const newest = delivered[delivered.length - 1].at;
+    const atNewest = [];
+    for (let i = delivered.length - 1; i >= 0 && delivered[i].at === newest; i -= 1) {
+      atNewest.push(delivered[i].id);
+    }
+    const carried = newest === boundary ? [...seen, ...atNewest] : [
+      ...pinnedAlreadySeen,
+      ...delivered.filter((entry) => entry.pinned).map((entry) => entry.id),
+      ...atNewest
+    ];
+    return { v: 1, s: "timestamp", t: newest, ids: carried.slice(-MAX_BOUNDARY_IDS) };
+  });
+}
+function lastItemPoll(fetched, state, context, polledAt) {
+  const keyed = fetched.map((item) => ({
+    item,
+    at: itemTimestamp(item, polledAt),
+    id: itemExternalId(item)
+  }));
+  const stopAt = state ? keyed.findIndex((entry) => entry.id === state.id) : -1;
+  const chronological = (stopAt === -1 ? keyed : keyed.slice(0, stopAt)).reverse();
+  return page(chronological, context, state !== void 0, (delivered) => ({
+    v: 1,
+    s: "lastItem",
+    id: delivered[delivered.length - 1].id
+  }));
+}
+async function pollWithDedupe(trigger, context) {
+  const strategy = trigger.dedupe;
+  const fetchItems = trigger.fetch;
+  if (!strategy || !fetchItems) {
+    throw new Error(`Trigger ${trigger.type} is not a declarative trigger`);
+  }
+  const polledAt = context.now();
+  if (strategy === "lastItem") {
+    const state2 = decodeCursor(context.cursor, "lastItem");
+    const fetched2 = await runFetch(trigger.type, fetchItems, {
+      config: context.config,
+      ...state2 && { lastItemId: state2.id },
+      ...context.limit !== void 0 && { limit: context.limit },
+      now: context.now
+    });
+    return lastItemPoll(fetched2, state2, context, polledAt);
+  }
+  const state = decodeCursor(context.cursor, "timestamp");
+  const since = state?.t ?? context.since;
+  const fetched = await runFetch(trigger.type, fetchItems, {
+    config: context.config,
+    ...since !== void 0 && { since },
+    ...context.limit !== void 0 && { limit: context.limit },
+    now: context.now
+  });
+  return timestampPoll(fetched, state, context, polledAt);
+}
+async function runFetch(type, fetchItems, context) {
+  const fetched = await fetchItems(context);
+  if (!Array.isArray(fetched)) {
+    throw new Error(`Trigger ${type} fetch() did not return an array`);
+  }
+  return fetched;
+}
+
 // src/runtime.ts
 var MAX_POLL_PAGES = 1e3;
 async function runPoll(connector, triggerType, options = {}) {
@@ -153,7 +192,7 @@ async function runPoll(connector, triggerType, options = {}) {
     ...options.limit !== void 0 && { limit: options.limit },
     now
   };
-  const outcome = await trigger.poll(context);
+  const outcome = typeof trigger.poll === "function" ? await trigger.poll(context) : await pollWithDedupe(trigger, context);
   if (!outcome || !Array.isArray(outcome.items)) {
     throw new Error(`Trigger ${triggerType} did not return an items array`);
   }
@@ -169,7 +208,7 @@ async function runPoll(connector, triggerType, options = {}) {
 async function drainPoll(connector, triggerType, options = {}) {
   const collected = [];
   let cursor = options.cursor;
-  for (let page = 0; page < MAX_POLL_PAGES; page++) {
+  for (let page2 = 0; page2 < MAX_POLL_PAGES; page2++) {
     const result = await runPoll(connector, triggerType, {
       ...options,
       ...cursor !== void 0 && { cursor }
@@ -226,6 +265,277 @@ async function runAction(connector, actionType, args, options = {}) {
   return output ?? {};
 }
 
+// src/check.ts
+function finding(level, code, target, message) {
+  return { level, code, target, message };
+}
+function sampleTrigger(trigger) {
+  return { ...trigger, poll: void 0, fetch: () => trigger.sample ?? [] };
+}
+async function checkPollBehaviour(connector, trigger, options) {
+  const found = [];
+  const probe = { ...connector, triggers: [trigger] };
+  const target = `trigger ${trigger.type}`;
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const attempt = async (cursor, code, what) => {
+    try {
+      return await runPoll(probe, trigger.type, {
+        config: options.config ?? {},
+        ...cursor !== void 0 && { cursor },
+        now
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return finding("error", code, target, `${what} threw: ${reason}`);
+    }
+  };
+  const first = await attempt(void 0, "poll-failed", "first poll");
+  if ("level" in first) return [first];
+  if (first.items.length === 0) {
+    found.push(
+      finding("warn", "no-items", target, "returned nothing, so delivery could not be verified")
+    );
+    return found;
+  }
+  if (first.nextCursor === void 0) {
+    found.push(
+      finding(
+        "error",
+        "no-cursor",
+        target,
+        "returned items but no nextCursor, so every poll will redeliver them"
+      )
+    );
+    return found;
+  }
+  const second = await attempt(
+    first.nextCursor,
+    "cursor-rejected",
+    "re-polling with its own nextCursor"
+  );
+  if ("level" in second) return [...found, second];
+  const delivered = new Set(first.items.map((item) => item.externalId));
+  const repeated = second.items.filter((item) => delivered.has(item.externalId));
+  if (repeated.length > 0) {
+    found.push(
+      finding(
+        "error",
+        "redelivers-items",
+        target,
+        `re-polling with its own nextCursor returned ${repeated.length} already-delivered item(s), starting with "${repeated[0].externalId}"`
+      )
+    );
+  }
+  if (second.hasMore && second.nextCursor === first.nextCursor) {
+    found.push(
+      finding("error", "stuck-cursor", target, "reports more pages but its cursor never advances")
+    );
+  }
+  return found;
+}
+async function checkConnector(connector, options = {}) {
+  const found = [];
+  if (!connector.description?.trim()) {
+    found.push(
+      finding(
+        "warn",
+        "missing-description",
+        connector.id,
+        "has no description; agents use it to decide when the connector applies"
+      )
+    );
+  }
+  const perTrigger = await Promise.all(
+    connector.triggers.map(async (trigger) => {
+      const target = `trigger ${trigger.type}`;
+      const triggerFindings = [];
+      if (!trigger.description?.trim()) {
+        triggerFindings.push(finding("warn", "missing-description", target, "has no description"));
+      }
+      if (options.live) {
+        triggerFindings.push(...await checkPollBehaviour(connector, trigger, options));
+      } else if (!trigger.sample?.length) {
+        triggerFindings.push(
+          finding(
+            "warn",
+            "unverifiable",
+            target,
+            "has no sample items and no credentials were supplied, so nothing could be verified"
+          )
+        );
+      } else if (!trigger.dedupe) {
+        triggerFindings.push(
+          finding(
+            "warn",
+            "sample-unusable",
+            target,
+            "declares sample items but implements poll() directly, so they cannot be replayed; re-run with --live"
+          )
+        );
+      } else {
+        triggerFindings.push(
+          ...await checkPollBehaviour(connector, sampleTrigger(trigger), options)
+        );
+      }
+      return triggerFindings;
+    })
+  );
+  found.push(...perTrigger.flat());
+  for (const action of connector.actions) {
+    const target = `action ${action.type}`;
+    if (!action.description?.trim()) {
+      found.push(
+        finding("warn", "missing-description", target, "has no description for the agent to read")
+      );
+    }
+    if (action.idempotent === void 0) {
+      found.push(
+        finding(
+          "warn",
+          "missing-idempotent",
+          target,
+          "does not declare `idempotent`, so an agent cannot tell whether retrying is safe"
+        )
+      );
+    }
+    for (const input of action.inputs ?? []) {
+      if (!input.description?.trim()) {
+        found.push(
+          finding(
+            "warn",
+            "missing-description",
+            `${target} input ${input.key}`,
+            "has no description"
+          )
+        );
+      }
+    }
+  }
+  return found;
+}
+function formatFindings(findings) {
+  return findings.map((item) => `${item.level.padEnd(5)}  ${item.target}: ${item.message} [${item.code}]`).join("\n");
+}
+
+// src/define.ts
+var KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+var PATH_DATA_PATTERN = /^[MmZzLlHhVvCcSsQqTtAa0-9\s,.\-+eE]+$/;
+var VIEW_BOX_PATTERN = /^-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+$/;
+var DEDUPE_STRATEGIES = ["timestamp", "lastItem"];
+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`);
+  }
+  if (definition.icon) {
+    const { viewBox, paths } = definition.icon;
+    if (!Array.isArray(paths) || paths.length === 0) {
+      throw new Error(`Connector ${definition.id} has an icon with no paths`);
+    }
+    for (const path of paths) {
+      if (typeof path !== "string" || !PATH_DATA_PATTERN.test(path)) {
+        throw new Error(
+          `Connector ${definition.id} has an icon path that is not SVG path data. Only path data is accepted, not markup.`
+        );
+      }
+    }
+    if (viewBox !== void 0 && !VIEW_BOX_PATTERN.test(viewBox)) {
+      throw new Error(`Connector ${definition.id} has an icon viewBox that is not four numbers`);
+    }
+  }
+  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`);
+    }
+    const loose = trigger;
+    const declarative = typeof loose.fetch === "function";
+    const imperative = typeof loose.poll === "function";
+    if (declarative && imperative) {
+      throw new Error(`Trigger ${trigger.type} declares both fetch() and poll(); pick one`);
+    }
+    if (declarative !== (loose.dedupe !== void 0)) {
+      throw new Error(
+        `Trigger ${trigger.type} needs fetch() and a dedupe strategy together, not one alone`
+      );
+    }
+    if (loose.dedupe !== void 0 && !DEDUPE_STRATEGIES.includes(loose.dedupe)) {
+      throw new Error(
+        `Trigger ${trigger.type} has unknown dedupe strategy ${JSON.stringify(loose.dedupe)}; expected ${DEDUPE_STRATEGIES.join(" or ")}`
+      );
+    }
+    if (loose.poll !== void 0 && !imperative) {
+      throw new Error(`Trigger ${trigger.type} declares poll but it is not a function`);
+    }
+    if (!declarative && !imperative) {
+      throw new Error(`Trigger ${trigger.type} is missing a fetch() or 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/setup.ts
 function pollToolName(triggerType) {
   return `poll_${triggerType}`;
@@ -245,7 +555,9 @@ function connectionSetup(connector, triggerType) {
       idField: "externalId",
       timestampField: "updatedAt",
       titleField: "title",
-      urlField: "url"
+      urlField: "url",
+      cursorArg: "cursor",
+      cursorPath: "nextCursor"
     },
     env: connector.config.map((field) => ({
       name: envNameFor(field.key, field.env),
@@ -261,6 +573,7 @@ function connectorManifest(connector) {
     name: connector.name,
     version: connector.version,
     ...connector.description !== void 0 && { description: connector.description },
+    ...connector.icon !== void 0 && { icon: connector.icon },
     triggers: connector.triggers.map((trigger) => ({
       type: trigger.type,
       label: trigger.label,
@@ -374,10 +687,12 @@ function createConnectorServer(connector, options = {}) {
     );
   }
   for (const action of connector.actions) {
+    const base = action.description ?? `${action.label} in ${connector.name}`;
+    const retryHint = action.idempotent === void 0 ? "" : action.idempotent ? " Safe to retry: repeating this call with the same arguments has no additional effect." : " Not idempotent: repeating this call performs the operation again.";
     server.registerTool(
       action.type,
       {
-        description: action.description ?? `${action.label} in ${connector.name}`,
+        description: `${base}${retryHint}`,
         inputSchema: inputShape(action.inputs ?? []),
         outputSchema: outputSchema(action.outputs ?? [])
       },
@@ -403,15 +718,18 @@ async function serveConnector(connector, options = {}) {
 }
 
 export {
-  envNameFor,
-  defineConnector,
-  resolveConfig,
   normalizeItem,
   normalizeItems,
+  pollWithDedupe,
   MAX_POLL_PAGES,
   runPoll,
   drainPoll,
   runAction,
+  checkConnector,
+  formatFindings,
+  envNameFor,
+  defineConnector,
+  resolveConfig,
   pollToolName,
   MANIFEST_TOOL,
   connectionSetup,

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import {
+  checkConnector,
   connectionSetup,
   connectorManifest,
+  formatFindings,
   resolveConfig,
   runPoll,
   serveConnector
-} from "./chunk-UANUTYUV.js";
+} from "./chunk-W4GGTEUK.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -15,25 +17,37 @@ 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
+  check <module>                Verify the connector against Vorn's contract
   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) {
+  --limit <n>                   Maximum items to request
+  --live                        Let check poll for real using the environment`;
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["live"]);
+function parseArgs(args) {
   const flags = {};
+  const positional = [];
   for (let index = 0; index < args.length; index++) {
     const arg = args[index];
-    if (!arg.startsWith("--")) continue;
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    if (BOOLEAN_FLAGS.has(name)) {
+      flags[name] = "true";
+      continue;
+    }
     const value = args[index + 1];
     if (value === void 0 || value.startsWith("--")) {
       throw new Error(`Missing value for ${arg}`);
     }
-    flags[arg.slice(2)] = value;
+    flags[name] = value;
     index++;
   }
-  return flags;
+  return { flags, positional };
 }
 function pickConnector(loaded, modulePath) {
   const module = loaded;
@@ -59,8 +73,7 @@ ${USAGE}`);
     return 1;
   }
   const connector = pickConnector(await deps.load(modulePath), modulePath);
-  const positional = rest.filter((arg) => !arg.startsWith("--"));
-  const flags = parseFlags(rest);
+  const { flags, positional } = parseArgs(rest);
   switch (command) {
     case "manifest":
       deps.write(JSON.stringify(connectorManifest(connector), null, 2));
@@ -81,6 +94,22 @@ ${USAGE}`);
       }
       return 0;
     }
+    case "check": {
+      const findings = await checkConnector(connector, {
+        ...flags.live === "true" && {
+          live: true,
+          config: resolveConfig(connector, deps.env ?? process.env)
+        }
+      });
+      const errors = findings.filter((item) => item.level === "error");
+      if (findings.length > 0) deps.write(formatFindings(findings));
+      deps.write(
+        errors.length > 0 ? `
+${errors.length} error(s), ${findings.length - errors.length} warning(s)` : `
+${connector.id} passed with ${findings.length} warning(s)`
+      );
+      return errors.length > 0 ? 1 : 0;
+    }
     case "poll": {
       const triggerType = positional[0];
       if (!triggerType) {

package/dist/index.d.ts

@@ -72,13 +72,74 @@ interface PollOutcome {
     nextCursor?: string;
     hasMore?: boolean;
 }
-interface TriggerDefinition {
+/**
+ * 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;
+}
+interface TriggerBase {
     /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
     type: string;
     label: string;
     description?: string;
-    poll(context: PollContext): Promise<PollOutcome> | PollOutcome;
+    /**
+     * 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;
+});
 interface ActionInputField {
     key: string;
     label: string;
@@ -105,16 +166,37 @@ interface ActionDefinition {
     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.
+     */
+    idempotent?: boolean;
     inputs?: ActionInputField[];
     outputs?: ActionOutputField[];
     run(args: Record<string, unknown>, context: ActionContext): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 }
+/**
+ * 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[];
+}
 interface ConnectorDefinition {
     /** Stable connector id, e.g. `azure-devops`. */
     id: string;
     name: string;
     version?: string;
     description?: string;
+    icon?: ConnectorIcon;
     config?: ConnectorConfigField[];
     triggers?: TriggerDefinition[];
     actions?: ActionDefinition[];
@@ -145,6 +227,47 @@ declare function defineConnector(definition: ConnectorDefinition): Connector;
  */
 declare function resolveConfig(connector: Connector, env?: NodeJS.ProcessEnv): ConnectorConfig;
 
+interface CheckFinding {
+    /** `error` means the connector will misbehave in Vorn; `warn` is advisory. */
+    level: 'error' | 'warn';
+    code: string;
+    /** 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;
+}
+/**
+ * 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[]>;
+/** Render findings for a terminal. Returns an empty string when all clear. */
+declare function formatFindings(findings: CheckFinding[]): string;
+
+/**
+ * Run a declarative trigger: call the author's `fetch`, then apply the chosen
+ * dedupe strategy.
+ *
+ * This exists because cursor bookkeeping is where hand-written pull connectors
+ * go wrong — duplicate deliveries, items lost at the timestamp boundary, and
+ * cursors that never advance. Solving it once here means every connector, and
+ * every connector an agent generates, inherits the fix.
+ */
+declare function pollWithDedupe(trigger: TriggerDefinition, context: PollContext): Promise<PollOutcome>;
+
 /**
  * Turn an author-supplied item into the flat JSON shape Vorn consumes.
  *
@@ -211,6 +334,8 @@ interface ConnectionSetup {
         timestampField: 'updatedAt';
         titleField: 'title';
         urlField: 'url';
+        cursorArg: 'cursor';
+        cursorPath: 'nextCursor';
     };
     /** Environment variable names the connector reads. */
     env: Array<{
@@ -225,7 +350,9 @@ interface ConnectionSetup {
  *
  * 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.
+ * 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;
 interface ConnectorManifest {
@@ -233,6 +360,7 @@ interface ConnectorManifest {
     name: string;
     version: string;
     description?: string;
+    icon?: ConnectorIcon;
     triggers: Array<{
         type: string;
         label: string;
@@ -295,4 +423,4 @@ interface ConnectorHarness {
  */
 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 };
+export { type ActionContext, type ActionDefinition, type ActionInputField, type CheckFinding, type CheckOptions, type ConnectionSetup, type Connector, type ConnectorConfig, type ConnectorConfigField, type ConnectorDefinition, type ConnectorHarness, type ConnectorIcon, type ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, type DedupeStrategy, type FetchContext, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, type NormalizedItem, type PollContext, type PollOutcome, type PollPage, type RunActionOptions, type RunPollOptions, type TriggerDefinition, checkConnector, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, formatFindings, normalizeItem, normalizeItems, pollToolName, pollWithDedupe, resolveConfig, runAction, runPoll, serveConnector };

package/dist/index.js

@@ -1,20 +1,23 @@
 import {
   MANIFEST_TOOL,
   MAX_POLL_PAGES,
+  checkConnector,
   connectionSetup,
   connectorManifest,
   createConnectorServer,
   defineConnector,
   drainPoll,
   envNameFor,
+  formatFindings,
   normalizeItem,
   normalizeItems,
   pollToolName,
+  pollWithDedupe,
   resolveConfig,
   runAction,
   runPoll,
   serveConnector
-} from "./chunk-UANUTYUV.js";
+} from "./chunk-W4GGTEUK.js";
 
 // src/harness.ts
 function createConnectorHarness(connector, harnessOptions = {}) {
@@ -49,6 +52,7 @@ function createConnectorHarness(connector, harnessOptions = {}) {
 export {
   MANIFEST_TOOL,
   MAX_POLL_PAGES,
+  checkConnector,
   connectionSetup,
   connectorManifest,
   createConnectorHarness,
@@ -56,9 +60,11 @@ export {
   defineConnector,
   drainPoll,
   envNameFor,
+  formatFindings,
   normalizeItem,
   normalizeItems,
   pollToolName,
+  pollWithDedupe,
   resolveConfig,
   runAction,
   runPoll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vornrun/connector-sdk",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Build and share Vorn pull connectors as ordinary npm packages",
   "type": "module",
   "license": "MIT",