@vornrun/connector-sdk 0.7.0-beta.14 → 0.7.0-beta.16

package/README.md

@@ -424,6 +424,121 @@ reads the manifest.
 Paths are filled with `currentColor`, so the icon picks up the surrounding
 text color instead of fighting the theme.
 
+## Extensions
+
+A connector polls a service. An **extension** contributes to a session card
+instead: a footer band under the status bar, a pane beside the terminal, or a
+handler offered when a link in the terminal is clicked. It is the same pack —
+same manifest, same check, same receipt, same catalog — declared with
+`defineExtension` rather than `defineConnector`.
+
+```ts
+import { defineExtension } from '@vornrun/connector-sdk'
+
+export const connector = defineExtension({
+  id: 'review',
+  name: 'Review',
+  description: 'Reads the session',
+  permissions: ['terminal.read'],
+  activates: { workspaceContains: ['package.json'] },
+  footers: [
+    {
+      id: 'checks',
+      title: 'Checks',
+      every: 30,
+      async run(context) {
+        const output = await context.host.output({ lines: 200 })
+        return [{ label: 'tests', value: /FAIL/.test(output) ? 'failing' : 'passing' }]
+      }
+    }
+  ],
+  panes: [{ id: 'report', title: 'Report', web: 'web/report/index.html' }]
+})
+```
+
+Start one with `vorn-connector new review --extension`.
+
+### What it may ask the host for
+
+Every method of `context.host` costs one permission, and the manifest has to
+declare it. A call outside what was declared is refused rather than answered —
+by `check` against its stub host, and by Vorn at run time — so what a person
+agreed to when installing is what the extension can reach.
+
+| Permission           | Host method          | What it grants                       |
+| -------------------- | -------------------- | ------------------------------------ |
+| `git.read`           | `diff()`, `status()` | The worktree's diff and status       |
+| `terminal.read`      | `output()`           | The session's recent terminal output |
+| `terminal.selection` | `selection()`        | The text selected in the terminal    |
+| `terminal.send`      | `send(text)`         | Typing into the session's terminal   |
+| `card.rename`        | `rename(name)`       | Naming the session card              |
+| `agent.usage`        | `usage()`            | Context and provider allowance       |
+
+Ask for only what the extension spends: `check` names a permission that was
+declared and never used.
+
+### Where it shows
+
+`activates` on the extension, and `when` on any one contribution, narrow where
+it appears. Every declared field has to hold, and each is satisfied by any one
+of its values, so an extension is simply absent where it has nothing to say.
+
+```ts
+activates: {
+  workspaceContains: ['Cargo.toml'],   // paths relative to the worktree
+  remoteHost: ['github.com'],
+  agent: ['claude', 'shell'],
+  platform: ['darwin', 'linux']
+}
+```
+
+### What a pane is drawn from
+
+A pane is either a page the pack carries or a program it runs. A page lives
+under `web/` in the package, and the directory it sits in is carried into the
+pack, so its stylesheet and script travel with it. Vorn serves the page and
+answers `bridge/<method>` beside it, on the page's own origin: the page holds no
+token, and Vorn grants the call exactly the permissions the manifest declared,
+knowing from the origin which pane is asking. A program is argv, run in the
+session's worktree and drawn as a terminal.
+
+```js
+const response = await fetch('bridge/output', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ lines: 200 })
+})
+const output = (await response.json()).result
+```
+
+```ts
+panes: [
+  { id: 'report', title: 'Report', web: 'web/report/index.html' },
+  { id: 'log', title: 'Log', command: ['./bin/log'], when: { agent: ['shell'] } }
+]
+```
+
+### What a link handler is offered for
+
+A handler names the pattern it matches against clicked text, and one example
+link it is for. The example is what `check` runs the handler on, so a handler is
+proved against a link it will really be offered for rather than a made-up one.
+
+```ts
+linkHandlers: [
+  {
+    id: 'pull-request',
+    title: 'Pull request',
+    pattern: 'https://github\\.com/[^/]+/[^/]+/pull/\\d+',
+    example: 'https://github.com/vorn-run/vorn/pull/1',
+    async run(context) {
+      await context.host.send(`Look at ${context.url}`)
+      return { openPane: 'report' }
+    }
+  }
+]
+```
+
 ## CLI
 
 ```
@@ -436,9 +551,10 @@ vorn-connector pack <module>              Build an installable .vorn.tgz pack
 vorn-connector serve <module>             Serve on stdio (what Vorn runs)
 ```
 
-`new` accepts `--out <dir>`, `--name "Display Name"`, and `--repo-conventions`,
+`new` accepts `--out <dir>`, `--name "Display Name"`, `--repo-conventions`,
 which shapes the package the way the connectors repository expects it (scoped
-name, changelog, compiler and test settings); `pack` accepts `--out <dir>`.
+name, changelog, compiler and test settings), and `--extension`, which
+scaffolds an extension rather than a connector; `pack` accepts `--out <dir>`.
 
 `poll` accepts `--since <iso>` and `--limit <n>`, and reads the connector's
 declared config from your shell environment — the fastest way to confirm

package/dist/{check-Hw1F1a5z.d.ts → check-Cv6UNBA4.d.ts}

@@ -465,12 +465,177 @@ interface ConnectorDefinition {
      */
     preflight?(): Promise<PreflightResult> | PreflightResult;
 }
+/** What a pack is: a connector polls a service, an extension contributes to a session card. */
+type ConnectorKind = 'connector' | 'extension';
 /** A validated definition. Every accessor below is guaranteed non-null. */
 interface Connector extends ConnectorDefinition {
     readonly version: string;
     readonly config: ConnectorConfigField[];
     readonly triggers: TriggerDefinition[];
     readonly actions: ActionDefinition[];
+    readonly kind: ConnectorKind;
+    /** What an extension adds to a card. Absent on a connector. */
+    readonly contributes?: ExtensionContributions;
+    /** What an extension may ask the host for. Absent on a connector. */
+    readonly permissions?: ExtensionPermission[];
+    /** Where an extension shows at all. Absent on a connector. */
+    readonly activates?: ActivationPredicate;
+}
+/**
+ * What an extension may ask the host for, named by what it grants rather than
+ * by the method that spends it.
+ *
+ * A closed set on purpose: a permission is shown to a person before they
+ * install, so every one of them has to be a sentence someone can weigh.
+ */
+type ExtensionPermission = 'git.read' | 'terminal.read' | 'terminal.selection' | 'terminal.send' | 'card.rename' | 'agent.usage';
+/** Session types an extension can name; `shell` is a plain terminal. */
+type ExtensionAgent = 'claude' | 'copilot' | 'codex' | 'opencode' | 'gemini' | 'shell';
+type ExtensionPlatform = 'darwin' | 'linux' | 'win32';
+/**
+ * Where a contribution shows.
+ *
+ * Every declared field must hold for it to show, and each is satisfied by any
+ * one of its values: a Rust footer says `workspaceContains: ['Cargo.toml']`
+ * and is simply absent everywhere else, rather than reporting nothing.
+ */
+interface ActivationPredicate {
+    /** Paths relative to the session's worktree; any one of them existing is enough. */
+    workspaceContains?: string[];
+    /** Host of the worktree's git remote, e.g. `github.com`. */
+    remoteHost?: string[];
+    agent?: ExtensionAgent[];
+    platform?: ExtensionPlatform[];
+}
+interface ContributionBase {
+    /** Stable within the extension; the host addresses the contribution by it. */
+    id: string;
+    title: string;
+    description?: string;
+    /** Narrows where this one shows, inside where the extension is active at all. */
+    when?: ActivationPredicate;
+}
+/**
+ * A pane the extension adds beside the terminal: either a page it ships or a
+ * program it runs, never both — a union, so the invalid pair is a type error
+ * while the extension is being written.
+ */
+type PaneContribution = ContributionBase & {
+    /** Glyph for the menu row and the pane's own bar; the extension's is used when absent. */
+    icon?: ConnectorIcon;
+} & ({
+    /** Page inside the pack, under `web/`, rendered in a pane. */
+    web: string;
+    command?: never;
+} | {
+    /** Argv run in the session's worktree, drawn as a terminal. */
+    command: string[];
+    web?: never;
+});
+/** One reading in a footer band: a label, its value, and how the value reads. */
+interface FooterItem {
+    label: string;
+    value: string;
+    /** `ok` and `danger` colour the value; anything else is ordinary text. */
+    tone?: 'default' | 'ok' | 'danger';
+    /** Opened when the item is clicked, for a reading that points somewhere. */
+    href?: string;
+}
+/** What the agent's provider says is left, for the windows it publishes. */
+interface ExtensionUsageWindow {
+    /** The window's own name, e.g. `5h`. */
+    window: string;
+    /** How much of the allowance is left, 0 to 1. */
+    remaining: number;
+    resetsAt?: string;
+}
+interface ExtensionUsage {
+    contextTokens?: number;
+    contextWindow?: number;
+    /** Session-cumulative prompt-cache hit rate, 0 to 1. */
+    cacheHitRate?: number;
+    limits?: ExtensionUsageWindow[];
+}
+/**
+ * The host, as an extension sees it.
+ *
+ * Every method costs exactly one permission — `HOST_PERMISSIONS` says which —
+ * and calling one the manifest did not declare is refused rather than ignored,
+ * so an extension cannot quietly reach past what a person agreed to.
+ */
+interface ExtensionHost {
+    /** The worktree's diff against its base. */
+    diff(): Promise<string>;
+    /** Porcelain status of the worktree. */
+    status(): Promise<string>;
+    /** The session's recent terminal output, newest last. */
+    output(options?: {
+        lines?: number;
+    }): Promise<string>;
+    /** The text selected in the terminal, empty when nothing is selected. */
+    selection(): Promise<string>;
+    /** Type text into the session's terminal, as a person would. */
+    send(text: string): Promise<void>;
+    /** Name the session card, until a person names it themselves. */
+    rename(name: string): Promise<void>;
+    /** Context and provider allowance for the session's agent. */
+    usage(): Promise<ExtensionUsage>;
+}
+/** Every method of the host, so the table naming what each one costs stays complete. */
+type ExtensionHostMethod = keyof ExtensionHost;
+/** What a contribution is told about the session it is running for. */
+interface ExtensionContext {
+    sessionId: string;
+    /** Where the session's work is, so a contribution reads the tree it is about. */
+    worktreePath: string;
+    agent: ExtensionAgent;
+    host: ExtensionHost;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+}
+/** What a link handler is told, on top of the session it was clicked in. */
+interface LinkContext extends ExtensionContext {
+    /** The clicked text, which matched this handler's pattern. */
+    url: string;
+}
+/** What a link handler asks the app to do once it has run. */
+interface LinkHandled {
+    /** Id of one of this extension's panes, opened for the session. */
+    openPane?: string;
+}
+/** A band under the card's status bar, recomputed on its own interval. */
+interface FooterContribution extends ContributionBase {
+    /** Seconds between calls; the host polls no faster than this. */
+    every: number;
+    run(context: ExtensionContext): Promise<FooterItem[]> | FooterItem[];
+}
+/** Offers this extension when the clicked text in a terminal matches. */
+interface LinkHandlerContribution extends ContributionBase {
+    /** Matched as a regular expression against clicked text, under a bound the app sets. */
+    pattern: string;
+    /** A link this handler is for, which its pattern must match; `check` runs the handler on it. */
+    example: string;
+    run(context: LinkContext): Promise<LinkHandled | void> | LinkHandled | void;
+}
+interface ExtensionContributions {
+    panes?: PaneContribution[];
+    footers?: FooterContribution[];
+    linkHandlers?: LinkHandlerContribution[];
+}
+interface ExtensionDefinition {
+    /** Stable extension id, e.g. `review`. */
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    icon?: ConnectorIcon;
+    /** Everything this extension may ask the host for, declared rather than inferred. */
+    permissions: ExtensionPermission[];
+    /** Where the extension shows at all; absent means every session. */
+    activates?: ActivationPredicate;
+    panes?: PaneContribution[];
+    footers?: FooterContribution[];
+    linkHandlers?: LinkHandlerContribution[];
 }
 
 /**
@@ -602,6 +767,10 @@ declare function runAction(connector: Connector, actionType: string, args: Recor
 
 /** 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";
 /**
@@ -649,14 +818,43 @@ interface ConnectionSetup {
  * strategy — rather than Vorn's timestamp comparison — decide what is new.
  */
 declare function connectionSetup(connector: Connector, triggerType: string): ConnectionSetup;
