@standardagents/code-plugin-sdk 0.0.0-stub.0 → 1.0.0-alpha.0

package/README.md

@@ -1,4 +1,91 @@
-# @standardagents/code-plugin-sdk
+# Standard Code plugin SDK
 
-This version is a placeholder that reserves the package name. It contains no
-code. Use a later version to author Standard Code plugins.
+`@standardagents/code-plugin-sdk` is the authoring package for Standard Code
+plugins. Standard Code bundles the SDK runtime into its signed release. The
+manifest `apiVersion` gates compatibility between a plugin and the product.
+
+A plugin exports `definePlugin({ id, activate })` as its default export.
+Its `package.json` includes a static `standardPlugin` manifest.
+
+```json
+{
+  "name": "example-status",
+  "type": "module",
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
+  "standardPlugin": {
+    "apiVersion": 1,
+    "id": "example-status",
+    "name": "Example status",
+    "version": "0.1.0",
+    "entry": "./index.ts",
+    "capabilities": ["surfaces"],
+    "contributions": [{ "id": "status", "kind": "section", "anchor": "plugins" }]
+  }
+}
+```
+
+```ts
+import { definePlugin } from '@standardagents/code-plugin-sdk'
+
+export default definePlugin({
+  id: 'example-status',
+  activate(ctx) {
+    const section = ctx.section('status')
+    section.replace({ kind: 'rows', rows: [{ id: 'ready', spans: [{ text: 'Ready' }] }] })
+  },
+})
+```
+
+The SDK is a peer dependency. Inside Standard Code the exact specifier
+`@standardagents/code-plugin-sdk` resolves to the bundled copy, so a plugin
+never loads a second runtime from `node_modules`. Subpath imports of the SDK
+package, such as `@standardagents/code-plugin-sdk/testing`, are refused when
+the plugin runs inside Standard Code. The `testing` export serves the
+plugin's own test suite.
+
+The runtime disposes publishers, subscriptions, schedules and pending requests.
+Plugins register additional cleanup through `ctx.onDispose` or an activation return value.
+Handlers receive an abort signal.
+Schedules allow one invocation at a time.
+
+Capabilities control SDK and daemon operations.
+Plugins retain Node access to files, networking and subprocesses under the user's identity.
+Worker threads provide JavaScript fault isolation.
+Memory exhaustion outside V8 limits and native crashes can affect the runner process.
+
+## Testing
+
+`@standardagents/code-plugin-sdk/testing` exports `createHarness`.
+It uses explicit fixture handlers and a manual clock.
+`activate`, `emit`, `visibility`, `advance`, `flush` and `dispose` drive its runtime.
+`trace`, `surfaces`, `subscriptions` and `resources` expose recorded behavior.
+`drainTrace` clears the bounded trace.
+The harness starts no subprocesses.
+
+## Supported interface
+
+The public interface is the package's default export, its `testing` export,
+and the declarations in `src/index.d.ts` and `src/testing.d.ts`.
+
+The harness records the frames that the SDK runtime exchanges with its host,
+and `harness.receive` accepts such a frame. That wire protocol between the
+SDK runtime and the Standard Code plugin runner is visible through the
+testing helpers, and it is not a supported public interface. Its frame
+shapes, operation names, limits and version can change in any release
+without notice. Plugin code and plugin tests should treat recorded frames as
+opaque values and drive the plugin through `PluginContext` and the harness
+methods.
+
+Local `ctx.state` belongs to one machine.
+The public context declarations are in `src/index.d.ts`.
+
+## Releases
+
+The Standard Code build workflow publishes this package when the version in
+`package.json` changes. Prereleases publish under the `next` dist-tag and
+releases under `latest`.
+
+## License
+
+MIT. See `LICENSE`.

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "0.0.0-stub.0",
-  "description": "Placeholder that reserves the Standard Code plugin SDK name. Real releases follow.",
+  "version": "1.0.0-alpha.0",
+  "type": "module",
+  "description": "Standard Code plugin authoring SDK",
   "license": "MIT",
-  "files": ["README.md", "LICENSE"],
-  "publishConfig": { "access": "public" }
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/standardagents/code-rs.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20" },
+  "exports": {
+    ".": { "types": "./src/index.d.ts", "import": "./src/index.mjs" },
+    "./testing": { "types": "./src/testing.d.ts", "import": "./src/testing.mjs" }
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/index.d.ts

@@ -0,0 +1,264 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type Capability = 'surfaces' | 'events' | 'hooks' | 'panes' | 'projects' |
+  'notifications' | 'url' | 'fetch' | 'secrets' | 'webhook';
+export type SurfaceKind = 'section' | 'slot' | 'badge' | 'panel' | 'overlay' |
+  'menu' | 'command' | 'key' | 'link';
+export type MenuPosition = 'top' | 'after-open' | 'before-danger' | 'bottom';
+export type Anchor = 'plugins' | 'machine.before' | 'machine.after' |
+  'project.before' | 'project.after' | 'pane.header' | 'pane.footer' |
+  'account' | 'machine' | 'project' | 'pane' | 'section';
+export interface ContributionDeclaration {
+  id: string;
+  kind: SurfaceKind;
+  anchor: Anchor;
+  title?: string;
+  merge?: 'by-machine' | 'by-identity';
+  width?: 'full' | 'half';
+  position?: MenuPosition;
+  group?: string;
+  chord?: string;
+  pattern?: string;
+  actionId?: string;
+}
+/** The package.json standardPlugin field is read before any plugin code runs. */
+export interface PluginManifest {
+  apiVersion: 1;
+  id: string;
+  name: string;
+  version: string;
+  entry: string;
+  singleton: boolean;
+  order: number;
+  capabilities: Capability[];
+  contributions: ContributionDeclaration[];
+  configSchema?: { [key: string]: Json };
+  hookTimeoutMs: number;
+}
+export type ManifestInput = Pick<PluginManifest, 'apiVersion' | 'id' | 'name' | 'version' | 'entry'> &
+  Partial<Omit<PluginManifest, 'apiVersion' | 'id' | 'name' | 'version' | 'entry'>>;
+export interface EntityRef {
+  kind: 'account' | 'machine' | 'project' | 'pane' | 'section';
+  id: string;
+  machineId?: string;
+  /** Decimal strings preserve 64-bit unsigned values across the JSON boundary. */
+  generation?: string;
+}
+export interface Producer {
+  pluginId: string;
+  machineId: string;
+  epoch: string;
+}
+export interface ContributionKey {
+  contributionId: string;
+  anchor: Anchor;
+  entity?: EntityRef;
+}
+export interface TextSpan {
+  text: string;
+  foreground?: string;
+  background?: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  actionId?: string;
+}
+export interface NativeRow {
+  id: string;
+  identity?: string;
+  providerRevision?: string;
+  spans: TextSpan[];
+  actionId?: string;
+  meter?: { value: number; max: number; label?: string };
+  spark?: number[];
+  divider?: boolean;
+}
+export type NativeContent = { kind: 'rows'; rows: NativeRow[] } |
+  { kind: 'text'; lines: TextSpan[][] } |
+  { kind: 'badge'; spans: TextSpan[]; actionId?: string };
+export interface CanvasSpec {
+  columns: number;
+  rows: number;
+  transparent?: boolean;
+  shade?: number;
+  captureInput?: boolean;
+}
+export type SurfaceContent = NativeContent | { kind: 'canvas'; canvas: CanvasSpec };
+export interface RequestOptions { signal?: AbortSignal; timeoutMs?: number }
+export interface Disposable { dispose(): void }
+export type Cleanup = () => void | Promise<void>;
+export type Condition = { kind: 'always' } |
+  { kind: 'section-visible' | 'slot-visible' | 'panel-open'; contributionId: string; entity?: EntityRef };
+export interface LaunchSpec {
+  version: 1;
+  argv: string[];
+  cwd: string;
+  env: Record<string, string>;
+  agent?: { id: string; prompt?: string; resumeId?: string; delivery: 'argv' | 'stdin' };
+  bootstrap?: { argv: string[]; on: 'create' };
+}
+export interface PaneCreate {
+  machineId: string;
+  projectId?: string;
+  launch: LaunchSpec;
+  title?: string;
+  presentation?: 'workspace' | 'popup';
+  restart?: 'never' | 'on-failure';
+  contributionId?: string;
+}
+export interface PaneResult { pane: EntityRef; operationId: string }
+export interface Selection { entity?: EntityRef; actionId: string; value?: Json }
+export interface LinkSelection extends Selection { url: string }
+export type ActionHandler = (event: Selection, context: HandlerContext) => Json | void | Promise<Json | void>;
+/** True consumes the URL; false allows the next matching handler to run. */
+export type LinkHandler = (event: LinkSelection, context: HandlerContext) => boolean | Promise<boolean>;
+export interface RegistrationOptions {
+  entity?: EntityRef;
+  actionId?: string;
+  title?: string;
+  condition?: Condition;
+}
+export interface MenuOptions extends RegistrationOptions { position?: MenuPosition }
+export interface CommandOptions extends RegistrationOptions { group?: string }
+/** Chords use the native serialized form, such as ctrl+k or ctrl+b w. */
+export interface KeyOptions extends RegistrationOptions { chord?: string }
+/** Patterns are bounded URL match expressions interpreted by the host. */
+export interface LinkOptions extends RegistrationOptions { pattern?: string }
+export interface GroupCommand extends RegistrationOptions { id: string; handler: ActionHandler }
+/** Registration metadata travels with an action subscription. */
+export type ActionRegistration = ContributionKey & { actionId: string; title: string } & (
+  { kind: 'menu'; position: MenuPosition } |
+  { kind: 'command'; group?: string } |
+  { kind: 'key'; chord: string } |
+  { kind: 'link'; pattern: string }
+);
+export interface HookEvent {
+  name: string;
+  entity?: EntityRef;
+  launch?: LaunchSpec;
+  ancestry: string[];
+  operationId: string;
+  deadlineMs: number;
+}
+export type HookResult = { decision: 'proceed'; launch?: LaunchSpec } |
+  { decision: 'cancel'; reason?: string };
+export interface PluginEvent {
+  name: string;
+  entity?: EntityRef;
+  data: Json;
+  deliveryId?: string;
+}
+export interface Popover {
+  kind: 'chooser' | 'form' | 'confirm';
+  title: string;
+  message?: string;
+  entity?: EntityRef;
+  choices?: { id: string; label: string; destructive?: boolean }[];
+  fields?: { id: string; label: string; type: 'text' | 'secret' | 'boolean'; value?: Json }[];
+}
+export interface OperationMap {
+  'pane.create': { input: PaneCreate; output: PaneResult };
+  'pane.close': { input: { pane: EntityRef; confirmationId?: string }; output: { operationId: string } };
+  'pane.restart': { input: { pane: EntityRef; launch?: LaunchSpec }; output: PaneResult };
+  'pane.input': { input: { pane: EntityRef; text: string }; output: null };
+  'pane.focus': { input: { pane: EntityRef }; output: null };
+  'pane.wait': { input: { pane: EntityRef }; output: { exitCode: number | null; lastLine: string } };
+  'project.create': { input: { machineId: string; path: string; name?: string }; output: EntityRef };
+  'project.remove': { input: { project: EntityRef; confirmationId?: string }; output: { operationId: string } };
+  'notification.show': { input: { title: string; message: string }; output: null };
+  'url.open': { input: { url: string }; output: null };
+  'fetch': { input: { url: string; method?: string; headers?: Record<string, string>; body?: string }; output: { status: number; headers: Record<string, string>; body: string } };
+  'secret.get': { input: { name: string }; output: string | null };
+  'config.get': { input: Record<string, never>; output: Record<string, Json> };
+  'state.get': { input: { key: string }; output: Json };
+  'state.set': { input: { key: string; value: Json }; output: null };
+  'context.get': { input: Record<string, never>; output: Json };
+  'popover.open': { input: Popover; output: { choiceId?: string; values?: Record<string, Json>; confirmationId?: string } | null };
+  'canvas.write': { input: { key: ContributionKey; ansi: string }; output: null };
+  'canvas.focus': { input: { key: ContributionKey; capture: boolean }; output: null };
+  'subscription.add': { input: { id: string; name: string; condition: Condition } & (
+    { kind: 'action'; registration?: ActionRegistration } |
+    { kind: 'event' | 'hook' | 'input' | 'select' | 'resize' | 'activate' | 'deactivate' | 'visibility' }
+  ); output: null };
+  'subscription.remove': { input: { id: string }; output: null };
+  'health.set': { input: { status: 'healthy' | 'degraded' | 'error'; message?: string }; output: null };
+  'webhook.ack': { input: { deliveryId: string }; output: null };
+}
+export type OperationName = keyof OperationMap;
+export type Operation = { [K in OperationName]: { op: K; args: OperationMap[K]['input'] } }[OperationName];
+export type Request = <K extends OperationName>(op: K, args: OperationMap[K]['input'], options?: RequestOptions) => Promise<OperationMap[K]['output']>;
+export interface Publisher extends Disposable {
+  replace(content: SurfaceContent): void;
+  clear(): void;
+}
+export interface Canvas extends Publisher {
+  write(ansi: string, options?: RequestOptions): Promise<null>;
+  focus(capture: boolean, options?: RequestOptions): Promise<null>;
+}
+export interface Subscription extends Disposable { ready: Promise<null> }
+export interface KeyRegistration extends Subscription {
+  /** Replaces this subscription's chord after its initial registration is ready. */
+  /** One update may be pending per registration. */
+  update(chord: string, options?: RequestOptions): Promise<null>;
+}
+export interface HandlerContext { signal: AbortSignal }
+export interface PluginContext {
+  readonly manifest: Readonly<PluginManifest>;
+  readonly producer: Readonly<Producer>;
+  readonly signal: AbortSignal;
+  request: Request;
+  section(id: string, entity?: EntityRef): Publisher;
+  slot(id: string, entity: EntityRef): Publisher;
+  badge(id: string, entity: EntityRef): Publisher;
+  panel(id: string, entity?: EntityRef): Publisher;
+  overlay(id: string, entity?: EntityRef): Publisher;
+  canvas(id: string, spec: CanvasSpec, entity?: EntityRef): Canvas;
+  /** IDs match static manifest contributions. Options override declaration defaults. */
+  menu(id: string, options: MenuOptions, handler: ActionHandler): Subscription;
+  menu(id: string, handler: ActionHandler): Subscription;
+  /** Registers a palette command in its declared context and optional group. */
+  command(id: string, options: CommandOptions, handler: ActionHandler): Subscription;
+  command(id: string, handler: ActionHandler): Subscription;
+  /** Each command has a static contribution ID. Disposal removes the whole group. */
+  commandGroup(group: string, commands: readonly GroupCommand[]): Subscription;
+  key(id: string, options: KeyOptions, handler: ActionHandler): KeyRegistration;
+  key(id: string, handler: ActionHandler): KeyRegistration;
+  link(id: string, options: LinkOptions, handler: LinkHandler): Subscription;
+  link(id: string, handler: LinkHandler): Subscription;
+  onEvent(name: string, handler: (event: PluginEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): Subscription;
+  onHook(name: string, handler: (event: HookEvent, context: HandlerContext) => HookResult | Promise<HookResult>): Subscription;
+  onAction(name: string, handler: (event: Selection, context: HandlerContext) => Json | void | Promise<Json | void>): Subscription;
+  onInput(name: string, handler: (event: Json, context: HandlerContext) => void | Promise<void>): Subscription;
+  onSelect(name: string, handler: (event: Selection, context: HandlerContext) => void | Promise<void>): Subscription;
+  onResize(name: string, handler: (event: { columns: number; rows: number }, context: HandlerContext) => void | Promise<void>): Subscription;
+  onActivate(name: string, handler: (event: Json, context: HandlerContext) => void | Promise<void>): Subscription;
+  onDeactivate(name: string, handler: (event: Json, context: HandlerContext) => void | Promise<void>): Subscription;
+  schedule(intervalMs: number, handler: (context: HandlerContext) => void | Promise<void>, options?: { condition?: Condition; immediate?: boolean }): Disposable;
+  onDispose(cleanup: Cleanup): Disposable;
+  panes: {
+    create(args: PaneCreate, options?: RequestOptions): Promise<PaneResult>;
+    close(args: OperationMap['pane.close']['input'], options?: RequestOptions): Promise<{ operationId: string }>;
+    restart(args: OperationMap['pane.restart']['input'], options?: RequestOptions): Promise<PaneResult>;
+    input(args: OperationMap['pane.input']['input'], options?: RequestOptions): Promise<null>;
+    focus(args: OperationMap['pane.focus']['input'], options?: RequestOptions): Promise<null>;
+    wait(args: OperationMap['pane.wait']['input'], options?: RequestOptions): Promise<OperationMap['pane.wait']['output']>;
+  };
+  projects: { create(args: OperationMap['project.create']['input'], options?: RequestOptions): Promise<EntityRef>; remove(args: OperationMap['project.remove']['input'], options?: RequestOptions): Promise<{ operationId: string }> };
+  notifications: { show(args: OperationMap['notification.show']['input'], options?: RequestOptions): Promise<null> };
+  url: { open(url: string, options?: RequestOptions): Promise<null> };
+  fetch(args: OperationMap['fetch']['input'], options?: RequestOptions): Promise<OperationMap['fetch']['output']>;
+  secrets: { get(name: string, options?: RequestOptions): Promise<string | null> };
+  config: { get(options?: RequestOptions): Promise<Record<string, Json>> };
+  /** Local state for one machine. It is never shared with other machines. */
+  state: { get(key: string, options?: RequestOptions): Promise<Json>; set(key: string, value: Json, options?: RequestOptions): Promise<null> };
+  context: { get(options?: RequestOptions): Promise<Json> };
+  popover: { open(args: Popover, options?: RequestOptions): Promise<OperationMap['popover.open']['output']> };
+  health: { set(args: OperationMap['health.set']['input'], options?: RequestOptions): Promise<null> };
+  webhook: { ack(deliveryId: string, options?: RequestOptions): Promise<null> };
+}
+export interface PluginDefinition {
+  id: string;
+  activate(context: PluginContext): void | Cleanup | Promise<void | Cleanup>;
+}
+export function definePlugin(definition: PluginDefinition): Readonly<PluginDefinition>;
+export function validateManifest(value: unknown): Readonly<PluginManifest>;
+export class PluginError extends Error { code: string; constructor(code: string, message: string) }

package/src/index.mjs

@@ -0,0 +1,9 @@
+import { ensure, identifier, validateManifest, PluginError } from './manifest.mjs'
+
+export { validateManifest, PluginError }
+
+export function definePlugin(definition) {
+  ensure(definition && identifier(definition.id) && typeof definition.activate === 'function',
+    'invalid_plugin', 'definePlugin requires an id and activate function')
+  return Object.freeze({ id: definition.id, activate: definition.activate })
+}

package/src/internal.d.ts

@@ -0,0 +1,39 @@
+import type { ContributionKey, SurfaceContent, Producer, Operation, Json, PluginManifest, PluginContext, PluginDefinition, RequestOptions, Condition } from './index.js';
+export * from './index.js';
+export const RUNNER_PROTOCOL_VERSION: 1;
+export const PLUGIN_API_VERSION: 1;
+export const PLUGIN_PEER_CAPABILITY: 'plugins.v1';
+export const LIMITS: Readonly<Record<string, number>>;
+export interface PreparedPlugin {
+  root: string;
+  entry: string;
+  manifest: PluginManifest;
+  manifestDigest: string;
+}
+export type HostOperation =
+  { op: 'runner.start' | 'runner.reload'; args: { root: string; manifestDigest: string; capabilities: string[]; linked?: boolean } } |
+  { op: 'runner.stop' | 'runner.diagnose' | 'runner.ping'; args: Record<string, never> } |
+  { op: 'runtime.invoke'; args: { subscriptionId: string; event: Json } } |
+  { op: 'runtime.visibility'; args: { conditions: Condition[] } };
+export type Envelope = { version: 1; producer: Producer } & (
+  { kind: 'request'; id: string; operation: Operation | HostOperation; timeoutMs: number } |
+  { kind: 'response'; id: string; result: { ok: true; value: Json } | { ok: false; error: { code: string; message: string } } } |
+  { kind: 'cancel'; id: string } |
+  { kind: 'surface'; key: ContributionKey; sequence: string; content: SurfaceContent | null }
+);
+export interface Clock { now(): number; setTimeout(callback: () => void | Promise<void>, ms: number): unknown; clearTimeout(id: unknown): void }
+export interface Runtime {
+  context: PluginContext;
+  receive(frame: Envelope): void;
+  activate(definition: PluginDefinition): Promise<void>;
+  dispose(): Promise<void>;
+}
+export function createRuntime(options: { manifest: PluginManifest; producer: Producer; send(frame: Envelope): void; clock?: Clock; instanceId?: string; onError?(error: Error): void }): Runtime;
+export function authorize(operation: Operation, capabilities: string[]): void;
+export function validateEnvelope(frame: unknown): Envelope;
+export class RpcPeer {
+  constructor(options: { producer: Producer; send(frame: Envelope): void; clock?: Clock; idPrefix?: string; onRequest?(operation: Operation | HostOperation, options: { signal: AbortSignal; timeoutMs: number }): Promise<Json> | Json; onSurface?(frame: Envelope): void; onError?(error: Error): void });
+  request(operation: Operation | HostOperation, options?: RequestOptions): Promise<Json>;
+  receive(frame: Envelope): void;
+  dispose(): void;
+}

package/src/internal.mjs

@@ -0,0 +1,5 @@
+// Re-exports for the plugin runner, which imports this file by relative path.
+// The package does not export this module; plugin code uses the public entry.
+export * from './manifest.mjs'
+export * from './protocol.mjs'
+export { createRuntime } from './runtime.mjs'

package/src/manifest.mjs

@@ -0,0 +1,86 @@
+export const CAPABILITIES = Object.freeze(['surfaces', 'events', 'hooks', 'panes', 'projects',
+  'notifications', 'url', 'fetch', 'secrets', 'webhook'])
+export const SURFACE_KINDS = Object.freeze(['section', 'slot', 'badge', 'panel', 'overlay',
+  'menu', 'command', 'key', 'link'])
+export const ANCHORS = Object.freeze(['plugins', 'machine.before', 'machine.after',
+  'project.before', 'project.after', 'pane.header', 'pane.footer',
+  'account', 'machine', 'project', 'pane', 'section'])
+export const LIMITS = Object.freeze({ manifestBytes: 65536, frameBytes: 262144,
+  pendingRequests: 128, subscriptions: 256, schedules: 128, contributions: 256,
+  queuedBytes: 4 * 1024 * 1024, hookTimeoutMs: 60000, requestTimeoutMs: 30000,
+  canvasColumns: 512, canvasRows: 256 })
+
+export class PluginError extends Error {
+  constructor(code, message) { super(message); this.name = 'PluginError'; this.code = code }
+}
+export function ensure(condition, code, message) {
+  if (!condition) throw new PluginError(code, message)
+}
+export function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+export function identifier(value) { return typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value) }
+export function jsonBytes(value, limit = LIMITS.frameBytes) {
+  // Reject non-JSON values before serialization can silently change their meaning.
+  const seen = new Set()
+  function visit(item, depth) {
+    ensure(depth <= 32, 'invalid_payload', 'JSON nesting exceeds 32 levels')
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return
+    if (typeof item === 'number') { ensure(Number.isFinite(item), 'invalid_payload', 'JSON numbers must be finite'); return }
+    ensure(object(item) || Array.isArray(item), 'invalid_payload', 'Payload must contain JSON values')
+    ensure(!seen.has(item), 'invalid_payload', 'Payload contains a cycle')
+    ensure(Array.isArray(item) || [Object.prototype, null].includes(Object.getPrototypeOf(item)), 'invalid_payload', 'Payload must contain plain objects')
+    seen.add(item)
+    for (const child of Object.values(item)) visit(child, depth + 1)
+    seen.delete(item)
+  }
+  visit(value, 0)
+  const text = JSON.stringify(value)
+  ensure(Buffer.byteLength(text) <= limit, 'payload_too_large', `Payload exceeds ${limit} bytes`)
+  return text
+}
+function freeze(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value) }
+  return value
+}
+export function validateManifest(value) {
+  ensure(object(value), 'invalid_manifest', 'package.json must contain a standardPlugin object')
+  jsonBytes(value, LIMITS.manifestBytes)
+  const allowed = ['apiVersion', 'id', 'name', 'version', 'entry', 'singleton', 'order',
+    'capabilities', 'contributions', 'configSchema', 'hookTimeoutMs']
+  ensure(Object.keys(value).every(key => allowed.includes(key)), 'invalid_manifest', 'Unknown manifest field')
+  const manifest = structuredClone({ singleton: false, order: 0, capabilities: [], contributions: [], hookTimeoutMs: 5000, ...value })
+  ensure(manifest.apiVersion === 1, 'incompatible_version', 'Plugin requires a different SDK API version')
+  ensure(identifier(manifest.id), 'invalid_manifest', 'Plugin id must be a stable identifier')
+  ensure(typeof manifest.name === 'string' && manifest.name.trim().length > 0 && manifest.name.length <= 128,
+    'invalid_manifest', 'Plugin name is required and bounded to 128 characters')
+  ensure(typeof manifest.version === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version),
+    'invalid_manifest', 'Plugin version must be semantic')
+  ensure(typeof manifest.entry === 'string' && manifest.entry.length <= 512 &&
+    !/[\\\u0000?#]/.test(manifest.entry) && !manifest.entry.startsWith('/') &&
+    manifest.entry.split('/').every(part => part && part !== '..') && /\.(?:mjs|cjs|js|mts|ts)$/.test(manifest.entry),
+  'invalid_manifest', 'Plugin entry must be a relative JavaScript or TypeScript file')
+  ensure(typeof manifest.singleton === 'boolean' && Number.isSafeInteger(manifest.order) && Math.abs(manifest.order) <= 2147483647,
+    'invalid_manifest', 'Invalid singleton or order')
+  ensure(Number.isSafeInteger(manifest.hookTimeoutMs) && manifest.hookTimeoutMs > 0 && manifest.hookTimeoutMs <= LIMITS.hookTimeoutMs,
+    'invalid_manifest', 'Hook timeout must be between 1 and 60000 ms')
+  ensure(Array.isArray(manifest.capabilities) && manifest.capabilities.every(item => CAPABILITIES.includes(item)) &&
+    new Set(manifest.capabilities).size === manifest.capabilities.length, 'invalid_manifest', 'Unknown or repeated capability')
+  ensure(Array.isArray(manifest.contributions) && manifest.contributions.length <= LIMITS.contributions,
+    'invalid_manifest', 'Too many contributions')
+  const ids = new Set()
+  for (const declaration of manifest.contributions) {
+    ensure(object(declaration) && identifier(declaration.id) && !ids.has(declaration.id) &&
+      SURFACE_KINDS.includes(declaration.kind) && ANCHORS.includes(declaration.anchor), 'invalid_manifest', 'Invalid contribution declaration')
+    ids.add(declaration.id)
+    for (const [key, choices] of Object.entries({ merge: ['by-machine', 'by-identity'], width: ['full', 'half'],
+      position: ['top', 'after-open', 'before-danger', 'bottom'] })) {
+      ensure(declaration[key] === undefined || choices.includes(declaration[key]), 'invalid_manifest', `Invalid contribution ${key}`)
+    }
+    for (const key of ['title', 'group', 'chord', 'pattern', 'actionId']) {
+      ensure(declaration[key] === undefined || (typeof declaration[key] === 'string' && declaration[key].length <= 512),
+        'invalid_manifest', `Invalid contribution ${key}`)
+    }
+  }
+  ensure(!manifest.contributions.length || manifest.capabilities.includes('surfaces'), 'invalid_manifest', 'Contributions require surfaces capability')
+  ensure(manifest.configSchema === undefined || object(manifest.configSchema), 'invalid_manifest', 'Configuration schema must be an object')
+  return freeze(manifest)
+}

