Add interfaces package

ts/data/agent.ts

@@ -0,0 +1,34 @@
+import type { TToolScope } from './tool.js';
+
+export type TAgentMode = 'auto' | 'ask' | 'suggest';
+
+export type TAgentGlyph = 'comfort' | 'sentinel' | 'watt' | 'dawn' | 'echo' | 'steward' | 'custom';
+
+export interface IAgentDefinition {
+  id: string;
+  name: string;
+  role: string;
+  glyph: TAgentGlyph;
+  color: string;
+  mode: TAgentMode;
+  model: string;
+  scopes: TToolScope[];
+  systemPrompt: string;
+  enabled: boolean;
+}
+
+export interface IAgentStatus {
+  agentId: string;
+  actionsToday: number;
+  latest?: string;
+  savings?: string;
+  runningToolIds: string[];
+}
+
+export interface IAgentReasoningEvent {
+  id: string;
+  agentId: string;
+  kind: 'observe' | 'think' | 'plan' | 'tool' | 'speak';
+  text: string;
+  createdAt: string;
+}

ts/data/audit.ts

@@ -0,0 +1,14 @@
+export type TAuditReceiptKind = 'tool' | 'approval' | 'automation' | 'agent' | 'system';
+
+export interface IAuditReceipt {
+  id: string;
+  kind: TAuditReceiptKind;
+  callerId: string;
+  toolId?: string;
+  approvalId?: string;
+  scope?: string;
+  inputSummary: string;
+  outputSummary: string;
+  reversible: boolean;
+  createdAt: string;
+}

ts/data/automation.ts

@@ -0,0 +1,28 @@
+import type { TToolScope } from './tool.js';
+
+export type TAutomationTriggerKind = 'time' | 'device' | 'presence' | 'calendar' | 'manual' | 'system';
+
+export interface IAutomationTrigger {
+  id: string;
+  kind: TAutomationTriggerKind;
+  expression: string;
+}
+
+export interface IAutomationDefinition {
+  id: string;
+  name: string;
+  sourcePath: string;
+  enabled: boolean;
+  triggers: IAutomationTrigger[];
+  requiredScopes: TToolScope[];
+}
+
+export interface IAutomationRun {
+  id: string;
+  automationId: string;
+  triggerId: string;
+  status: 'running' | 'completed' | 'failed';
+  startedAt: string;
+  finishedAt?: string;
+  errorMessage?: string;
+}

ts/data/dashboard.ts

@@ -0,0 +1,27 @@
+export type TDashboardWidgetKind =
+  | 'agentRoster'
+  | 'approvalQueue'
+  | 'deviceGrid'
+  | 'floorPlan'
+  | 'timeline'
+  | 'activityStream'
+  | 'energyChart'
+  | 'custom';
+
+export interface IDashboardWidget {
+  id: string;
+  kind: TDashboardWidgetKind;
+  title: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  config: Record<string, unknown>;
+}
+
+export interface IDashboardDefinition {
+  id: string;
+  homeId: string;
+  name: string;
+  widgets: IDashboardWidget[];
+}

ts/data/device.ts

