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

package/src/index.mjs

@@ -0,0 +1,13 @@
+import { ensure, identifier, validateManifest, PluginError } from './manifest.mjs'
+import { COLLECTION_FILE, resolveCollection, validateCollection } from './collection.mjs'
+import { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement } from './publish.mjs'
+
+export { validateManifest, PluginError }
+export { COLLECTION_FILE, resolveCollection, validateCollection }
+export { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement }
+
+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/publish.mjs

@@ -0,0 +1,62 @@
+import { PluginError, ensure, object, validateManifest } from './manifest.mjs'
+
+export const SDK_PACKAGE = '@standardagents/code-plugin-sdk'
+export const SOURCE_KINDS = Object.freeze(['git', 'npm'])
+const LOCKFILES = Object.freeze({ git: Object.freeze(['package-lock.json', 'npm-shrinkwrap.json']), npm: Object.freeze(['npm-shrinkwrap.json']) })
+
+function names(section) { return object(section) ? Object.keys(section) : [] }
+
+/** Runtime dependencies are the ones npm installs for a consumer of the package. */
+export function runtimeDependencies(packageJson) {
+  ensure(object(packageJson), 'invalid_package', 'package.json must contain an object')
+  return [...new Set([...names(packageJson.dependencies), ...names(packageJson.optionalDependencies)])]
+}
+
+/**
+ * A plugin with runtime dependencies ships a lockfile. npm publishes
+ * npm-shrinkwrap.json and drops package-lock.json, so an npm source needs the
+ * shrinkwrap; a Git source may keep either file.
+ */
+export function lockfileRequirement({ packageJson, sourceKind }) {
+  ensure(SOURCE_KINDS.includes(sourceKind), 'invalid_source', 'Source kind must be git or npm')
+  const dependencies = runtimeDependencies(packageJson)
+  return Object.freeze({ required: dependencies.length > 0, dependencies: Object.freeze(dependencies), lockfiles: LOCKFILES[sourceKind] })
+}
+
+function normalize(path) { return path.replace(/^\.\//, '') }
+
+/**
+ * Pure publish checks for one plugin directory. `files` lists the relative
+ * POSIX paths that ship with the package. Returns a list of problems; an empty
+ * list means the package passes.
+ */
+export function checkPackageForPublish({ packageJson, files, sourceKind = 'npm', requireManifest = true, expectedId } = {}) {
+  ensure(Array.isArray(files) && files.every(file => typeof file === 'string'), 'invalid_source', 'files must list relative paths')
+  const problems = []
+  const problem = (code, message) => problems.push(Object.freeze({ code, message }))
+  if (!object(packageJson)) return Object.freeze([Object.freeze({ code: 'invalid_package', message: 'package.json must contain an object' })])
+  const present = new Set(files.map(normalize))
+  if (packageJson.private === true && sourceKind === 'npm') problem('package_private', 'package.json marks the package private, so npm refuses to publish it')
+  const requirement = lockfileRequirement({ packageJson, sourceKind })
+  if (requirement.required && !requirement.lockfiles.some(name => present.has(name))) {
+    problem('lockfile_missing', `Dependencies (${requirement.dependencies.join(', ')}) need ${requirement.lockfiles.join(' or ')} beside package.json`)
+  }
+  for (const section of ['dependencies', 'optionalDependencies']) {
+    if (names(packageJson[section]).includes(SDK_PACKAGE)) problem('sdk_dependency', `${SDK_PACKAGE} belongs under peerDependencies, not ${section}`)
+  }
+  let manifest = null
+  if (packageJson.standardPlugin === undefined) {
+    if (requireManifest) problem('manifest_missing', 'package.json has no standardPlugin manifest')
+  } else {
+    try { manifest = validateManifest(packageJson.standardPlugin) } catch (error) {
+      if (!(error instanceof PluginError)) throw error
+      problem(error.code, error.message)
+    }
+  }
+  if (manifest) {
+    if (!names(packageJson.peerDependencies).includes(SDK_PACKAGE)) problem('sdk_peer_missing', `${SDK_PACKAGE} must be listed under peerDependencies`)
+    if (!present.has(normalize(manifest.entry))) problem('entry_missing', `Entry ${manifest.entry} is not among the package files`)
+    if (expectedId !== undefined && manifest.id !== expectedId) problem('id_mismatch', `Manifest id ${manifest.id} differs from collection entry ${expectedId}`)
+  }
+  return Object.freeze(problems)
+}