@standardagents/code-plugin-sdk 1.0.0-alpha.1 → 1.0.0-alpha.11-headers.0

package/src/testing.mjs

@@ -1,6 +1,6 @@
 import { createRuntime } from './runtime.mjs'
 import { RpcPeer } from './protocol.mjs'
-import { PluginError, ensure, LIMITS, validateManifest } from './manifest.mjs'
+import { PluginError, ensure, jsonBytes, 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 } = {}) {
@@ -9,7 +9,7 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
   const trace = []
   const surfaces = new Map()
   const subscriptions = new Map()
-  const localState = new Map()
+  const accountState = new Map()
   const timers = new Map()
   let timerId = 0
   let disposed = false
@@ -36,12 +36,16 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
       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.get': return structuredClone(accountState.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
+          // The product stores these values in the account: 256 keys per
+          // plugin, 64 KiB per value.
+          ensure(accountState.has(args.key) || accountState.size < LIMITS.stateKeys, 'queue_full', 'Harness state holds 256 keys for this plugin')
+          jsonBytes(args.value, LIMITS.stateValueBytes)
+          accountState.set(args.key, structuredClone(args.value)); return null
+        case 'state.keys': return [...accountState.keys()].sort()
         case 'config.get': return {}
-        case 'context.get': return { machineId }
+        case 'context.get': return { accountId: 'test-account', machineId, build: null, fleet: null, projects: [], panes: [], complete: true }
         case 'health.set': return null
         default: throw new PluginError('missing_fixture', `Provide a harness handler for ${operation.op}`)
       }
@@ -88,6 +92,13 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
     },
     visibility: conditions => host.request({ op: 'runtime.visibility', args: { conditions } }),
     receive: frame => runtime.receive(frame),
