AdaptiveAgent

Highlights since v0.1.48

• JEV-based agent selection: opt-in TypeSafe JEV routing selects a capable profile from the agent catalog using the objective and attachment modalities, with configurable policy and confidence thresholds.
• Adaptive execution: opt-in routing chooses between a direct run and specialist orchestration across text, image, file, and audio inputs. Explicit --agent and --orchestrate overrides remain available.
• Inspectable orchestration: specialist assignments and routing decisions are recorded with durable runs; a JEV study command compares prompt or persisted-session routing cases.
• Unified session recovery: SDK and desktop bridge hosts can recover ordinary runs, swarms, and saved orchestration through one entry point, preserving completed work and surfacing cases that need user action.
• Historical configuration evidence: inspect persisted session model, profile, and snapshot settings with trace-session settings session, without confusing current profile files with historical configuration.
• Lower-memory model streaming: built-in adapters no longer retain raw stream chunks; generation and output repair share runtime execution policy.

See the changelog for the full update and the configuration examples below for JEV selection and adaptive execution.

What is AdaptiveAgent?

AdaptiveAgent is the operating layer for reliable AI agents.

It is a Bun + TypeScript runtime and CLI stack for running goal-oriented agents with typed tools, structured events, approvals, resumable runs, retries, child-run delegation, and multi-model support. It helps teams move from fragile agent demos to controlled, inspectable, recoverable production workflows.

The stack includes decision-oriented trace reporting, an embedded SQLite runtime, host-facing desktop and trace sidecars, a Tauri desktop app, and an authenticated capability gateway. Durable runtime semantics remain in core.

Getting Started in 60secs

1. Install

macOS:

curl -fsSL https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.sh | sh

Linux:

curl -fsSL https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.ps1 | iex

If the installer says adaptive-agent is not on your PATH, run the exact PATH command it prints.

2. Add an API key

The default quickstart calls OpenRouter directly:

export OPENROUTER_API_KEY="<your-key>"

Windows PowerShell:

$env:OPENROUTER_API_KEY = "<your-key>"

Other supported providers use their own keys:

• OpenRouter: OPENROUTER_API_KEY
• Mistral: MISTRAL_API_KEY
• Mesh: MESH_API_KEY
• Ollama: no API key, but Ollama must be running locally

Optional web tool providers are configured independently:

export PARALLEL_API_KEY="<your-key>"
export WEB_SEARCH_PROVIDER=parallel
export WEB_READ_PAGE_PROVIDER=parallel

web_search defaults to DuckDuckGo unless an API-backed provider is configured. read_web_page defaults to direct HTTP fetch unless WEB_READ_PAGE_PROVIDER=parallel is set with PARALLEL_API_KEY.

3. Init and run

adaptive-agent init
adaptive-agent doctor --provider-check
adaptive-agent run "Hello, confirm you are working"

That is it. You now have a configured local agent that can run goals, use tools, and produce inspectable runtime history.

Four CLI demonstrations

These examples progress from a single default-agent run to scoped delegation and capability-based specialist routing. Run them from the repository or project that you want the agents to inspect.

1. Run one useful goal

Ask the default agent to inspect the current repository while showing progress and a compact post-run summary:

adaptive-agent run \
  --progress \
  --inspect \
  "Explain this repository to a new contributor in five bullets."

This exercises default agent resolution, one-shot goal execution, local tools, progress updates, and persisted run inspection. Add --events to display the full lifecycle event stream.

Discover available profiles before selecting one by name:

adaptive-agent agents
adaptive-agent run --agent reviewer "Review the current changes."

Use adaptive-agent agents --output json when embedding discovery in a host. It returns safe metadata and the exact id, configPath, and configurationFingerprint selection descriptor used by desktop-bridge. Discovery does not load agent tools or delegate handlers and does not expose credentials or system instructions.

2. Refine an idea through chat

Start an interactive conversation:

adaptive-agent chat

For example, develop a release plan over several turns:

You: Help me plan the next release of this project.
You: Adapt the plan for a small open-source team with one maintainer.
You: Turn it into a checklist ordered by release risk.

You can also provide the first message directly or pipe it from a file:

adaptive-agent chat "Help me review this implementation plan."
cat implementation-plan.md | adaptive-agent chat