package/src/protocol.mjs

@@ -0,0 +1,166 @@
+import { ensure, identifier, object, jsonBytes, LIMITS, PluginError } from './manifest.mjs'
+
+export const RUNNER_PROTOCOL_VERSION = 1
+export const PLUGIN_API_VERSION = 1
+export const PLUGIN_PEER_CAPABILITY = 'plugins.v1'
+export const OPERATIONS = Object.freeze({
+  'pane.create': 'panes', 'pane.close': 'panes', 'pane.restart': 'panes',
+  'pane.input': 'panes', 'pane.focus': 'panes', 'pane.wait': 'panes',
+  'project.create': 'projects', 'project.remove': 'projects',
+  'notification.show': 'notifications', 'url.open': 'url', fetch: 'fetch',
+  'secret.get': 'secrets', 'config.get': null, 'state.get': null, 'state.set': null,
+  'context.get': null, 'popover.open': 'surfaces', 'canvas.write': 'surfaces',
+  'canvas.focus': 'surfaces', 'subscription.add': null, 'subscription.remove': null,
+  'health.set': null, 'webhook.ack': 'webhook',
+})
+export const HOST_OPERATIONS = Object.freeze(['runner.start', 'runner.stop', 'runner.reload',
+  'runner.diagnose', 'runner.ping', 'runtime.invoke', 'runtime.visibility'])
+
+export function authorize(operation, capabilities) {
+  ensure(object(operation) && Object.hasOwn(OPERATIONS, operation.op) && object(operation.args),
+    'unsupported_operation', 'Unknown SDK operation or invalid arguments')
+  let capability = OPERATIONS[operation.op]
+  if (operation.op === 'subscription.add') {
+    const { id, kind, name } = operation.args
+    ensure(identifier(id) && typeof name === 'string' && name.length <= 256 &&
+      ['event', 'hook', 'action', 'input', 'select', 'resize', 'activate', 'deactivate', 'visibility'].includes(kind),
+    'invalid_payload', 'Invalid subscription')
+    capability = kind === 'hook' ? 'hooks' : kind === 'event' ? (name === 'webhook' ? 'webhook' : 'events') : 'surfaces'
+  }
+  ensure(!capability || capabilities.includes(capability), 'capability_denied', `Operation requires ${capability} capability`)
+  jsonBytes(operation)
+}
+export function validateProducer(producer) {
+  ensure(object(producer) && identifier(producer.pluginId) && typeof producer.machineId === 'string' &&
+    producer.machineId.length > 0 && producer.machineId.length <= 128 && typeof producer.epoch === 'string' &&
+    /^(0|[1-9]\d{0,19})$/.test(producer.epoch) && BigInt(producer.epoch) <= 18446744073709551615n,
+  'invalid_payload', 'Invalid plugin producer identity')
+  return producer
+}
+export function sameProducer(a, b) {
+  return a.pluginId === b.pluginId && a.machineId === b.machineId && a.epoch === b.epoch
+}
+export function validateEnvelope(frame) {
+  jsonBytes(frame)
+  ensure(object(frame) && frame.version === RUNNER_PROTOCOL_VERSION, 'incompatible_version', 'Daemon and runner protocol versions differ')
+  validateProducer(frame.producer)
+  ensure(['request', 'response', 'cancel', 'surface'].includes(frame.kind), 'invalid_payload', 'Unknown runner frame kind')
+  if (frame.kind === 'surface') {
+    ensure(object(frame.key) && identifier(frame.key.contributionId) && typeof frame.sequence === 'string' &&
+      /^(0|[1-9]\d{0,19})$/.test(frame.sequence) && BigInt(frame.sequence) <= 18446744073709551615n &&
+      Object.hasOwn(frame, 'content'), 'invalid_payload', 'Invalid surface replacement')
+  } else {
+    ensure(typeof frame.id === 'string' && frame.id.length > 0 && frame.id.length <= 128, 'invalid_payload', 'Missing correlation id')
+    if (frame.kind === 'request') {
+      ensure(object(frame.operation) && (Object.hasOwn(OPERATIONS, frame.operation.op) || HOST_OPERATIONS.includes(frame.operation.op)) &&
+        object(frame.operation.args) && Number.isSafeInteger(frame.timeoutMs) && frame.timeoutMs > 0 && frame.timeoutMs <= LIMITS.hookTimeoutMs,
+      'invalid_payload', 'Invalid runner request')
+    }
+    if (frame.kind === 'response') {
+      ensure(object(frame.result) && typeof frame.result.ok === 'boolean' &&
+        (frame.result.ok ? Object.hasOwn(frame.result, 'value') :
+          object(frame.result.error) && typeof frame.result.error.code === 'string' && typeof frame.result.error.message === 'string'),
+      'invalid_payload', 'Invalid runner response')
+    }
+  }
+  return frame
+}
+export function wireError(error) {
+  return { code: error instanceof PluginError ? error.code : 'plugin_error',
+    message: String(error?.message ?? 'Plugin operation failed').slice(0, 1024) }
+}
+export const realClock = Object.freeze({ now: () => Date.now(), setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: id => clearTimeout(id) })
+
+/** A single correlation path for commands, actions and hooks. Send must refuse overflow synchronously. */
+export class RpcPeer {
+  constructor({ producer, send, clock = realClock, onRequest, onSurface, onError = () => {}, idPrefix = 'host' }) {
+    this.producer = Object.freeze({ ...validateProducer(producer) })
+    this.send = send
+    this.clock = clock
+    this.onRequest = onRequest
+    this.onSurface = onSurface
+    this.onError = onError
+    this.pending = new Map()
+    this.incoming = new Map()
+    this.nextId = 0
+    this.idPrefix = idPrefix
+    this.closed = false
+  }
+  frame(kind, values) { return { version: RUNNER_PROTOCOL_VERSION, producer: this.producer, kind, ...values } }
+  transmit(frame) { validateEnvelope(frame); this.send(frame) }
+  request(operation, { signal, timeoutMs = LIMITS.requestTimeoutMs } = {}) {
+    if (this.closed) return Promise.reject(new PluginError('disposed', 'Plugin runtime is disposed'))
+    if (signal?.aborted) return Promise.reject(new PluginError('cancelled', 'Request was cancelled'))
+    if (this.pending.size >= LIMITS.pendingRequests) return Promise.reject(new PluginError('queue_full', 'Too many pending requests'))
+    const id = `${this.idPrefix}-${++this.nextId}`
+    return new Promise((resolve, reject) => {
+      let timer
+      const finish = (error, value) => {
+        if (!this.pending.delete(id)) return
+        this.clock.clearTimeout(timer)
+        signal?.removeEventListener('abort', cancel)
+        error ? reject(error) : resolve(value)
+      }
+      const cancelWith = code => {
+        finish(new PluginError(code, code === 'timeout' ? 'Request deadline elapsed' : 'Request was cancelled'))
+        try { this.transmit(this.frame('cancel', { id })) } catch (error) { this.onError(error) }
+      }
+      const cancel = () => cancelWith('cancelled')
+      this.pending.set(id, { finish })
+      signal?.addEventListener('abort', cancel, { once: true })
+      timer = this.clock.setTimeout(() => cancelWith('timeout'), timeoutMs)
+      try { this.transmit(this.frame('request', { id, operation, timeoutMs })) }
+      catch (error) { finish(error) }
+    })
+  }
+  receive(frame) {
+    if (this.closed) return
+    validateEnvelope(frame)
+    ensure(sameProducer(frame.producer, this.producer), 'stale_producer', 'Frame belongs to another plugin instance')
+    if (frame.kind === 'surface') { this.onSurface?.(frame); return }
+    if (frame.kind === 'response') {
+      const result = frame.result
+      this.pending.get(frame.id)?.finish(result.ok ? null : new PluginError(result.error.code, result.error.message), result.value)
+      return
+    }
+    if (frame.kind === 'cancel') { this.incoming.get(frame.id)?.cancel(); return }
+    ensure(!this.incoming.has(frame.id), 'duplicate_request', 'Request id is still in flight')
+    const respond = result => {
+      if (!this.closed) {
+        try { this.transmit(this.frame('response', { id: frame.id, result })) }
+        catch (error) { this.onError(error) }
+      }
+    }
+    if (this.incoming.size >= LIMITS.pendingRequests) {
+      respond({ ok: false, error: { code: 'queue_full', message: 'Too many incoming requests' } })
+      return
+    }
+    const controller = new AbortController()
+    // Retain the occupied slot until a cancelled handler settles. An uncooperative
+    // handler cannot turn repeated cancellation into unbounded concurrent work.
+    const cancel = () => { controller.abort(); this.clock.clearTimeout(timer) }
+    const timer = this.clock.setTimeout(() => {
+      cancel()
+      respond({ ok: false, error: { code: 'timeout', message: 'Handler deadline elapsed' } })
+    }, frame.timeoutMs)
+    this.incoming.set(frame.id, { cancel })
+    Promise.resolve().then(() => {
+      ensure(!controller.signal.aborted, 'cancelled', 'Request was cancelled')
+      ensure(typeof this.onRequest === 'function', 'unsupported_operation', 'No request handler')
+      return this.onRequest(frame.operation, { signal: controller.signal, timeoutMs: frame.timeoutMs })
+    }).then(value => {
+      if (!controller.signal.aborted) respond({ ok: true, value: value ?? null })
+    }, error => {
+      if (!controller.signal.aborted) respond({ ok: false, error: wireError(error) })
+    }).finally(() => { this.clock.clearTimeout(timer); this.incoming.delete(frame.id) })
+  }
+  dispose() {
+    if (this.closed) return
+    for (const [id, request] of this.pending) {
+      request.finish(new PluginError('disposed', 'Plugin runtime was disposed'))
+      try { this.transmit(this.frame('cancel', { id })) } catch (error) { this.onError(error) }
+    }
+    this.closed = true
+    for (const request of this.incoming.values()) request.cancel()
+  }
+}

