@contractspec/example.agent-console 1.57.0 → 1.58.0

package/dist/node/agent.capability.js

@@ -0,0 +1,16 @@
+// src/agent.capability.ts
+import { defineCapability, StabilityEnum } from "@contractspec/lib.contracts";
+var AgentCapability = defineCapability({
+  meta: {
+    key: "agent",
+    version: "1.0.0",
+    kind: "ui",
+    stability: StabilityEnum.Experimental,
+    description: "AI agent management and console capability",
+    owners: ["platform.core"],
+    tags: ["agent", "ai", "console"]
+  }
+});
+export {
+  AgentCapability
+};

package/dist/node/agent.feature.js

@@ -0,0 +1,118 @@
+// src/agent.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var AgentConsoleFeature = defineFeature({
+  meta: {
+    key: "agent-console",
+    version: "1.0.0",
+    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"
+  },
+  operations: [
+    { key: "agent-console.agent.create", version: "1.0.0" },
+    { key: "agent-console.agent.update", version: "1.0.0" },
+    { key: "agent-console.agent.get", version: "1.0.0" },
+    { key: "agent-console.agent.list", version: "1.0.0" },
+    { key: "agent-console.agent.assignTool", version: "1.0.0" },
+    { key: "agent-console.agent.removeTool", version: "1.0.0" },
+    { key: "agent.tool.create", version: "1.0.0" },
+    { key: "agent.tool.update", version: "1.0.0" },
+    { key: "agent.tool.get", version: "1.0.0" },
+    { key: "agent.tool.list", version: "1.0.0" },
+    { key: "agent.tool.test", version: "1.0.0" },
+    { key: "agent.run.execute", version: "1.0.0" },
+    { key: "agent.run.cancel", version: "1.0.0" },
+    { key: "agent.run.get", version: "1.0.0" },
+    { key: "agent.run.list", version: "1.0.0" },
+    { key: "agent.run.getSteps", version: "1.0.0" },
+    { key: "agent.run.getLogs", version: "1.0.0" },
+    { key: "agent.run.getMetrics", version: "1.0.0" }
+  ],
+  events: [
+    { key: "agent-console.agent.created", version: "1.0.0" },
+    { key: "agent-console.agent.updated", version: "1.0.0" },
+    { key: "agent-console.agent.toolAssigned", version: "1.0.0" },
+    { key: "agent-console.agent.toolRemoved", version: "1.0.0" },
+    { key: "agent.tool.created", version: "1.0.0" },
+    { key: "agent.tool.updated", version: "1.0.0" },
+    { key: "agent.tool.statusChanged", version: "1.0.0" },
+    { key: "agent.run.started", version: "1.0.0" },
+    { key: "agent.run.completed", version: "1.0.0" },
+    { key: "agent.run.failed", version: "1.0.0" },
+    { key: "agent.run.cancelled", version: "1.0.0" },
+    { key: "agent.run.toolInvoked", version: "1.0.0" },
+    { key: "agent.run.toolCompleted", version: "1.0.0" },
+    { key: "agent.run.messageGenerated", version: "1.0.0" }
+  ],
+  presentations: [
+    { key: "agent-console.dashboard", version: "1.0.0" },
+    { key: "agent-console.agent.viewList", version: "1.0.0" },
+    { key: "agent-console.agent.detail", version: "1.0.0" },
+    { key: "agent-console.run.list", version: "1.0.0" },
+    { key: "agent-console.run.detail", version: "1.0.0" },
+    { key: "agent-console.tool.list", version: "1.0.0" },
+    { key: "agent-console.tool.detail", version: "1.0.0" }
+  ],
+  opToPresentation: [
+    {
+      op: { key: "agent-console.agent.list", version: "1.0.0" },
+      pres: { key: "agent-console.agent.viewList", version: "1.0.0" }
+    },
+    {
+      op: { key: "agent-console.agent.get", version: "1.0.0" },
+      pres: { key: "agent-console.agent.detail", version: "1.0.0" }
+    },
+    {
+      op: { key: "agent.run.list", version: "1.0.0" },
+      pres: { key: "agent-console.run.list", version: "1.0.0" }
+    },
+    {
+      op: { key: "agent.run.get", version: "1.0.0" },
+      pres: { key: "agent-console.run.detail", version: "1.0.0" }
+    },
+    {
+      op: { key: "agent.tool.list", version: "1.0.0" },
+      pres: { key: "agent-console.tool.list", version: "1.0.0" }
+    },
+    {
+      op: { key: "agent.tool.get", version: "1.0.0" },
+      pres: { key: "agent-console.tool.detail", version: "1.0.0" }
+    }
+  ],
+  presentationsTargets: [
+    {
+      key: "agent-console.dashboard",
+      version: "1.0.0",
+      targets: ["react", "markdown"]
+    },
+    {
+      key: "agent-console.agent.viewList",
+      version: "1.0.0",
+      targets: ["react", "markdown", "application/json"]
+    },
+    {
+      key: "agent-console.run.list",
+      version: "1.0.0",
+      targets: ["react", "markdown", "application/json"]
+    },
+    {
+      key: "agent-console.tool.list",
+      version: "1.0.0",
+      targets: ["react", "markdown", "application/json"]
+    }
+  ],
+  capabilities: {
+    requires: [
+      { key: "identity", version: "1.0.0" },
+      { key: "audit-trail", version: "1.0.0" },
+      { key: "jobs", version: "1.0.0" }
+    ],
+    provides: [{ key: "agent", version: "1.0.0" }]
+  }
+});
+export {
+  AgentConsoleFeature
+};

package/dist/node/docs/agent-console.docblock.js

@@ -0,0 +1,93 @@
+// src/docs/agent-console.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var agentConsoleDocBlocks = [
+  {
+    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/dist/node/docs/index.js

@@ -0,0 +1,93 @@
+// src/docs/agent-console.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var agentConsoleDocBlocks = [
+  {
+    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/dist/node/example.js

@@ -0,0 +1,42 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "agent-console",
+    version: "1.0.0",
+    title: "Agent Console",
+    description: "AI agent ops console: tools, agents, runs, logs, and metrics (spec-first, regenerable).",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["ai", "agents", "tools", "orchestration"]
+  },
+  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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/handlers/agent.handlers.js

@@ -0,0 +1,252 @@
+// src/handlers/agent.handlers.ts
+import { web } from "@contractspec/lib.runtime-sandbox";
+var { generateId } = web;
+function rowToAgent(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    modelProvider: row.modelProvider,
+    modelName: row.modelName,
+    systemPrompt: row.systemPrompt ?? undefined,
+    temperature: row.temperature,
+    maxTokens: row.maxTokens,
+    status: row.status,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function rowToTool(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    version: row.version,
+    category: row.category,
+    status: row.status,
+    inputSchema: row.inputSchema ?? undefined,
+    outputSchema: row.outputSchema ?? undefined,
+    endpoint: row.endpoint ?? undefined,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function rowToRun(row, agentName) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    agentId: row.agentId,
+    agentName,
+    status: row.status,
+    input: row.input ?? undefined,
+    output: row.output ?? undefined,
+    totalTokens: row.totalTokens,
+    promptTokens: row.promptTokens,
+    completionTokens: row.completionTokens,
+    estimatedCostUsd: row.estimatedCostUsd,
+    durationMs: row.durationMs ?? undefined,
+    errorMessage: row.errorMessage ?? undefined,
+    queuedAt: new Date(row.queuedAt),
+    startedAt: row.startedAt ? new Date(row.startedAt) : undefined,
+    completedAt: row.completedAt ? new Date(row.completedAt) : undefined
+  };
+}
+function createAgentHandlers(db) {
+  async function listAgents(input) {
+    const {
+      projectId,
+      organizationId,
+      status,
+      search,
+      limit = 20,
+      offset = 0
+    } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (organizationId) {
+      whereClause += " AND organizationId = ?";
+      params.push(organizationId);
+    }
+    if (status && status !== "all") {
+      whereClause += " AND status = ?";
+      params.push(status);
+    }
+    if (search) {
+      whereClause += " AND (name LIKE ? OR description LIKE ?)";
+      params.push(`%${search}%`, `%${search}%`);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM agent_definition ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM agent_definition ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      items: rows.map(rowToAgent),
+      total,
+      hasMore: offset + rows.length < total
+    };
+  }
+  async function getAgent(id) {
+    const rows = (await db.query(`SELECT * FROM agent_definition WHERE id = ?`, [id])).rows;
+    return rows[0] ? rowToAgent(rows[0]) : null;
+  }
+  async function createAgent(input, context) {
+    const id = generateId("agent");
+    const now = new Date().toISOString();
+    await db.execute(`INSERT INTO agent_definition (id, projectId, organizationId, name, description, modelProvider, modelName, systemPrompt, temperature, maxTokens, status, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      context.projectId,
+      context.organizationId,
+      input.name,
+      input.description ?? null,
+      input.modelProvider ?? "openai",
+      input.modelName ?? "gpt-4",
+      input.systemPrompt ?? null,
+      input.temperature ?? 0.7,
+      input.maxTokens ?? 4096,
+      "DRAFT",
+      now,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM agent_definition WHERE id = ?`, [id])).rows;
+    const row = rows[0];
+    if (!row) {
+      throw new Error("Failed to retrieve created agent");
+    }
+    return rowToAgent(row);
+  }
+  async function updateAgent(input) {
+    const now = new Date().toISOString();
+    const updates = ["updatedAt = ?"];
+    const params = [now];
+    if (input.name !== undefined) {
+      updates.push("name = ?");
+      params.push(input.name);
+    }
+    if (input.description !== undefined) {
+      updates.push("description = ?");
+      params.push(input.description);
+    }
+    if (input.status !== undefined) {
+      updates.push("status = ?");
+      params.push(input.status);
+    }
+    params.push(input.id);
+    await db.execute(`UPDATE agent_definition SET ${updates.join(", ")} WHERE id = ?`, params);
+    const rows = (await db.query(`SELECT * FROM agent_definition WHERE id = ?`, [input.id])).rows;
+    if (!rows[0]) {
+      throw new Error("NOT_FOUND");
+    }
+    return rowToAgent(rows[0]);
+  }
+  async function listTools(input) {
+    const {
+      projectId,
+      organizationId,
+      category,
+      status,
+      search,
+      limit = 50,
+      offset = 0
+    } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (organizationId) {
+      whereClause += " AND organizationId = ?";
+      params.push(organizationId);
+    }
+    if (category && category !== "all") {
+      whereClause += " AND category = ?";
+      params.push(category);
+    }
+    if (status && status !== "all") {
+      whereClause += " AND status = ?";
+      params.push(status);
+    }
+    if (search) {
+      whereClause += " AND (name LIKE ? OR description LIKE ?)";
+      params.push(`%${search}%`, `%${search}%`);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM agent_tool ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM agent_tool ${whereClause} ORDER BY name ASC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      items: rows.map(rowToTool),
+      total,
+      hasMore: offset + rows.length < total
+    };
+  }
+  async function listRuns(input) {
+    const { projectId, agentId, status, limit = 20, offset = 0 } = input;
+    let whereClause = "WHERE r.projectId = ?";
+    const params = [projectId];
+    if (agentId) {
+      whereClause += " AND r.agentId = ?";
+      params.push(agentId);
+    }
+    if (status && status !== "all") {
+      whereClause += " AND r.status = ?";
+      params.push(status);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM agent_run r ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    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 
+       ${whereClause} 
+       ORDER BY r.queuedAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      items: rows.map((r) => rowToRun(r, r.agentName)),
+      total,
+      hasMore: offset + rows.length < total
+    };
+  }
+  async function getRunMetrics(input) {
+    let whereClause = "WHERE projectId = ?";
+    const params = [input.projectId];
+    if (input.agentId) {
+      whereClause += " AND agentId = ?";
+      params.push(input.agentId);
+    }
+    if (input.startDate) {
+      whereClause += " AND queuedAt >= ?";
+      params.push(input.startDate.toISOString());
+    }
+    if (input.endDate) {
+      whereClause += " AND queuedAt <= ?";
+      params.push(input.endDate.toISOString());
+    }
+    const result = (await db.query(`SELECT 
+        COUNT(*) as totalRuns,
+        SUM(CASE WHEN status = 'COMPLETED' THEN 1 ELSE 0 END) as completedRuns,
+        AVG(CASE WHEN status = 'COMPLETED' THEN durationMs ELSE NULL END) as avgDuration,
+        COALESCE(SUM(totalTokens), 0) as totalTokens,
+        COALESCE(SUM(estimatedCostUsd), 0) as totalCost
+       FROM agent_run ${whereClause}`, params)).rows;
+    const data = result[0];
+    const totalRuns = data?.totalRuns ?? 0;
+    const completedRuns = data?.completedRuns ?? 0;
+    return {
+      totalRuns,
+      successRate: totalRuns > 0 ? completedRuns / totalRuns : 0,
+      averageDurationMs: data?.avgDuration ?? 0,
+      totalTokens: data?.totalTokens ?? 0,
+      totalCostUsd: data?.totalCost ?? 0
+    };
+  }
+  return {
+    listAgents,
+    getAgent,
+    createAgent,
+    updateAgent,
+    listTools,
+    listRuns,
+    getRunMetrics
+  };
+}
+export {
+  createAgentHandlers
+};