@contractspec/example.agent-console 1.44.0

package/src/tool/tool.event.ts

@@ -0,0 +1,119 @@
+import { defineEvent, defineSchemaModel } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const OWNERS = ['@agent-console-team'] as const;
+
+/**
+ * Payload for tool created event.
+ */
+const ToolCreatedPayload = defineSchemaModel({
+  name: 'ToolCreatedPayload',
+  description: 'Payload for tool created event',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    implementationType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    createdById: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * ToolCreatedEvent - A new tool was created.
+ */
+export const ToolCreatedEvent = defineEvent({
+  meta: {
+    key: 'agent.tool.created',
+    version: 1,
+    description: 'A new AI tool was created.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'created'],
+  },
+  payload: ToolCreatedPayload,
+});
+
+/**
+ * Payload for tool updated event.
+ */
+const ToolUpdatedPayload = defineSchemaModel({
+  name: 'ToolUpdatedPayload',
+  description: 'Payload for tool updated event',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    updatedFields: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * ToolUpdatedEvent - A tool was updated.
+ */
+export const ToolUpdatedEvent = defineEvent({
+  meta: {
+    key: 'agent.tool.updated',
+    version: 1,
+    description: 'An AI tool configuration was updated.',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'updated'],
+  },
+  payload: ToolUpdatedPayload,
+});
+
+/**
+ * Payload for tool status changed event.
+ */
+const ToolStatusChangedPayload = defineSchemaModel({
+  name: 'ToolStatusChangedPayload',
+  description: 'Payload for tool status changed event',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    previousStatus: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    newStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * ToolStatusChangedEvent - A tool's status was changed.
+ */
+export const ToolStatusChangedEvent = defineEvent({
+  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,
+});

package/src/tool/tool.handler.ts

@@ -0,0 +1,154 @@
+/**
+ * Mock handlers for Tool contracts.
+ */
+import { MOCK_TOOLS } from '../shared/mock-tools';
+
+export interface ListToolsInput {
+  organizationId: string;
+  category?:
+    | 'RETRIEVAL'
+    | 'COMPUTATION'
+    | 'COMMUNICATION'
+    | 'INTEGRATION'
+    | 'UTILITY'
+    | 'CUSTOM';
+  status?: 'DRAFT' | 'ACTIVE' | 'DEPRECATED' | 'DISABLED';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ToolSummary {
+  id: string;
+  name: string;
+  slug: string;
+  description: string;
+  category:
+    | 'RETRIEVAL'
+    | 'COMPUTATION'
+    | 'COMMUNICATION'
+    | 'INTEGRATION'
+    | 'UTILITY'
+    | 'CUSTOM';
+  status: 'DRAFT' | 'ACTIVE' | 'DEPRECATED' | 'DISABLED';
+  version: string;
+  createdAt: Date;
+}
+
+export interface ListToolsOutput {
+  items: ToolSummary[];
+  total: number;
+  hasMore: boolean;
+}
+
+/**
+ * Mock handler for ListToolsQuery.
+ */
+export async function mockListToolsHandler(
+  input: ListToolsInput
+): Promise<ListToolsOutput> {
+  const {
+    organizationId,
+    category,
+    status,
+    search,
+    limit = 20,
+    offset = 0,
+  } = input;
+
+  let filtered = MOCK_TOOLS.filter((t) => t.organizationId === organizationId);
+  if (category) filtered = filtered.filter((t) => t.category === category);
+  if (status) filtered = filtered.filter((t) => t.status === status);
+  if (search) {
+    const q = search.toLowerCase();
+    filtered = filtered.filter(
+      (t) =>
+        t.name.toLowerCase().includes(q) ||
+        t.description.toLowerCase().includes(q)
+    );
+  }
+
+  const total = filtered.length;
+  const items = filtered.slice(offset, offset + limit).map((t) => ({
+    id: t.id,
+    name: t.name,
+    slug: t.slug,
+    description: t.description,
+    category: t.category,
+    status: t.status,
+    version: t.version,
+    createdAt: t.createdAt,
+  }));
+
+  return { items, total, hasMore: offset + limit < total };
+}
+
+/**
+ * Mock handler for GetToolQuery.
+ */
+export async function mockGetToolHandler(input: { toolId: string }) {
+  const tool = MOCK_TOOLS.find((t) => t.id === input.toolId);
+  if (!tool) throw new Error('TOOL_NOT_FOUND');
+  return tool;
+}
+
+/**
+ * Mock handler for CreateToolCommand.
+ */
+export async function mockCreateToolHandler(input: {
+  organizationId: string;
+  name: string;
+  slug: string;
+  description: string;
+  implementationType: 'http' | 'function' | 'workflow';
+}) {
+  const exists = MOCK_TOOLS.some(
+    (t) => t.organizationId === input.organizationId && t.slug === input.slug
+  );
+  if (exists) throw new Error('SLUG_EXISTS');
+  return {
+    id: `tool-${Date.now()}`,
+    name: input.name,
+    slug: input.slug,
+    status: 'DRAFT' as const,
+  };
+}
+
+/**
+ * Mock handler for UpdateToolCommand.
+ */
+export async function mockUpdateToolHandler(input: {
+  toolId: string;
+  name?: string;
+  status?: 'DRAFT' | 'ACTIVE' | 'DEPRECATED' | 'DISABLED';
+}) {
+  const tool = MOCK_TOOLS.find((t) => t.id === input.toolId);
+  if (!tool) throw new Error('TOOL_NOT_FOUND');
+  return {
+    id: tool.id,
+    name: input.name ?? tool.name,
+    status: input.status ?? tool.status,
+    updatedAt: new Date(),
+  };
+}
+
+/**
+ * Mock handler for TestToolCommand.
+ */
+export async function mockTestToolHandler(input: {
+  toolId: string;
+  testInput: Record<string, unknown>;
+}) {
+  const tool = MOCK_TOOLS.find((t) => t.id === input.toolId);
+  if (!tool) throw new Error('TOOL_NOT_FOUND');
+
+  // Simulate tool execution
+  const startTime = Date.now();
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  return {
+    success: true,
+    output: { result: 'Test successful', input: input.testInput },
+    durationMs: Date.now() - startTime,
+  };
+}

package/src/tool/tool.operation.ts

@@ -0,0 +1,366 @@
+import {
+  defineCommand,
+  defineQuery,
+} from '@contractspec/lib.contracts/operations';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import { ToolCategoryEnum, ToolStatusEnum } from './tool.enum';
+import {
+  CreateToolInputModel,
+  ToolModel,
+  ToolSummaryModel,
+  UpdateToolInputModel,
+} from './tool.schema';
+
+const OWNERS = ['@agent-console-team'] as const;
+
+/**
+ * CreateToolCommand - Creates a new tool definition.
+ */
+export const CreateToolCommand = defineCommand({
+  meta: {
+    key: 'agent.tool.create',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'create'],
+    description: 'Creates a new AI tool definition.',
+    goal: 'Allow users to define new tools that agents can use.',
+    context: 'Called from the tool builder UI when creating a new tool.',
+  },
+  io: {
+    input: CreateToolInputModel,
+    output: defineSchemaModel({
+      name: 'CreateToolOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        status: { type: ToolStatusEnum, isOptional: false },
+      },
+    }),
+    errors: {
+      SLUG_EXISTS: {
+        description: 'A tool with this slug already exists in the organization',
+        http: 409,
+        gqlCode: 'SLUG_EXISTS',
+        when: 'Slug is already taken',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: {
+    emits: [
+      {
+        key: 'tool.created',
+        version: 1,
+        stability: 'stable',
+        owners: [...OWNERS],
+        tags: ['tool', 'created'],
+        when: 'Tool is successfully created',
+        payload: ToolSummaryModel,
+      },
+    ],
+    audit: ['tool.created'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'create-tool-happy-path',
+        given: ['User is authenticated', 'Organization exists'],
+        when: ['User submits valid tool configuration'],
+        then: ['New tool is created', 'ToolCreated event is emitted'],
+      },
+      {
+        key: 'create-tool-slug-conflict',
+        given: ['Tool with same slug exists'],
+        when: ['User submits tool with duplicate slug'],
+        then: ['SLUG_EXISTS error is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'create-api-tool',
+        input: {
+          name: 'Weather API',
+          slug: 'weather-api',
+          category: 'api',
+          description: 'Fetches weather data',
+        },
+        output: {
+          id: 'tool-123',
+          name: 'Weather API',
+          slug: 'weather-api',
+          status: 'draft',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * UpdateToolCommand - Updates an existing tool.
+ */
+export const UpdateToolCommand = defineCommand({
+  meta: {
+    key: 'agent.tool.update',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'update'],
+    description: 'Updates an existing AI tool definition.',
+    goal: 'Allow users to modify tool settings and configuration.',
+    context: 'Called from the tool settings UI.',
+  },
+  io: {
+    input: UpdateToolInputModel,
+    output: defineSchemaModel({
+      name: 'UpdateToolOutput',
+      fields: {
+        id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+        status: { type: ToolStatusEnum, isOptional: false },
+        updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+      },
+    }),
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: {
+    emits: [
+      {
+        key: 'tool.updated',
+        version: 1,
+        stability: 'stable',
+        owners: [...OWNERS],
+        tags: ['tool', 'updated'],
+        when: 'Tool is updated',
+        payload: ToolSummaryModel,
+      },
+    ],
+    audit: ['tool.updated'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'update-tool-happy-path',
+        given: ['Tool exists', 'User owns the tool'],
+        when: ['User submits updated configuration'],
+        then: ['Tool is updated', 'ToolUpdated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'update-description',
+        input: { toolId: 'tool-123', description: 'Updated weather API tool' },
+        output: {
+          id: 'tool-123',
+          name: 'Weather API',
+          status: 'draft',
+          updatedAt: '2025-01-01T00:00:00Z',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * GetToolQuery - Retrieves a tool by ID.
+ */
+export const GetToolQuery = defineQuery({
+  meta: {
+    key: 'agent.tool.get',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'get'],
+    description: 'Retrieves a tool by its ID.',
+    goal: 'View detailed tool configuration.',
+    context: 'Called when viewing tool details or editing.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'GetToolInput',
+      fields: {
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      },
+    }),
+    output: ToolModel,
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-tool-happy-path',
+        given: ['Tool exists'],
+        when: ['User requests tool by ID'],
+        then: ['Tool details are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-basic',
+        input: { toolId: 'tool-123' },
+        output: {
+          id: 'tool-123',
+          name: 'Weather API',
+          status: 'active',
+          category: 'api',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * ListToolsQuery - Lists tools for an organization.
+ */
+export const ListToolsQuery = defineQuery({
+  meta: {
+    key: 'agent.tool.list',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'list'],
+    description: 'Lists tools for an organization with optional filtering.',
+    goal: 'Browse and search available tools.',
+    context: 'Tool list/dashboard view.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'ListToolsInput',
+      fields: {
+        organizationId: {
+          type: ScalarTypeEnum.String_unsecure(),
+          isOptional: false,
+        },
+        category: { type: ToolCategoryEnum, isOptional: true },
+        status: { type: ToolStatusEnum, isOptional: true },
+        search: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+        limit: {
+          type: ScalarTypeEnum.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 20,
+        },
+        offset: {
+          type: ScalarTypeEnum.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 0,
+        },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'ListToolsOutput',
+      fields: {
+        items: { type: ToolSummaryModel, isArray: true, isOptional: false },
+        total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+        hasMore: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: 'user' },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'list-tools-happy-path',
+        given: ['Organization has tools'],
+        when: ['User lists tools'],
+        then: ['Paginated list of tools is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'list-by-category',
+        input: { organizationId: 'org-123', category: 'api', limit: 10 },
+        output: { items: [], total: 0, hasMore: false },
+      },
+    ],
+  },
+});
+
+/**
+ * TestToolCommand - Tests a tool with sample input.
+ */
+export const TestToolCommand = defineCommand({
+  meta: {
+    key: 'agent.tool.test',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['tool', 'test'],
+    description: 'Tests a tool with sample input to verify it works correctly.',
+    goal: 'Validate tool configuration before deployment.',
+    context: 'Tool builder UI - test panel.',
+  },
+  io: {
+    input: defineSchemaModel({
+      name: 'TestToolInput',
+      fields: {
+        toolId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+        testInput: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+      },
+    }),
+    output: defineSchemaModel({
+      name: 'TestToolOutput',
+      fields: {
+        success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+        output: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+        error: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+        durationMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+      },
+    }),
+    errors: {
+      TOOL_NOT_FOUND: {
+        description: 'The specified tool does not exist',
+        http: 404,
+        gqlCode: 'TOOL_NOT_FOUND',
+        when: 'Tool ID is invalid',
+      },
+      TOOL_EXECUTION_ERROR: {
+        description: 'Tool execution failed',
+        http: 500,
+        gqlCode: 'TOOL_EXECUTION_ERROR',
+        when: 'Tool returns an error',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+  sideEffects: { audit: ['tool.tested'] },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'test-tool-success',
+        given: ['Tool exists', 'Tool is configured correctly'],
+        when: ['User runs test with valid input'],
+        then: ['Tool executes successfully', 'Output is returned'],
+      },
+      {
+        key: 'test-tool-failure',
+        given: ['Tool exists', 'Tool has configuration error'],
+        when: ['User runs test'],
+        then: ['TOOL_EXECUTION_ERROR is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'test-weather-api',
+        input: { toolId: 'tool-123', testInput: { city: 'Paris' } },
+        output: { success: true, output: { temperature: 22 }, durationMs: 150 },
+      },
+    ],
+  },
+});

package/src/tool/tool.presentation.ts

@@ -0,0 +1,56 @@
+import type { PresentationSpec } from '@contractspec/lib.contracts';
+import { StabilityEnum } from '@contractspec/lib.contracts';
+import { ToolSummaryModel } from './tool.schema';
+
+/**
+ * Presentation for displaying a list of tools.
+ */
+export const ToolListPresentation: PresentationSpec = {
+  meta: {
+    key: 'agent-console.tool.list',
+    version: 1,
+    title: 'Tool List',
+    description:
+      'List view of AI tools with category, status, and version info',
+    goal: 'Provide an overview of all available tools for agents.',
+    context: 'Tool management dashboard.',
+    domain: 'agent-console',
+    owners: ['@agent-console-team'],
+    tags: ['tool', 'list', 'dashboard'],
+    stability: StabilityEnum.Experimental,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ToolListView',
+    props: ToolSummaryModel,
+  },
+  targets: ['react', 'markdown', 'application/json'],
+  policy: { flags: ['agent-console.enabled'] },
+};
+
+/**
+ * Presentation for tool detail view.
+ */
+export const ToolDetailPresentation: PresentationSpec = {
+  meta: {
+    key: 'agent-console.tool.detail',
+    version: 1,
+    title: 'Tool Details',
+    description:
+      'Detailed view of an AI tool with configuration and test panel',
+    goal: 'Allow users to inspect and test a specific tool.',
+    context: 'Detailed view of a tool.',
+    domain: 'agent-console',
+    owners: ['@agent-console-team'],
+    tags: ['tool', 'detail'],
+    stability: StabilityEnum.Experimental,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ToolDetailView',
+  },
+  targets: ['react', 'markdown'],
+  policy: { flags: ['agent-console.enabled'] },
+};