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

package/README.md

@@ -1,4 +1,175 @@
-# @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.
+
+## Collections
+
+A plugin installs from a Git repository or an npm package. One source holds
+one plugin or a collection of plugins.
+
+A collection lists its plugins in `standard-plugins.json` at the root of the
+repository or package:
+
+```json
+{
+  "schema": 1,
+  "plugins": [
+    { "id": "builds-monitor", "path": "builds-monitor" },
+    { "id": "pong", "path": "games/pong" }
+  ]
+}
+```
+
+`schema` is `1`. `plugins` holds 1 to 256 entries. Each `id` follows the
+plugin id pattern of the manifest and equals the `standardPlugin.id` in that
+entry's `package.json`. Each `path` is a relative POSIX path of at most 512
+characters with no leading slash, no backslash, and no empty, `.`, or `..`
+segment. Ids and paths are unique within one collection. An installer
+selects one entry with `--plugin <id>`.
+
+A root without `standard-plugins.json` is a single plugin when its
+`package.json` carries a valid `standardPlugin` manifest. Discovery treats it
+as one entry at path `""`.
+
+`validateCollection(value)` checks a parsed collection file and returns a
+frozen `PluginCollection`. `resolveCollection({ collection, packageJson })`
+applies the single-plugin fallback. `COLLECTION_FILE` names the file.
+
+## Dependencies
+
+A plugin with `dependencies` or `optionalDependencies` ships a lockfile
+beside its `package.json`, so every machine installs the same dependency
+tree. The installer refuses a plugin with dependencies and no lockfile.
+
+For an npm package the lockfile is `npm-shrinkwrap.json`. npm never
+publishes `package-lock.json`; `npm shrinkwrap` converts an existing
+`package-lock.json` into `npm-shrinkwrap.json`, and npm includes that file
+when it publishes the package. For a Git repository either
+`package-lock.json` or `npm-shrinkwrap.json` satisfies the rule.
+
+The SDK belongs under `peerDependencies`, with a `devDependencies` copy for
+the plugin's own tests. Inside Standard Code the bundled runtime supplies it.
+
+`lockfileRequirement({ packageJson, sourceKind })` returns whether the rule
+applies and which lockfile names satisfy it for `"npm"` or `"git"`.
+`checkPackageForPublish({ packageJson, files })` reports problems as
+`{ code, message }` objects: a missing lockfile, the SDK under
+`dependencies`, a missing peer declaration, a missing or invalid manifest, an
+entry outside the package files, or an id that differs from the collection
+entry. Both helpers are pure; they read no files.
+
+In a collection, each plugin directory holds its own `package.json` and its
+own lockfile.
+
+## Publishing a plugin
+
+The package installs a `standard-plugin` command for authoring.
+
+```sh
+npx standard-plugin check
+npx standard-plugin pack
+npm publish
+```
+
+`check [dir] [--source npm|git]` reads `package.json`, the optional
+`standard-plugins.json`, every collection entry's `package.json`, and the
+lockfiles. It prints each problem as `<path>: <code>: <message>` and exits
+with status 1 when it finds one. `--source git` applies the Git lockfile
+rule; the default is `npm`.
+
+`pack [dir]` runs `check`. When a plugin has dependencies and no
+`npm-shrinkwrap.json`, it runs `npm shrinkwrap`, which converts
+`package-lock.json`, and asks you to commit the new file. It then runs
+`npm pack --dry-run` and prints the files that npm will publish.
+
+The command is authoring tooling. The SDK entry never imports it, and a
+plugin never depends on it at run time.
+
+## 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,
+the declarations in `src/index.d.ts` and `src/testing.d.ts`, and the
+`standard-plugin` command's `check` and `pack` behavior.
+
+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/bin/standard-plugin.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Authoring tool for plugin packages. The SDK entry never imports this file.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { COLLECTION_FILE, PluginError, checkPackageForPublish, validateCollection } from '../src/index.mjs'
+
+const USAGE = `usage: standard-plugin check [dir] [--source npm|git]
+       standard-plugin pack [dir]
+
+check  validates package.json, ${COLLECTION_FILE}, each collection entry, and lockfiles
+pack   runs check, creates npm-shrinkwrap.json when dependencies need one, then runs npm pack --dry-run`
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git'])
+const FILE_LIMIT = 50000
+
+function readJson(path) {
+  let text
+  try { text = readFileSync(path, 'utf8') } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+  return JSON.parse(text)
+}
+
+/** Relative POSIX paths of regular files under root, without following links. */
+function listFiles(root) {
+  const files = []
+  const pending = ['']
+  while (pending.length) {
+    const directory = pending.pop()
+    for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+      const path = directory ? `${directory}/${entry.name}` : entry.name
+      if (entry.isDirectory()) { if (!IGNORED_DIRECTORIES.has(entry.name)) pending.push(path) }
+      else if (entry.isFile()) files.push(path)
+      if (files.length > FILE_LIMIT) throw new Error(`More than ${FILE_LIMIT} files under ${root}`)
+    }
+  }
+  return files
+}
+
+function tryJson(root, name, problems, location) {
+  try { return readJson(join(root, name)) } catch (error) {
+    problems.push({ location, code: 'invalid_json', message: `${name}: ${error.message}` })
+    return undefined
+  }
+}
+
+function collect(problems, location, list) {
+  for (const problem of list) problems.push({ location, ...problem })
+}
+
+/** Checks one source directory. Returns problems with the directory each one belongs to. */
+function checkDirectory(root, { sourceKind = 'npm' } = {}) {
+  const problems = []
+  const files = listFiles(root)
+  const packageJson = tryJson(root, 'package.json', problems, '.')
+  const collectionInput = tryJson(root, COLLECTION_FILE, problems, '.')
+  if (collectionInput === undefined) {
+    if (packageJson === undefined) problems.push({ location: '.', code: 'package_missing', message: `package.json or ${COLLECTION_FILE} is required` })
+    else collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind }))
+    return problems
+  }
+  let collection
+  try { collection = validateCollection(collectionInput) } catch (error) {
+    if (!(error instanceof PluginError)) throw error
+    problems.push({ location: '.', code: error.code, message: `${COLLECTION_FILE}: ${error.message}` })
+    return problems
+  }
+  if (packageJson !== undefined) collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind, requireManifest: false }))
+  else if (sourceKind === 'npm') problems.push({ location: '.', code: 'package_missing', message: 'an npm package needs a root package.json' })
+  for (const entry of collection.plugins) {
+    const entryPackage = tryJson(join(root, entry.path), 'package.json', problems, entry.path)
+    if (entryPackage === undefined) {
+      if (!problems.some(problem => problem.location === entry.path)) {
+        problems.push({ location: entry.path, code: 'package_missing', message: `collection entry ${entry.id} has no package.json` })
+      }
+      continue
+    }
+    const prefix = `${entry.path}/`
+    const entryFiles = files.filter(file => file.startsWith(prefix)).map(file => file.slice(prefix.length))
+    collect(problems, entry.path, checkPackageForPublish({ packageJson: entryPackage, files: entryFiles, sourceKind, expectedId: entry.id }))
+  }
+  return problems
+}
+
+function report(problems) {
+  for (const problem of problems) console.log(`${problem.location}: ${problem.code}: ${problem.message}`)
+  console.log(problems.length ? `${problems.length} problem${problems.length === 1 ? '' : 's'}` : 'ok')
+}
+
+function npm(args, cwd) {
+  const result = spawnSync('npm', args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function parse(argv) {
+  const [command, ...rest] = argv
+  const options = { directory: '.', sourceKind: 'npm' }
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index]
+    if (argument === '--source') {
+      options.sourceKind = rest[++index]
+      if (!['npm', 'git'].includes(options.sourceKind)) throw new Error('--source takes npm or git')
+    } else if (argument.startsWith('-')) throw new Error(`unknown option ${argument}`)
+    else options.directory = argument
+  }
+  return { command, ...options, directory: resolve(options.directory) }
+}
+
+function check(options) {
+  const problems = checkDirectory(options.directory, options)
+  report(problems)
+  return problems.length ? 1 : 0
+}
+
+function pack(options) {
+  if (options.sourceKind !== 'npm') throw new Error('pack checks an npm package; --source git does not apply')
+  let problems = checkDirectory(options.directory, options)
+  const missing = problems.filter(problem => problem.code === 'lockfile_missing')
+  for (const problem of missing) {
+    const directory = resolve(options.directory, problem.location)
+    if (!existsSync(join(directory, 'package-lock.json'))) {
+      console.log(`${problem.location}: run npm install first so npm shrinkwrap has a package-lock.json to convert`)
+      continue
+    }
+    console.log(`${problem.location}: creating npm-shrinkwrap.json from package-lock.json`)
+    const status = npm(['shrinkwrap'], directory)
+    if (status !== 0) return status
+    console.log(`${problem.location}: commit npm-shrinkwrap.json; npm publishes it with the package`)
+  }
+  if (missing.length) problems = checkDirectory(options.directory, options)
+  report(problems)
+  if (problems.length) return 1
+  return npm(['pack', '--dry-run'], options.directory)
+}
+
+function main(argv) {
+  let options
+  try { options = parse(argv) } catch (error) { console.error(error.message); console.error(USAGE); return 2 }
+  try {
+    if (options.command === 'check') return check(options)
+    if (options.command === 'pack') return pack(options)
+  } catch (error) { console.error(`standard-plugin: ${error.message}`); return 2 }
+  console.error(USAGE)
+  return 2
+}
+
+process.exitCode = main(process.argv.slice(2))

