Skip to content
ContractSpec
Start here

Package manual · examples

·Examples and implementation patterns

example.agent-console

Agent Console example - AI agent orchestration with tools, runs, and logs

examplesexamplev5.0.5stableservernode
@lssm-tech/example.agent-console
bun add @lssm-tech/example.agent-console
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

Agent Console example - AI agent orchestration with tools, runs, and logs.

What This Demonstrates

  • Rich Landing Screen: Product introduction explaining agent management concepts, demo path, and navigation.
  • Navigation Rail: Clear sidebar navigation between Overview, Agent Fleet, Tool Registry, Run History, Metrics, and Proof.
  • Agent Entity: Full lifecycle management with status tracking (draft, active, paused, retired).
  • Run Tracking: Event-driven execution with status enums and state transitions.
  • Tool Registry: Typed schemas and operation handlers for agent capabilities.
  • Contract-Backed Visualizations: Charts and metrics derived from run activity.
  • Deterministic Replay: Offline-safe demo runtime with proof evidence.
  • Presentation Layer: React UI components, hooks, modals, overlays, and DataTable for run history.
  • Multi-Surface Output: Markdown and React renderers for different contexts.
  • Seeded Local Data: Mock agents, tools, and runs for immediate demo usage.

Canonical Demo Path

  • Default sandbox route: /sandbox
  • Explicit sandbox route: /sandbox?template=agent-console
  • Proof artifact: examples/agent-console/proofs/agent-console-meetup.replay.json

The canonical walkthrough is deterministic and local-first:

  1. Landing Screen - Start on the product introduction explaining agent management concepts.
  2. Navigation - Use the sidebar rail to navigate between sections.
  3. Agent Fleet - Inspect seeded agents (Customer Support Bot, Code Review Assistant, Data Analyst, Meeting Scheduler).
  4. Tool Registry - Browse available tools and their schemas.
  5. Run History - View execution history with status and metrics.
  6. Metrics - See contract-backed visualizations of run activity.
  7. Proof - Inspect deterministic replay evidence.

New Features

  • LandingScreen: Product-style introduction with value proposition and demo path.
  • AgentConsolePreviewV2: Enhanced preview with sidebar navigation and dedicated screens.
  • AgentConsoleNav: Navigation rail for moving between sections.
  • Navigation: Clear paths from landing to specific agent, tool, and run views.

Runtime Boundaries

  • React hooks and the sandbox use createAgentConsoleDemoHandlers(...) for the meetup path.
  • Markdown renderers prefer runtime-fetched data and fall back to the same deterministic demo handlers.
  • The demo runtime is intentionally mocked and offline-safe by default.
  • Database-backed createAgentHandlers(db) remains available for non-demo runtime wiring.

Running Locally

From examples/agent-console:

  • bun run dev
  • bun run build
  • bun run test
  • bun run proof
  • bun run typecheck
  • bun run preflight

From the repository root:

  • bun run meetup:agent-console:policy
  • bun run meetup:agent-console:proof
  • bun run meetup:agent-console:preflight

Usage

Use @lssm-tech/example.agent-console as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles.

Architecture

  • src/agent is part of the package's public or composition surface.
  • src/agent.capability.ts defines a capability surface.
  • src/agent.feature.ts defines a feature entrypoint.
  • src/docs/ contains docblocks and documentation-facing exports.
  • src/example.ts is the runnable example entrypoint.
  • src/handlers/ contains handlers or demo adapters wired to contract surfaces.
  • src/index.ts is the root public barrel and package entrypoint.
  • src/proof/ contains the exported meetup proof scenario and suite.
  • src/ui/AgentConsolePreview.tsx is the cross-platform preview component used by web and mobile example surfaces.

Public Entry Points

  • Export . resolves through ./src/index.ts.
  • Export ./agent resolves through ./src/agent/index.ts.
  • Export ./agent.capability resolves through ./src/agent.capability.ts.
  • Export ./agent.feature resolves through ./src/agent.feature.ts.
  • Export ./agent/agent.entity resolves through ./src/agent/agent.entity.ts.
  • Export ./agent/agent.enum resolves through ./src/agent/agent.enum.ts.
  • Export ./agent/agent.event resolves through ./src/agent/agent.event.ts.
  • Export ./agent/agent.handler resolves through ./src/agent/agent.handler.ts.
  • Export ./agent/agent.operation resolves through ./src/agent/agent.operation.ts.
  • Export ./agent/agent.presentation resolves through ./src/agent/agent.presentation.ts.
  • Export ./proof resolves through ./src/proof/index.ts.
  • Export ./proof/meetup-proof.scenario resolves through ./src/proof/meetup-proof.scenario.ts.
  • Export ./proof/meetup-proof.suite resolves through ./src/proof/meetup-proof.suite.ts.
  • The package publishes 72 total export subpaths; keep docs aligned with package.json.

Local Commands

  • bun run dev — contractspec-bun-build dev
  • bun run build — contractspec-bun-build build
  • bun run test — bun test
  • bun run proof — bun ../../scripts/generate-agent-console-meetup-proof.ts
  • bun run preflight — bun run build && bun run typecheck && bun run test && bun ../../scripts/check-agent-console-meetup-policy.ts && bun run proof
  • bun run lint — bun lint:fix
  • bun run lint:check — biome check .
  • bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
  • bun run typecheck — tsgo --noEmit
  • bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
  • bun run publish:pkg:canary — bun publish:pkg --tag canary
  • bun run clean — rimraf dist .turbo
  • bun run build:bundle — contractspec-bun-build transpile
  • bun run build:types — contractspec-bun-build types
  • bun run prebuild — contractspec-bun-build prebuild

Recent Updates

  • Unified the meetup demo around a single seeded runtime.
  • Added focused handler tests, a sandbox smoke test, and a harness replay proof.
  • Added a slice-scoped meetup preflight instead of relying on the repo-wide policy backlog.

Notes

  • Works alongside @lssm-tech/lib.contracts-spec, @lssm-tech/lib.design-system, @lssm-tech/lib.example-shared-ui, @lssm-tech/lib.runtime-sandbox, @lssm-tech/lib.schema, ...

Relationships

THIS PACKAGEexample.agent-console83 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

12 declarations

Declared capabilities

This manifest does not declare a capability catalogue. Use the guide, import map and source to assess the package.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../scripts/biome.cjs check --write .
  • lint:checknode ../../scripts/biome.cjs check .
  • testbun test
  • proofbun ../../scripts/generate-agent-console-meetup-proof.ts
  • preflightbun run build && bun run typecheck && bun run test && bun ../../scripts/check-agent-console-meetup-policy.ts && bun run proof
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit