Add SDK package

ts/classes.agentproxy.ts

@@ -0,0 +1,36 @@
+import * as plugins from './plugins.js';
+import type { ShxAutomationContext } from './classes.automationcontext.js';
+
+export class AgentProxy {
+  constructor(private context: ShxAutomationContext) {}
+
+  public async decide(optionsArg: {
+    agentId: string;
+    goal: string;
+    scopes: plugins.shxInterfaces.data.TToolScope[];
+    input?: Record<string, unknown>;
+    confidence?: number;
+  }) {
+    const callId = `call:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const plan: plugins.shxInterfaces.data.IToolPlan = {
+      id: `plan:${callId}`,
+      callerId: this.context.options.callerId,
+      title: `Ask ${optionsArg.agentId}`,
+      reason: optionsArg.goal,
+      confidence: optionsArg.confidence ?? 0.65,
+      calls: [
+        {
+          id: callId,
+          toolId: `agent:${optionsArg.agentId}:decide`,
+          callerId: this.context.options.callerId,
+          input: {
+            goal: optionsArg.goal,
+            scopes: optionsArg.scopes,
+            ...(optionsArg.input ?? {}),
+          },
+        },
+      ],
+    };
+    return this.context.executePlan(plan);
+  }
+}

ts/classes.automationcontext.ts

@@ -0,0 +1,76 @@
+import * as plugins from './plugins.js';
+import { AgentProxy } from './classes.agentproxy.js';
+import { DeviceProxy } from './classes.deviceproxy.js';
+
+export type TAutomationEvent = {
+  triggerId: string;
+  kind: plugins.shxInterfaces.data.TAutomationTriggerKind;
+  payload: Record<string, unknown>;
+};
+
+export type TAutomationHandler = (
+  eventArg: TAutomationEvent,
+  contextArg: ShxAutomationContext
+) => Promise<void> | void;
+
+export type TToolPlanExecutor = (
+  planArg: plugins.shxInterfaces.data.IToolPlan
+) => Promise<plugins.shxInterfaces.data.IToolPlanResult>;
+
+export interface IShxAutomationContextOptions {
+  callerId: string;
+  executePlan?: TToolPlanExecutor;
+}
+
+export interface IAutomationRegistration {
+  trigger: plugins.shxInterfaces.data.IAutomationTrigger;
+  handler: TAutomationHandler;
+}
+
+export class ShxAutomationContext {
+  public devices = new DeviceProxy(this);
+  public agents = new AgentProxy(this);
+  private registrations: IAutomationRegistration[] = [];
+
+  constructor(public options: IShxAutomationContextOptions) {}
+
+  public on(
+    triggerArg: plugins.shxInterfaces.data.IAutomationTrigger,
+    handlerArg: TAutomationHandler
+  ) {
+    this.registrations.push({
+      trigger: triggerArg,
+      handler: handlerArg,
+    });
+    return triggerArg;
+  }
+
+  public getRegistrations() {
+    return [...this.registrations];
+  }
+
+  public async runTrigger(eventArg: TAutomationEvent) {
+    const matchingRegistrations = this.registrations.filter((registrationArg) => {
+      return registrationArg.trigger.id === eventArg.triggerId || registrationArg.trigger.kind === eventArg.kind;
+    });
+    for (const registration of matchingRegistrations) {
+      await registration.handler(eventArg, this);
+    }
+  }
+
+  public async executePlan(planArg: plugins.shxInterfaces.data.IToolPlan) {
+    if (this.options.executePlan) {
+      return this.options.executePlan(planArg);
+    }
+    return {
+      planId: planArg.id,
+      results: planArg.calls.map((callArg: plugins.shxInterfaces.data.IToolCall) => ({
+        callId: callArg.id,
+        status: 'suggested' as const,
+        output: {
+          message: 'No hub executor attached. Plan was recorded as a suggestion.',
+        },
+      })),
+    };
+  }
+}

ts/classes.deviceproxy.ts

@@ -0,0 +1,47 @@
+import * as plugins from './plugins.js';
+import type { ShxAutomationContext } from './classes.automationcontext.js';
+
+export class DeviceProxy {
+  constructor(private context: ShxAutomationContext) {}
+
+  public async call(optionsArg: {
+    deviceId: string;
+    toolId: string;
+    title: string;
+    reason: string;
+    input?: Record<string, unknown>;
+    confidence?: number;
+  }) {
+    const callId = `call:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const plan: plugins.shxInterfaces.data.IToolPlan = {
+      id: `plan:${callId}`,
+      callerId: this.context.options.callerId,
+      title: optionsArg.title,
+      reason: optionsArg.reason,
+      confidence: optionsArg.confidence ?? 0.5,
+      calls: [
+        {
+          id: callId,
+          toolId: optionsArg.toolId,
+          callerId: this.context.options.callerId,
+          input: {
+            deviceId: optionsArg.deviceId,
+            ...(optionsArg.input ?? {}),
+          },
+        },
+      ],
+    };
+    return this.context.executePlan(plan);
+  }
+
+  public async read(deviceIdArg: string) {
+    return this.call({
+      deviceId: deviceIdArg,
+      toolId: `device:${deviceIdArg}:read`,
+      title: `Read ${deviceIdArg}`,
+      reason: 'Automation requested current device state.',
+      input: {},
+      confidence: 1,
+    });
+  }
+}

ts/index.ts

@@ -0,0 +1,20 @@
+export * from './classes.automationcontext.js';
+export * from './classes.agentproxy.js';
+export * from './classes.deviceproxy.js';
+
+import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import { ShxAutomationContext, type TAutomationHandler } from './classes.automationcontext.js';
+import { AgentProxy } from './classes.agentproxy.js';
+import { DeviceProxy } from './classes.deviceproxy.js';
+
+export const defaultAutomationContext = new ShxAutomationContext({
+  callerId: 'automation:default',
+});
+
+export const on: (
+  triggerArg: shxInterfaces.data.IAutomationTrigger,
+  handlerArg: TAutomationHandler
+) => shxInterfaces.data.IAutomationTrigger = defaultAutomationContext.on.bind(defaultAutomationContext);
+
+export const devices: DeviceProxy = defaultAutomationContext.devices;
+export const agents: AgentProxy = defaultAutomationContext.agents;

ts/plugins.ts

@@ -0,0 +1,4 @@
+// Project scope
+import * as shxInterfaces from '@smarthome.exchange/interfaces';
+
+export { shxInterfaces };