@contractspec/example.agent-console 1.44.0

package/src/agent/agent.schema.ts

@@ -0,0 +1,214 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import {
+  AgentStatusEnum,
+  ModelProviderEnum,
+  ToolChoiceEnum,
+} from './agent.enum';
+
+/**
+ * AI agent configuration schema.
+ */
+export const AgentModel = defineSchemaModel({
+  name: 'Agent',
+  description: 'AI agent configuration',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: AgentStatusEnum, isOptional: false },
+    modelProvider: { type: ModelProviderEnum, isOptional: false },
+    modelName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    modelConfig: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    systemPrompt: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userPromptTemplate: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    toolIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    toolChoice: {
+      type: ToolChoiceEnum,
+      isOptional: false,
+      defaultValue: 'auto',
+    },
+    maxIterations: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false,
+      defaultValue: 10,
+    },
+    maxTokensPerRun: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeoutMs: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false,
+      defaultValue: 120000,
+    },
+    version: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Summary of an agent for list views.
+ */
+export const AgentSummaryModel = defineSchemaModel({
+  name: 'AgentSummary',
+  description: 'Summary of an agent for list views',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: AgentStatusEnum, isOptional: false },
+    modelProvider: { type: ModelProviderEnum, isOptional: false },
+    modelName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    version: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Tool reference in agent context.
+ */
+export const AgentToolRefModel = defineSchemaModel({
+  name: 'AgentToolRef',
+  description: 'Tool reference in agent context',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Agent with associated tools.
+ */
+export const AgentWithToolsModel = defineSchemaModel({
+  name: 'AgentWithTools',
+  description: 'Agent with associated tools',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: AgentStatusEnum, isOptional: false },
+    modelProvider: { type: ModelProviderEnum, isOptional: false },
+    modelName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    modelConfig: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    systemPrompt: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userPromptTemplate: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    toolIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    toolChoice: { type: ToolChoiceEnum, isOptional: false },
+    maxIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    maxTokensPerRun: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    tools: { type: AgentToolRefModel, isArray: true, isOptional: true },
+  },
+});
+
+/**
+ * Input for creating an agent.
+ */
+export const CreateAgentInputModel = defineSchemaModel({
+  name: 'CreateAgentInput',
+  description: 'Input for creating an agent',
+  fields: {
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    modelProvider: { type: ModelProviderEnum, isOptional: false },
+    modelName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    modelConfig: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    systemPrompt: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userPromptTemplate: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    toolIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    toolChoice: { type: ToolChoiceEnum, isOptional: true },
+    maxIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    maxTokensPerRun: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});
+
+/**
+ * Input for updating an agent.
+ */
+export const UpdateAgentInputModel = defineSchemaModel({
+  name: 'UpdateAgentInput',
+  description: 'Input for updating an agent',
+  fields: {
+    agentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: AgentStatusEnum, isOptional: true },
+    modelConfig: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    systemPrompt: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    userPromptTemplate: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    toolIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    toolChoice: { type: ToolChoiceEnum, isOptional: true },
+    maxIterations: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    maxTokensPerRun: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeoutMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});

package/src/agent/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent domain - AI agent configuration and management.
+ */
+
+// Enums
+export {
+  AgentStatusEnum,
+  ModelProviderEnum,
+  ToolChoiceEnum,
+} from './agent.enum';
+
+// Schema models
+export {
+  AgentModel,
+  AgentSummaryModel,
+  AgentToolRefModel,
+  AgentWithToolsModel,
+  CreateAgentInputModel,
+  UpdateAgentInputModel,
+} from './agent.schema';
+
+// Contracts
+export {
+  CreateAgentCommand,
+  UpdateAgentCommand,
+  GetAgentQuery,
+  ListAgentsQuery,
+  AssignToolToAgentCommand,
+  RemoveToolFromAgentCommand,
+} from './agent.operation';
+
+// Events
+export {
+  AgentCreatedEvent,
+  AgentUpdatedEvent,
+  AgentToolAssignedEvent,
+  AgentToolRemovedEvent,
+} from './agent.event';
+
+// Entities
+export {
+  AgentStatusEntityEnum,
+  ModelProviderEntityEnum,
+  AgentEntity,
+  AgentToolEntity,
+} from './agent.entity';
+
+// Presentations
+export {
+  AgentListPresentation,
+  AgentDetailPresentation,
+  AgentConsoleDashboardPresentation,
+} from './agent.presentation';
+
+// Handlers
+export {
+  mockListAgentsHandler,
+  mockGetAgentHandler,
+  mockCreateAgentHandler,
+  mockUpdateAgentHandler,
+  type ListAgentsInput,
+  type AgentSummary,
+  type ListAgentsOutput,
+  type GetAgentInput,
+  type AgentToolRef,
+  type AgentWithTools,
+} from './agent.handler';

package/src/agent.feature.ts

@@ -0,0 +1,146 @@
+/**
+ * Agent Console Feature Module Specification
+ *
+ * Defines the feature module for agent orchestration capabilities.
+ */
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+
+/**
+ * Agent Console feature module that bundles all agent, tool, and run
+ * operations, events, and presentations into an installable feature.
+ */
+export const AgentConsoleFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'agent-console',
+    version: 1,
+    title: 'AI Agent Console',
+    description: 'AI agent orchestration with tools, runs, and logs management',
+    domain: 'ai-ops',
+    owners: ['@agent-console-team'],
+    tags: ['ai', 'agents', 'orchestration'],
+    stability: 'stable',
+  },
+
+  // All contract operations included in this feature
+  operations: [
+    // Agent operations
+    { key: 'agent-console.agent.create', version: 1 },
+    { key: 'agent-console.agent.update', version: 1 },
+    { key: 'agent-console.agent.get', version: 1 },
+    { key: 'agent-console.agent.list', version: 1 },
+    { key: 'agent-console.agent.assignTool', version: 1 },
+    { key: 'agent-console.agent.removeTool', version: 1 },
+
+    // Tool operations
+    { key: 'agent.tool.create', version: 1 },
+    { key: 'agent.tool.update', version: 1 },
+    { key: 'agent.tool.get', version: 1 },
+    { key: 'agent.tool.list', version: 1 },
+    { key: 'agent.tool.test', version: 1 },
+
+    // Run operations
+    { key: 'agent.run.execute', version: 1 },
+    { key: 'agent.run.cancel', version: 1 },
+    { key: 'agent.run.get', version: 1 },
+    { key: 'agent.run.list', version: 1 },
+    { key: 'agent.run.getSteps', version: 1 },
+    { key: 'agent.run.getLogs', version: 1 },
+    { key: 'agent.run.getMetrics', version: 1 },
+  ],
+
+  // Events emitted by this feature
+  events: [
+    // Agent events
+    { key: 'agent-console.agent.created', version: 1 },
+    { key: 'agent-console.agent.updated', version: 1 },
+    { key: 'agent-console.agent.toolAssigned', version: 1 },
+    { key: 'agent-console.agent.toolRemoved', version: 1 },
+
+    // Tool events
+    { key: 'agent.tool.created', version: 1 },
+    { key: 'agent.tool.updated', version: 1 },
+    { key: 'agent.tool.statusChanged', version: 1 },
+
+    // Run events
+    { key: 'agent.run.started', version: 1 },
+    { key: 'agent.run.completed', version: 1 },
+    { key: 'agent.run.failed', version: 1 },
+    { key: 'agent.run.cancelled', version: 1 },
+    { key: 'agent.run.toolInvoked', version: 1 },
+    { key: 'agent.run.toolCompleted', version: 1 },
+    { key: 'agent.run.messageGenerated', version: 1 },
+  ],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'agent-console.dashboard', version: 1 },
+    { key: 'agent-console.agent.list', version: 1 },
+    { key: 'agent-console.agent.detail', version: 1 },
+    { key: 'agent-console.run.list', version: 1 },
+    { key: 'agent-console.run.detail', version: 1 },
+    { key: 'agent-console.tool.list', version: 1 },
+    { key: 'agent-console.tool.detail', version: 1 },
+  ],
+
+  // Link operations to their primary presentations
+  opToPresentation: [
+    {
+      op: { key: 'agent-console.agent.list', version: 1 },
+      pres: { key: 'agent-console.agent.list', version: 1 },
+    },
+    {
+      op: { key: 'agent-console.agent.get', version: 1 },
+      pres: { key: 'agent-console.agent.detail', version: 1 },
+    },
+    {
+      op: { key: 'agent.run.list', version: 1 },
+      pres: { key: 'agent-console.run.list', version: 1 },
+    },
+    {
+      op: { key: 'agent.run.get', version: 1 },
+      pres: { key: 'agent-console.run.detail', version: 1 },
+    },
+    {
+      op: { key: 'agent.tool.list', version: 1 },
+      pres: { key: 'agent-console.tool.list', version: 1 },
+    },
+    {
+      op: { key: 'agent.tool.get', version: 1 },
+      pres: { key: 'agent-console.tool.detail', version: 1 },
+    },
+  ],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    {
+      key: 'agent-console.dashboard',
+      version: 1,
+      targets: ['react', 'markdown'],
+    },
+    {
+      key: 'agent-console.agent.list',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'agent-console.run.list',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'agent-console.tool.list',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [
+      { key: 'identity', version: 1 },
+      { key: 'audit-trail', version: 1 },
+      { key: 'jobs', version: 1 },
+    ],
+    provides: [{ key: 'agent', version: 1 }],
+  },
+};

