SuperCharged-Claude-Code-Upgrade/dexto/AGENTS.md

Dexto Development Guidelines for AI Assistants

This repo is reviewed by automated agents (including CodeRabbit). This file is the source of truth for repo-wide conventions and review expectations.

Package manager: pnpm (do not use npm/yarn)

Code Quality Requirements

Before completing significant tasks, prompt the user to ask if they want to run:

/quality-checks

This runs scripts/quality-checks.sh for build, tests, lint, and typecheck. See .claude/commands/quality-checks.md.

General Rules

• Optimize for correctness. Use facts and code as the source of truth.
• Read relevant code before recommending changes. Prefer grep/glob + direct file references over assumptions.
• If something requires assumptions, state them and ask for confirmation.
• Don't communicate to the user via code comments. Comments are for future readers of the code, not for explaining decisions to the user.

Stack Rules (important)

These rules are intended to prevent stack fragmentation and review churn.

WebUI (packages/webui)

• Build tool: Vite
• Routing: TanStack Router (@tanstack/react-router). Do not introduce react-router-dom or other routing systems unless explicitly migrating.
• Server-state/data fetching: TanStack Query (@tanstack/react-query). Prefer it for request caching, invalidation, and async state.
• Client-side state: Zustand exists; prefer it only for genuinely client-only state (UI preferences, local toggles). Avoid duplicating server state into stores.

Server (packages/server)