Use chat while shaping a goal through conversation. Use run when the desired outcome is already clear enough to execute as one objective.

TypeSafe JEV routing study

The repository study script can evaluate a prompt against the current agent catalog or replay persisted SQLite routing cases without modifying history:

bun run jev-routing-study prompt --attachment-type image "Extract this diagram"
bun run jev-routing-study history --session-id <session-id>
bun run jev-routing-study history --limit 10

It uses ./agent.settings.json by default, including the configured TypeSafe model and selection policy. With executionRouting.mode: "adaptive", the study uses the Agent SDK's opt-in staged TypeSafe path: decide execution mode first, then evaluate only direct profile selection or orchestration assignments. The exact state and question shapes, with direct and orchestration examples, are documented in Staged TypeSafe Routing Requests. CLI and desktop bridge default to combined routing and can opt into staged routing with agentSelection.typesafe.routingStrategy: "staged". JSON results include the mode, primary profile, assignments, per-stage scores and usage; table mode shows the existing/studied mode pair. Each staged evaluation can make two paid calls; --repeat multiplies both. If those settings do not specify a SQLite path, history defaults to ~/.adaptiveAgent/desktop.sqlite. Use --policy <path> for a study-only policy, --output json|jsonl for machine-readable results, and --show-state or --show-response for diagnostics. Historical cases without linked selector inputs use the current catalog by default and are marked approx; pass --no-allow-current-catalog to require exact context. Adaptive history re-evaluates even persisted single-profile JEV decisions, because those are not staged-routing results. The table's modalities column uses I, A, and F for image, audio, and file (- for text-only). Latency, token, and cost pairs are existing/JEV; JEV latency is client wall-clock time and JEV cost is an input-token estimate at the configurable price (default $0.042 per million input tokens). --repeat performs repeated paid calls and disables cache reuse.

3. Delegate focused research to a skill

The default core bundle includes a planner agent and a scoped research skill. Give the planner a goal that combines local repository evidence with external research:

adaptive-agent run \
  --agent planner \
  --events \
  --inspect \
  "Compare this project's retry and recovery model with current agent-runtime practices. Produce a concise plan for communicating three meaningful differentiators, cite the external sources used, and identify claims that still need verification."

The planner owns the top-level objective and can delegate the research portion to a skill-backed child run. The delegate receives focused instructions and a scoped tool set, then returns its findings to the parent for synthesis. The event stream makes the parent and child-run boundaries visible.

4. Route a request to a specialist

Orchestration routes work using agent catalog metadata instead of asking a model to choose arbitrary profiles. The installed reviewer profile declares code review as a preferred subject, so it can handle the specialist stage before the requested default agent synthesizes the final response:

adaptive-agent run \
  --agent default-agent \
  --orchestrate \
  --catalog reviewer \
  --events \
  --inspect \
  "Perform a code review of the current changes and prioritize correctness, security, and missing tests."

Catalog profiles can also declare supported and preferred text, image, file, and audio modalities. With multiple matching specialists, orchestration can run independent stages before final synthesis. Preview the resolved configuration and request without spending model tokens by adding --dry-run.

--orchestrate is an explicit force override: it uses every valid, non-archived run profile discovered from configured agents.dirs, plus any profiles named with --catalog. The requested --agent remains the primary and final synthesis profile. Routing validates every attachment modality before starting a stage; missing capability metadata means text-only. When one specialist wins multiple modalities, it receives all of those attachments in one grouped run. Run output and durable plans record the selected catalog IDs, grouped modality assignments, routing reason, and credential-free catalog fingerprint.

Plain run is unchanged: it still executes one fixed profile or, when settings.agent.mode is auto, selects one profile that supports every input modality. Automatic direct-versus-orchestrated selection is not enabled in this phase.

Opt-in adaptive execution routing

To let the configured agentSelection.engine choose direct execution or a validated specialist orchestration, opt in explicitly:

{
  "agent": {
    "mode": "auto",
    "configPath": "./agents/default.json"
  },
  "executionRouting": {
    "mode": "adaptive",
    "maxSpecialists": 4
  },
  "agentSelection": {
    "engine": "typesafe",
    "lowConfidenceFallback": "error",
    "typesafe": {
      "model": "jev-latest",
      "apiKeyEnv": "TYPESAFE_API_KEY",
      "policy": {
        "relevance": {
          "instructions": "Is this profile a strong match for the objective and this attachment modality?"
        },
        "selection": {
          "candidateCriteria": "Prefer the narrowest capable specialist."
        },
        "routing": {
          "modeInstructions": "Choose direct only when one profile should handle the complete objective; otherwise choose orchestration.",
          "primaryInstructions": "Choose the best profile to own and synthesize the complete objective.",
          "assignmentInstructions": "Choose the strongest capable specialist for this modality."
        }
      }
    }
  }
}

Both agent and typesafe engines produce the same validated ExecutionRoutingDecision. TypeSafe evaluates candidate-by-modality relevance, execution mode, primary profile, and modality assignments. The agent engine returns the equivalent structured object from a tool-free router run. Agent SDK rejects unknown IDs, unsupported or duplicate assignments, missing modalities, and decisions exceeding maxSpecialists before starting execution. The optional TypeSafe policy.routing questions tune execution-shape, primary, and per-modality choices independently of the legacy single-agent policy.selection.instructions; selection.candidateCriteria remains common guidance for candidate choices.

CLI and desktop-bridge can opt into mode-first TypeSafe routing by adding "routingStrategy": "staged" to agentSelection.typesafe while keeping agent.mode: "auto" and executionRouting.mode: "adaptive". The shared Agent SDK decision path then asks for execution mode first, followed by single-profile selection or modality-based orchestration assignments. Omission or "combined" preserves the existing request. Update/rebuild the SDK and restart the client after changing settings. See Staged TypeSafe Routing Requests for full request examples, rollout, rollback, and per-stage diagnostics.

On a TypeSafe selection or routing confidence/relevance threshold failure, Agent SDK asks agentSelection.agent to make the same kind of decision, or fails if it is absent. Set agentSelection.lowConfidenceFallback to error to disable this fallback explicitly, or agent to require a configured selector at settings validation time. Missing credentials, malformed answers, and invalid routing decisions still fail rather than silently falling back. The older executionRouting.lowConfidenceFallback: "direct" remains readable for the agent engine's adaptive routing; TypeSafe configurations using it must migrate to agentSelection.agent or explicit lowConfidenceFallback: "error". Explicit --agent remains fixed. Explicit --orchestrate remains a force override and preserves deterministic Phase 1 routing. Without executionRouting.mode: "adaptive", ordinary single-profile selection is unchanged.

Adaptive routing currently preserves the compatibility ordering in which routing/selection occurs before task preparation. The routing decision is recorded under request metadata and, for orchestration, in the durable plan and lifecycle events. Selector inputs contain safe profile summaries and attachment types/counts, not config paths, credentials, instructions, or attachment paths.

Delegation, orchestration, and swarms serve different scopes:

| Capability | Best use | | --- | --- | | Delegate skill | One running agent hands off a bounded responsibility to a scoped child run. | | Orchestration | The SDK routes known input modalities or subjects to catalog specialists. | | swarm-run | A coordinator dynamically decomposes a broad objective into independent worker runs and synthesizes their results. |

Choose the right CLI command

Use run for a one-shot goal. The command accepts the goal directly or reads it from a file:

adaptive-agent run "Summarize this repository and identify the main packages"
adaptive-agent run --file ./prompts/release-notes.md

Task preparation can assess and improve a goal before the execution agent runs it. Configure taskPreparation in agent.settings.json, or override its mode for one command with --enhance never|auto|always. A dry run performs task preparation but does not start the execution agent:

adaptive-agent run --dry-run --enhance auto \
  "Gather last week's AI news and write a styled HTML bulletin"

Preparation is a real model-backed run, so this kind of dry run can have latency and cost. Its output includes a preparation run ID. Reuse that exact prepared goal later without another preparation model call:

adaptive-agent run \
  --from-preparation 62e5b46f-18d8-49aa-ae55-e78f7980ca75 \
  --progress

--from-preparation supplies both the original and prepared goals from the persisted preparation, so do not add positional goal text or --file. It is also mutually exclusive with --enhance. Reuse requires the same SQLite or Postgres runtime; an in-memory preparation is not available after its CLI process exits. The consuming run records the original goal, prepared goal, preparation decision, and preparation run ID in metadata. trace-session reports both goals and the preparation run ID while keeping the preparation run separate from the execution trace.