package/src/docs/agent-console.docblock.ts

@@ -0,0 +1,97 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const agentConsoleDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.agent-console.goal',
+    title: 'Agent Console — Goal',
+    summary: 'AI agent ops console: tools, agents, runs, logs, and metrics.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/agent-console/goal',
+    tags: ['ai', 'agents', 'goal'],
+    body: `## Why it matters
+- Provides a regenerable agent operations surface with tool registry and run history.
+- Prevents drift between tool schemas, agent configs, and execution logs.
+
+## Business/Product goal
+- Safely manage tools/agents/runs with auditability and observability.
+- Enable staged rollout of tools and metrics via feature flags.
+
+## Success criteria
+- Tool/agent/run specs regenerate UI/API/events cleanly.
+- Logs/metrics stay aligned and PII is scoped.`,
+  },
+  {
+    id: 'docs.examples.agent-console.usage',
+    title: 'Agent Console — Usage',
+    summary: 'How to operate, extend, and regenerate the agent console safely.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/agent-console/usage',
+    tags: ['ai', 'agents', 'usage'],
+    body: `## Setup
+1) Seed (if available) or create tools and agents; define run configs.
+2) Configure Notifications for run completion/failure; Audit for changes.
+
+## Extend & regenerate
+1) Adjust tool schemas (inputs/outputs), agent configs, run metrics in spec.
+2) Regenerate to sync UI/API/events/logs; mark PII paths for run payloads.
+3) Use Feature Flags to gate risky tools or execution policies.
+
+## Guardrails
+- Emit events for run lifecycle; store logs with redaction where needed.
+- Enforce tool input validation; avoid unsafe arbitrary code exec in handlers.
+- Keep tenant/user scoping explicit for ops data.`,
+  },
+  {
+    id: 'docs.examples.agent-console.reference',
+    title: 'Agent Console — Reference',
+    summary:
+      'Entities, contracts, events, and presentations for the agent console.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/agent-console',
+    tags: ['ai', 'agents', 'reference'],
+    body: `## Entities
+- Tool, Agent, AgentTool, Run, RunStep, RunLog, RunMetric.
+
+## Contracts
+- tool/create, agent/create, agent/execute, run/get, run/logs, run/metrics.
+
+## Events
+- tool.created, agent.created, run.started/completed/failed, tool.invoked.
+
+## Presentations
+- Tool registry, agent list/detail, run list/detail, metrics dashboards.
+
+## Notes
+- Keep tool schemas explicit; enforce validation in spec.
+- Use Audit Trail for agent/run changes; Notifications for run outcomes.`,
+  },
+  {
+    id: 'docs.examples.agent-console.constraints',
+    title: 'Agent Console — Constraints & Safety',
+    summary:
+      'Internal guardrails for tool/agent/run safety, PII, and regeneration.',
+    kind: 'reference',
+    visibility: 'internal',
+    route: '/docs/examples/agent-console/constraints',
+    tags: ['ai', 'agents', 'constraints', 'internal'],
+    body: `## Constraints
+- Tool schemas (inputs/outputs) must be explicit in spec; no arbitrary untyped payloads.
+- Events to emit: tool.created, agent.created, run.started/completed/failed, tool.invoked.
+- Regeneration must not loosen execution policies or logging without explicit spec diff.
+
+## Safety & PII
+- Mark PII in run payloads/logs; redact in markdown/JSON targets.
+- Avoid exposing raw tool outputs to MCP/web without policy checks.
+
+## Verification
+- Add fixtures for tool schema changes and run lifecycle.
+- Ensure Audit/Notifications remain wired for runs; metrics collection unchanged.
+- Use Feature Flags to gate risky tools; default safe/off.`,
+  },
+];
+
+registerDocBlocks(agentConsoleDocBlocks);

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './agent-console.docblock';

