@contractspec/example.agent-console 1.46.0 → 1.47.0

package/src/shared/overlay-types.ts

@@ -0,0 +1,39 @@
+export interface OverlayDefinition {
+  overlayId: string;
+  version: string;
+  description: string;
+  appliesTo: Record<string, string>;
+  modifications: OverlayModification[];
+}
+
+export type OverlayModification =
+  | HideFieldModification
+  | RenameLabelModification
+  | AddBadgeModification
+  | SetLimitModification;
+
+export interface HideFieldModification {
+  type: 'hideField';
+  field: string;
+  reason?: string;
+}
+
+export interface RenameLabelModification {
+  type: 'renameLabel';
+  field: string;
+  newLabel: string;
+}
+
+export interface AddBadgeModification {
+  type: 'addBadge';
+  position: 'header' | 'footer';
+  label: string;
+  variant: 'warning' | 'info' | 'error' | 'success' | 'default';
+}
+
+export interface SetLimitModification {
+  type: 'setLimit';
+  field: string;
+  max: number;
+  message: string;
+}

package/src/tool/tool.presentation.ts

@@ -1,11 +1,10 @@
-import type { PresentationSpec } from '@contractspec/lib.contracts';
-import { StabilityEnum } from '@contractspec/lib.contracts';
+import { StabilityEnum, definePresentation } from '@contractspec/lib.contracts';
 import { ToolSummaryModel } from './tool.schema';
 
 /**
  * Presentation for displaying a list of tools.
  */
