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

package/dist/{chunk-PMMEWBVK.js → chunk-FHGC7LE7.js}

@@ -4,6 +4,75 @@ var PATH_DATA_PATTERN = /^[MmZzLlHhVvCcSsQqTtAa0-9\s,.\-+eE]+$/;
 var VIEW_BOX_PATTERN = /^-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+$/;
 var DEDUPE_STRATEGIES = ["timestamp", "lastItem"];
 var AUTH_RUNGS = ["none", "cli", "key", "oauth"];
+var EXTENSION_PERMISSIONS = [
+  "git.read",
+  "terminal.read",
+  "terminal.selection",
+  "terminal.send",
+  "card.rename",
+  "agent.usage"
+];
+var HOST_PERMISSIONS = {
+  diff: "git.read",
+  status: "git.read",
+  output: "terminal.read",
+  selection: "terminal.selection",
+  send: "terminal.send",
+  rename: "card.rename",
+  usage: "agent.usage"
+};
+var EXTENSION_AGENTS = [
+  "claude",
+  "copilot",
+  "codex",
+  "opencode",
+  "gemini",
+  "shell"
+];
+var EXTENSION_PLATFORMS = ["darwin", "linux", "win32"];
+var WEB_ENTRY_PATTERN = /^web\/[A-Za-z0-9._/-]+\.html$/;
+var MIN_FOOTER_SECONDS = 5;
+var MAX_PATTERN_LENGTH = 256;
+var GROUP_OPEN = /^\((\?(:|=|!|<=|<!|<[A-Za-z_$][\w$]*>))?/;
+function hasNestedQuantifier(pattern) {
+  const quantifierAt = (at) => {
+    const ch = pattern[at];
+    return ch !== void 0 && "*+?{".includes(ch);
+  };
+  const quantified = [];
+  let inClass = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "\\") {
+      i++;
+      continue;
+    }
+    if (inClass) {
+      if (ch === "]") inClass = false;
+      continue;
+    }
+    if (ch === "[") {
+      inClass = true;
+      continue;
+    }
+    if (ch === "(") {
+      quantified.push(false);
+      i += (GROUP_OPEN.exec(pattern.slice(i))?.[0].length ?? 1) - 1;
+      continue;
+    }
+    if (ch === ")") {
+      const heldOne = quantified.pop() ?? false;
+      const repeated = quantifierAt(i + 1);
+      if (heldOne && repeated) return true;
+      if ((heldOne || repeated) && quantified.length > 0) {
+        quantified[quantified.length - 1] = true;
+      }
+      continue;
+    }
+    if (quantifierAt(i) && quantified.length > 0) quantified[quantified.length - 1] = true;
+  }
+  return false;
+}
 var ABSOLUTE_URL_PATTERN = /^https?:\/\//i;
 var CONFIG_ROOTED_URL_PATTERN = /^\{\{\s*config\./;
 function assertUnique(kind, keys) {
@@ -46,33 +115,38 @@ function assertAuth(definition) {
     }
   }
 }
-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) {
+function assertIdentity(kind, definition) {
   if (!KEY_PATTERN.test(definition.id ?? "")) {
-    throw new Error(`Connector id "${definition.id}" must start with a letter and be url-safe`);
+    throw new Error(`${kind} 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`);
+    throw new Error(`${kind} ${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`);
+  assertIcon(`${kind} ${definition.id}`, definition.icon);
+}
+function assertIcon(subject, icon) {
+  if (!icon) return;
+  const { viewBox, paths } = icon;
+  if (!Array.isArray(paths) || paths.length === 0) {
+    throw new Error(`${subject} has an icon with no paths`);
+  }
+  for (const path of paths) {
+    if (typeof path !== "string" || !PATH_DATA_PATTERN.test(path)) {
+      throw new Error(
+        `${subject} 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(`${subject} has an icon viewBox that is not four numbers`);
+  }
+}
+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) {
+  assertIdentity("Connector", definition);
   const triggers = definition.triggers ?? [];
   const actions = definition.actions ?? [];
   if (triggers.length === 0 && actions.length === 0) {
@@ -156,12 +230,191 @@ function defineConnector(definition) {
   assertAuth(definition);
   return {
     ...definition,
+    kind: "connector",
     version: definition.version ?? "0.0.0",
     config: definition.config ?? [],
     triggers,
     actions
   };
 }
+function assertPredicate(id, where, predicate) {
+  if (!predicate) return;
+  const lists = [
+    ["workspaceContains", predicate.workspaceContains],
+    ["remoteHost", predicate.remoteHost],
+    ["agent", predicate.agent],
+    ["platform", predicate.platform]
+  ];
+  for (const [field, value] of lists) {
+    if (value === void 0) continue;
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new Error(`Extension ${id} ${where} declares "${field}" with nothing in it`);
+    }
+    for (const entry of value) {
+      if (typeof entry !== "string" || entry.trim() === "") {
+        throw new Error(`Extension ${id} ${where} declares an empty "${field}" value`);
+      }
+    }
+  }
+  for (const glob of predicate.workspaceContains ?? []) {
+    if (glob.startsWith("/") || glob.split("/").includes("..")) {
+      throw new Error(
+        `Extension ${id} ${where} looks for "${glob}", which is not inside the worktree`
+      );
+    }
+  }
+  for (const agent of predicate.agent ?? []) {
+    if (!EXTENSION_AGENTS.includes(agent)) {
+      throw new Error(
+        `Extension ${id} ${where} names unknown agent ${JSON.stringify(agent)}; expected ${EXTENSION_AGENTS.join(", ")}`
+      );
+    }
+  }
+  for (const platform of predicate.platform ?? []) {
+    if (!EXTENSION_PLATFORMS.includes(platform)) {
+      throw new Error(
+        `Extension ${id} ${where} names unknown platform ${JSON.stringify(platform)}; expected ${EXTENSION_PLATFORMS.join(", ")}`
+      );
+    }
+  }
+}
+function assertPane(id, pane) {
+  assertIcon(`Extension ${id} pane ${pane.id}`, pane.icon);
+  const loose = pane;
+  const page2 = loose.web !== void 0;
+  const program = loose.command !== void 0;
+  if (page2 && program) {
+    throw new Error(`Extension ${id} pane ${pane.id} declares both a web page and a command`);
+  }
+  if (!page2 && !program) {
+    throw new Error(`Extension ${id} pane ${pane.id} declares neither a web page nor a command`);
+  }
+  if (page2) {
+    const web = loose.web;
+    if (typeof web !== "string" || !WEB_ENTRY_PATTERN.test(web) || web.split("/").includes("..")) {
+      throw new Error(
+        `Extension ${id} pane ${pane.id} declares the page ${JSON.stringify(web)}; a page is an .html file under web/ in the package`
+      );
+    }
+    return;
+  }
+  const command = loose.command;
+  if (!Array.isArray(command) || command.length === 0) {
+    throw new Error(`Extension ${id} pane ${pane.id} declares a command with nothing to run`);
+  }
+  for (const arg of command) {
+    if (typeof arg !== "string" || arg === "") {
+      throw new Error(`Extension ${id} pane ${pane.id} declares a command with an empty argument`);
+    }
+  }
+}
+function defineExtension(definition) {
+  assertIdentity("Extension", definition);
+  const id = definition.id;
+  const panes = definition.panes ?? [];
+  const footers = definition.footers ?? [];
+  const linkHandlers = definition.linkHandlers ?? [];
+  if (panes.length === 0 && footers.length === 0 && linkHandlers.length === 0) {
+    throw new Error(`Extension ${id} contributes nothing`);
+  }
+  const permissions = definition.permissions ?? [];
+  if (!Array.isArray(permissions)) {
+    throw new Error(`Extension ${id} declares permissions that are not a list`);
+  }
+  for (const permission of permissions) {
+    if (!EXTENSION_PERMISSIONS.includes(permission)) {
+      throw new Error(
+        `Extension ${id} asks for unknown permission ${JSON.stringify(permission)}; expected ${EXTENSION_PERMISSIONS.join(", ")}`
+      );
+    }
+  }
+  assertUnique("permission", permissions);
+  const contributions = [...panes, ...footers, ...linkHandlers];
+  for (const contribution of contributions) {
+    if (!KEY_PATTERN.test(contribution.id ?? "")) {
+      throw new Error(
+        `Contribution id "${contribution.id}" must start with a letter and be url-safe`
+      );
+    }
+    if (!contribution.title?.trim()) {
+      throw new Error(`Extension ${id} contribution ${contribution.id} is missing a title`);
+    }
+    assertPredicate(id, `contribution ${contribution.id}`, contribution.when);
+  }
+  assertUnique(
+    "contribution",
+    contributions.map((contribution) => contribution.id)
+  );
+  assertPredicate(id, "activates", definition.activates);
+  for (const pane of panes) assertPane(id, pane);
+  for (const footer of footers) {
+    if (typeof footer.run !== "function") {
+      throw new Error(`Extension ${id} footer ${footer.id} is missing a run() implementation`);
+    }
+    if (!Number.isFinite(footer.every) || footer.every < MIN_FOOTER_SECONDS) {
+      throw new Error(
+        `Extension ${id} footer ${footer.id} asks to run every ${footer.every}s; ${MIN_FOOTER_SECONDS}s is the shortest interval a footer may ask for`
+      );
+    }
+  }
+  for (const handler of linkHandlers) {
+    if (typeof handler.run !== "function") {
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} is missing a run() implementation`
+      );
+    }
+    if (typeof handler.pattern !== "string" || handler.pattern.length > MAX_PATTERN_LENGTH) {
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} has a pattern longer than ${MAX_PATTERN_LENGTH} characters; it is matched on every click`
+      );
+    }
+    if (hasNestedQuantifier(handler.pattern)) {
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} has a pattern that repeats a group which already repeats; matching it can take exponential time on a click`
+      );
+    }
+    let matcher;
+    try {
+      matcher = new RegExp(handler.pattern);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} has a pattern that is not a regular expression: ${reason}`,
+        { cause: error }
+      );
+    }
+    if (typeof handler.example !== "string" || handler.example.trim() === "") {
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} names no example link its pattern matches`
+      );
+    }
+    if (!matcher.test(handler.example)) {
+      throw new Error(
+        `Extension ${id} link handler ${handler.id} has the example ${JSON.stringify(handler.example)}, which its own pattern ${JSON.stringify(handler.pattern)} does not match`
+      );
+    }
+  }
+  return {
+    id,
+    name: definition.name,
+    ...definition.description !== void 0 && { description: definition.description },
+    ...definition.icon !== void 0 && { icon: definition.icon },
+    kind: "extension",
+    version: definition.version ?? "0.0.0",
+    // Its credential is the host's own token, so there is nothing to sign in to.
+    auth: { rung: "none" },
+    config: [],
+    triggers: [],
+    actions: [],
+    permissions,
+    ...definition.activates !== void 0 && { activates: definition.activates },
+    contributes: {
+      ...panes.length > 0 && { panes },
+      ...footers.length > 0 && { footers },
+      ...linkHandlers.length > 0 && { linkHandlers }
+    }
+  };
+}
 function resolveConfig(connector, env = process.env) {
   const config = {};
   const missing = [];
@@ -186,6 +439,12 @@ function resolveConfig(connector, env = process.env) {
 function pollToolName(triggerType) {
   return `poll_${triggerType}`;
 }
+function footerToolName(footerId) {
+  return `vorn_footer_${footerId}`;
+}
+function handlerToolName(handlerId) {
+  return `vorn_handler_${handlerId}`;
+}
 var MANIFEST_TOOL = "vorn_connector_manifest";
 var PREFLIGHT_TOOL = "vorn_connector_preflight";
 var OPTIONS_TOOL = "vorn_connector_options";
@@ -216,14 +475,49 @@ function connectionSetup(connector, triggerType) {
     }))
   };
 }
+function manifestContributions(connector) {
+  const contributes = connector.contributes;
+  if (!contributes) return void 0;
+  const shared = (contribution) => ({
+    id: contribution.id,
+    title: contribution.title,
+    ...contribution.description !== void 0 && { description: contribution.description },
+    ...contribution.when !== void 0 && { when: contribution.when }
+  });
+  return {
+    ...contributes.panes !== void 0 && {
+      panes: contributes.panes.map((pane) => ({
+        ...shared(pane),
+        ...pane.icon !== void 0 && { icon: pane.icon },
+        ...pane.web !== void 0 && { web: pane.web },
+        ...pane.command !== void 0 && { command: pane.command }
+      }))
+    },
+    ...contributes.footers !== void 0 && {
+      footers: contributes.footers.map((footer) => ({ ...shared(footer), every: footer.every }))
+    },
+    ...contributes.linkHandlers !== void 0 && {
+      linkHandlers: contributes.linkHandlers.map((handler) => ({
+        ...shared(handler),
+        pattern: handler.pattern,
+        example: handler.example
+      }))
+    }
+  };
+}
 function connectorManifest(connector) {
+  const contributes = manifestContributions(connector);
   return {
     id: connector.id,
     name: connector.name,
     version: connector.version,
+    kind: connector.kind,
     ...connector.description !== void 0 && { description: connector.description },
     ...connector.icon !== void 0 && { icon: connector.icon },
     ...connector.auth !== void 0 && { auth: connector.auth },
+    ...contributes !== void 0 && { contributes },
+    ...connector.permissions !== void 0 && { permissions: connector.permissions },
+    ...connector.activates !== void 0 && { activates: connector.activates },
     triggers: connector.triggers.map((trigger) => ({
       type: trigger.type,
       label: trigger.label,
@@ -256,11 +550,12 @@ function connectorManifest(connector) {
 
 // src/packaging.ts
 import { builtinModules } from "module";
-import { readFileSync } from "fs";
-import { mkdtemp, writeFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { cp, mkdtemp, readdir, stat, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname, isAbsolute, join, resolve } from "path";
 var MAX_PACK_BYTES = 8 * 1024 * 1024;
+var MAX_UNPACKED_BYTES = 32 * 1024 * 1024;
 var LIFECYCLE_SCRIPTS = [
   "preinstall",
   "install",
@@ -434,6 +729,15 @@ function readNearestPackageJson(fromDir) {
     }
   }
 }
+function packageRootFor(fromDir) {
+  let current = resolve(fromDir);
+  for (; ; ) {
+    if (existsSync(join(current, "package.json"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(fromDir);
+    current = parent;
+  }
+}
 function packEntryContents(entry, sdkModule = "@vornrun/connector-sdk") {
   return [
     `import { serveConnector } from ${JSON.stringify(sdkModule)}`,
@@ -444,7 +748,20 @@ function packEntryContents(entry, sdkModule = "@vornrun/connector-sdk") {
     ""
   ].join("\n");
 }
-async function stagePack(connector, code) {
+var WEB_DIR = "web";
+async function directoryBytes(dir) {
+  let total = 0;
+  for (const entry of await readdir(dir, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    total += (await stat(join(entry.parentPath, entry.name))).size;
+  }
+  return total;
+}
+function webDirectories(connector) {
+  const dirs = (connector.contributes?.panes ?? []).map((pane) => pane.web).filter((web) => web !== void 0).map((web) => dirname(web));
+  return [...new Set(dirs)];
+}
+async function stagePack(connector, code, packageRoot) {
   const dir = await mkdtemp(join(tmpdir(), "vorn-pack-"));
   await writeFile(join(dir, "index.js"), code, "utf8");
   await writeFile(
@@ -453,6 +770,12 @@ async function stagePack(connector, code) {
 `,
     "utf8"
   );
+  if (packageRoot !== void 0) {
+    for (const relative of webDirectories(connector)) {
+      const from = join(packageRoot, relative);
+      if (existsSync(from)) await cp(from, join(dir, relative), { recursive: true });
+    }
+  }
   return dir;
 }
 var LAUNCH_TIMEOUT_MS = 15e3;
@@ -570,6 +893,81 @@ async function esbuildBundle(request) {
   };
 }
 
+// src/host.ts
+var HOST_URL_ENV = "VORN_EXTENSION_HOST";
+var HOST_TOKEN_ENV = "VORN_EXTENSION_TOKEN";
+var PermissionDeniedError = class extends Error {
+  constructor(method, detail) {
+    super(`The host refused ${method}: ${detail}`);
+    this.name = "PermissionDeniedError";
+  }
+};
+var HostReplyError = class extends Error {
+  constructor(method, detail) {
+    super(`The host answered ${method} with ${detail}`);
+    this.name = "HostReplyError";
+  }
+};
+var HOST_TIMEOUT_MS = 15e3;
+var LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "[::1]"];
+function endpoint(env) {
+  const url = env[HOST_URL_ENV]?.trim();
+  const token = env[HOST_TOKEN_ENV]?.trim();
+  if (!url || !token) {
+    throw new Error(
+      `This extension was started without a host bridge; ${HOST_URL_ENV} and ${HOST_TOKEN_ENV} are set by Vorn`
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`${HOST_URL_ENV} is ${JSON.stringify(url)}, which is not a URL`);
+  }
+  if (parsed.protocol !== "http:" || !LOOPBACK_HOSTS.includes(parsed.hostname)) {
+    throw new Error(
+      `${HOST_URL_ENV} is ${JSON.stringify(url)}; the bridge is served on this machine, over http on ${LOOPBACK_HOSTS.join(", ")}`
+    );
+  }
+  return { url: url.replace(/\/$/, ""), token };
+}
+function createExtensionHost(options) {
+  const env = options.env ?? process.env;
+  const call = options.fetchImpl ?? fetch;
+  async function ask(method, params) {
+    const { url, token } = endpoint(env);
+    const response = await call(`${url}/${method}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ sessionId: options.sessionId, ...params }),
+      signal: AbortSignal.timeout(HOST_TIMEOUT_MS)
+    });
+    const text = await response.text();
+    if (response.status === 403) throw new PermissionDeniedError(method, text || "not granted");
+    if (!response.ok) throw new Error(`The host answered ${method} with HTTP ${response.status}`);
+    if (text === "") return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new HostReplyError(method, "a body that is not JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || !("result" in parsed)) {
+      throw new HostReplyError(method, "a body carrying no result");
+    }
+    return parsed.result;
+  }
+  return {
+    diff: () => ask("diff", {}),
+    status: () => ask("status", {}),
+    output: (opts) => ask("output", { ...opts?.lines !== void 0 && { lines: opts.lines } }),
+    selection: () => ask("selection", {}),
+    send: (text) => ask("send", { text }),
+    rename: (name) => ask("rename", { name }),
+    usage: () => ask("usage", {})
+  };
+}
+
 // src/normalize.ts
 var RESERVED_KEYS = [
   "externalId",
@@ -1024,8 +1422,8 @@ var DEFAULT_BASE_DELAY_MS = 250;
 var DEFAULT_MAX_DELAY_MS = 3e4;
 var MAX_ATTEMPTS = 10;
 var MAX_TOTAL_WAIT_MS = 12e4;
-var wait = (ms) => new Promise((resolve3) => {
-  setTimeout(resolve3, ms);
+var wait = (ms) => new Promise((resolve4) => {
+  setTimeout(resolve4, ms);
 });
 function retryAfterMs(header, now) {
   if (!header) return void 0;
@@ -1327,9 +1725,44 @@ function createConnectorHarness(connector, harnessOptions = {}) {
     withMockHttp
   };
 }
+var HOST_FIXTURES = {
+  diff: async () => "diff --git a/src/index.ts b/src/index.ts\n@@ -1 +1 @@\n-const a = 1\n+const a = 2\n",
+  status: async () => " M src/index.ts\n",
+  output: async () => "$ yarn test\n  Test Files  1 passed (1)\n",
+  selection: async () => "",
+  send: async () => {
+  },
+  rename: async () => {
+  },
+  usage: async () => ({
+    contextTokens: 13e4,
+    contextWindow: 1e6,
+    cacheHitRate: 0.93,
+    limits: [{ window: "5h", remaining: 0.72 }]
+  })
+};
+function mockExtensionHost(granted, answers = {}) {
+  const allowed = new Set(granted);
+  const used = /* @__PURE__ */ new Set();
+  const host = {};
+  for (const name of Object.keys(HOST_FIXTURES)) {
+    const permission = HOST_PERMISSIONS[name];
+    host[name] = async (...args) => {
+      used.add(permission);
+      if (!allowed.has(permission)) {
+        throw new PermissionDeniedError(name, `this extension does not ask for ${permission}`);
+      }
+      const answer = answers[name] ?? HOST_FIXTURES[name];
+      return answer(...args);
+    };
+  }
+  return { host, used };
+}
 
 // src/check.ts
+import { existsSync as existsSync2 } from "fs";
 import { rm } from "fs/promises";
+import { resolve as resolve2, sep } from "path";
 var EXECUTABLE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 var CREDENTIAL_NAME = /(secret|token|password|passphrase|api[-_]?key|credential)/i;
 var INPUT_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "select", "json"]);
@@ -1429,6 +1862,10 @@ function bundles(options) {
 function launches(options) {
   return bundles(options) && options.mock === true;
 }
+function packageRootOf(options) {
+  if (options.packageDir === void 0) return void 0;
+  return packageRootFor(packageDirFor(options.packageDir, options.entry));
+}
 async function packageFindings(connector, options) {
   if (options.packageDir === void 0) return [];
   const pkg = readNearestPackageJson(packageDirFor(options.packageDir, options.entry));
@@ -1452,7 +1889,7 @@ async function packageFindings(connector, options) {
     });
     found.push(...bundleDependencyFindings(built.external), ...bundledRequireFindings(built.code));
     if (options.mock) {
-      const dir = await stagePack(connector, built.code);
+      const dir = await stagePack(connector, built.code, packageRootOf(options));
       try {
         found.push(...await packLaunchFindings(dir));
       } finally {
@@ -1523,6 +1960,153 @@ async function mockFindings(connector, options) {
   }
   return found;
 }
+var CHECK_SESSION = {
+  sessionId: "check",
+  worktreePath: process.cwd(),
+  agent: "claude"
+};
+var FOOTER_TONES = ["default", "ok", "danger"];
+var FOOTER_HREF_PROTOCOLS = ["http:", "https:"];
+function invalidItem(item) {
+  if (!item || typeof item !== "object") return "is not an object";
+  const reading = item;
+  if (typeof reading.label !== "string" || reading.label === "") return "has no label";
+  if (typeof reading.value !== "string") return "has no value";
+  if (reading.tone !== void 0 && !FOOTER_TONES.includes(reading.tone)) {
+    return `has unknown tone ${JSON.stringify(reading.tone)}`;
+  }
+  if (reading.href === void 0) return void 0;
+  if (typeof reading.href !== "string") return "has a link that is not text";
+  let protocol;
+  try {
+    protocol = new URL(reading.href).protocol;
+  } catch {
+    return `has the link ${JSON.stringify(reading.href)}, which is not a URL`;
+  }
+  if (!FOOTER_HREF_PROTOCOLS.includes(protocol)) {
+    return `has the link ${JSON.stringify(reading.href)}; a reading links to ${FOOTER_HREF_PROTOCOLS.join(" or ")} and nothing else`;
+  }
+  return void 0;
+}
+async function contributionFindings(connector) {
+  const contributes = connector.contributes;
+  if (!contributes) return [];
+  const found = [];
+  const declared = connector.permissions ?? [];
+  const spent = /* @__PURE__ */ new Set();
+  const ran = async (kind, id, code, body) => {
+    const { host, used } = mockExtensionHost(declared);
+    try {
+      return await body(host);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      found.push(
+        finding2(
+          "error",
+          error instanceof PermissionDeniedError ? "permission-undeclared" : code,
+          `${kind} ${id}`,
+          error instanceof PermissionDeniedError ? `asked the host for something this extension does not declare: ${reason}` : `threw: ${reason}`
+        )
+      );
+      return void 0;
+    } finally {
+      for (const permission of used) spent.add(permission);
+    }
+  };
+  for (const footer of contributes.footers ?? []) {
+    const items = await ran(
+      "footer",
+      footer.id,
+      "footer-failed",
+      (host) => Promise.resolve(footer.run({ ...CHECK_SESSION, host, now: () => (/* @__PURE__ */ new Date()).toISOString() }))
+    );
+    if (items === void 0) continue;
+    if (!Array.isArray(items)) {
+      found.push(
+        finding2(
+          "error",
+          "footer-items-invalid",
+          `footer ${footer.id}`,
+          "returned something that is not a list of readings"
+        )
+      );
+      continue;
+    }
+    for (const item of items) {
+      const wrong = invalidItem(item);
+      if (wrong) {
+        found.push(
+          finding2(
+            "error",
+            "footer-items-invalid",
+            `footer ${footer.id}`,
+            `returned a reading that ${wrong}`
+          )
+        );
+      }
+    }
+  }
+  for (const handler of contributes.linkHandlers ?? []) {
+    await ran(
+      "link handler",
+      handler.id,
+      "handler-failed",
+      (host) => Promise.resolve(
+        handler.run({
+          ...CHECK_SESSION,
+          host,
+          now: () => (/* @__PURE__ */ new Date()).toISOString(),
+          url: handler.example
+        })
+      )
+    );
+  }
+  const observable = !(contributes.panes ?? []).some((pane) => pane.web !== void 0);
+  for (const permission of declared) {
+    if (observable && !spent.has(permission)) {
+      found.push(
+        finding2(
+          "warn",
+          "permission-unused",
+          `${connector.id} permissions`,
+          `asks for ${permission} but nothing this run exercised used it; ask only for what it spends`
+        )
+      );
+    }
+  }
+  return found;
+}
+function paneFindings(connector, packageRoot) {
+  if (packageRoot === void 0) return [];
+  const root = resolve2(packageRoot);
+  const found = [];
+  for (const pane of connector.contributes?.panes ?? []) {
+    if (pane.web === void 0) continue;
+    const full = resolve2(root, pane.web);
+    if (full !== root && !full.startsWith(`${root}${sep}`)) {
+      found.push(
+        finding2(
+          "error",
+          "web-entry-outside-package",
+          `pane ${pane.id}`,
+          `declares the page "${pane.web}", which resolves outside the package`
+        )
+      );
+      continue;
+    }
+    if (!existsSync2(full)) {
+      found.push(
+        finding2(
+          "error",
+          "web-entry-missing",
+          `pane ${pane.id}`,
+          `declares the page "${pane.web}", which the package does not carry`
+        )
+      );
+    }
+  }
+  return found;
+}
 var AUTH_FAILURE = /\b(401|403|unauthor|unauthenticat|forbidden|invalid[- ]?(token|credential))/i;
 function liveRunnable(action) {
   if (action.idempotent !== true) return false;
@@ -1651,8 +2235,10 @@ async function checkConnector(connector, options = {}) {
       )
     );
   }
-  found.push(...authFindings(connector));
+  if (connector.kind !== "extension") found.push(...authFindings(connector));
   found.push(...secretFindings(connector));
+  found.push(...paneFindings(connector, packageRootOf(options)));
+  found.push(...await contributionFindings(connector));
   found.push(...await packageFindings(connector, options));
   found.push(...await mockFindings(connector, options));
   found.push(...await liveFindings(connector, options));
@@ -1750,10 +2336,23 @@ var CHECK_OWNERS = {
   "mock-not-observed": "mock",
   "preflight-failed": "live",
   "live-action-failed": "live",
-  "pack-launch": "launch"
+  "pack-launch": "launch",
+  "web-entry-missing": "contributes",
+  "web-entry-outside-package": "contributes",
+  "footer-failed": "footers",
+  "footer-items-invalid": "footers",
+  "handler-failed": "handlers",
+  "permission-undeclared": "permissions",
+  "permission-unused": "permissions"
 };
 function checksRun(connector, options) {
-  const names = ["manifest", "auth"];
+  const names = ["manifest"];
+  if (connector.kind !== "extension") names.push("auth");
+  const contributes = connector.contributes;
+  if (contributes?.panes?.length && options.packageDir !== void 0) names.push("contributes");
+  if (contributes?.footers?.length) names.push("footers");
+  if (contributes?.linkHandlers?.length) names.push("handlers");
+  if (connector.permissions !== void 0) names.push("permissions");
   if (connector.config.length > 0) names.push("secrets");
   if (connector.actions.length > 0) names.push("actions");
   if (connector.triggers.length > 0) names.push("dedupe");
@@ -1790,8 +2389,9 @@ function formatFindings(findings) {
 }
 
 // src/pack.ts
-import { mkdir, rm as rm2, stat } from "fs/promises";
-import { join as join2, resolve as resolve2 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { mkdir, rm as rm2, stat as stat2 } from "fs/promises";
+import { join as join2, resolve as resolve3 } from "path";
 function finding3(code, target, message) {
   return { level: "error", code, target, message };
 }
@@ -1799,9 +2399,10 @@ function packFileName(connector) {
   return `${connector.id}-${connector.version}.vorn.tgz`;
 }
 async function packConnector(connector, options) {
-  const resolveDir = resolve2(options.resolveDir ?? process.cwd());
+  const resolveDir = resolve3(options.resolveDir ?? process.cwd());
   const entryDir = packageDirFor(resolveDir, options.entry);
-  const findings = await checkConnector(connector);
+  const packageRoot = packageRootFor(entryDir);
+  const findings = await checkConnector(connector, { packageDir: packageRoot });
   findings.push(...lifecycleScriptFindings(readNearestPackageJson(entryDir)));
   if (findings.some((item) => item.level === "error")) return { findings };
   const contents = packEntryContents(options.entry, options.sdkModule);
@@ -1809,19 +2410,37 @@ async function packConnector(connector, options) {
   const built = await bundle({ contents, resolveDir });
   findings.push(...bundleDependencyFindings(built.external), ...bundledRequireFindings(built.code));
   if (findings.some((item) => item.level === "error")) return { findings };
-  const outDir = resolve2(options.outDir ?? process.cwd());
+  const outDir = resolve3(options.outDir ?? process.cwd());
   await mkdir(outDir, { recursive: true });
   const file = join2(outDir, packFileName(connector));
-  const staging = await stagePack(connector, built.code);
+  const staging = await stagePack(connector, built.code, packageRoot);
   try {
     findings.push(...await (options.launch ?? packLaunchFindings)(staging));
     if (findings.some((item) => item.level === "error")) return { findings };
+    const unpacked = await directoryBytes(staging);
+    const maxUnpacked = options.maxUnpackedBytes ?? MAX_UNPACKED_BYTES;
+    if (unpacked > maxUnpacked) {
+      return {
+        findings: [
+          ...findings,
+          finding3(
+            "pack-too-large",
+            "bundle",
+            `The pack unpacks to ${Math.round(unpacked / 1024)} KB; Vorn unpacks at most ${Math.round(maxUnpacked / 1024)} KB`
+          )
+        ]
+      };
+    }
     const { create } = await import("tar");
-    await create({ gzip: true, file, cwd: staging }, ["manifest.json", "index.js"]);
+    await create({ gzip: true, file, cwd: staging }, [
+      "manifest.json",
+      "index.js",
+      ...existsSync3(join2(staging, WEB_DIR)) ? [WEB_DIR] : []
+    ]);
   } finally {
     await rm2(staging, { recursive: true, force: true });
   }
-  const bytes = (await stat(file)).size;
+  const bytes = (await stat2(file)).size;
   const maxBytes = options.maxBytes ?? MAX_PACK_BYTES;
   if (bytes > maxBytes) {
     await rm2(file, { force: true });
@@ -1841,7 +2460,7 @@ async function packConnector(connector, options) {
 
 // src/scaffold.ts
 var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-var SDK_DEPENDENCY_RANGE = "^0.7.0-beta.9";
+var SDK_DEPENDENCY_RANGE = "^0.7.0-beta.14";
 var SCAFFOLD_VERSION = "0.1.0";
 var VITEST_RANGE = "^4.1.10";
 function jsonFile(value) {
@@ -1851,17 +2470,24 @@ function jsonFile(value) {
 function titleCase(id) {
   return id.split(/[-_]+/).filter((part) => part !== "").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 }
-function packageJson(id, description, inRepo) {
+function packageJson(id, description, inRepo, kind) {
+  const scoped = kind === "extension" ? "extension" : "connector";
   return jsonFile({
-    name: inRepo ? `@vornrun/connector-${id}` : `vorn-connector-${id}`,
+    name: inRepo ? `@vornrun/${scoped}-${id}` : `vorn-${scoped}-${id}`,
     version: SCAFFOLD_VERSION,
     description,
     type: "module",
     license: "MIT",
-    bin: { [`vorn-connector-${id}`]: "dist/index.js" },
+    bin: { [`vorn-${scoped}-${id}`]: "dist/index.js" },
     main: "./dist/index.js",
     types: "./dist/index.d.ts",
-    files: ["dist", "README.md", ...inRepo ? ["CHANGELOG.md"] : []],
+    // A pane's page ships beside the bundle, so `web` is published like `dist`.
+    files: [
+      "dist",
+      "README.md",
+      ...kind === "extension" ? ["web"] : [],
+      ...inRepo ? ["CHANGELOG.md"] : []
+    ],
     ...inRepo && {
       repository: {
         type: "git",
@@ -1884,11 +2510,12 @@ function packageJson(id, description, inRepo) {
       typescript: "^6.0.3",
       vitest: VITEST_RANGE
     },
-    // Read by the catalog build: how this connector is filed, found, and what it asks of you.
+    // Read by the catalog build: how this is filed, found, and what it asks of you.
     vorn: {
-      category: "Other",
+      category: kind === "extension" ? "Extensions" : "Other",
       keywords: [id],
-      ...inRepo && { auth: "Say in one line what signing in takes." }
+      ...kind === "extension" && { kind: "extension" },
+      ...inRepo && kind === "connector" && { auth: "Say in one line what signing in takes." }
     }
   });
 }
@@ -2010,11 +2637,149 @@ export const connector = defineConnector({
 })
 `;
 }
-function entrySource() {
+function extensionSource(id, name, description) {
+  return `import { defineExtension } from '@vornrun/connector-sdk'
+// Bundled at build time: a pack is one file, so a version read from disk is not there to read.
+import pkg from '../package.json'
+
+export const connector = defineExtension({
+  id: ${JSON.stringify(id)},
+  name: ${JSON.stringify(name)},
+  description: ${JSON.stringify(description)},
+  version: pkg.version,
+  // Only what this actually spends: the check names one it declared and never used.
+  permissions: ['terminal.read'],
+  // Absent where none of these hold, rather than showing a band with nothing in it.
+  activates: { workspaceContains: ['package.json'] },
+  footers: [
+    {
+      id: 'checks',
+      title: 'Checks',
+      description: 'What the last commands in this session said',
+      every: 30,
+      async run(context) {
+        const output = await context.host.output({ lines: 200 })
+        const failed = /\\b(FAIL|failed|error)\\b/i.test(output)
+        return [
+          {
+            label: 'tests',
+            value: failed ? 'failing' : 'passing',
+            tone: failed ? 'danger' : 'ok'
+          }
+        ]
+      }
+    }
+  ],
+  panes: [
+    {
+      id: 'report',
+      title: 'Report',
+      description: 'The reading, in full, beside the terminal',
+      // Drawn beside the pane's name wherever it is offered; path data only.
+      icon: { viewBox: '0 0 24 24', paths: ['M4 4h16v16H4z M8 9h8 M8 13h8 M8 17h5'] },
+      // Served from the pack; everything the page needs lives under web/.
+      web: 'web/report/index.html'
+    }
+  ]
+})
+`;
+}
+function extensionPage(name) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${name}</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 12px;
+        font: 12px ui-sans-serif, system-ui, sans-serif;
+        color: #faf9f7;
+        background: #101012;
+      }
+      h1 {
+        font-size: 13px;
+        font-weight: 500;
+        margin: 0 0 8px;
+      }
+      pre {
+        margin: 0;
+        white-space: pre-wrap;
+        color: rgba(255, 255, 255, 0.55);
+      }
+    </style>
+  </head>
+  <body>
+    <h1>${name}</h1>
+    <pre id="output">Reading the session\u2026</pre>
+    <script type="module">
+      // Same origin, so the page carries no credential: Vorn knows which pane is
+      // asking and grants exactly the permissions the manifest declared.
+      const ask = async (method, body = {}) => {
+        const response = await fetch('bridge/' + method, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body)
+        })
+        if (!response.ok) throw new Error(method + ' answered ' + response.status)
+        return (await response.json()).result
+      }
+
+      const node = document.getElementById('output')
+      try {
+        node.textContent = await ask('output', { lines: 200 })
+      } catch (error) {
+        node.textContent = String(error)
+      }
+    </script>
+  </body>
+</html>
+`;
+}
+function extensionTestSource(name) {
+  return `import { describe, expect, it } from 'vitest'
+import { mockExtensionHost } from '@vornrun/connector-sdk'
+import { connector } from './extension'
+
+/** Runs one footer the way the host will, against a stub that enforces the manifest. */
+async function footer(id: string, output: string) {
+  const { host } = mockExtensionHost(connector.permissions ?? [], { output: async () => output })
+  const declared = connector.contributes?.footers?.find((entry) => entry.id === id)
+  if (!declared) throw new Error('no footer ' + id)
+  return declared.run({
+    sessionId: 'test',
+    worktreePath: process.cwd(),
+    agent: 'claude',
+    host,
+    now: () => '2026-01-01T00:00:00.000Z'
+  })
+}
+
+describe(${JSON.stringify(name)}, () => {
+  it('reads the session as passing when nothing failed', async () => {
+    expect(await footer('checks', 'Test Files  1 passed (1)')).toEqual([
+      { label: 'tests', value: 'passing', tone: 'ok' }
+    ])
+  })
+
+  it('reads it as failing when the output says so', async () => {
+    expect(await footer('checks', 'FAIL src/index.test.ts')).toEqual([
+      { label: 'tests', value: 'failing', tone: 'danger' }
+    ])
+  })
+
+  it('asks for nothing it did not declare', () => {
+    expect(connector.permissions).toEqual(['terminal.read'])
+  })
+})
+`;
+}
+function entrySource(module) {
   return `import { realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { serveConnector } from '@vornrun/connector-sdk'
-import { connector } from './connector'
+import { connector } from './${module}'
 
 /** True when this file was run directly rather than imported. */
 export function isEntryPoint(moduleUrl: string, argv = process.argv): boolean {
@@ -2082,8 +2847,8 @@ describe('the packaged connector', () => {
 })
 `;
 }
-function indexSource() {
-  return `import { connector } from './connector'
+function indexSource(module) {
+  return `import { connector } from './${module}'
 import { serveIfEntryPoint } from './entry'
 
 export { connector }
@@ -2188,21 +2953,67 @@ Rename the trigger, the action and the settings to whatever this connector
 really talks to; the shapes here are a starting point, not a rule.
 `;
 }
+function extensionReadme(id, name, description) {
+  return `# ${name}
+
+${description}
+
+## Build and check
+
+\`\`\`sh
+yarn install
+yarn build
+yarn check      # verifies the extension against Vorn's contract
+yarn test
+yarn pack       # writes ${id}-${SCAFFOLD_VERSION}.vorn.tgz, installable in Vorn
+\`\`\`
+
+## What it contributes
+
+| Kind | Name | What it does |
+| --- | --- | --- |
+| Footer | Checks | A band under the card's status bar, recomputed every 30s |
+| Pane | Report | A page beside the terminal, served from \`web/report\` |
+
+## What it asks for
+
+| Permission | What it grants |
+| --- | --- |
+| \`terminal.read\` | The session's recent terminal output |
+
+Ask for only what the extension spends: \`check\` names a permission that was
+declared and never used.
+
+## Where it shows
+
+Sessions whose worktree has a \`package.json\`. Widen or narrow that in
+\`activates\`, and narrow one contribution further with its own \`when\`.
+`;
+}
 function scaffoldFiles(options) {
+  const kind = options.kind ?? "connector";
   if (!ID_PATTERN.test(options.id ?? "")) {
-    throw new Error(`Connector id "${options.id}" must start with a letter and be url-safe`);
+    throw new Error(
+      `${kind === "extension" ? "Extension" : "Connector"} id "${options.id}" must start with a letter and be url-safe`
+    );
   }
   const name = options.name?.trim() || titleCase(options.id);
-  const description = options.description?.trim() || `${name} connector for Vorn`;
+  const description = options.description?.trim() || `${name} ${kind} for Vorn`;
   const inRepo = options.repoConventions ?? false;
+  const module = kind === "extension" ? "extension" : "connector";
   return [
-    { path: "package.json", contents: packageJson(options.id, description, inRepo) },
-    { path: "src/connector.ts", contents: connectorSource(options.id, name, description) },
-    { path: "src/entry.ts", contents: entrySource() },
-    { path: "src/index.ts", contents: indexSource() },
-    { path: "src/connector.test.ts", contents: testSource(name) },
+    { path: "package.json", contents: packageJson(options.id, description, inRepo, kind) },
+    kind === "extension" ? { path: "src/extension.ts", contents: extensionSource(options.id, name, description) } : { path: "src/connector.ts", contents: connectorSource(options.id, name, description) },
+    { path: "src/entry.ts", contents: entrySource(module) },
+    { path: "src/index.ts", contents: indexSource(module) },
+    kind === "extension" ? { path: "src/extension.test.ts", contents: extensionTestSource(name) } : { path: "src/connector.test.ts", contents: testSource(name) },
     { path: "src/entry.test.ts", contents: entryTestSource() },
-    { path: "README.md", contents: readme(options.id, name, description) },
+    // The page a pane is drawn from, carried into the pack as it stands here.
+    ...kind === "extension" ? [{ path: "web/report/index.html", contents: extensionPage(name) }] : [],
+    {
+      path: "README.md",
+      contents: kind === "extension" ? extensionReadme(options.id, name, description) : readme(options.id, name, description)
+    },
     // Everywhere: the generated source imports its package.json, which needs resolveJsonModule to compile.
     { path: "tsconfig.json", contents: tsconfig(inRepo) },
     ...inRepo ? [
@@ -2369,6 +3180,67 @@ function createConnectorServer(connector, options = {}) {
       }
     );
   }
+  const sessionShape = {
+    sessionId: z.string().describe("The session this is being computed for"),
+    worktreePath: z.string().describe("Where the session's work is"),
+    agent: z.enum(EXTENSION_AGENTS).describe("Which agent runs in the session")
+  };
+  const sessionContext = (args, host) => ({
+    sessionId: args.sessionId,
+    worktreePath: args.worktreePath,
+    agent: args.agent,
+    host,
+    now: options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString())
+  });
+  const hostFor = (sessionId) => options.host?.(sessionId) ?? createExtensionHost({ sessionId });
+  for (const footer of connector.contributes?.footers ?? []) {
+    server.registerTool(
+      footerToolName(footer.id),
+      {
+        title: footer.title,
+        description: footer.description ?? `Recompute ${footer.title} for one session`,
+        inputSchema: sessionShape,
+        outputSchema: z.looseObject({
+          items: z.array(z.looseObject({ label: z.string(), value: z.string() })).describe("The readings to show in the band")
+        })
+      },
+      async (args) => {
+        try {
+          const items = await footer.run(sessionContext(args, hostFor(args.sessionId)));
+          return json({ items });
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  for (const handler of connector.contributes?.linkHandlers ?? []) {
+    server.registerTool(
+      handlerToolName(handler.id),
+      {
+        title: handler.title,
+        description: handler.description ?? `Open ${handler.title} for a clicked link`,
+        inputSchema: {
+          ...sessionShape,
+          url: z.string().describe("The clicked text, which matched this handler")
+        },
+        outputSchema: z.looseObject({
+          openPane: z.string().optional().describe("Id of one of this extension's panes to open")
+        })
+      },
+      async (args) => {
+        try {
+          const handled = await handler.run({
+            ...sessionContext(args, hostFor(args.sessionId)),
+            url: args.url
+          });
+          return json({ ...handled ?? {} });
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
   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.";
@@ -2403,10 +3275,15 @@ async function serveConnector(connector, options = {}) {
 }
 
 export {
+  EXTENSION_PERMISSIONS,
+  HOST_PERMISSIONS,
   envNameFor,
   defineConnector,
+  defineExtension,
   resolveConfig,
   pollToolName,
+  footerToolName,
+  handlerToolName,
   MANIFEST_TOOL,
   PREFLIGHT_TOOL,
   OPTIONS_TOOL,
@@ -2418,6 +3295,10 @@ export {
   bundledRequireFindings,
   readNearestPackageJson,
   esbuildBundle,
+  HOST_URL_ENV,
+  HOST_TOKEN_ENV,
+  PermissionDeniedError,
+  createExtensionHost,
   normalizeItem,
   normalizeItems,
   pollWithDedupe,
@@ -2441,6 +3322,7 @@ export {
   escapedMockHttp,
   withMockHttp,
   createConnectorHarness,
+  mockExtensionHost,
   checkConnector,
   CHECK_OWNERS,
   runConformance,