@lssm/example.agent-console 1.41.0 → 1.42.2

package/src/run/run.event.ts

@@ -1,6 +1,8 @@
 import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
 import { ScalarTypeEnum, defineEnum } from '@lssm/lib.schema';
 
+const OWNERS = ['@agent-console-team'] as const;
+
 /**
  * Payload for run started event.
  */
@@ -26,9 +28,14 @@ const RunStartedPayload = defineSchemaModel({
  * RunStartedEvent - An agent run was started.
  */
 export const RunStartedEvent = defineEvent({
-  name: 'agent.run.started',
-  version: 1,
-  description: 'An agent run was started.',
+  meta: {
+    key: 'agent.run.started',
+    version: 1,
+    description: 'An agent run was started.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'started'],
+  },
   payload: RunStartedPayload,
 });
 
@@ -68,9 +75,14 @@ const RunCompletedPayload = defineSchemaModel({
  * RunCompletedEvent - An agent run completed successfully.
  */
 export const RunCompletedEvent = defineEvent({
-  name: 'agent.run.completed',
-  version: 1,
-  description: 'An agent run completed successfully.',
+  meta: {
+    key: 'agent.run.completed',
+    version: 1,
+    description: 'An agent run completed successfully.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'completed'],
+  },
   payload: RunCompletedPayload,
 });
 
@@ -102,9 +114,14 @@ const RunFailedPayload = defineSchemaModel({
  * RunFailedEvent - An agent run failed.
  */
 export const RunFailedEvent = defineEvent({
-  name: 'agent.run.failed',
-  version: 1,
-  description: 'An agent run encountered an error.',
+  meta: {
+    key: 'agent.run.failed',
+    version: 1,
+    description: 'An agent run encountered an error.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'failed'],
+  },
   payload: RunFailedPayload,
 });
 
@@ -134,9 +151,14 @@ const RunCancelledPayload = defineSchemaModel({
  * RunCancelledEvent - An agent run was cancelled.
  */
 export const RunCancelledEvent = defineEvent({
-  name: 'agent.run.cancelled',
-  version: 1,
-  description: 'An agent run was cancelled by the user.',
+  meta: {
+    key: 'agent.run.cancelled',
+    version: 1,
+    description: 'An agent run was cancelled by the user.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'cancelled'],
+  },
   payload: RunCancelledPayload,
 });
 
@@ -160,9 +182,14 @@ const ToolInvokedPayload = defineSchemaModel({
  * ToolInvokedEvent - A tool was invoked during a run.
  */
 export const ToolInvokedEvent = defineEvent({
-  name: 'agent.run.toolInvoked',
-  version: 1,
-  description: 'A tool was invoked during an agent run.',
+  meta: {
+    key: 'agent.run.toolInvoked',
+    version: 1,
+    description: 'A tool was invoked during an agent run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'tool', 'invoked'],
+  },
   payload: ToolInvokedPayload,
 });
 
@@ -189,9 +216,14 @@ const ToolCompletedPayload = defineSchemaModel({
  * ToolCompletedEvent - A tool invocation completed.
  */
 export const ToolCompletedEvent = defineEvent({
-  name: 'agent.run.toolCompleted',
-  version: 1,
-  description: 'A tool invocation completed during an agent run.',
+  meta: {
+    key: 'agent.run.toolCompleted',
+    version: 1,
+    description: 'A tool invocation completed during an agent run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'tool', 'completed'],
+  },
   payload: ToolCompletedPayload,
 });
 
@@ -220,8 +252,13 @@ const MessageGeneratedPayload = defineSchemaModel({
  * MessageGeneratedEvent - Agent generated a message.
  */
 export const MessageGeneratedEvent = defineEvent({
-  name: 'agent.run.messageGenerated',
-  version: 1,
-  description: 'An agent generated a message during a run.',
+  meta: {
+    key: 'agent.run.messageGenerated',
+    version: 1,
+    description: 'An agent generated a message during a run.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['run', 'message', 'generated'],
+  },
   payload: MessageGeneratedPayload,
 });

package/src/run/{run.contracts.ts → run.operation.ts}

@@ -1,23 +1,23 @@
-import { defineCommand, defineQuery } from '@lssm/lib.contracts/spec';
+import { defineCommand, defineQuery } from '@lssm/lib.contracts/operations';
 import { defineSchemaModel, ScalarTypeEnum } from '@lssm/lib.schema';
-import { RunStatusEnum, LogLevelEnum, GranularityEnum } from './run.enum';
+import { GranularityEnum, LogLevelEnum, RunStatusEnum } from './run.enum';
 import {
   RunInputModel,
+  RunLogModel,
   RunModel,
-  RunSummaryModel,
   RunStepModel,
-  RunLogModel,
+  RunSummaryModel,
   TimelineDataPointModel,
 } from './run.schema';
 
-const OWNERS = ['agent-console-team'] as const;
+const OWNERS = ['@agent-console-team'] as const;
 
 /**
  * ExecuteAgentCommand - Starts a new agent run.
  */
 export const ExecuteAgentCommand = defineCommand({
   meta: {
-    name: 'agent.run.execute',
+    key: 'agent.run.execute',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -72,14 +72,40 @@ export const ExecuteAgentCommand = defineCommand({
   sideEffects: {
     emits: [
       {
-        name: 'run.started',
+        key: 'run.started',
         version: 1,
+        stability: 'stable',
+        owners: [...OWNERS],
+        tags: ['run', 'started'],
         when: 'Run is queued',
         payload: RunSummaryModel,
       },
     ],
     audit: ['run.started'],
   },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'execute-agent-happy-path',
+        given: ['Agent exists', 'Agent is active'],
+        when: ['User submits execution request'],
+        then: ['Run is created', 'RunStarted event is emitted'],
+      },
+      {
+        key: 'execute-agent-not-active',
+        given: ['Agent exists but is not active'],
+        when: ['User attempts to execute'],
+        then: ['AGENT_NOT_ACTIVE error is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'basic-execute',
+        input: { agentId: 'agent-123', input: { message: 'Hello' } },
+        output: { runId: 'run-456', status: 'pending', estimatedWaitMs: 5000 },
+      },
+    ],
+  },
 });
 
 /**
@@ -87,7 +113,7 @@ export const ExecuteAgentCommand = defineCommand({
  */
 export const CancelRunCommand = defineCommand({
   meta: {
-    name: 'agent.run.cancel',
+    key: 'agent.run.cancel',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -130,14 +156,40 @@ export const CancelRunCommand = defineCommand({
   sideEffects: {
     emits: [
       {
-        name: 'run.cancelled',
+        key: 'run.cancelled',
         version: 1,
+        stability: 'stable',
+        owners: [...OWNERS],
+        tags: ['run', 'cancelled'],
         when: 'Run is cancelled',
         payload: RunSummaryModel,
       },
     ],
     audit: ['run.cancelled'],
   },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'cancel-run-happy-path',
+        given: ['Run exists', 'Run is in progress'],
+        when: ['User cancels run'],
+        then: ['Run is cancelled', 'RunCancelled event is emitted'],
+      },
+      {
+        key: 'cancel-run-already-completed',
+        given: ['Run exists but is already completed'],
+        when: ['User attempts to cancel'],
+        then: ['RUN_NOT_CANCELLABLE error is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'cancel-basic',
+        input: { runId: 'run-456', reason: 'User requested' },
+        output: { success: true, status: 'cancelled' },
+      },
+    ],
+  },
 });
 
 /**
@@ -145,7 +197,7 @@ export const CancelRunCommand = defineCommand({
  */
 export const GetRunQuery = defineQuery({
   meta: {
-    name: 'agent.run.get',
+    key: 'agent.run.get',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -174,6 +226,23 @@ export const GetRunQuery = defineQuery({
     },
   },
   policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-run-happy-path',
+        given: ['Run exists'],
+        when: ['User requests run by ID'],
+        then: ['Run details are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-with-steps',
+        input: { runId: 'run-456', includeSteps: true, includeLogs: false },
+        output: { id: 'run-456', status: 'completed', steps: [] },
+      },
+    ],
+  },
 });
 
 /**
@@ -181,7 +250,7 @@ export const GetRunQuery = defineQuery({
  */
 export const ListRunsQuery = defineQuery({
   meta: {
-    name: 'agent.run.list',
+    key: 'agent.run.list',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -226,6 +295,23 @@ export const ListRunsQuery = defineQuery({
     }),
   },
   policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'list-runs-happy-path',
+        given: ['Organization has runs'],
+        when: ['User lists runs'],
+        then: ['Paginated list of runs is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'list-by-agent',
+        input: { agentId: 'agent-123', limit: 20, offset: 0 },
+        output: { items: [], total: 0, hasMore: false },
+      },
+    ],
+  },
 });
 
 /**
@@ -233,7 +319,7 @@ export const ListRunsQuery = defineQuery({
  */
 export const GetRunStepsQuery = defineQuery({
   meta: {
-    name: 'agent.run.getSteps',
+    key: 'agent.run.getSteps',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -257,6 +343,23 @@ export const GetRunStepsQuery = defineQuery({
     }),
   },
   policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-run-steps-happy-path',
+        given: ['Run exists with steps'],
+        when: ['User requests steps'],
+        then: ['Steps list is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-steps-basic',
+        input: { runId: 'run-456' },
+        output: { steps: [] },
+      },
+    ],
+  },
 });
 
 /**
@@ -264,7 +367,7 @@ export const GetRunStepsQuery = defineQuery({
  */
 export const GetRunLogsQuery = defineQuery({
   meta: {
-    name: 'agent.run.getLogs',
+    key: 'agent.run.getLogs',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -302,6 +405,23 @@ export const GetRunLogsQuery = defineQuery({
     }),
   },
   policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-run-logs-happy-path',
+        given: ['Run exists with logs'],
+        when: ['User requests logs'],
+        then: ['Paginated logs list is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-logs-filtered',
+        input: { runId: 'run-456', level: 'error', limit: 50 },
+        output: { items: [], total: 0, hasMore: false },
+      },
+    ],
+  },
 });
 
 /**
@@ -309,7 +429,7 @@ export const GetRunLogsQuery = defineQuery({
  */
 export const GetRunMetricsQuery = defineQuery({
   meta: {
-    name: 'agent.run.getMetrics',
+    key: 'agent.run.getMetrics',
     version: 1,
     stability: 'stable',
     owners: [...OWNERS],
@@ -367,4 +487,35 @@ export const GetRunMetricsQuery = defineQuery({
     }),
   },
   policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-run-metrics-happy-path',
+        given: ['Organization has run history'],
+        when: ['User requests metrics for date range'],
+        then: ['Aggregated metrics are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-daily-metrics',
+        input: {
+          organizationId: 'org-123',
+          startDate: '2025-01-01',
+          endDate: '2025-01-31',
+          granularity: 'day',
+        },
+        output: {
+          totalRuns: 100,
+          completedRuns: 90,
+          failedRuns: 10,
+          totalTokens: 50000,
+          totalCostUsd: 5.0,
+          averageDurationMs: 2500,
+          successRate: 0.9,
+          timeline: [],
+        },
+      },
+    ],
+  },
 });

package/src/run/run.presentation.ts

@@ -1,18 +1,23 @@
-import type { PresentationDescriptorV2 } from '@lssm/lib.contracts';
+import type { PresentationSpec } from '@lssm/lib.contracts';
+import { StabilityEnum } from '@lssm/lib.contracts';
 import { RunSummaryModel } from './run.schema';
 
 /**
  * Presentation for displaying a list of agent runs.
  */
-export const RunListPresentation: PresentationDescriptorV2 = {
+export const RunListPresentation: PresentationSpec = {
   meta: {
-    name: 'agent-console.run.list',
+    key: 'agent-console.run.list',
     version: 1,
+    title: 'Run List',
     description:
       'List view of agent runs with status, tokens, and duration info',
+    goal: 'Provide an overview of agent execution history and performance.',
+    context: 'Run history dashboard.',
     domain: 'agent-console',
     owners: ['@agent-console-team'],
     tags: ['run', 'list', 'dashboard'],
+    stability: StabilityEnum.Experimental,
   },
   source: {
     type: 'component',
@@ -27,14 +32,18 @@ export const RunListPresentation: PresentationDescriptorV2 = {
 /**
  * Presentation for run detail view.
  */
-export const RunDetailPresentation: PresentationDescriptorV2 = {
+export const RunDetailPresentation: PresentationSpec = {
   meta: {
-    name: 'agent-console.run.detail',
+    key: 'agent-console.run.detail',
     version: 1,
+    title: 'Run Details',
     description: 'Detailed view of an agent run with steps, logs, and metrics',
+    goal: 'Allow users to inspect and debug a specific agent run.',
+    context: 'Detailed view of an agent run.',
     domain: 'agent-console',
     owners: ['@agent-console-team'],
     tags: ['run', 'detail'],
+    stability: StabilityEnum.Experimental,
   },
   source: {
     type: 'component',

package/src/tool/index.ts

@@ -24,7 +24,7 @@ export {
   GetToolQuery,
   ListToolsQuery,
   TestToolCommand,
-} from './tool.contracts';
+} from './tool.operation';
 
 // Events
 export {

package/src/tool/tool.entity.ts

@@ -1,9 +1,4 @@
-import {
-  defineEntity,
-  defineEntityEnum,
-  field,
-  index,
-} from '@lssm/lib.schema/entity';
+import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
 
 /**
  * Tool category enum for entities.

package/src/tool/tool.event.ts

@@ -1,6 +1,8 @@
 import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
 import { ScalarTypeEnum } from '@lssm/lib.schema';
 
+const OWNERS = ['@agent-console-team'] as const;
+
 /**
  * Payload for tool created event.
  */
@@ -29,9 +31,14 @@ const ToolCreatedPayload = defineSchemaModel({
  * ToolCreatedEvent - A new tool was created.
  */
 export const ToolCreatedEvent = defineEvent({
-  name: 'agent.tool.created',
-  version: 1,
-  description: 'A new AI tool was created.',
+  meta: {
+    key: 'agent.tool.created',
+    version: 1,
+    description: 'A new AI tool was created.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'created'],
+  },
   payload: ToolCreatedPayload,
 });
 
@@ -62,9 +69,14 @@ const ToolUpdatedPayload = defineSchemaModel({
  * ToolUpdatedEvent - A tool was updated.
  */
 export const ToolUpdatedEvent = defineEvent({
-  name: 'agent.tool.updated',
-  version: 1,
-  description: 'An AI tool configuration was updated.',
+  meta: {
+    key: 'agent.tool.updated',
+    version: 1,
+    description: 'An AI tool configuration was updated.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'updated'],
+  },
   payload: ToolUpdatedPayload,
 });
 
@@ -94,9 +106,14 @@ const ToolStatusChangedPayload = defineSchemaModel({
  * ToolStatusChangedEvent - A tool's status was changed.
  */
 export const ToolStatusChangedEvent = defineEvent({
-  name: 'agent.tool.statusChanged',
-  version: 1,
-  description:
-    'An AI tool status was changed (activated, deprecated, disabled).',
+  meta: {
+    key: 'agent.tool.statusChanged',
+    version: 1,
+    description:
+      'An AI tool status was changed (activated, deprecated, disabled).',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'status'],
+  },
   payload: ToolStatusChangedPayload,
 });