@@ -0,0 +1,64 @@
+export type TDeviceProtocol =
+  | 'matter'
+  | 'zigbee'
+  | 'zwave'
+  | 'thread'
+  | 'mqtt'
+  | 'homekit'
+  | 'esphome'
+  | 'homeassistant'
+  | 'hue'
+  | 'http'
+  | 'cloud'
+  | 'virtual'
+  | 'unknown';
+
+export type TDeviceCapability =
+  | 'switch'
+  | 'sensor'
+  | 'light'
+  | 'cover'
+  | 'lock'
+  | 'fan'
+  | 'climate'
+  | 'camera'
+  | 'media'
+  | 'energy'
+  | 'notification';
+
+export type TDeviceStateValue = string | number | boolean | null | Record<string, unknown>;
+
+export interface IDeviceFeature {
+  id: string;
+  capability: TDeviceCapability;
+  name: string;
+  readable: boolean;
+  writable: boolean;
+  unit?: string;
+}
+
+export interface IDeviceState {
+  featureId: string;
+  value: TDeviceStateValue;
+  updatedAt: string;
+}
+
+export interface IDeviceDefinition {
+  id: string;
+  integrationDomain?: string;
+  name: string;
+  room?: string;
+  protocol: TDeviceProtocol;
+  manufacturer?: string;
+  model?: string;
+  online: boolean;
+  features: IDeviceFeature[];
+  state: IDeviceState[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface IRoomDefinition {
+  id: string;
+  name: string;
+  floor?: string;
+}

ts/data/home.ts

@@ -0,0 +1,34 @@
+import type { IAgentDefinition, IAgentStatus } from './agent.js';
+import type { IAuditReceipt } from './audit.js';
+import type { IDashboardDefinition } from './dashboard.js';
+import type { IDeviceDefinition, IRoomDefinition } from './device.js';
+import type { IApprovalRequest } from './tool.js';
+
+export interface IHomeMember {
+  id: string;
+  name: string;
+  initials: string;
+  present: boolean;
+  locationLabel?: string;
+  eta?: string;
+}
+
+export interface IHomeDefinition {
+  id: string;
+  name: string;
+  address?: string;
+  timezone: string;
+  members: IHomeMember[];
+  rooms: IRoomDefinition[];
+}
+
+export interface IHomeSnapshot {
+  home: IHomeDefinition;
+  devices: IDeviceDefinition[];
+  agents: IAgentDefinition[];
+  agentStatuses: IAgentStatus[];
+  approvals: IApprovalRequest[];
+  dashboards: IDashboardDefinition[];
+  receipts: IAuditReceipt[];
+  createdAt: string;
+}

ts/data/index.ts

@@ -0,0 +1,7 @@
+export * from './agent.js';
+export * from './audit.js';
+export * from './automation.js';
+export * from './dashboard.js';
+export * from './device.js';
+export * from './home.js';
+export * from './tool.js';

ts/data/tool.ts

@@ -0,0 +1,74 @@
+import type { TAgentMode } from './agent.js';
+
+export type TToolScope =
+  | '*.read'
+  | 'device.read'
+  | 'device.write'
+  | 'light.read'
+  | 'light.write'
+  | 'climate.read'
+  | 'climate.write'
+  | 'energy.read'
+  | 'energy.write'
+  | 'lock.read'
+  | 'lock.write'
+  | 'camera.read'
+  | 'alarm.write'
+  | 'agent.invoke'
+  | 'automation.write'
+  | 'approval.write';
+
+export type TToolJsonSchema = Record<string, unknown>;
+
+export interface IToolDefinition {
+  id: string;
+  ownerId: string;
+  name: string;
+  description: string;
+  inputSchema: TToolJsonSchema;
+  requiredScopes: TToolScope[];
+  mode: TAgentMode;
+}
+
+export interface IToolCall {
+  id: string;
+  toolId: string;
+  callerId: string;
+  input: Record<string, unknown>;
+}
+
+export interface IToolPlan {
+  id: string;
+  callerId: string;
+  title: string;
+  reason: string;
+  confidence: number;
+  calls: IToolCall[];
+}
+
+export interface IToolExecutionResult {
+  callId: string;
+  status: 'executed' | 'queuedForApproval' | 'suggested' | 'failed';
+  output?: Record<string, unknown>;
+  approvalId?: string;
+  errorMessage?: string;
+}
+
+export interface IToolPlanResult {
+  planId: string;
+  results: IToolExecutionResult[];
+}
+
+export interface IApprovalRequest {
+  id: string;
+  planId: string;
+  callId: string;
+  agentId: string;
+  title: string;
+  reason: string;
+  confidence: number;
+  requestedScopes: TToolScope[];
+  status: 'pending' | 'approved' | 'rejected' | 'expired';
+  createdAt: string;
+  decidedAt?: string;
+}

ts/index.ts

@@ -0,0 +1,4 @@
+import * as data from './data/index.js';
+import * as request from './request/index.js';
+
+export { data, request };

ts/plugins.ts

@@ -0,0 +1,9 @@
+// @api.global scope
+import * as typedRequestInterfaces from '@api.global/typedrequest-interfaces';
+
+export { typedRequestInterfaces };
+
+// @tsclass scope
+import * as tsclass from '@tsclass/tsclass';
+
+export { tsclass };

ts/request/agent.ts

@@ -0,0 +1,15 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListAgents
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListAgents
+  > {
+  method: 'listAgents';
+  request: {};
+  response: {
+    agents: data.IAgentDefinition[];
+    statuses: data.IAgentStatus[];
+  };
+}

ts/request/approval.ts

@@ -0,0 +1,32 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListApprovals
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListApprovals
+  > {
+  method: 'listApprovals';
+  request: {
+    status?: data.IApprovalRequest['status'];
+  };
+  response: {
+    approvals: data.IApprovalRequest[];
+  };
+}
+
+export interface IReq_SubmitApproval
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_SubmitApproval
+  > {
+  method: 'submitApproval';
+  request: {
+    approvalId: string;
+    decision: 'approved' | 'rejected';
+  };
+  response: {
+    approval: data.IApprovalRequest;
+    receipt: data.IAuditReceipt;
+  };
+}

ts/request/device.ts

@@ -0,0 +1,17 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListDevices
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListDevices
+  > {
+  method: 'listDevices';
+  request: {
+    room?: string;
+    capability?: data.TDeviceCapability;
+  };
+  response: {
+    devices: data.IDeviceDefinition[];
+  };
+}

ts/request/home.ts

@@ -0,0 +1,14 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetHomeSnapshot
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_GetHomeSnapshot
+  > {
+  method: 'getHomeSnapshot';
+  request: {};
+  response: {
+    snapshot: data.IHomeSnapshot;
+  };
+}

ts/request/index.ts

@@ -0,0 +1,5 @@
+export * from './agent.js';
+export * from './approval.js';
+export * from './device.js';
+export * from './home.js';
+export * from './tool.js';

ts/request/tool.ts

@@ -0,0 +1,28 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListTools
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListTools
+  > {
+  method: 'listTools';
+  request: {
+    ownerId?: string;
+  };
+  response: {
+    tools: data.IToolDefinition[];
+  };
+}
+
+export interface IReq_ExecuteToolPlan
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ExecuteToolPlan
+  > {
+  method: 'executeToolPlan';
+  request: {
+    plan: data.IToolPlan;
+  };
+  response: data.IToolPlanResult;
+}