Every run or chat start has a core sessionId. When a caller does not provide one, the runtime generates it. Inline task selection, task preparation, clarification attempts, and execution share the same session so their usage is accounted together. --from-preparation reuses the stored preparation session unless --session-id is supplied explicitly.

To select the execution profile for each task, set agent.mode to auto. The configured agent.id and agent.configPath remain the bootstrap profile. By default, agentSelection.agent (or the legacy taskPreparation.agent fallback) performs a tool-free structured selection from the valid, active run profiles in agents.dirs:

{
  "agent": {
    "mode": "auto",
    "id": "byok-agent",
    "configPath": "/Users/ugmurthy/.adaptiveAgent/agents/byok-agent.json"
  },
  "agents": {
    "dirs": ["$HOME/.adaptiveAgent/agents"]
  },
  "agentSelection": {
    "agent": "task-preparer"
  },
  "taskPreparation": {
    "agent": "task-preparer",
    "mode": "auto"
  }
}

Omitting agent.mode preserves fixed-profile behavior. An explicit CLI --agent or exact desktop runtime profile selection also remains fixed for that invocation.

TypeSafe JEV agent selection

Auto-selection can use TypeSafe JEV as a fast typed decision layer instead of a generative selector agent. Set TYPESAFE_API_KEY (or configure another apiKeyEnv) and select the TypeSafe engine:

{
  "agent": { "mode": "auto", "configPath": "./agents/default.json" },
  "agents": { "dirs": ["./agents"] },
  "agentSelection": {
    "engine": "typesafe",
    "agent": "agent-selector",
    "lowConfidenceFallback": "agent",
    "typesafe": {
      "model": "jev-1.13.0",
      "apiKeyEnv": "TYPESAFE_API_KEY",
      "policyPath": "./agent-routing-policy.json",
      "timeoutMs": 10000
    }
  },
  "executionRouting": { "mode": "adaptive", "maxSpecialists": 4 },
  "taskPreparation": { "mode": "auto", "agent": "task-preparer" }
}

Here agentSelection.agent is a tool-free selector/router used only on a low-confidence TypeSafe decision; taskPreparation.agent separately prepares the task after the execution profile and shape have been chosen. The policy file contains relevance, selection, routing, minimumConfidence, and minimumRelevance as shown below. Alternatively place that object inline at agentSelection.typesafe.policy, but do not set both policy and policyPath.

The policy file controls both JEV questions and the confidence gates without a code change:

{
  "relevance": {
    "instructions": "Is the referenced profile a strong match for this objective and all requested attachment types?",
    "criteria": {
      "true": "The profile has the relevant specialization, tools, and attachment capabilities.",
      "false": "The profile is mismatched or lacks a required capability."
    }
  },
  "selection": {
    "instructions": "Which candidate is the single best profile for this objective?",
    "candidateCriteria": "Prefer the narrowest capable specialist."
  },
  "minimumRelevance": 0.65,
  "minimumConfidence": 0.7
}

The same object can be placed inline at agentSelection.typesafe.policy; do not set both policy and policyPath. Before calling JEV, the CLI removes profiles that do not declare support for every supplied image, file, or audio modality. The JEV request contains the prompt, attachment modality names and counts, and safe profile summaries; it does not contain attachment paths or contents. An explicit policy replaces the built-in policy rather than merging with it: omitted question guidance is not inherited, and only thresholds specified in the policy are enforced. With no policy, the built-in guidance and 0.5 confidence/relevance thresholds apply. The desktop bridge uses the same policy for automatic runs; an exact desktop profile selection remains fixed. When either configured threshold is missed, the configured selector agent can make the decision; without that fallback, selection fails closed.

Use chat for an interactive conversation, or provide the first message on the command line:

adaptive-agent chat
adaptive-agent chat "Help me refine this implementation plan"

Use spec when the request is already described by an AdaptiveAgent JSON spec:

adaptive-agent spec ./task.json

Use swarm-run when a top-level objective should be decomposed into bounded worker runs and synthesized into one result:

adaptive-agent swarm-run \
  --agent coordinator-agent \
  --worker-catalog researcher.json,writer.json \
  --max-workers 2 \
  "Research the market and produce a launch brief"

Use ambient start to run a foreground supervisor that turns configured filesystem inbox or cron triggers into durable agent runs:

adaptive-agent ambient start --config ./ambient.config.json

The --config path is resolved from the directory where the command is run. Paths inside the config are resolved as described below.

Ambient filesystem inbox config

This complete example watches agent_inbox/pending for Markdown files. Each file's contents become the goal for one agent run.

{
  "version": 1,
  "workspaceRoot": ".",
  "artifactsRoot": "./artifacts/ambient",
  "agent": {
    "configPath": "./agents/inbox-agent.json"
  },
  "settings": {
    "configPath": "./agent.settings.json"
  },
  "runtime": {
    "mode": "sqlite"
  },
  "interaction": {
    "approvalMode": "reject",
    "clarificationMode": "fail"
  },
  "defaults": {
    "maxSteps": 30,
    "toolTimeoutMs": 120000,
    "modelTimeoutMs": 300000,
    "requireApprovalForWriteTools": true
  },
  "triggers": [
    {
      "id": "inbox",
      "type": "filesystem",
      "inboxDir": "./agent_inbox",
      "pattern": "*.md",
      "pollIntervalMs": 30000,
      "stabilityDelayMs": 1000
    }
  ]
}

The supervisor creates and manages this layout:

agent_inbox/
  pending/      # Put new .md task files here.
  processing/   # Files claimed by active runs.
  processed/    # Files whose runs succeeded.
  failed/       # Failed, interrupted, approval, or clarification cases.
  .ambient/
    tasks.jsonl # Append-only task ledger.

For example:

mkdir -p agent_inbox/pending
printf '%s\n' 'Summarize the release changes in CHANGELOG.md.' \
  > agent_inbox/pending/release-summary.md
adaptive-agent ambient start --config ./ambient.config.json

inboxDir is relative to workspaceRoot; the legacy-equivalent field name path is also accepted. pattern supports * wildcards and defaults to *.md. The supervisor waits stabilityDelayMs after detecting a file and only claims it if its size and modification time remain unchanged.

Ambient cron config

This complete example starts one run at 8:00 AM every weekday in New York:

{
  "version": 1,
  "workspaceRoot": ".",
  "artifactsRoot": "./artifacts/ambient",
  "agent": "./agents/daily-summary-agent.json",
  "settings": "./agent.settings.json",
  "runtime": {
    "mode": "sqlite"
  },
  "interaction": {
    "approvalMode": "reject",
    "clarificationMode": "fail"
  },
  "defaults": {
    "maxSteps": 30,
    "toolTimeoutMs": 120000,
    "modelTimeoutMs": 300000,
    "requireApprovalForWriteTools": true
  },
  "triggers": [
    {
      "id": "weekday-repo-summary",
      "type": "cron",
      "schedule": "0 8 * * MON-FRI",
      "timezone": "America/New_York",
      "goalFile": "./tasks/weekday-repo-summary.md",
      "artifactPath": "artifacts/ambient/weekday-repo-summary/{{yyyyMMdd}}-{{HH}}{{mm}}",
      "pollIntervalMs": 30000,
      "concurrency": 1,
      "misfirePolicy": "skip"
    }
  ]
}

The schedule is a five-field cron expression: minute, hour, day of month, month, and day of week. Lists, ranges, steps, three-letter month/weekday names, and 0 or 7 for Sunday are supported. timezone must be an IANA timezone and defaults to UTC.

Use exactly one of goalFile or an inline goal:

{
  "goal": "Review the repository and write today's engineering status summary."
}

goalFile is relative to workspaceRoot and is read for each occurrence. artifactPath is also relative to workspaceRoot and supports {{taskId}}, {{occurrenceId}}, {{triggerId}}, {{scheduledAt}}, {{yyyy}}, {{MM}}, {{dd}}, {{HH}}, {{mm}}, and {{yyyyMMdd}}. Cron task ledgers are stored under <artifactsRoot>/.ambient/. The current release supports only concurrency: 1 and misfirePolicy: "skip"; missed occurrences are not run later.

