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

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' })
+    },
+  }
+}