package/src/runtime.mjs

@@ -0,0 +1,354 @@
+import { LIMITS, PluginError, ensure, jsonBytes, validateManifest, ANCHORS, identifier, object } from './manifest.mjs'
+import { RpcPeer, authorize, realClock } from './protocol.mjs'
+
+const always = Object.freeze({ kind: 'always' })
+const menuPositions = ['top', 'after-open', 'before-danger', 'bottom']
+const entityKinds = ['account', 'machine', 'project', 'pane', 'section']
+function boundedText(value, label, limit = 512) {
+  ensure(typeof value === 'string' && value.trim().length > 0 && value.length <= limit &&
+    !/[\u0000-\u001f\u007f]/.test(value), 'invalid_payload', `Invalid ${label}`)
+  return value
+}
+function validateEntity(entity) {
+  ensure(object(entity) && entityKinds.includes(entity.kind), 'invalid_payload', 'Invalid registration entity')
+  boundedText(entity.id, 'entity id', 128)
+  if (entity.machineId !== undefined) boundedText(entity.machineId, 'machine id', 128)
+  if (entity.generation !== undefined) {
+    ensure(typeof entity.generation === 'string' && /^(0|[1-9]\d{0,19})$/.test(entity.generation) &&
+      BigInt(entity.generation) <= 18446744073709551615n, 'invalid_payload', 'Invalid entity generation')
+  }
+  return { kind: entity.kind, id: entity.id,
+    ...(entity.machineId !== undefined ? { machineId: entity.machineId } : {}),
+    ...(entity.generation !== undefined ? { generation: entity.generation } : {}) }
+}
+function validateChord(chord) {
+  boundedText(chord, 'key chord', 128)
+  const presses = chord.split(' ')
+  const namedKeys = ['space', 'enter', 'esc', 'tab', 'backspace', 'left', 'right', 'up', 'down', 'pageup', 'pagedown', 'home', 'end']
+  ensure(presses.length <= 2 && presses.every(press => {
+    const parts = press.split('+')
+    const modifiers = parts.filter(part => ['shift', 'alt', 'ctrl'].includes(part))
+    const keys = parts.filter(part => !['shift', 'alt', 'ctrl'].includes(part))
+    return new Set(modifiers).size === modifiers.length && keys.length === 1 &&
+      (namedKeys.includes(keys[0]) || Array.from(keys[0]).length === 1)
+  }), 'invalid_payload', 'Invalid native key chord')
+  return chord
+}
+function conditionKey(condition) { return JSON.stringify([condition.kind, condition.contributionId ?? null, condition.entity ?? null]) }
+function validateCondition(condition) {
+  ensure(condition && ['always', 'section-visible', 'slot-visible', 'panel-open'].includes(condition.kind) &&
+    (condition.kind === 'always' || identifier(condition.contributionId)), 'invalid_payload', 'Invalid schedule condition')
+  return structuredClone(condition)
+}
+function validateContent(content) {
+  jsonBytes(content)
+  ensure(content && ['rows', 'text', 'badge', 'canvas'].includes(content.kind), 'invalid_payload', 'Invalid surface content')
+  if (content.kind === 'canvas') {
+    const { columns, rows, shade = 0 } = content.canvas ?? {}
+    ensure(Number.isSafeInteger(columns) && columns > 0 && columns <= LIMITS.canvasColumns &&
+      Number.isSafeInteger(rows) && rows > 0 && rows <= LIMITS.canvasRows &&
+      Number.isFinite(shade) && shade >= 0 && shade <= 1, 'invalid_payload', 'Invalid canvas dimensions or shade')
+  }
+}
+
+export function createRuntime({ manifest: input, producer, send, clock = realClock, onError = () => {}, instanceId = '0' }) {
+  const manifest = validateManifest(input)
+  ensure(producer.pluginId === manifest.id, 'identity_mismatch', 'Manifest and producer ids differ')
+  const lifetime = new AbortController()
+  const subscriptions = new Map()
+  const schedules = new Set()
+  const cleanups = new Set()
+  const publishers = new Map()
+  let visibility = new Set()
+  let counter = 0
+  let sequence = 0n
+  let disposal
+  ensure(identifier(instanceId), 'invalid_payload', 'Invalid runtime instance id')
+  const peer = new RpcPeer({ producer, send, clock, onError, idPrefix: 'sdk', onRequest: async (operation, options) => {
+    if (operation.op === 'runtime.visibility') {
+      ensure(Array.isArray(operation.args.conditions) && operation.args.conditions.length <= LIMITS.contributions,
+        'invalid_payload', 'Invalid visibility snapshot')
+      visibility = new Set(operation.args.conditions.map(condition => conditionKey(validateCondition(condition))))
+      for (const schedule of schedules) schedule.visibilityChanged(visibility)
+      return null
+    }
+    ensure(operation.op === 'runtime.invoke', 'unsupported_operation', 'Unsupported worker operation')
+    const subscription = subscriptions.get(operation.args.subscriptionId)
+    ensure(subscription, 'subscription_missing', 'Subscription was disposed')
+    if (subscription.condition.kind !== 'always' && !visibility.has(conditionKey(subscription.condition))) return null
+    const result = await subscription.handler(operation.args.event, { signal: options.signal })
+    if (subscription.kind === 'hook') {
+      ensure(result && ['proceed', 'cancel'].includes(result.decision), 'invalid_payload', 'Hook must return proceed or cancel')
+    }
+    return result ?? null
+  } })
+  function active() { ensure(!lifetime.signal.aborted, 'disposed', 'Plugin runtime is disposed') }
+  function request(op, args, options) {
+    try { active(); authorize({ op, args }, manifest.capabilities) }
+    catch (error) { onError(error); return Promise.reject(error) }
+    return peer.request({ op, args }, options)
+  }
+  function publish(kind, id, entity) {
+    active()
+    ensure(manifest.capabilities.includes('surfaces'), 'capability_denied', 'Publishing requires surfaces capability')
+    const declaration = manifest.contributions.find(item => item.id === id)
+    ensure(declaration && (!kind || declaration.kind === kind) && ANCHORS.includes(declaration.anchor),
+      'contribution_missing', 'Surface must match its static contribution declaration')
+    const key = { contributionId: id, anchor: declaration.anchor, ...(entity ? { entity: structuredClone(entity) } : {}) }
+    const identity = JSON.stringify(key)
+    ensure(!publishers.has(identity), 'duplicate_contribution', 'Contribution publisher exists')
+    ensure(publishers.size < LIMITS.contributions, 'queue_full', 'Too many contribution publishers')
+    let disposed = false
+    const replace = content => {
+      active()
+      ensure(!disposed, 'disposed', 'Contribution publisher is disposed')
+      if (content !== null) validateContent(content)
+      peer.transmit(peer.frame('surface', { key, sequence: String(++sequence), content }))
+    }
+    const publisher = { replace, clear: () => replace(null), dispose() {
+      if (disposed) return
+      try { if (!lifetime.signal.aborted) replace(null) }
+      finally { disposed = true; publishers.delete(identity) }
+    } }
+    publishers.set(identity, publisher)
+    return { publisher, key }
+  }
+  function subscribe(kind, name, handler, condition = always, registration) {
+    active()
+    ensure(typeof handler === 'function', 'invalid_payload', 'Subscription requires a handler')
+    ensure(subscriptions.size < LIMITS.subscriptions, 'queue_full', 'Too many subscriptions')
+    condition = validateCondition(condition)
+    const id = `subscription-${instanceId}-${++counter}`
+    const args = { id, kind, name, condition, ...(registration ? { registration } : {}) }
+    authorize({ op: 'subscription.add', args }, manifest.capabilities)
+    const entry = { kind, handler, condition, registration }
+    subscriptions.set(id, entry)
+    let disposed = false
+    let updating = false
+    const remove = () => { if (!lifetime.signal.aborted) request('subscription.remove', { id }).catch(onError) }
+    const ready = request('subscription.add', args)
+    ready.then(() => { if (disposed) remove() }, error => {
+      disposed = true
+      subscriptions.delete(id)
+      remove()
+      onError(error)
+    })
+    const subscription = { ready, dispose() {
+      if (disposed) return
+      disposed = true
+      subscriptions.delete(id)
+      remove()
+    } }
+    if (registration?.kind === 'key') subscription.update = async (chord, options) => {
+      active()
+      ensure(!disposed, 'disposed', 'Key registration is disposed')
+      validateChord(chord)
+      ensure(!updating, 'request_in_flight', 'A key registration update is pending')
+      updating = true
+      try {
+        await ready
+        active()
+        ensure(!disposed, 'disposed', 'Key registration is disposed')
+        const next = { ...entry.registration, chord }
+        await request('subscription.add', { ...args, registration: next }, options)
+        if (!disposed) entry.registration = next
+        return null
+      } finally {
+        updating = false
+        if (disposed) remove()
+      }
+    }
+    return subscription
+  }
+  function prepareRegistration(kind, id, options, handler) {
+    active()
+    if (typeof options === 'function' && handler === undefined) { handler = options; options = {} }
+    ensure(identifier(id) && object(options) && typeof handler === 'function', 'invalid_payload', 'Invalid contribution registration')
+    jsonBytes(options, LIMITS.manifestBytes)
+    const declaration = manifest.contributions.find(item => item.id === id && item.kind === kind)
+    ensure(declaration, 'contribution_missing', 'Registration must match its static contribution declaration')
+    const actionId = options.actionId ?? declaration.actionId ?? id
+    ensure(identifier(actionId), 'invalid_payload', 'Invalid registration action id')
+    const registration = { contributionId: id, kind, anchor: declaration.anchor, actionId,
+      title: boundedText(options.title ?? declaration.title ?? id, 'registration title'),
+      ...(options.entity !== undefined ? { entity: validateEntity(options.entity) } : {}) }
+    if (kind === 'menu') {
+      registration.position = options.position ?? declaration.position ?? 'bottom'
+      ensure(menuPositions.includes(registration.position), 'invalid_payload', 'Invalid menu position')
+    } else if (kind === 'command') {
+      const group = options.group ?? declaration.group
+      if (group !== undefined) registration.group = boundedText(group, 'command group')
+    } else if (kind === 'key') {
+      registration.chord = validateChord(options.chord ?? declaration.chord)
+    } else if (kind === 'link') {
+      registration.pattern = boundedText(options.pattern ?? declaration.pattern, 'link pattern')
+    }
+    const condition = validateCondition(options.condition ?? always)
+    if (condition.entity !== undefined) condition.entity = validateEntity(condition.entity)
+    jsonBytes({ registration, condition }, LIMITS.manifestBytes)
+    const invoke = async (event, context) => {
+      ensure(object(event) && event.actionId === actionId, 'invalid_payload', 'Invalid registered action selection')
+      if (event.entity !== undefined) validateEntity(event.entity)
+      if (kind === 'link') boundedText(event.url, 'link URL', 8192)
+      const result = await handler(event, context)
+      if (kind === 'link') ensure(typeof result === 'boolean', 'invalid_payload', 'Link handlers must return a boolean')
+      return result
+    }
+    return { registration, handler: invoke, condition }
+  }
+  const registrationKey = registration => JSON.stringify([registration.contributionId, registration.entity ?? null])
+  function registerPrepared({ registration, handler, condition }) {
+    const identity = registrationKey(registration)
+    ensure(![...subscriptions.values()].some(entry => entry.registration && registrationKey(entry.registration) === identity),
+      'duplicate_contribution', 'Contribution registration exists')
+    return subscribe('action', registration.actionId, handler, condition, registration)
+  }
+  function commandGroup(group, commands) {
+    active()
+    boundedText(group, 'command group')
+    ensure(Array.isArray(commands) && commands.length > 0 && commands.length <= LIMITS.contributions &&
+      subscriptions.size + commands.length <= LIMITS.subscriptions, 'queue_full', 'Invalid or excessive group commands')
+    const prepared = commands.map(command => {
+      ensure(object(command), 'invalid_payload', 'Invalid group command')
+      const { id, handler, ...options } = command
+      return prepareRegistration('command', id, { ...options, group }, handler)
+    })
+    const identities = new Set([...subscriptions.values()].filter(entry => entry.registration).map(entry => registrationKey(entry.registration)))
+    for (const { registration } of prepared) {
+      const identity = registrationKey(registration)
+      ensure(!identities.has(identity), 'duplicate_contribution', 'Contribution registration exists')
+      identities.add(identity)
+    }
+    const members = []
+    const dispose = () => { for (const member of members) member.dispose() }
+    try { for (const item of prepared) members.push(registerPrepared(item)) }
+    catch (error) { dispose(); throw error }
+    const ready = Promise.all(members.map(member => member.ready)).then(() => null)
+    ready.catch(dispose)
+    return { ready, dispose }
+  }
+  function schedule(intervalMs, handler, { condition = always, immediate = false } = {}) {
+    active()
+    ensure(Number.isFinite(intervalMs) && intervalMs >= 1000 / 30 && intervalMs <= 2147483647,
+      'invalid_payload', 'Schedule interval must be between 1000/30 and 2147483647 ms')
+    ensure(typeof handler === 'function' && schedules.size < LIMITS.schedules, 'queue_full', 'Invalid or excessive schedules')
+    condition = validateCondition(condition)
+    const interest = condition.kind === 'always' ? null : subscribe('visibility', condition.contributionId, () => {}, condition)
+    const conditionIdentity = conditionKey(condition)
+    const controller = new AbortController()
+    let activeRun = null
+    let timer
+    const beginRun = () => {
+      const runController = new AbortController()
+      const cancelFromSchedule = () => runController.abort()
+      const cancelFromLifetime = () => runController.abort()
+      controller.signal.addEventListener('abort', cancelFromSchedule, { once: true })
+      lifetime.signal.addEventListener('abort', cancelFromLifetime, { once: true })
+      const run = {
+        controller: runController,
+        finish() {
+          controller.signal.removeEventListener('abort', cancelFromSchedule)
+          lifetime.signal.removeEventListener('abort', cancelFromLifetime)
+          if (activeRun?.controller === runController) activeRun = null
+        },
+      }
+      activeRun = run
+      return run
+    }
+    const tick = async () => {
+      if (controller.signal.aborted || lifetime.signal.aborted) return
+      const visible = condition.kind === 'always' || visibility.has(conditionIdentity)
+      if (!visible) {
+        timer = clock.setTimeout(tick, intervalMs)
+        return
+      }
+      const run = beginRun()
+      try {
+        await handler({ signal: run.controller.signal })
+      } catch (error) {
+        if (!run.controller.signal.aborted || condition.kind === 'always') onError(error)
+      } finally {
+        run.finish()
+      }
+      // Each schedule has at most one invocation in flight.
+      if (!controller.signal.aborted && !lifetime.signal.aborted) timer = clock.setTimeout(tick, intervalMs)
+    }
+    const disposable = {
+      visibilityChanged(nextVisibility) {
+        if (condition.kind !== 'always' && !nextVisibility.has(conditionIdentity)) activeRun?.controller.abort()
+      },
+      dispose() {
+        controller.abort()
+        activeRun?.controller.abort()
+        clock.clearTimeout(timer)
+        interest?.dispose()
+        schedules.delete(disposable)
+      },
+    }
+    schedules.add(disposable)
+    timer = clock.setTimeout(tick, immediate ? 0 : intervalMs)
+    return disposable
+  }
+  const method = op => (args, options) => request(op, args, options)
+  const context = Object.freeze({
+    manifest, producer: peer.producer, signal: lifetime.signal, request,
+    ...Object.fromEntries(['section', 'slot', 'badge', 'panel', 'overlay'].map(kind => [kind,
+      (id, entity) => publish(kind, id, entity).publisher])),
+    canvas(id, spec, entity) {
+      const { publisher, key } = publish(null, id, entity)
+      try { publisher.replace({ kind: 'canvas', canvas: spec }) }
+      catch (error) { publisher.dispose(); throw error }
+      return { ...publisher, write: (ansi, options) => request('canvas.write', { key, ansi }, options),
+        focus: (capture, options) => request('canvas.focus', { key, capture }, options) }
+    },
+    ...Object.fromEntries(['Event', 'Hook', 'Action', 'Input', 'Select', 'Resize', 'Activate', 'Deactivate'].map(name =>
+      [`on${name}`, (event, handler, condition) => subscribe(name.toLowerCase(), event, handler, condition)])),
+    ...Object.fromEntries(['menu', 'command', 'key', 'link'].map(kind => [kind,
+      (id, options, handler) => registerPrepared(prepareRegistration(kind, id, options, handler))])),
+    commandGroup,
+    schedule,
+    onDispose(cleanup) {
+      active()
+      ensure(typeof cleanup === 'function' && cleanups.size < LIMITS.subscriptions, 'queue_full', 'Invalid or excessive cleanup callbacks')
+      cleanups.add(cleanup)
+      return { dispose: () => { cleanups.delete(cleanup) } }
+    },
+    panes: Object.freeze(Object.fromEntries(['create', 'close', 'restart', 'input', 'focus', 'wait'].map(name => [name, method(`pane.${name}`)]))),
+    projects: Object.freeze({ create: method('project.create'), remove: method('project.remove') }),
+    notifications: Object.freeze({ show: method('notification.show') }),
+    url: Object.freeze({ open: (url, options) => request('url.open', { url }, options) }),
+    fetch: method('fetch'),
+    secrets: Object.freeze({ get: (name, options) => request('secret.get', { name }, options) }),
+    config: Object.freeze({ get: options => request('config.get', {}, options) }),
+    state: Object.freeze({ get: (key, options) => request('state.get', { key }, options),
+      set: (key, value, options) => request('state.set', { key, value }, options) }),
+    context: Object.freeze({ get: options => request('context.get', {}, options) }),
+    popover: Object.freeze({ open: method('popover.open') }),
+    health: Object.freeze({ set: method('health.set') }),
+    webhook: Object.freeze({ ack: (deliveryId, options) => request('webhook.ack', { deliveryId }, options) }),
+  })
+  return {
+    context, receive: frame => peer.receive(frame),
+    async activate(definition) {
+      active()
+      ensure(definition?.id === manifest.id && typeof definition.activate === 'function', 'identity_mismatch', 'Runtime plugin must match static manifest id')
+      const cleanup = await definition.activate(context)
+      if (typeof cleanup === 'function') {
+        if (lifetime.signal.aborted) await cleanup()
+        else context.onDispose(cleanup)
+      }
+    },
+    dispose() {
+      if (disposal) return disposal
+      // Remove owned surfaces before the lifetime signal prevents new work.
+      for (const publisher of publishers.values()) { try { publisher.dispose() } catch (error) { onError(error) } }
+      lifetime.abort()
+      for (const disposable of schedules) disposable.dispose()
+      peer.dispose()
+      subscriptions.clear()
+      disposal = Promise.allSettled([...cleanups].reverse().map(cleanup => Promise.resolve().then(cleanup)))
+        .then(results => { for (const result of results) if (result.status === 'rejected') onError(result.reason); cleanups.clear() })
+      return disposal
+    },
+  }
+}