+    /** The current content of a published contribution, or undefined when it is clear. */
+    surface(id, entity) {
+      const declaration = manifest.contributions.find(item => item.id === id)
+      if (!declaration) return undefined
+      const key = { contributionId: id, anchor: declaration.anchor, ...(entity ? { entity } : {}) }
+      return structuredClone(surfaces.get(JSON.stringify(key))?.content)
+    },
     drainTrace() { return trace.splice(0) },
     get resources() { return { timers: timers.size, subscriptions: subscriptions.size, surfaces: surfaces.size, disposed } },
     async dispose() {

package/src/view.mjs

@@ -0,0 +1,257 @@
+import { LIMITS, ensure, identifier, jsonBytes, object } from './manifest.mjs'
+
+// Mirrors crates/standard-protocol/src/plugin_view.rs. The host applies the
+// same bounds; checking here reports a mistake at the replace() call.
+// items and logLines bound the list-shaped nodes: the host lays every entry
+// out again on each paint, so a long list costs a frame, not just memory.
+export const VIEW_LIMITS = Object.freeze({ depth: 8, nodes: 4096, tableRows: 512, tableColumns: 12,
+  items: 512, logLines: 2048, cardLines: 6, actionValueBytes: 512 })
+export const TONES = Object.freeze(['ok', 'info', 'warn', 'error', 'muted', 'accent', 'pending', 'bright'])
+const WEIGHTS = ['normal', 'bold', 'dim']
+const ALIGNS = ['start', 'center', 'end']
+// C0, DEL, C1, and the bidirectional formatting characters that can reorder terminal output.
+const FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/
+
+const invalid = message => ensure(false, 'invalid_payload', message)
+function text(value, field) {
+  if (typeof value !== 'string') invalid(`Plugin view ${field} must be a string`)
+  ensure(!FORBIDDEN.test(value), 'invalid_payload', 'Plugin view text contains a control or bidirectional character')
+}
+function optionalText(value, field) { if (value !== undefined) text(value, field) }
+function choice(value, choices, field) {
+  ensure(value === undefined || choices.includes(value), 'invalid_payload', `Invalid plugin view ${field}`)
+}
+function tone(value) { choice(value, TONES, 'tone') }
+function integer(value, max, field) {
+  ensure(value === undefined || (Number.isInteger(value) && value >= 0 && value <= max), 'invalid_payload', `Invalid plugin view ${field}`)
+}
+function flag(value, field) { ensure(value === undefined || typeof value === 'boolean', 'invalid_payload', `Invalid plugin view ${field}`) }
+function number(value) {
+  ensure(typeof value === 'number' && Number.isFinite(value), 'invalid_payload', 'Plugin view number is not finite')
+}
+function list(value, field, optional = false) {
+  if (optional && value === undefined) return []
+  ensure(Array.isArray(value), 'invalid_payload', `Plugin view ${field} must be an array`)
+  return value
+}
+function entries(value, field, optional, check) {
+  for (const item of list(value, field, optional)) {
+    ensure(object(item), 'invalid_payload', `Plugin view ${field} must contain objects`)
+    check(item)
+  }
+}
+function bounded(value, field, limit, optional = false) {
+  const values = list(value, field, optional)
+  ensure(values.length <= limit, 'invalid_payload', `Plugin view ${field} has more than ${limit} entries`)
+  return values
+}
+// A list-shaped node's entries, held to the bound the host applies.
+function boundedEntries(value, field, check) {
+  entries(bounded(value, field, VIEW_LIMITS.items), field, false, check)
+}
+function spans(value, optional) {
+  entries(value, 'spans', optional, span => {
+    text(span.text, 'span text')
+    tone(span.tone)
+    choice(span.weight, WEIGHTS, 'weight')
+    flag(span.mono, 'mono')
+  })
+}
+function action(value, optional = true) {
+  if (optional && value === undefined) return
+  ensure(object(value), 'invalid_payload', 'Plugin view action must be an object')
+  text(value.actionId, 'action id')
+  optionalText(value.value, 'action value')
+  optionalText(value.opens, 'action opens')
+}
+function meter(item) {
+  number(item.value)
+  number(item.max)
+  tone(item.tone)
+  optionalText(item.label, 'label')
+}
+function children(node, depth, count) {
+  for (const child of list(node.children, 'children', true)) walk(child, depth + 1, count)
+}
+
+const NODES = {
+  stack(node, depth, count) { integer(node.gap, 255, 'gap'); children(node, depth, count) },
+  row(node, depth, count) { choice(node.align, ALIGNS, 'align'); children(node, depth, count) },
+  divider(node) { optionalText(node.label, 'label') },
+  text(node) {
+    optionalText(node.text, 'text')
+    spans(node.spans, true)
+    tone(node.tone)
+    choice(node.weight, WEIGHTS, 'weight')
+    flag(node.mono, 'mono')
+  },
+  badge(node) { text(node.label, 'label'); tone(node.tone) },
+  dot(node) { tone(node.tone) },
+  progress: meter,
+  segments(node) { boundedEntries(node.items, 'items', meter) },
+  card(node, depth, count) { optionalText(node.title, 'title'); tone(node.tone); children(node, depth, count) },
+  stat(node) {
+    text(node.label, 'label')
+    text(node.value, 'value')
+    tone(node.tone)
+    optionalText(node.hint, 'hint')
+  },
+  kv(node) {
+    boundedEntries(node.items, 'items', item => {
+      text(item.label, 'label')
+      text(item.value, 'value')
+      flag(item.mono, 'mono')
+      flag(item.copy, 'copy')
+    })
+  },
+  tabs(node) {
+    text(node.id, 'id')
+    optionalText(node.filters, 'filters')
+    action(node.action)
+    boundedEntries(node.items, 'items', item => {
+      text(item.id, 'id')
+      text(item.label, 'label')
+      optionalText(item.sublabel, 'sublabel')
+      tone(item.tone)
+      integer(item.count, 0xffffffff, 'count')
+      optionalText(item.tag, 'tag')
+    })
+  },
+  select(node) {
+    text(node.id, 'id')
+    text(node.label, 'label')
+    optionalText(node.filters, 'filters')
+    action(node.action)
+    boundedEntries(node.options, 'options', option => {
+      text(option.id, 'id')
+      text(option.label, 'label')
+      optionalText(option.group, 'group')
+      integer(option.count, 0xffffffff, 'count')
+      optionalText(option.tag, 'tag')
+    })
+  },
+  table(node, depth, count) {
+    const columns = list(node.columns, 'columns')
+    const rows = list(node.rows, 'rows', true)
+    ensure(columns.length <= VIEW_LIMITS.tableColumns, 'invalid_payload', 'Plugin table has more than 12 columns')
+    ensure(rows.length <= VIEW_LIMITS.tableRows, 'invalid_payload', 'Plugin table has more than 512 rows')
+    text(node.id, 'id')
+    entries(columns, 'columns', false, column => {
+      text(column.id, 'column id')
+      optionalText(column.label, 'column label')
+      if (column.width !== 'fill') integer(column.width, 0xffff, 'column width')
+      integer(column.maxWidth, 0xffff, 'column maxWidth')
+      choice(column.align, ALIGNS, 'align')
+      integer(column.priority, 255, 'column priority')
+    })
+    entries(rows, 'rows', false, row => {
+      text(row.id, 'row id')
+      tone(row.tone)
+      spans(row.note, true)
+      for (const tag of bounded(row.tags, 'tags', VIEW_LIMITS.items, true)) text(tag, 'tag')
+      action(row.action)
+      ensure(row.cells === undefined || object(row.cells), 'invalid_payload', 'Plugin table cells must be an object')
+      for (const [column, cell] of Object.entries(row.cells ?? {})) {
+        text(column, 'cell column')
+        walk(cell, depth + 1, count)
+      }
+    })
+  },
+  log(node) { for (const line of bounded(node.lines, 'lines', VIEW_LIMITS.logLines)) text(line, 'log line') },
+  button(node) { text(node.label, 'label'); action(node.action, false) },
+}
+
+function walk(node, depth, count) {
+  ensure(depth <= VIEW_LIMITS.depth, 'invalid_payload', 'Plugin view nests deeper than 8 nodes')
+  ensure(++count.nodes <= VIEW_LIMITS.nodes, 'invalid_payload', 'Plugin view has more than 4096 nodes')
+  ensure(object(node) && typeof node.type === 'string', 'invalid_payload', 'Plugin view node requires a type')
+  // A node type this SDK does not know draws nothing on hosts that do not know it either.
+  if (Object.hasOwn(NODES, node.type)) NODES[node.type](node, depth, count)
+}
+
+// The daemon checks below mirror crates/standardd/src/plugin_view_content.rs.
+
+/** Visits the actions a viewer can activate, in the nodes the daemon searches. */
+function visitActions(node, visit) {
+  switch (node.type) {
+    case 'stack': case 'row': case 'card':
+      for (const child of node.children ?? []) visitActions(child, visit)
+      break
+    case 'button': visit(node.action); break
+    case 'tabs': case 'select': if (node.action !== undefined) visit(node.action); break
+    case 'table':
+      for (const row of node.rows ?? []) {
+        if (row.action !== undefined) visit(row.action)
+        for (const cell of Object.values(row.cells ?? {})) visitActions(cell, visit)
+      }
+      break
+  }
+}
+
+const ONE_LINE = ['text', 'badge', 'dot', 'progress', 'segments', 'stat', 'divider']
+const PANEL_ONLY = ['card', 'kv', 'tabs', 'select', 'table', 'log', 'button']
+/** Cards hold one-line summaries arranged by stacks and rows; unknown nodes draw nothing. */
+function cardLines(node) {
+  if (node.type === 'stack') {
+    const children = node.children ?? []
+    return children.reduce((total, child) => total + cardLines(child), (node.gap ?? 0) * Math.max(children.length - 1, 0))
+  }
+  if (node.type === 'row') return (node.children ?? []).reduce((tallest, child) => Math.max(tallest, cardLines(child)), 0)
+  if (ONE_LINE.includes(node.type)) return 1
+  ensure(!PANEL_ONLY.includes(node.type), 'invalid_payload', `A card view cannot contain a ${node.type} node`)
+  return 0
+}
+
+/**
+ * Throws a PluginError when a view tree breaks a protocol bound or a rule the
+ * serving daemon applies. `kind: 'card'` adds the card rules, and `manifest`
+ * requires every action `opens` to name one of its panels.
+ */
+export function validateView(root, { kind, manifest } = {}) {
+  walk(root, 1, { nodes: 0 })
+  jsonBytes(root, LIMITS.frameBytes)
+  visitActions(root, action => {
+    ensure(identifier(action.actionId), 'invalid_payload', 'Plugin view action id must be a plugin identifier')
+    ensure(action.value === undefined || Buffer.byteLength(action.value) <= VIEW_LIMITS.actionValueBytes,
+      'payload_too_large', 'Plugin view action value exceeds 512 bytes')
+    ensure(action.opens === undefined || identifier(action.opens), 'invalid_payload', 'Plugin view action opens must be a plugin identifier')
+    ensure(action.opens === undefined || !manifest ||
+      manifest.contributions.some(item => item.id === action.opens && item.kind === 'panel'),
+    'invalid_payload', 'Plugin view action opens must name a declared panel')
+  })
+  if (kind === 'card') {
+    ensure(cardLines(root) <= VIEW_LIMITS.cardLines, 'payload_too_large', 'A card view is taller than 6 lines')
+  }
+}
+
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined))
+}
+const node = (type, fields) => compact({ type, ...fields })
+
+/** Optional builders. Each returns the plain protocol JSON for one node. */
+export const ui = Object.freeze({
+  view: (root, { title } = {}) => compact({ kind: 'view', root, title }),
+  action: (actionId, { value, opens } = {}) => compact({ actionId, value, opens }),
+  span: (value, { tone, weight, mono } = {}) => compact({ text: value, tone, weight, mono }),
+  stack: (items, { gap } = {}) => node('stack', { gap, children: items }),
+  row: (items, { align } = {}) => node('row', { children: items, align }),
+  divider: label => node('divider', { label }),
+  /** A string sets `text`; an array of spans sets `spans`. */
+  text: (content, { tone, weight, mono } = {}) =>
+    node('text', { ...(Array.isArray(content) ? { spans: content.map(compact) } : { text: content }), tone, weight, mono }),
+  badge: (label, tone) => node('badge', { label, tone }),
+  dot: tone => node('dot', { tone }),
+  progress: (value, max, { tone, label } = {}) => node('progress', { value, max, tone, label }),
+  segments: items => node('segments', { items: items.map(compact) }),
+  card: (items, { title, tone } = {}) => node('card', { title, tone, children: items }),
+  stat: (label, value, { tone, hint } = {}) => node('stat', { label, value, tone, hint }),
+  kv: items => node('kv', { items: items.map(compact) }),
+  tabs: (id, items, { filters, action } = {}) => node('tabs', { id, items: items.map(compact), filters, action }),
+  select: (id, label, options, { filters, action } = {}) =>
+    node('select', { id, label, options: options.map(compact), filters, action }),
+  table: (id, columns, rows = []) => node('table', { id, columns: columns.map(compact), rows: rows.map(compact) }),
+  log: lines => node('log', { lines }),
+  /** `action` is an action object or an action id. */
+  button: (label, action) => node('button', { label, action: typeof action === 'string' ? { actionId: action } : action }),
+})