+/** A contribution as the manifest carries it: everything but the code that runs it. */
+interface ManifestContribution {
+    id: string;
+    title: string;
+    description?: string;
+    when?: ActivationPredicate;
+}
+interface ManifestContributions {
+    panes?: Array<ManifestContribution & {
+        icon?: ConnectorIcon;
+        web?: string;
+        command?: string[];
+    }>;
+    footers?: Array<ManifestContribution & {
+        every: number;
+    }>;
+    linkHandlers?: Array<ManifestContribution & {
+        pattern: string;
+        example: string;
+    }>;
+}
 interface ConnectorManifest {
     id: string;
     name: string;
     version: string;
+    /** Absent on a manifest written before extensions, which reads as a connector. */
+    kind?: ConnectorKind;
     description?: string;
     icon?: ConnectorIcon;
     /** How the connector signs in, so the app can say so before installing it. */
     auth?: ConnectorAuth;
+    /** What an extension adds to a card. Present only on an extension. */
+    contributes?: ManifestContributions;
+    /** What an extension may ask the host for. Present only on an extension. */
+    permissions?: ExtensionPermission[];
+    /** Where an extension shows at all. Present only on an extension. */
+    activates?: ActivationPredicate;
     triggers: Array<{
         type: string;
         label: string;
@@ -783,6 +981,24 @@ declare function withMockHttp<T>(routes: MockRoute[], body: () => Promise<T> | T
  * spawning anything. Authors get real assertions in a plain unit test.
  */
 declare function createConnectorHarness(connector: Connector, harnessOptions?: HarnessOptions): ConnectorHarness;
+/** Answers a footer or handler from fixtures, and refuses what the manifest never asked for. */
+interface MockHostRun {
+    host: ExtensionHost;
+    /** Permissions the run actually spent, so a declared-but-unused one can be named. */
+    used: Set<ExtensionPermission>;
+}
+/** Replaces what the stub answers, for a test whose subject is the reading rather than the plumbing. */
+type MockHostAnswers = Partial<{
+    [K in ExtensionHostMethod]: ExtensionHost[K];
+}>;
+/**
+ * A host that answers from fixtures and enforces the manifest.
+ *
+ * The check runs every footer and handler against this rather than a real
+ * session, which is what lets a conformance run catch an extension reaching
+ * for something it never declared — before a person is asked to grant it.
+ */
+declare function mockExtensionHost(granted: readonly ExtensionPermission[], answers?: MockHostAnswers): MockHostRun;
 
 /**
  * Every finding this SDK can report.
@@ -791,7 +1007,7 @@ declare function createConnectorHarness(connector: Connector, harnessOptions?: H
  * 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';
+type CheckCode = 'missing-description' | 'auth-undeclared' | 'auth-probe-missing' | 'secret-not-marked' | 'action-no-outputs' | 'input-type-unsupported' | 'missing-idempotent' | 'unverifiable' | 'sample-unusable' | 'poll-failed' | 'no-items' | 'no-cursor' | 'cursor-rejected' | 'redelivers-items' | 'stuck-cursor' | 'lifecycle-scripts' | 'keywords-missing' | 'runtime-dependencies' | 'mock-action-failed' | 'mock-network-escape' | 'mock-not-observed' | 'preflight-failed' | 'live-action-failed' | 'pack-launch' | 'pack-too-large' | 'web-entry-missing' | 'web-entry-outside-package' | 'footer-failed' | 'footer-items-invalid' | 'handler-failed' | 'permission-undeclared' | 'permission-unused';
 interface CheckFinding {
     /** `error` means the connector will misbehave in Vorn; `warn` is advisory. */
     level: 'error' | 'warn';
@@ -880,4 +1096,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 { type StatusSuggestion as $, type ActionRequest as A, type BundleRequest as B, type CheckFinding as C, type DedupeStrategy as D, MAX_PACK_BYTES as E, type FetchContext as F, MAX_POLL_PAGES as G, type HarnessOptions as H, type MockCall as I, type MockRoute as J, MockRouteMissError as K, type MockRun as L, MANIFEST_TOOL as M, type NormalizedItem as N, OPTIONS_TOOL as O, type PollContext as P, type OptionsContext as Q, type OptionsLoader as R, PREFLIGHT_TOOL as S, type TriggerDefinition as T, type PaginationStrategy as U, type PollPage as V, type PreflightResult as W, type ResilientFetchOptions as X, type RetryPolicy as Y, type RunActionOptions as Z, type RunPollOptions as _, type BundleOutput as a, backoffMs as a0, bundleDependencyFindings as a1, bundledRequireFindings as a2, checkConnector as a3, connectionSetup as a4, connectorManifest as a5, createConnectorHarness as a6, drainPoll as a7, esbuildBundle as a8, escapedMockHttp as a9, formatFindings as aa, lifecycleScriptFindings 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 ConnectorDefinition as b, type Connector as c, type ConnectorConfig as d, type PollOutcome as e, type ConnectorItem as f, type PostReceiveOp as g, type ActionContext as h, type ActionDefinition as i, type ActionInputField as j, type ActionInputOption as k, type ActionInputType as l, type ActionOutputField as m, type AuthRung as n, CHECK_OWNERS as o, type CheckCode as p, type CheckOptions as q, type ConformanceRun as r, type ConnectionSetup as s, type ConnectorAuth as t, type ConnectorConfigField as u, type ConnectorHarness as v, type ConnectorIcon as w, type ConnectorManifest as x, type ConnectorVerification as y, type DefaultWorkflow as z };
+export { MAX_PACK_BYTES as $, type ActionRequest as A, type BundleRequest as B, type CheckFinding as C, type ConnectorIcon as D, type ExtensionPermission as E, type ConnectorKind as F, type ConnectorManifest as G, type ConnectorVerification as H, type DedupeStrategy as I, type DefaultWorkflow as J, type ExtensionAgent as K, type ExtensionContext as L, type ExtensionContributions as M, type NormalizedItem as N, type ExtensionPlatform as O, type PollContext as P, type ExtensionUsage as Q, type ExtensionUsageWindow as R, type FetchContext as S, type TriggerDefinition as T, type FooterContribution as U, type FooterItem as V, type HarnessOptions as W, type LinkContext as X, type LinkHandled as Y, type LinkHandlerContribution as Z, MANIFEST_TOOL 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, OPTIONS_TOOL as a8, type OptionsContext as a9, pollToolName as aA, readNearestPackageJson as aB, resilientFetch as aC, retryAfterMs as aD, runAction as aE, runConformance as aF, runOptions as aG, runPoll as aH, withMockHttp as aI, type OptionsLoader as aa, PREFLIGHT_TOOL as ab, type PaginationStrategy as ac, type PaneContribution as ad, type PollPage as ae, type PreflightResult as af, type ResilientFetchOptions as ag, type RetryPolicy as ah, type RunActionOptions as ai, type RunPollOptions as aj, type StatusSuggestion as ak, backoffMs as al, bundleDependencyFindings as am, bundledRequireFindings as an, checkConnector as ao, connectionSetup as ap, connectorManifest as aq, createConnectorHarness as ar, drainPoll as as, esbuildBundle as at, escapedMockHttp as au, footerToolName as av, formatFindings as aw, handlerToolName as ax, lifecycleScriptFindings as ay, mockExtensionHost 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, CHECK_OWNERS as s, type CheckCode as t, type CheckOptions as u, type ConformanceRun as v, type ConnectionSetup as w, type ConnectorAuth as x, type ConnectorConfigField as y, type ConnectorHarness as z };