@lssm/example.agent-console 0.0.0-canary-20251210082611 → 0.0.0-canary-20251212004227

package/.turbo/turbo-build.log

@@ -2,7 +2,7 @@ $ bun build:bundle && bun build:types
 $ tsdown
 ℹ tsdown v0.17.0 powered by rolldown v1.0.0-beta.53
 ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/agent-console/tsdown.config.js 
-ℹ entry: src/events.ts, src/feature.ts, src/index.ts, src/entities/agent.ts, src/entities/index.ts, src/entities/log.ts, src/entities/run.ts, src/entities/tool.ts, src/handlers/agent.handlers.ts, src/handlers/index.ts, src/handlers/mock-data.ts, src/handlers/run.handlers.ts, src/handlers/tool.handlers.ts, src/contracts/agent.ts, src/contracts/index.ts, src/contracts/run.ts, src/contracts/tool.ts, src/presentations/agent-list.ts, src/presentations/dashboard.ts, src/presentations/index.ts, src/presentations/run-list.ts, src/presentations/tool-registry.ts
+ℹ entry: src/events.ts, src/feature.ts, src/index.ts, src/contracts/agent.ts, src/contracts/index.ts, src/contracts/run.ts, src/contracts/tool.ts, src/docs/agent-console.docblock.ts, src/docs/index.ts, src/entities/agent.ts, src/entities/index.ts, src/entities/log.ts, src/entities/run.ts, src/entities/tool.ts, src/handlers/agent.handlers.ts, src/handlers/index.ts, src/handlers/mock-data.ts, src/handlers/run.handlers.ts, src/handlers/tool.handlers.ts, src/presentations/agent-list.ts, src/presentations/dashboard.ts, src/presentations/index.ts, src/presentations/run-list.ts, src/presentations/tool-registry.ts
 ℹ target: esnext
 ℹ tsconfig: tsconfig.json
 ℹ Build start
@@ -11,8 +11,9 @@ $ tsdown
 ℹ dist/events.js                        8.95 kB │ gzip: 1.37 kB
 ℹ dist/handlers/mock-data.js            8.88 kB │ gzip: 2.49 kB
 ℹ dist/contracts/tool.js                7.03 kB │ gzip: 1.66 kB
-ℹ dist/index.js                         4.93 kB │ gzip: 1.27 kB
+ℹ dist/index.js                         4.95 kB │ gzip: 1.28 kB
 ℹ dist/entities/run.js                  4.34 kB │ gzip: 1.35 kB
+ℹ dist/docs/agent-console.docblock.js   3.37 kB │ gzip: 1.36 kB
 ℹ dist/entities/agent.js                2.85 kB │ gzip: 1.12 kB
 ℹ dist/feature.js                       2.75 kB │ gzip: 0.60 kB
 ℹ dist/handlers/run.handlers.js         2.32 kB │ gzip: 1.00 kB
@@ -28,6 +29,7 @@ $ tsdown
 ℹ dist/presentations/index.js           0.65 kB │ gzip: 0.24 kB
 ℹ dist/entities/index.js                0.58 kB │ gzip: 0.24 kB
 ℹ dist/presentations/dashboard.js       0.44 kB │ gzip: 0.28 kB
-ℹ 22 files, total: 74.15 kB
-✔ Build complete in 63ms
+ℹ dist/docs/index.js                    0.04 kB │ gzip: 0.06 kB
+ℹ 24 files, total: 77.58 kB
+✔ Build complete in 62ms
 $ tsc --noEmit

package/CHANGELOG.md

@@ -1,13 +1,13 @@
 # @lssm/example.agent-console
 
-## 0.0.0-canary-20251210082611
+## 0.0.0-canary-20251212004227
 
 ### Patch Changes
 
 - 3086383: refactor: dependencies upgrade
 - Updated dependencies [3086383]
-  - @lssm/lib.contracts@0.0.0-canary-20251210082611
-  - @lssm/lib.schema@0.0.0-canary-20251210082611
-  - @lssm/lib.jobs@0.0.0-canary-20251210082611
-  - @lssm/lib.identity-rbac@0.0.0-canary-20251210082611
-  - @lssm/module.audit-trail@0.0.0-canary-20251210082611
+  - @lssm/lib.contracts@0.0.0-canary-20251212004227
+  - @lssm/lib.schema@0.0.0-canary-20251212004227
+  - @lssm/lib.jobs@0.0.0-canary-20251212004227
+  - @lssm/lib.identity-rbac@0.0.0-canary-20251212004227
+  - @lssm/module.audit-trail@0.0.0-canary-20251212004227

package/README.md

@@ -80,4 +80,4 @@ This example builds on the following cross-cutting modules:
 
 - `@lssm/lib.identity-rbac` - User and organization management
 - `@lssm/lib.jobs` - Async job processing for long-running agents