For both trigger types, workspaceRoot, agent, and settings paths are resolved relative to the ambient config file. A bare agent value such as "news-bulletin-agent" selects a discoverable agent by name. runtime.mode accepts memory, sqlite, or postgres. The safe unattended defaults are approvalMode: "reject" and clarificationMode: "fail"; approval or clarification requests therefore finish the ambient task without blocking the supervisor. Validate the config and inspect its resolved paths and defaults before starting:

adaptive-agent ambient start --config ./ambient.config.json --dry-run

For persisted runs, choose the control command based on what you need:

• inspect <runId>: show the current run state and a compact event summary.
• replay <runId>: render stored events without running the agent or its tools again.
• interrupt <runId>: request that an active run stop; use a durable runtime such as Postgres when controlling a run from another process.
• resume <runId>: continue an interrupted or waiting run in place.
• retry --run-id <runId>: make another attempt after a failed run.
• continue <runId>: create a new, auditable continuation linked to a failed source run while leaving that source run unchanged.
• recover <runId>: let the runtime choose the cheapest safe action among resume, retry, and continue. Add --dry-run to inspect the recovery plan first.

For example:

adaptive-agent inspect <runId>
adaptive-agent recover <runId> --dry-run
adaptive-agent recover <runId>

Recover a session from an SDK or desktop host

Programmatic hosts can recover ordinary runs, swarms, and saved catalog orchestration with the same SDK entry point:

const preview = await sdk.recover({ sessionId, dryRun: true });
const recovery = await sdk.recover({ sessionId });

if (recovery.outcome === 'completed') console.log(recovery.result);
else console.log(recovery.outcome, recovery.reason);

Recovery preserves successful independent workers/stages and reuses persisted continuations. It reports blocked, busy, or ambiguous cases rather than bypassing pending approvals, clarification, changed configurations, or uncertain tool effects. Dry runs invoke no models and change no durable execution state. Use the original runtime stores and keep the referenced profiles available; SQLite or Postgres is required across process restarts.

Desktop hosts can negotiate bridge protocol 1.20 and call agent/recover after runtime initialization. This is a host API, not a new desktop UI control; the CLI recover command still takes a run ID. See the SDK recovery contract for explicit selectors and approval handling, and the bridge protocol for RPC examples.

Use agent-create to generate an agent profile from a description. It previews the generated profile and asks for confirmation before writing it:

adaptive-agent agent-create \
  --id release-notes-writer \
  "Create an agent that turns changelog entries into concise release notes"

Use context to create and manage project-scoped bundles of prior run and session evidence:

adaptive-agent context create release-evidence \
  --ref run:550e8400-e29b-41d4-a716-446655440000 \
  --description "Evidence for the next release"
adaptive-agent context list
adaptive-agent context show release-evidence

Reuse prior evidence with a named context bundle

Create a project-scoped bundle of existing run and session outputs, then reuse it in direct run or chat requests:

adaptive-agent context create migration-research \
  --ref run:550e8400-e29b-41d4-a716-446655440000 \
  --ref session:session_456

adaptive-agent run \
  --context-bundle migration-research \
  "Draft the migration plan"

Bundles are stored under .adaptiveAgent/context-bundles in the selected --cwd. Use adaptive-agent context list, context show <name>, and context delete <name> to manage them. Bundle names, canonical digests, and the exact expanded refs are persisted in consuming run metadata for inspection. Values after run: must be complete run UUIDs; session IDs remain free-form strings.

Preparing handler-backed skills

A skill can expose a scoped tool by declaring a handler in SKILL.md:

my-skill/
|-- SKILL.md
|-- handler.ts
|-- package.json
`-- bun.lock

---
name: my-skill
description: Run the custom skill handler
handler: handler.ts
---

Use the handler to complete the delegated objective.

Put packages imported by handler.ts in the skill's package.json, then install them in the skill directory or an enclosing project. AdaptiveAgent prepares referenced handlers automatically when it loads an agent. You can also prepare and validate one explicitly:

adaptive-agent skill prepare ./skills/my-skill
adaptive-agent skill prepare ./skills/my-skill --force

Preparation uses the Bun runtime embedded in the binary CLI or agent-runtime sidecar. It compiles TypeScript, bundles ordinary JavaScript dependencies, and writes a platform-specific, content-addressed artifact under ~/.adaptiveAgent/cache/skill-handlers. The CLI and desktop sidecars use the same Agent SDK preparation path and resolve skills by absolute path, so sidecar behavior does not depend on its working directory.

Some dependencies cannot be bundled safely, including native .node addons, packages that discover modules dynamically, and packages that require files or executables beside node_modules. Keep those dependencies materialized beside the skill and select package mode in the skill's package.json:

{
  "type": "module",
  "dependencies": {
    "native-or-dynamic-package": "1.2.3"
  },
  "adaptiveAgent": {
    "handlerMode": "package"
  }
}

In package mode, the handler is loaded from the skill directory and normal module resolution finds its local or enclosing node_modules. The dependency must be compatible with Bun and with the sidecar's operating system and CPU.

Skills preparation do's and don'ts

Do:

• Commit package.json and a lockfile with the skill source.
• Declare every runtime dependency used by the handler.
• Run adaptive-agent skill prepare <dir> before selecting or running a new handler-backed skill; automatic preparation remains a startup fallback.
• Use the default bundled mode for portable JavaScript and TypeScript packages.
• Use package mode for native addons, dynamic module loading, or package-owned runtime assets, and test it on every target platform.
• Treat handler code and dependencies as trusted executable code. A handler runs with the permissions of the CLI or sidecar process.

Don't:

• Expect a package embedded inside the AdaptiveAgent binary to be visible to an external handler. Handler dependencies belong to the skill package.
• Expect preparation to download missing dependencies silently. Install or vendor them first; missing imports fail with an actionable error.
• Copy only handler.ts when the handler depends on package.json, a lockfile, assets, native modules, or package-mode node_modules.
• Share a package-mode artifact across operating systems or CPU architectures unless all of its dependencies are platform independent.
• Edit files in ~/.adaptiveAgent/cache/skill-handlers; change the skill source and prepare it again instead.

Repository packages

The current workspace packages are:

• @adaptive-agent/core in packages/core: runtime semantics, durable stores, events, snapshots, tools, delegation, retry, and continuation.
• @adaptive-agent/agent-sdk in packages/agent-sdk: user-facing adaptive-agent CLI, config loading, built-in tool registration, install/update flows, and evaluation helpers.
• @adaptive-agent/trace-session in packages/trace-session: decision-oriented SQLite/Postgres trace reporter with a read-only NDJSON JSON-RPC 2.0 stdio sidecar for native and desktop trace consumers.
• @adaptive-agent/trace-workbench in packages/trace-workbench: Bun + Svelte trace workbench for choosing persisted sessions/runs, exploring timelines, resource spend, messages, diagnostics, and exporting markdown/PDF reports.
• @adaptive-agent/gateway-protocol, @adaptive-agent/gateway-client, and @adaptive-agent/capability-gateway: shared JSON-RPC contracts, client integration, and the authenticated capability/inference gateway.
• @adaptive-agent/desktop-bridge: the NDJSON JSON-RPC 2.0 stdio sidecar for agent discovery and exact selection, runtime initialization, execution, run control, interactions, events, and safe CLI access.
• @adaptive-agent/desktop-app: the Tauri 2 + Svelte desktop client backed by desktop-bridge.

Useful local commands:

bun run core:test
bun run agent:build
bun run trace-session list traces --limit 20
bun run trace-session view run <run-id>
bun run trace-session settings session <session-id> --json
bun run trace-session compare <baseline-run-id> <candidate-run-id>
bun run trace-session aggregate model --since 7d
bun run trace-workbench:dev

trace-session reads core SQLite or Postgres runtime tables directly; gateway session tables are optional. Its default summary report separates runtime reliability from answer quality, reports missing evidence as uncertainty, and keeps model/tool output cost separate from external tool-provider cost. See packages/trace-session/README.md for the report model, investigation workflow, cache controls, and complete command examples.

trace-session settings session <session-id> reads persisted model fields, profile identity/path/fingerprint, execution context, initial snapshot system messages/output schema, and latest snapshot tool visibility for root and child runs. It never reads current profile files. Reconstruction is partial, not a runnable configuration export: limits, retry policies, and full tool/profile definitions were not archived, and null means unavailable rather than a default. Review system messages and execution context for sensitive data before sharing the report.