@standardagents/code-plugin-sdk 1.0.0-alpha.2 → 1.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",

package/src/index.d.ts

@@ -92,6 +92,14 @@ export interface CanvasSpec {
   captureInput?: boolean;
 }
 export type CanvasContent = { kind: 'canvas'; canvas: CanvasSpec };
+/**
+ * What an `onInput` handler for a canvas receives. Keys arrive while the canvas
+ * declares `captureInput` and holds focus; focus loss arrives when the host
+ * stops showing it.
+ */
+export type CanvasInputEvent =
+  | { kind: 'key'; key: string; phase: 'press' | 'repeat'; contributionId: string; entity?: EntityRef }
+  | { kind: 'focus'; focused: false; contributionId: string; entity?: EntityRef };
 
 /** Semantic tones. The host maps each tone to the viewer's theme. */
 export type Tone = 'ok' | 'info' | 'warn' | 'error' | 'muted' | 'accent' | 'pending' | 'bright';
@@ -207,6 +215,40 @@ export interface PluginEvent {
   data: Json;
   deliveryId?: string;
 }
+/** The native release this machine runs. */
+export type BuildInfo = {
+  version: string;
+  /** The 40-character lowercase commit SHA. */
+  commit: string;
+  /** The Git ref of the build's source, such as `refs/heads/main`, or null when it is not known. */
+  ref: string | null;
+  channel: 'branch' | 'canary' | 'production' | 'team' | null;
+};
+/** The account-wide build policy every machine in the fleet follows. */
+export type FleetPolicy = {
+  mode: 'follow' | 'pin' | 'production' | null;
+  npmTag: string | null;
+  /** The Git ref of the followed channel, or null when it is not known. */
+  ref: string | null;
+  /** The pinned or target version, or null when it is not known. */
+  version: string | null;
+};
+/** The `context.get` result. `build` and `fleet` are null when unknown. */
+export type PluginContextInfo = {
+  accountId: string;
+  machineId: string;
+  build?: BuildInfo | null;
+  fleet?: FleetPolicy | null;
+};
+/** The `data` of a `build-context` event. */
+export type BuildContextEventData = {
+  build: BuildInfo | null;
+  fleet: FleetPolicy | null;
+};
+export interface BuildContextEvent extends PluginEvent {
+  name: 'build-context';
+  data: BuildContextEventData;
+}
 export interface Popover {
   kind: 'chooser' | 'form' | 'confirm';
   title: string;
@@ -231,7 +273,7 @@ export interface OperationMap {
   '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 };
+  'context.get': { input: Record<string, never>; output: PluginContextInfo };
   '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 };
@@ -287,9 +329,11 @@ export interface PluginContext {
   key(id: string, handler: ActionHandler): KeyRegistration;
   link(id: string, options: LinkOptions, handler: LinkHandler): Subscription;
   link(id: string, handler: LinkHandler): Subscription;
+  onEvent(name: 'build-context', handler: (event: BuildContextEvent, context: HandlerContext) => void | Promise<void>, condition?: Condition): 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;
+  /** For a canvas, `name` is its contribution ID and events are `CanvasInputEvent` values. */
   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;
@@ -313,7 +357,7 @@ export interface PluginContext {
   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> };
+  context: { get(options?: RequestOptions): Promise<PluginContextInfo> };
   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> };

package/src/testing.mjs

@@ -41,7 +41,7 @@ export function createHarness({ manifest: input, machineId = 'test-machine', epo
           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 'context.get': return { accountId: 'test-account', machineId, build: null, fleet: null }
         case 'health.set': return null
         default: throw new PluginError('missing_fixture', `Provide a harness handler for ${operation.op}`)
       }