• HTTP API: Hono routes live in packages/server/src/hono/routes/*.ts.
• Error mapping middleware: packages/server/src/hono/middleware/error.ts.

Core (packages/core)

• Core is the business logic layer. Keep policy, validation boundaries, and reusable services here.

CLI (packages/cli)

• Entry point: packages/cli/src/cli/index.ts
• Static commands (e.g., dexto init, dexto setup): packages/cli/src/cli/commands/
• Interactive CLI commands (e.g., /help, /compact): packages/cli/src/cli/commands/interactive-commands/
• Ink-based UI components: packages/cli/src/cli/ink-cli/

Other Important Packages

• @dexto/client-sdk: Lightweight type-safe client for the Dexto API (Hono-based). Use for external integrations.
• @dexto/agent-management: Agent registry, config discovery, preferences, and agent resolution logic.
• @dexto/analytics: Shared PostHog analytics utilities for CLI and WebUI (opt-in telemetry).
• @dexto/registry: Shared registry data (MCP server presets, etc.) for CLI and WebUI.
• @dexto/tools-*: Modular tool packages (tools-filesystem, tools-process, tools-todo, tools-plan). Each provides a tool provider that registers with the core tool registry.

Images (packages/image-*)

Images are pre-configured bundles of providers, tools, and defaults for specific deployment targets. They use defineImage() from core.

• @dexto/image-local: Local development image with filesystem/process tools, SQLite storage.
• @dexto/image-bundler: Build tool for bundling images (dexto-bundle CLI).

Image definition files use the convention dexto.image.ts and register providers (blob stores, custom tools) as side-effects when imported.

Adding New Packages

All @dexto/* packages use fixed versioning (shared version number).

When creating a new package:

1. Add the package name to the fixed array in .changeset/config.json
2. Set its version in package.json to match other packages (check packages/core/package.json)

Avoiding Duplication (repo-wide)

Before adding any new helper/utility/service:

1. Search the codebase first (glob/grep for similar patterns).
2. Prefer extending existing code over creating new.
3. If new code is necessary, justify why existing code doesn't work.

This applies everywhere (core, server, cli, webui). Violations will be flagged in review.

Architecture & Design Patterns

API / Server Layer

• Routes should be thin wrappers around core capabilities (primarily DextoAgent + core services).
• Keep business logic out of routes; keep route code focused on:
  • request parsing/validation
  • calling core
  • mapping errors + returning responses
• DextoAgent class should also not have too much business logic; should call helper methods within services it owns.

Service Initialization

• Config file is source of truth: Agent YAML files in agents/ directory (e.g., agents/coding-agent/coding-agent.yml).
• Override pattern for advanced use: use InitializeServicesOptions only for top-level services (avoid wiring every internal dependency).
• CLI Config Enrichment: CLI adds per-agent paths (logs, database, blobs) via enrichAgentConfig() before agent initialization.
  • Source: packages/agent-management/src/config/config-enrichment.ts

Execution Context Detection

Dexto infers its execution environment to enable context-aware defaults and path resolution. Use these utilities when behavior should differ based on how dexto is running.

Context types:

• dexto-source: Running within the dexto monorepo itself (development)
• dexto-project: Running in a project that has dexto as a dependency
• global-cli: Running as globally installed CLI or in a non-dexto project

Key files:

• packages/core/src/utils/execution-context.ts - Context detection
• packages/core/src/utils/path.ts - Context-aware path resolution
• packages/cli/src/cli/utils/api-key-setup.ts - Context-aware setup UX

Zod / Schema Design

• Always use .strict() for configuration objects (reject typos/unknown fields).
• Prefer discriminatedUnion over union for clearer errors.
• Describe fields with .describe() where it improves usability.
• Prefer sensible defaults via .default().
• Use superRefine for cross-field validation.

Type extraction conventions (repo rule):

• Use z.input<typeof Schema> for raw/unvalidated input types.
• Use z.output<typeof Schema> for validated/output types.
• Do not use z.infer (lint-restricted).

Result Pattern & Validation Boundary

Core Principles

• DextoAgent is the validation boundary: public-facing methods validate inputs; internal layers can assume validated inputs.
• Internal validation helpers should return Result-style objects; public methods throw typed errors.

Result Helpers

Use standardized helpers from: packages/core/src/utils/result.ts

• ok(data, issues?)
• fail(issues)
• hasErrors(issues)
• splitIssues(issues)
• zodToIssues(zodError)

Error Handling

Core Error Classes

• DextoRuntimeError: single runtime failure (I/O, network, invariant violation)
• DextoValidationError: multiple validation issues

Rules

• Avoid throw new Error() in packages/core. Prefer typed errors.
• Non-core packages may use plain Error when a typed error is not available.
• Use module-specific error factory pattern for new modules.
  • Reference examples:
    • packages/core/src/config/errors.ts
    • packages/core/src/logger/v2/errors.ts
    • packages/core/src/storage/errors.ts
    • packages/core/src/telemetry/errors.ts
• Exemption: Build-time CLI tools and development tooling (bundlers, compilers, build scripts) are exempt from the strict DextoRuntimeError/DextoValidationError requirement. Plain Error is acceptable for build tool failures to align with standard build tool practices (tsc, esbuild, vite).

Server/API error mapping

• Source of truth: mapErrorTypeToStatus() in packages/server/src/hono/middleware/error.ts

Imports / ESM

• In packages/core, local relative imports must include .js in the TypeScript source for Node ESM output compatibility.
• Do not add .js to package imports (e.g. zod, hono, @dexto/*).

OpenAPI Documentation

• Never directly edit docs/static/openapi/openapi.json (generated file).
• OpenAPI is generated from Hono route definitions in packages/server/src/hono/routes/*.ts.

Update process:

1. Modify route definitions / Zod schemas in packages/server/src/hono/routes/*.ts
2. Run pnpm run sync-openapi-docs
3. Verify the generated output includes your changes

Logging

The repo contains logger v1 and logger v2 APIs (core). Prefer patterns compatible with structured logging.

• Prefer: logger.info('Message', { contextKey: value }) (structured context as the second parameter where supported)
• Avoid: logger.error('Failed:', err) style extra-arg logging; it's ambiguous across logger versions/transports.
• Template literals are fine when interpolating values:
  • logger.info(\Server running at ${url}`)`

Colors:

• Color formatting exists (chalk-based), but treat color choice as optional and primarily CLI-facing (don't encode “must use exact color X” rules in new code unless the existing subsystem already does).

Browser safety:

• packages/core/src/logger/logger.ts is Node-oriented (fs/path/winston). Be careful not to import Node-only runtime modules into packages/webui bundles. Prefer import type when consuming core types from the WebUI.

TypeScript Guidelines

• Strict null safety: handle null / undefined explicitly.
• Avoid any across the repo.
  • Prefer unknown + type guards.
  • If any is unavoidable (third-party typing gaps / boundary code), keep the usage local and justify it.
• In tests, prefer @ts-expect-error over as any when intentionally testing invalid inputs.
• Avoid introducing optional parameters unless necessary; prefer explicit overloads or separate functions if it improves call-site clarity.

Module Organization

• Selective barrel strategy: only add index.ts at real public module boundaries.
• Prefer direct imports internally; avoid deep re-export chains.
• Avoid wildcard exports; prefer explicit named exports.
• Watch for mega barrels (>20 symbols or >10 files) and split if needed.

Git / PR Standards

• Never use git add . or git add -A. Stage explicit files/paths only.
• Always inspect staged files before committing.
• Never amend commits (git commit --amend). Create new commits instead.
• Don't include AI-generated footers in commits/PRs.
• Keep commit messages technical and descriptive.

Documentation Changes

• Always request user review before committing documentation changes.
• Never auto-commit documentation updates.
• Keep documentation user-focused; avoid exposing unnecessary internal complexity.

Testing

Test types:

• Unit: *.test.ts
• Integration: *.integration.test.ts

Test location: Co-locate tests with source files (e.g., foo.ts → foo.test.ts in same directory).

Common commands:

• pnpm test
• pnpm run test:unit
• pnpm run test:integ

When fixing bugs, add regression coverage where feasible.

Maintaining This File

Keep AGENTS.md updated when:

• Adding a new package: add a brief description under the appropriate Stack Rules section
• Architecture boundaries change (server/webui/cli)
• Repo-wide conventions change (lint/type patterns, errors, OpenAPI generation)
• File paths referenced here move