package/src/testing.d.ts

@@ -0,0 +1,24 @@
+import type { Json, ManifestInput, OperationMap, PluginContext, PluginDefinition, Condition, RequestOptions } from './index.js';
+import type { Envelope } from './internal.js';
+export interface Harness {
+  context: PluginContext;
+  trace: unknown[];
+  surfaces: Map<string, Envelope>;
+  subscriptions: Map<string, Json>;
+  activate(definition: PluginDefinition): Promise<void>;
+  flush(): Promise<void>;
+  advance(milliseconds: number): Promise<void>;
+  emit(kind: string, name: string, event: Json, options?: RequestOptions): Promise<Json[]>;
+  visibility(conditions: Condition[]): Promise<Json>;
+  receive(frame: Envelope): void;
+  drainTrace(): unknown[];
+  readonly resources: { timers: number; subscriptions: number; surfaces: number; disposed: boolean };
+  dispose(): Promise<void>;
+}
+export function createHarness(options: {
+  manifest: ManifestInput;
+  machineId?: string;
+  epoch?: string;
+  now?: number;
+  handlers?: { [K in keyof OperationMap]?: (args: OperationMap[K]['input'], context: { signal: AbortSignal; timeoutMs: number }) => OperationMap[K]['output'] | Promise<OperationMap[K]['output']> };
+}): Harness;