-- `@lssm/modules.audit-trail` - Audit logging for compliance
+- `@lssm/module.audit-trail` - Audit logging for compliance

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

@@ -0,0 +1,49 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{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.`}]);

package/dist/docs/index.js

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

package/dist/index.js

@@ -1 +1 @@
-import{AgentCreatedEvent as e,AgentCreatedPayload as t,AgentToolAssignedEvent as n,AgentToolAssignedPayload as r,AgentToolRemovedEvent as i,AgentToolRemovedPayload as a,AgentUpdatedEvent as o,AgentUpdatedPayload as s,MessageGeneratedEvent as c,MessageGeneratedPayload as l,MessageTypeEnum as u,RunCancelledEvent as d,RunCancelledPayload as f,RunCompletedEvent as p,RunCompletedPayload as m,RunFailedEvent as h,RunFailedPayload as g,RunStartedEvent as _,RunStartedPayload as v,ToolCompletedEvent as y,ToolCompletedPayload as b,ToolCreatedEvent as x,ToolCreatedPayload as S,ToolInvokedEvent as C,ToolInvokedPayload as w,ToolStatusChangedEvent as T,ToolStatusChangedPayload as E,ToolUpdatedEvent as D,ToolUpdatedPayload as O}from"./events.js";import{AgentConsoleFeature as k}from"./feature.js";import{ToolCategoryEnum as A,ToolEntity as j,ToolStatusEnum as M}from"./entities/tool.js";import{AgentEntity as N,AgentStatusEnum as P,AgentToolEntity as F,ModelProviderEnum as I}from"./entities/agent.js";import{LogLevelEnum as L,RunEntity as R,RunLogEntity as z,RunStatusEnum as B,RunStepEntity as V,RunStepTypeEnum as H}from"./entities/run.js";import"./entities/index.js";import{CreateToolCommand as U,GetToolQuery as W,ListToolsQuery as G,TestToolCommand as K,UpdateToolCommand as q}from"./contracts/tool.js";import{AssignToolToAgentCommand as J,CreateAgentCommand as Y,GetAgentQuery as X,ListAgentsQuery as Z,RemoveToolFromAgentCommand as Q,UpdateAgentCommand as $}from"./contracts/agent.js";import{CancelRunCommand as ee,ExecuteAgentCommand as te,GetRunLogsQuery as ne,GetRunMetricsQuery as re,GetRunQuery as ie,GetRunStepsQuery as ae,ListRunsQuery as oe}from"./contracts/run.js";import"./contracts/index.js";import{MOCK_AGENTS as se,MOCK_RUNS as ce,MOCK_RUN_LOGS as le,MOCK_RUN_STEPS as ue,MOCK_TOOLS as de}from"./handlers/mock-data.js";import{mockCreateAgentHandler as fe,mockGetAgentHandler as pe,mockListAgentsHandler as me,mockUpdateAgentHandler as he}from"./handlers/agent.handlers.js";import{mockCreateToolHandler as ge,mockGetToolHandler as _e,mockListToolsHandler as ve,mockTestToolHandler as ye}from"./handlers/tool.handlers.js";import{mockCancelRunHandler as be,mockExecuteAgentHandler as xe,mockGetRunHandler as Se,mockGetRunMetricsHandler as Ce,mockListRunsHandler as we}from"./handlers/run.handlers.js";import{AgentDetailPresentation as Te,AgentListPresentation as Ee}from"./presentations/agent-list.js";import{RunDetailPresentation as De,RunListPresentation as Oe,RunMetricsPresentation as ke}from"./presentations/run-list.js";import{ToolDetailPresentation as Ae,ToolRegistryPresentation as je}from"./presentations/tool-registry.js";import{AgentConsoleDashboardPresentation as Me}from"./presentations/dashboard.js";import{AgentConsolePresentations as Ne}from"./presentations/index.js";export{Me as AgentConsoleDashboardPresentation,k as AgentConsoleFeature,Ne as AgentConsolePresentations,e as AgentCreatedEvent,t as AgentCreatedPayload,Te as AgentDetailPresentation,N as AgentEntity,Ee as AgentListPresentation,P as AgentStatusEnum,n as AgentToolAssignedEvent,r as AgentToolAssignedPayload,F as AgentToolEntity,i as AgentToolRemovedEvent,a as AgentToolRemovedPayload,o as AgentUpdatedEvent,s as AgentUpdatedPayload,J as AssignToolToAgentCommand,ee as CancelRunCommand,Y as CreateAgentCommand,U as CreateToolCommand,te as ExecuteAgentCommand,X as GetAgentQuery,ne as GetRunLogsQuery,re as GetRunMetricsQuery,ie as GetRunQuery,ae as GetRunStepsQuery,W as GetToolQuery,Z as ListAgentsQuery,oe as ListRunsQuery,G as ListToolsQuery,L as LogLevelEnum,se as MOCK_AGENTS,ce as MOCK_RUNS,le as MOCK_RUN_LOGS,ue as MOCK_RUN_STEPS,de as MOCK_TOOLS,c as MessageGeneratedEvent,l as MessageGeneratedPayload,u as MessageTypeEnum,I as ModelProviderEnum,Q as RemoveToolFromAgentCommand,d as RunCancelledEvent,f as RunCancelledPayload,p as RunCompletedEvent,m as RunCompletedPayload,De as RunDetailPresentation,R as RunEntity,h as RunFailedEvent,g as RunFailedPayload,Oe as RunListPresentation,z as RunLogEntity,ke as RunMetricsPresentation,_ as RunStartedEvent,v as RunStartedPayload,B as RunStatusEnum,V as RunStepEntity,H as RunStepTypeEnum,K as TestToolCommand,A as ToolCategoryEnum,y as ToolCompletedEvent,b as ToolCompletedPayload,x as ToolCreatedEvent,S as ToolCreatedPayload,Ae as ToolDetailPresentation,j as ToolEntity,C as ToolInvokedEvent,w as ToolInvokedPayload,je as ToolRegistryPresentation,T as ToolStatusChangedEvent,E as ToolStatusChangedPayload,M as ToolStatusEnum,D as ToolUpdatedEvent,O as ToolUpdatedPayload,$ as UpdateAgentCommand,q as UpdateToolCommand,be as mockCancelRunHandler,fe as mockCreateAgentHandler,ge as mockCreateToolHandler,xe as mockExecuteAgentHandler,pe as mockGetAgentHandler,Se as mockGetRunHandler,Ce as mockGetRunMetricsHandler,_e as mockGetToolHandler,me as mockListAgentsHandler,we as mockListRunsHandler,ve as mockListToolsHandler,ye as mockTestToolHandler,he as mockUpdateAgentHandler};
+import{AgentCreatedEvent as e,AgentCreatedPayload as t,AgentToolAssignedEvent as n,AgentToolAssignedPayload as r,AgentToolRemovedEvent as i,AgentToolRemovedPayload as a,AgentUpdatedEvent as o,AgentUpdatedPayload as s,MessageGeneratedEvent as c,MessageGeneratedPayload as l,MessageTypeEnum as u,RunCancelledEvent as d,RunCancelledPayload as f,RunCompletedEvent as p,RunCompletedPayload as m,RunFailedEvent as h,RunFailedPayload as g,RunStartedEvent as _,RunStartedPayload as v,ToolCompletedEvent as y,ToolCompletedPayload as b,ToolCreatedEvent as x,ToolCreatedPayload as S,ToolInvokedEvent as C,ToolInvokedPayload as w,ToolStatusChangedEvent as T,ToolStatusChangedPayload as E,ToolUpdatedEvent as D,ToolUpdatedPayload as O}from"./events.js";import{AgentConsoleFeature as k}from"./feature.js";import{ToolCategoryEnum as A,ToolEntity as j,ToolStatusEnum as M}from"./entities/tool.js";import{AgentEntity as N,AgentStatusEnum as P,AgentToolEntity as F,ModelProviderEnum as I}from"./entities/agent.js";import{LogLevelEnum as L,RunEntity as R,RunLogEntity as z,RunStatusEnum as B,RunStepEntity as V,RunStepTypeEnum as H}from"./entities/run.js";import"./entities/index.js";import{CreateToolCommand as U,GetToolQuery as W,ListToolsQuery as G,TestToolCommand as K,UpdateToolCommand as q}from"./contracts/tool.js";import{AssignToolToAgentCommand as J,CreateAgentCommand as Y,GetAgentQuery as X,ListAgentsQuery as Z,RemoveToolFromAgentCommand as Q,UpdateAgentCommand as $}from"./contracts/agent.js";import{CancelRunCommand as ee,ExecuteAgentCommand as te,GetRunLogsQuery as ne,GetRunMetricsQuery as re,GetRunQuery as ie,GetRunStepsQuery as ae,ListRunsQuery as oe}from"./contracts/run.js";import"./contracts/index.js";import{MOCK_AGENTS as se,MOCK_RUNS as ce,MOCK_RUN_LOGS as le,MOCK_RUN_STEPS as ue,MOCK_TOOLS as de}from"./handlers/mock-data.js";import{mockCreateAgentHandler as fe,mockGetAgentHandler as pe,mockListAgentsHandler as me,mockUpdateAgentHandler as he}from"./handlers/agent.handlers.js";import{mockCreateToolHandler as ge,mockGetToolHandler as _e,mockListToolsHandler as ve,mockTestToolHandler as ye}from"./handlers/tool.handlers.js";import{mockCancelRunHandler as be,mockExecuteAgentHandler as xe,mockGetRunHandler as Se,mockGetRunMetricsHandler as Ce,mockListRunsHandler as we}from"./handlers/run.handlers.js";import{AgentDetailPresentation as Te,AgentListPresentation as Ee}from"./presentations/agent-list.js";import{RunDetailPresentation as De,RunListPresentation as Oe,RunMetricsPresentation as ke}from"./presentations/run-list.js";import{ToolDetailPresentation as Ae,ToolRegistryPresentation as je}from"./presentations/tool-registry.js";import{AgentConsoleDashboardPresentation as Me}from"./presentations/dashboard.js";import{AgentConsolePresentations as Ne}from"./presentations/index.js";import"./docs/index.js";export{Me as AgentConsoleDashboardPresentation,k as AgentConsoleFeature,Ne as AgentConsolePresentations,e as AgentCreatedEvent,t as AgentCreatedPayload,Te as AgentDetailPresentation,N as AgentEntity,Ee as AgentListPresentation,P as AgentStatusEnum,n as AgentToolAssignedEvent,r as AgentToolAssignedPayload,F as AgentToolEntity,i as AgentToolRemovedEvent,a as AgentToolRemovedPayload,o as AgentUpdatedEvent,s as AgentUpdatedPayload,J as AssignToolToAgentCommand,ee as CancelRunCommand,Y as CreateAgentCommand,U as CreateToolCommand,te as ExecuteAgentCommand,X as GetAgentQuery,ne as GetRunLogsQuery,re as GetRunMetricsQuery,ie as GetRunQuery,ae as GetRunStepsQuery,W as GetToolQuery,Z as ListAgentsQuery,oe as ListRunsQuery,G as ListToolsQuery,L as LogLevelEnum,se as MOCK_AGENTS,ce as MOCK_RUNS,le as MOCK_RUN_LOGS,ue as MOCK_RUN_STEPS,de as MOCK_TOOLS,c as MessageGeneratedEvent,l as MessageGeneratedPayload,u as MessageTypeEnum,I as ModelProviderEnum,Q as RemoveToolFromAgentCommand,d as RunCancelledEvent,f as RunCancelledPayload,p as RunCompletedEvent,m as RunCompletedPayload,De as RunDetailPresentation,R as RunEntity,h as RunFailedEvent,g as RunFailedPayload,Oe as RunListPresentation,z as RunLogEntity,ke as RunMetricsPresentation,_ as RunStartedEvent,v as RunStartedPayload,B as RunStatusEnum,V as RunStepEntity,H as RunStepTypeEnum,K as TestToolCommand,A as ToolCategoryEnum,y as ToolCompletedEvent,b as ToolCompletedPayload,x as ToolCreatedEvent,S as ToolCreatedPayload,Ae as ToolDetailPresentation,j as ToolEntity,C as ToolInvokedEvent,w as ToolInvokedPayload,je as ToolRegistryPresentation,T as ToolStatusChangedEvent,E as ToolStatusChangedPayload,M as ToolStatusEnum,D as ToolUpdatedEvent,O as ToolUpdatedPayload,$ as UpdateAgentCommand,q as UpdateToolCommand,be as mockCancelRunHandler,fe as mockCreateAgentHandler,ge as mockCreateToolHandler,xe as mockExecuteAgentHandler,pe as mockGetAgentHandler,Se as mockGetRunHandler,Ce as mockGetRunMetricsHandler,_e as mockGetToolHandler,me as mockListAgentsHandler,we as mockListRunsHandler,ve as mockListToolsHandler,ye as mockTestToolHandler,he as mockUpdateAgentHandler};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/example.agent-console",
-  "version": "0.0.0-canary-20251210082611",
+  "version": "0.0.0-canary-20251212004227",
   "description": "Agent Console example - AI agent orchestration with tools, runs, and logs",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,8 @@
     "./contracts/agent": "./src/contracts/agent.ts",
     "./contracts/run": "./src/contracts/run.ts",
     "./contracts/tool": "./src/contracts/tool.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/agent-console.docblock": "./src/docs/agent-console.docblock.ts",
     "./entities": "./src/entities/index.ts",
     "./entities/agent": "./src/entities/agent.ts",
     "./entities/log": "./src/entities/log.ts",
@@ -63,6 +65,8 @@
       "./contracts/agent": "./dist/contracts/agent.js",
       "./contracts/run": "./dist/contracts/run.js",
       "./contracts/tool": "./dist/contracts/tool.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/agent-console.docblock": "./dist/docs/agent-console.docblock.js",
       "./entities": "./dist/entities/index.js",
       "./entities/agent": "./dist/entities/agent.js",
       "./entities/log": "./dist/entities/log.js",

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

@@ -0,0 +1,97 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/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/index.ts

@@ -32,3 +32,4 @@ export * from './presentations';
 
 // Feature spec export
 export * from './feature';
+import './docs';