-export const ToolListPresentation: PresentationSpec = {
+export const ToolListPresentation = definePresentation({
   meta: {
     key: 'agent-console.tool.list',
     version: '1.0.0',
@@ -27,12 +26,12 @@ export const ToolListPresentation: PresentationSpec = {
   },
   targets: ['react', 'markdown', 'application/json'],
   policy: { flags: ['agent-console.enabled'] },
-};
+});
 
 /**
  * Presentation for tool detail view.
  */
-export const ToolDetailPresentation: PresentationSpec = {
+export const ToolDetailPresentation = definePresentation({
   meta: {
     key: 'agent-console.tool.detail',
     version: '1.0.0',
@@ -53,4 +52,4 @@ export const ToolDetailPresentation: PresentationSpec = {
   },
   targets: ['react', 'markdown'],
   policy: { flags: ['agent-console.enabled'] },
-};
+});

package/src/tool/tool.test-spec.ts

@@ -0,0 +1,55 @@
+import { defineTestSpec } from '@contractspec/lib.contracts';
+
+export const toolListTest = defineTestSpec({
+  meta: {
+    key: 'test.agent.tool.list',
+    version: '1.0.0',
+    owners: ['@agent-console-team'],
+    description: 'Test for listing tools',
+    stability: 'stable',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'agent.tool.list', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'agent.tool.list' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'agent.tool.list' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const toolGetTest = defineTestSpec({
+  meta: {
+    key: 'test.agent.tool.get',
+    version: '1.0.0',
+    owners: ['@agent-console-team'],
+    description: 'Test for getting tool',
+    stability: 'stable',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'agent.tool.get', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'agent.tool.get' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'agent.tool.get' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});

package/src/ui/AgentDashboard.tsx

@@ -0,0 +1,416 @@
+'use client';
+
+/**
+ * Agent Console Dashboard
+ *
+ * Fully integrated with ContractSpec example handlers,
+ * design-system components, and command mutations.
+ *
+ * Commands wired:
+ * - CreateAgentCommand -> Create Agent button + modal
+ * - UpdateAgentCommand -> Status changes via modal
+ * - ExecuteAgentCommand -> Execute agent via modal
+ */
+import { useState, useMemo, useCallback } from 'react';
+import {
+  StatCard,
+  StatCardGroup,
+  Button,
+} from '@contractspec/lib.design-system';
+// import { AgentListView } from './views/AgentListView';
+import { RunListView } from './views/RunListView';
+import { ToolRegistryView } from './views/ToolRegistryView';
+import { useRunList, type RunMetrics } from './hooks/useRunList';
+import { useAgentList, type Agent } from './hooks/useAgentList';
+import { useAgentMutations } from './hooks/useAgentMutations';
+import { CreateAgentModal } from './modals/CreateAgentModal';
+import { AgentActionsModal } from './modals/AgentActionsModal';
+
+type Tab = 'runs' | 'agents' | 'tools' | 'metrics';
+
+export function AgentDashboard() {
+  const [activeTab, setActiveTab] = useState<Tab>('runs');
+  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
+  const [selectedAgent, setSelectedAgent] = useState<Agent | null>(null);
+  const [isAgentActionsOpen, setIsAgentActionsOpen] = useState(false);
+
+  const { metrics, refetch: refetchRuns } = useRunList();
+  const { refetch: refetchAgents } = useAgentList();
+
+  const mutations = useAgentMutations({
+    onSuccess: () => {
+      refetchAgents();
+      refetchRuns();
+    },
+  });
+
+  const handleAgentClick = useCallback((agent: Agent) => {
+    setSelectedAgent(agent);
+    setIsAgentActionsOpen(true);
+  }, []);
+
+  const tabs: { id: Tab; label: string; icon: string }[] = [
+    { id: 'runs', label: 'Runs', icon: '▶' },
+    { id: 'agents', label: 'Agents', icon: '🤖' },
+    { id: 'tools', label: 'Tools', icon: '🔧' },
+    { id: 'metrics', label: 'Metrics', icon: '📊' },
+  ];
+
+  // Compute summary stats from metrics
+  const summaryStats = useMemo(() => {
+    if (!metrics) {
+      return [
+        { label: 'Total Runs', value: '-', hint: 'Loading...' },
+        { label: 'Success Rate', value: '-', hint: '' },
+        { label: 'Total Tokens', value: '-', hint: '' },
+        { label: 'Total Cost', value: '-', hint: '' },
+      ];
+    }
+    return [
+      {
+        label: 'Total Runs',
+        value: metrics.totalRuns.toLocaleString(),
+        hint: `${(metrics.successRate * 100).toFixed(0)}% success`,
+      },
+      {
+        label: 'Success Rate',
+        value: `${(metrics.successRate * 100).toFixed(0)}%`,
+        hint: 'of all runs',
+      },
+      {
+        label: 'Total Tokens',
+        value:
+          metrics.totalTokens >= 1000000
+            ? `${(metrics.totalTokens / 1000000).toFixed(1)}M`
+            : `${(metrics.totalTokens / 1000).toFixed(0)}K`,
+        hint: 'This period',
+      },
+      {
+        label: 'Total Cost',
+        value: `$${metrics.totalCostUsd.toFixed(2)}`,
+        hint: 'This period',
+      },
+    ];
+  }, [metrics]);
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <h2 className="text-2xl font-bold">AI Agent Console</h2>
+        <Button onPress={() => setIsCreateModalOpen(true)}>
+          <span className="mr-2">+</span> New Agent
+        </Button>
+      </div>
+
+      {/* Summary Stats Row */}
+      <StatCardGroup>
+        {summaryStats.map((stat, i) => (
+          <StatCard
+            key={i}
+            label={stat.label}
+            value={stat.value}
+            hint={stat.hint}
+          />
+        ))}
+      </StatCardGroup>
+
+      {/* Navigation Tabs */}
+      <nav className="bg-muted flex gap-1 rounded-lg p-1" role="tablist">
+        {tabs.map((tab) => (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={activeTab === tab.id}
+            onClick={() => setActiveTab(tab.id)}
+            className={`flex flex-1 items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium transition-colors ${
+              activeTab === tab.id
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground'
+            }`}
+          >
+            <span>{tab.icon}</span>
+            {tab.label}
+          </button>
+        ))}
+      </nav>
+
+      {/* Tab Content */}
+      <div className="min-h-[400px]" role="tabpanel">
+        {activeTab === 'runs' && <RunListView />}
+        {activeTab === 'agents' && (
+          <AgentListViewWithActions onAgentClick={handleAgentClick} />
+        )}
+        {activeTab === 'tools' && <ToolRegistryView />}
+        {activeTab === 'metrics' && <MetricsView metrics={metrics} />}
+      </div>
+
+      {/* Create Agent Modal */}
+      <CreateAgentModal
+        isOpen={isCreateModalOpen}
+        onClose={() => setIsCreateModalOpen(false)}
+        onSubmit={async (input) => {
+          await mutations.createAgent(input);
+        }}
+        isLoading={mutations.createState.loading}
+      />
+
+      {/* Agent Actions Modal */}
+      <AgentActionsModal
+        isOpen={isAgentActionsOpen}
+        agent={selectedAgent}
+        onClose={() => {
+          setIsAgentActionsOpen(false);
+          setSelectedAgent(null);
+        }}
+        onActivate={async (agentId) => {
+          await mutations.activateAgent(agentId);
+        }}
+        onPause={async (agentId) => {
+          await mutations.pauseAgent(agentId);
+        }}
+        onArchive={async (agentId) => {
+          await mutations.archiveAgent(agentId);
+        }}
+        onExecute={async (agentId, message) => {
+          await mutations.executeAgent({ agentId, message });
+        }}
+        isLoading={mutations.isLoading}
+      />
+    </div>
+  );
+}
+
+/**
+ * Agent List View with click handler
+ */
+function AgentListViewWithActions({
+  onAgentClick,
+}: {
+  onAgentClick: (agent: Agent) => void;
+}) {
+  const { data, loading, error, stats, refetch } = useAgentList();
+
+  if (loading && !data) {
+    return (
+      <div className="text-muted-foreground flex h-64 items-center justify-center">
+        Loading agents...
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="text-destructive flex h-64 flex-col items-center justify-center">
+        <p>Failed to load agents: {error.message}</p>
+        <Button variant="outline" onPress={refetch} className="mt-2">
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  if (!data?.items.length) {
+    return (
+      <div className="text-muted-foreground flex h-64 flex-col items-center justify-center">
+        <p className="text-lg font-medium">No agents yet</p>
+        <p className="text-sm">Create your first AI agent to get started.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Stats */}
+      {stats && (
+        <div className="flex gap-4 text-sm">
+          <span>Total: {stats.total}</span>
+          <span className="text-green-600">Active: {stats.active}</span>
+          <span className="text-yellow-600">Paused: {stats.paused}</span>
+          <span className="text-blue-600">Draft: {stats.draft}</span>
+        </div>
+      )}
+
+      {/* Agent Grid */}
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+        {data.items.map((agent) => (
+          <AgentCard
+            key={agent.id}
+            agent={agent}
+            onClick={() => onAgentClick(agent)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Agent Card Component
+ */
+function AgentCard({ agent, onClick }: { agent: Agent; onClick: () => void }) {
+  const statusColors: Record<string, string> = {
+    ACTIVE:
+      'bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400',
+    DRAFT: 'bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400',
+    PAUSED:
+      'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400',
+    ARCHIVED: 'bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-400',
+  };
+
+  return (
+    <div
+      onClick={onClick}
+      className="border-border bg-card cursor-pointer rounded-xl border p-4 transition-all hover:shadow-md"
+      role="button"
+      tabIndex={0}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') onClick();
+      }}
+    >
+      <div className="flex items-start justify-between">
+        <div className="min-w-0 flex-1">
+          <h3 className="truncate font-semibold">{agent.name}</h3>
+          <p className="text-muted-foreground text-sm">
+            {agent.modelProvider} / {agent.modelName}
+          </p>
+        </div>
+        <span
+          className={`rounded-full px-2 py-0.5 text-xs font-medium ${statusColors[agent.status]}`}
+        >
+          {agent.status}
+        </span>
+      </div>
+      {agent.description && (
+        <p className="text-muted-foreground mt-2 line-clamp-2 text-sm">
+          {agent.description}
+        </p>
+      )}
+      <div className="mt-3 flex items-center justify-between">
+        <span className="text-muted-foreground text-xs">{agent.modelName}</span>
+        <Button variant="ghost" size="sm" onPress={onClick}>
+          Actions
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Metrics View - Shows usage analytics
+ */
+function MetricsView({ metrics }: { metrics: RunMetrics | null }) {
+  if (!metrics) {
+    return (
+      <div className="text-muted-foreground flex h-64 items-center justify-center">
+        Loading metrics...
+      </div>
+    );
+  }
+
+  // Calculate derived metrics
+  const completedRuns = Math.round(metrics.totalRuns * metrics.successRate);
+  const failedRuns = metrics.totalRuns - completedRuns;
+
+  return (
+    <div className="space-y-6">
+      <h3 className="text-lg font-semibold">Usage Analytics</h3>
+
+      <div className="grid gap-6 md:grid-cols-2">
+        {/* Success/Failure breakdown */}
+        <div className="border-border bg-card rounded-xl border p-4">
+          <h4 className="font-medium">Run Outcomes</h4>
+          <div className="mt-4 space-y-3">
+            <ProgressBar
+              label="Completed"
+              value={completedRuns}
+              total={metrics.totalRuns}
+              color="bg-green-500"
+            />
+            <ProgressBar
+              label="Failed"
+              value={failedRuns}
+              total={metrics.totalRuns}
+              color="bg-red-500"
+            />
+          </div>
+        </div>
+
+        {/* Key Stats */}
+        <div className="border-border bg-card rounded-xl border p-4">
+          <h4 className="font-medium">Performance</h4>
+          <dl className="mt-4 grid grid-cols-2 gap-4">
+            <div>
+              <dt className="text-muted-foreground text-sm">Avg Duration</dt>
+              <dd className="text-xl font-semibold">
+                {(metrics.averageDurationMs / 1000).toFixed(1)}s
+              </dd>
+            </div>
+            <div>
+              <dt className="text-muted-foreground text-sm">Success Rate</dt>
+              <dd className="text-xl font-semibold">
+                {(metrics.successRate * 100).toFixed(0)}%
+              </dd>
+            </div>
+          </dl>
+        </div>
+      </div>
+
+      {/* Key Metrics */}
+      <div className="border-border bg-card rounded-xl border p-4">
+        <h4 className="font-medium">Key Metrics</h4>
+        <dl className="mt-4 grid gap-4 sm:grid-cols-3">
+          <div>
+            <dt className="text-muted-foreground text-sm">Total Runs</dt>
+            <dd className="text-2xl font-semibold">
+              {metrics.totalRuns.toLocaleString()}
+            </dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground text-sm">Total Tokens</dt>
+            <dd className="text-2xl font-semibold">
+              {(metrics.totalTokens / 1000).toFixed(0)}K
+            </dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground text-sm">Cost per Run</dt>
+            <dd className="text-2xl font-semibold">
+              $
+              {metrics.totalRuns > 0
+                ? (metrics.totalCostUsd / metrics.totalRuns).toFixed(4)
+                : '0'}
+            </dd>
+          </div>
+        </dl>
+      </div>
+    </div>
+  );
+}
+
+function ProgressBar({
+  label,
+  value,
+  total,
+  color,
+}: {
+  label: string;
+  value: number;
+  total: number;
+  color: string;
+}) {
+  const pct = total > 0 ? (value / total) * 100 : 0;
+  return (
+    <div>
+      <div className="flex justify-between text-sm">
+        <span>{label}</span>
+        <span className="text-muted-foreground">
+          {value} ({pct.toFixed(0)}%)
+        </span>
+      </div>
+      <div className="bg-muted mt-1 h-2 overflow-hidden rounded-full">
+        <div className={`h-full ${color}`} style={{ width: `${pct}%` }} />
+      </div>
+    </div>
+  );
+}

package/src/ui/AgentRunList.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+/**
+ * Agent Run List - Standalone component for run history
+ *
+ * Re-exports RunListView for backward compatibility
+ */
+export { RunListView as AgentRunList } from './views/RunListView';

package/src/ui/AgentToolRegistry.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+/**
+ * Agent Tool Registry - Standalone component for tool management
+ *
+ * Re-exports ToolRegistryView for backward compatibility
+ */
+export { ToolRegistryView as AgentToolRegistry } from './views/ToolRegistryView';

package/src/ui/hooks/index.ts

@@ -0,0 +1,14 @@
+'use client';
+
+/**
+ * Data hooks for agent-console template
+ */
+export { useAgentList, type UseAgentListOptions } from './useAgentList';
+export { useRunList, type UseRunListOptions } from './useRunList';
+export { useToolList, type UseToolListOptions } from './useToolList';
+export {
+  useAgentMutations,
+  type UseAgentMutationsOptions,
+  type CreateAgentInput,
+  type UpdateAgentInput,
+} from './useAgentMutations';

package/src/ui/hooks/useAgentList.ts

@@ -0,0 +1,80 @@
+/**
+ * Hook for fetching and managing agent list data
+ *
+ * Uses runtime-local database-backed handlers.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
+import type {
+  Agent as RuntimeAgent,
+  ListAgentsOutput as RuntimeListAgentsOutput,
+} from '../../handlers/agent.handlers';
+import type { AgentHandlers } from '../../handlers/agent.handlers';
+
+// Re-export types for convenience
+export type Agent = RuntimeAgent;
+export type ListAgentsOutput = RuntimeListAgentsOutput;
+
+export interface UseAgentListOptions {
+  search?: string;
+  status?: 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'all';
+  limit?: number;
+}
+
+export function useAgentList(options: UseAgentListOptions = {}) {
+  const { handlers, projectId } = useTemplateRuntime<{
+    agent: AgentHandlers;
+  }>();
+  const { agent } = handlers;
+
+  const [data, setData] = useState<ListAgentsOutput | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [page, setPage] = useState(1);
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await agent.listAgents({
+        projectId,
+        search: options.search,
+        status: options.status === 'all' ? undefined : options.status,
+        limit: options.limit ?? 20,
+        offset: (page - 1) * (options.limit ?? 20),
+      });
+      setData(result);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setLoading(false);
+    }
+  }, [agent, projectId, options.search, options.status, options.limit, page]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  // Calculate stats
+  const stats = useMemo(() => {
+    if (!data) return null;
+    return {
+      total: data.total,
+      active: data.items.filter((a) => a.status === 'ACTIVE').length,
+      paused: data.items.filter((a) => a.status === 'PAUSED').length,
+      draft: data.items.filter((a) => a.status === 'DRAFT').length,
+    };
+  }, [data]);
+
+  return {
+    data,
+    loading,
+    error,
+    stats,
+    page,
+    refetch: fetchData,
+    nextPage: () => setPage((p) => p + 1),
+    prevPage: () => page > 1 && setPage((p) => p - 1),
+  };
+}