package/src/testing.mjs

@@ -0,0 +1,104 @@
+import { createRuntime } from './runtime.mjs'
+import { RpcPeer } from './protocol.mjs'
+import { PluginError, ensure, LIMITS, validateManifest } from './manifest.mjs'
+
+/** Explicit time and fixture-owned responses; this harness starts no threads or subprocesses. */
+export function createHarness({ manifest: input, machineId = 'test-machine', epoch = '1', handlers = {}, now = 0 } = {}) {
+  const manifest = validateManifest(input)
+  const producer = { pluginId: manifest.id, machineId, epoch }
+  const trace = []
+  const surfaces = new Map()
+  const subscriptions = new Map()
+  const localState = new Map()
+  const timers = new Map()
+  let timerId = 0
+  let disposed = false
+  const clock = {
+    now: () => now,
+    setTimeout(callback, delay) { const id = ++timerId; timers.set(id, { due: now + delay, callback }); return id },
+    clearTimeout(id) { timers.delete(id) },
+  }
+  const record = event => {
+    ensure(trace.length < 10000, 'queue_full', 'Harness trace reached 10000 entries; drain it before continuing')
+    trace.push(event)
+  }
+  let runtime
+  const host = new RpcPeer({ producer, clock,
+    send(frame) { record({ type: 'host', frame: structuredClone(frame) }); runtime.receive(frame) },
+    onSurface(frame) {
+      const key = JSON.stringify(frame.key)
+      frame.content === null ? surfaces.delete(key) : surfaces.set(key, structuredClone(frame))
+    },
+    onRequest(operation, options) {
+      record({ type: 'command', operation: structuredClone(operation) })
+      if (handlers[operation.op]) return handlers[operation.op](operation.args, options)
+      const args = operation.args
+      switch (operation.op) {
+        case 'subscription.add': subscriptions.set(args.id, structuredClone(args)); return null
+        case 'subscription.remove': subscriptions.delete(args.id); return null
+        case 'state.get': return structuredClone(localState.get(args.key) ?? null)
+        case 'state.set':
+          ensure(localState.has(args.key) || localState.size < LIMITS.contributions, 'queue_full', 'Harness state is full')
+          localState.set(args.key, structuredClone(args.value)); return null
+        case 'config.get': return {}
+        case 'context.get': return { machineId }
+        case 'health.set': return null
+        default: throw new PluginError('missing_fixture', `Provide a harness handler for ${operation.op}`)
+      }
+    },
+    onError: error => record({ type: 'error', code: error.code, message: error.message }),
+  })
+  runtime = createRuntime({ manifest, producer, clock,
+    send(frame) { record({ type: 'plugin', frame: structuredClone(frame) }); host.receive(frame) },
+    onError: error => record({ type: 'error', code: error.code, message: error.message }),
+  })
+  async function flush() { for (let turn = 0; turn < 64; turn++) await Promise.resolve() }
+  return {
+    context: runtime.context, trace, surfaces, subscriptions,
+    activate: definition => runtime.activate(definition),
+    flush,
+    async advance(milliseconds) {
+      ensure(Number.isFinite(milliseconds) && milliseconds >= 0, 'invalid_payload', 'Advance requires a nonnegative duration')
+      const end = now + milliseconds
+      await flush()
+      let ticks = 0
+      while (true) {
+        const next = [...timers].filter(([, timer]) => timer.due <= end)
+          .sort((a, b) => a[1].due - b[1].due || a[0] - b[0])[0]
+        if (!next) break
+        ensure(++ticks <= 10000, 'queue_full', 'Advance exceeds the harness timer budget')
+        now = next[1].due
+        timers.delete(next[0])
+        const result = next[1].callback()
+        Promise.resolve(result).catch(error => record({ type: 'error', code: error.code, message: error.message }))
+        await flush()
+      }
+      now = end
+      await flush()
+    },
+    async emit(kind, name, event, options) {
+      await flush()
+      const results = []
+      for (const [subscriptionId, subscription] of subscriptions) {
+        if (subscription.kind === kind && subscription.name === name) {
+          results.push(await host.request({ op: 'runtime.invoke', args: { subscriptionId, event } }, options))
+        }
+      }
+      return results
+    },
+    visibility: conditions => host.request({ op: 'runtime.visibility', args: { conditions } }),
+    receive: frame => runtime.receive(frame),
+    drainTrace() { return trace.splice(0) },
+    get resources() { return { timers: timers.size, subscriptions: subscriptions.size, surfaces: surfaces.size, disposed } },
+    async dispose() {
+      if (disposed) return
+      disposed = true
+      await runtime.dispose()
+      host.dispose()
+      subscriptions.clear()
+      surfaces.clear()
+      timers.clear()
+      record({ type: 'disposed' })
+    },
+  }
+}