@contractspec/example.agent-console 3.2.0 → 3.4.0

package/dist/node/ui/AgentDashboard.js

@@ -519,6 +519,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -560,10 +565,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -573,7 +591,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/dist/node/ui/hooks/index.js

@@ -203,6 +203,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -244,10 +249,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -257,7 +275,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/dist/node/ui/hooks/useAgentMutations.js

@@ -14,6 +14,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -55,10 +60,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -68,7 +86,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 export {

package/dist/node/ui/index.js

@@ -519,6 +519,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -560,10 +565,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -573,7 +591,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/dist/ui/AgentDashboard.js

@@ -520,6 +520,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -561,10 +566,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -574,7 +592,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/dist/ui/hooks/index.js

@@ -204,6 +204,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -245,10 +250,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -258,7 +276,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/dist/ui/hooks/useAgentMutations.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, CreateAgentInput, UpdateAgentInput } from '../../handlers/agent.handlers';
+import type { Agent, Run, CreateAgentInput, UpdateAgentInput } from '../../handlers/agent.handlers';
 export interface MutationState<T> {
     loading: boolean;
     error: Error | null;
@@ -17,9 +17,10 @@ export declare function useAgentMutations(options?: UseAgentMutationsOptions): {
     executeAgent: (input: {
         agentId: string;
         message: string;
-    }) => Promise<null>;
+    }) => Promise<Run | null>;
     createState: MutationState<Agent>;
     updateState: MutationState<Agent>;
+    executeState: MutationState<Run>;
     isLoading: boolean;
 };
-export type { CreateAgentInput, UpdateAgentInput, Agent };
+export type { CreateAgentInput, UpdateAgentInput, Agent, Run };

package/dist/ui/hooks/useAgentMutations.js

@@ -15,6 +15,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -56,10 +61,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -69,7 +87,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 export {

package/dist/ui/index.js

@@ -520,6 +520,11 @@ function useAgentMutations(options = {}) {
     error: null,
     data: null
   });
+  const [executeState, setExecuteState] = useState4({
+    loading: false,
+    error: null,
+    data: null
+  });
   const createAgent = useCallback4(async (input) => {
     setCreateState({ loading: true, error: null, data: null });
     try {
@@ -561,10 +566,23 @@ function useAgentMutations(options = {}) {
     return updateAgent({ id: agentId, status: "ARCHIVED" });
   }, [updateAgent]);
   const executeAgent = useCallback4(async (input) => {
-    console.log("Execute agent:", input);
-    options.onSuccess?.();
-    return null;
-  }, [options]);
+    setExecuteState({ loading: true, error: null, data: null });
+    try {
+      const result = await agent.executeAgent({
+        agentId: input.agentId,
+        message: input.message,
+        context: { projectId, organizationId: "demo-org" }
+      });
+      setExecuteState({ loading: false, error: null, data: result });
+      options.onSuccess?.();
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to execute agent");
+      setExecuteState({ loading: false, error, data: null });
+      options.onError?.(error);
+      return null;
+    }
+  }, [agent, projectId, options]);
   return {
     createAgent,
     updateAgent,
@@ -574,7 +592,8 @@ function useAgentMutations(options = {}) {
     executeAgent,
     createState,
     updateState,
-    isLoading: createState.loading || updateState.loading
+    executeState,
+    isLoading: createState.loading || updateState.loading || executeState.loading
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.agent-console",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Agent Console example - AI agent orchestration with tools, runs, and logs",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -582,20 +582,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.schema": "3.2.0",
-    "@contractspec/lib.contracts-spec": "3.2.0",
-    "@contractspec/lib.example-shared-ui": "3.2.0",
-    "@contractspec/lib.design-system": "3.2.0",
-    "@contractspec/lib.runtime-sandbox": "2.2.0",
+    "@contractspec/lib.schema": "3.4.0",
+    "@contractspec/lib.contracts-spec": "3.4.0",
+    "@contractspec/lib.example-shared-ui": "3.4.0",
+    "@contractspec/lib.design-system": "3.4.0",
+    "@contractspec/lib.runtime-sandbox": "2.4.0",
     "react": "19.2.4",
     "react-dom": "19.2.4"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.2.0",
+    "@contractspec/tool.typescript": "3.4.0",
     "typescript": "^5.9.3",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.2",
-    "@contractspec/tool.bun": "3.2.0"
+    "@contractspec/tool.bun": "3.4.0"
   },
   "publishConfig": {
     "exports": {

package/src/agent.feature.ts

@@ -144,4 +144,15 @@ export const AgentConsoleFeature: FeatureModuleSpec = defineFeature({
     ],
     provides: [{ key: 'agent', version: '1.0.0' }],
   },
+
+  telemetry: [{ key: 'agent-console.telemetry', version: '1.0.0' }],
+
+  jobs: [{ key: 'agent-console.job.run-execution', version: '1.0.0' }],
+
+  docs: [
+    'docs.examples.agent-console.goal',
+    'docs.examples.agent-console.usage',
+    'docs.examples.agent-console.reference',
+    'docs.examples.agent-console.constraints',
+  ],
 });

package/src/handlers/agent.handlers.ts

@@ -558,11 +558,45 @@ export function createAgentHandlers(db: DatabasePort) {
     };
   }
 