package/package.json

@@ -1,8 +1,21 @@
 {
   "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.1",
+  "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" }
+  },
+  "bin": { "standard-plugin": "./bin/standard-plugin.mjs" },
+  "files": ["src", "bin", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/index.d.ts

@@ -0,0 +1,310 @@
+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) }
+
+/** One plugin inside a collection. The path is relative to the source root. */
+export interface PluginCollectionEntry {
+  id: string;
+  /** Relative POSIX path; "" names the source root for a single-plugin source. */
+  path: string;
+}
+/** The standard-plugins.json file at the root of a repository or npm package. */
+export interface PluginCollection {
+  schema: 1;
+  plugins: PluginCollectionEntry[];
+}
+/** File name of the collection manifest: standard-plugins.json. */
+export const COLLECTION_FILE: 'standard-plugins.json';
+export function validateCollection(value: unknown): Readonly<PluginCollection>;
+/** A collection file wins; without one, a valid package manifest makes the root one plugin at path "". */
+export function resolveCollection(source: { collection?: unknown; packageJson?: unknown }): Readonly<PluginCollection>;
+
+export type SourceKind = 'git' | 'npm';
+export type LockfileName = 'package-lock.json' | 'npm-shrinkwrap.json';
+export interface LockfileRequirement {
+  /** True when the package declares dependencies or optionalDependencies. */
+  required: boolean;
+  dependencies: readonly string[];
+  /** Lockfile names that satisfy the rule for this source kind. */
+  lockfiles: readonly LockfileName[];
+}
+/** Package name of this SDK, which a plugin lists under peerDependencies. */
+export const SDK_PACKAGE: '@standardagents/code-plugin-sdk';
+export function lockfileRequirement(input: { packageJson: unknown; sourceKind: SourceKind }): LockfileRequirement;
+export interface PublishProblem {
+  code: 'invalid_package' | 'package_private' | 'lockfile_missing' | 'sdk_dependency' | 'sdk_peer_missing' |
+    'manifest_missing' | 'invalid_manifest' | 'invalid_payload' | 'payload_too_large' | 'incompatible_version' |
+    'entry_missing' | 'id_mismatch';
+  message: string;
+}
+/** Pure checks over a package.json and the relative paths of the files that ship with it. */
+export function checkPackageForPublish(input: {
+  packageJson: unknown;
+  files: readonly string[];
+  sourceKind?: SourceKind;
+  /** False for a collection root whose package.json carries no plugin manifest. */
+  requireManifest?: boolean;
+  /** The collection entry id the manifest must match. */
+  expectedId?: string;
+}): readonly PublishProblem[];