package/src/example.ts

@@ -0,0 +1,34 @@
+const example = {
+  id: 'agent-console',
+  title: 'Agent Console',
+  summary:
+    'AI agent ops console: tools, agents, runs, logs, and metrics (spec-first, regenerable).',
+  tags: ['ai', 'agents', 'tools', 'orchestration'],
+  kind: 'template',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.agent-console.reference',
+    goalDocId: 'docs.examples.agent-console.goal',
+    usageDocId: 'docs.examples.agent-console.usage',
+    constraintsDocId: 'docs.examples.agent-console.constraints',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.agent-console',
+    feature: './feature',
+    contracts: './contracts',
+    presentations: './presentations',
+    handlers: './handlers',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ['playground', 'specs', 'builder', 'markdown', 'evolution'],
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;

package/src/handlers/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent Console Handlers - re-exports from domain modules for backward compatibility.
+ */
+
+// Agent handlers and types
+export {
+  mockCreateAgentHandler,
+  mockGetAgentHandler,
+  mockListAgentsHandler,
+  type AgentSummary,
+} from '../agent/agent.handler';
+
+// Run handlers and types
+export {
+  mockExecuteAgentHandler,
+  mockGetRunHandler,
+  mockListRunsHandler,
+  type RunSummary,
+} from '../run/run.handler';
+
+// Tool handlers and types
+export {
+  mockCreateToolHandler,
+  mockGetToolHandler,
+  mockListToolsHandler,
+  type ToolSummary,
+} from '../tool/tool.handler';

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent Console Example
+ *
+ * A ContractSpec example demonstrating AI agent orchestration with tools, runs, and logs.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ToolEntity,
+ *   AgentEntity,
+ *   RunEntity,
+ *   CreateToolCommand,
+ *   ExecuteAgentCommand
+ * } from '@contractspec/example.agent-console';
+ * ```
+ */
+
+// Domain exports
+export * from './agent';
+export * from './run';
+export * from './tool';
+export * from './shared';
+
+// Feature spec export
+export * from './agent.feature';
+export { default as example } from './example';
+import './docs';

package/src/presentations/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent Console Presentations - re-exports from domain modules for backward compatibility.
+ */
+
+// Agent presentations
+export {
+  AgentListPresentation,
+  AgentDetailPresentation,
+  AgentConsoleDashboardPresentation,
+} from '../agent/agent.presentation';
+
+// Run presentations
+export {
+  RunListPresentation,
+  RunDetailPresentation,
+} from '../run/run.presentation';
+// Alias: RunMetricsPresentation -> RunDetailPresentation (for backward compatibility)
+export { RunDetailPresentation as RunMetricsPresentation } from '../run/run.presentation';
+
+// Tool presentations
+export {
+  ToolListPresentation,
+  ToolDetailPresentation,
+} from '../tool/tool.presentation';
+// Alias: ToolRegistryPresentation -> ToolListPresentation (for backward compatibility)
+export { ToolListPresentation as ToolRegistryPresentation } from '../tool/tool.presentation';