+  /**
+   * Execute an agent (create a run and queue it).
+   */
+  async function executeAgent(input: {
+    agentId: string;
+    message: string;
+    context?: { projectId: string; organizationId: string };
+  }): Promise<Run> {
+    const agent = await getAgent(input.agentId);
+    if (!agent) throw new Error('AGENT_NOT_FOUND');
+    if (agent.status !== 'ACTIVE') throw new Error('AGENT_NOT_ACTIVE');
+
+    const id = generateId('run');
+    const now = new Date().toISOString();
+    const pid = input.context?.projectId ?? agent.projectId;
+
+    await db.execute(
+      `INSERT INTO agent_run (id, projectId, agentId, status, input, totalTokens, promptTokens, completionTokens, estimatedCostUsd, queuedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, pid, input.agentId, 'QUEUED', input.message, 0, 0, 0, 0, now]
+    );
+
+    const rows = (
+      await db.query(
+        `SELECT r.*, a.name as agentName FROM agent_run r LEFT JOIN agent_definition a ON r.agentId = a.id WHERE r.id = ?`,
+        [id]
+      )
+    ).rows as unknown as (RunRow & { agentName: string })[];
+
+    if (!rows[0]) throw new Error('Failed to retrieve created run');
+    return rowToRun(rows[0], rows[0].agentName);
+  }
+
   return {
     listAgents,
     getAgent,
     createAgent,
     updateAgent,
+    executeAgent,
     listTools,
     listRuns,
     getRunMetrics,

package/src/ui/hooks/useAgentMutations.ts

@@ -9,6 +9,7 @@ import { useCallback, useState } from 'react';
 import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
 import type {
   Agent,
+  Run,
   CreateAgentInput,
   UpdateAgentInput,
   AgentHandlers,
@@ -43,6 +44,12 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
     data: null,
   });
 
+  const [executeState, setExecuteState] = useState<MutationState<Run>>({
+    loading: false,
+    error: null,
+    data: null,
+  });
+
   /**
    * Create a new agent
    */
@@ -121,17 +128,32 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
   );
 
   /**
-   * Execute an agent (placeholder - needs run handler)
-   * Note: Execute functionality requires adding createRun/executeRun to agent handlers
+   * Execute an agent (creates a queued run).
    */
   const executeAgent = useCallback(
-    async (input: { agentId: string; message: string }): Promise<null> => {
-      // TODO: Implement execute when run creation handler is added to runtime-local
-      console.log('Execute agent:', input);
-      options.onSuccess?.();
-      return null;
+    async (input: {
+      agentId: string;
+      message: string;
+    }): Promise<Run | null> => {
+      setExecuteState({ loading: true, error: null, data: null });
+      try {
+        const result = await agent.executeAgent({
+          agentId: input.agentId,
+          message: input.message,
+          context: { projectId, organizationId: 'demo-org' },
+        });
+        setExecuteState({ loading: false, error: null, data: result });
+        options.onSuccess?.();
+        return result;
+      } catch (err) {
+        const error =
+          err instanceof Error ? err : new Error('Failed to execute agent');
+        setExecuteState({ loading: false, error, data: null });
+        options.onError?.(error);
+        return null;
+      }
     },
-    [options]
+    [agent, projectId, options]
   );
 
   return {
@@ -146,11 +168,13 @@ export function useAgentMutations(options: UseAgentMutationsOptions = {}) {
     // State
     createState,
     updateState,
+    executeState,
 
     // Convenience
-    isLoading: createState.loading || updateState.loading,
+    isLoading:
+      createState.loading || updateState.loading || executeState.loading,
   };
 }
 
 // Re-export types for convenience
-export type { CreateAgentInput, UpdateAgentInput, Agent };
+export type { CreateAgentInput, UpdateAgentInput, Agent, Run };