@accomplish_ai/agent-core-enterprise

Enterprise extension of @accomplish_ai/agent-core that adds the Agent Flight Recorder -- a trace capture and telemetry system for recording detailed execution traces during agent task runs.

This package re-exports everything from the upstream agent-core so it can be used as a drop-in replacement, while adding telemetry modules and a pnpm patch that hooks trace callbacks into the task lifecycle.

Installation

pnpm add @accomplish_ai/agent-core-enterprise

The postinstall script automatically applies the enterprise patch to @accomplish_ai/agent-core.

What's Included

Everything from @accomplish_ai/agent-core (re-exported), plus:

• TaskRecorderService -- Orchestrates per-task trace recording (reasoning, tool calls, user interactions, step finishes)
• Trace storage -- Per-step local filesystem storage with screenshot, ARIA, AXTree, DOM snapshot, and raw HTML artifacts
• Trace extraction -- Parses tool output to extract embedded trace data via file markers, MCP JSON arrays, or raw base64
• Telemetry uploader -- Background pipeline that zips, encrypts (libsodium sealed-box), and uploads step data to GCS
• MCP browser trace capture -- Pre/post action hooks for browser tools that capture full page state via CDP
• Patch -- Adds onToolUse, onStepFinish, and onReasoning callback hooks to TaskCallbacks

Quick Start

import {
  // All upstream agent-core exports are available
  createTaskManager,
  createStorage,

  // Enterprise telemetry
  TaskRecorderService,
  extractTraceData,
  initTraceStorage,
  initTelemetryUploader,
  setOnStepSavedCallback,
  enqueueStepUpload,
} from '@accomplish_ai/agent-core-enterprise';

// 1. Initialize trace storage
initTraceStorage('/path/to/traces');

// 2. Optionally initialize the upload pipeline
await initTelemetryUploader({
  tracesDir: '/path/to/traces',
  serviceUrl: 'https://telemetry.example.com',
});

// 3. Wire step saves to uploads
setOnStepSavedCallback((taskId, stepIndex, stepDir) => {
  enqueueStepUpload(taskId, stepIndex, stepDir);
});

// 4. Create a recorder for a task
const recorder = new TaskRecorderService('task-123', 'Navigate to example.com', {
  tracesDir: '/path/to/traces',
  contextProvider: () => ({
    user_id: 'user-1',
    platform: process.platform,
    app_version: '1.0.0',
    ga_session_id: 'session-abc',
    environment: 'production',
    arch: process.arch,
    os_version: '14.0',
    plan_type: 'enterprise',
    deployment_type: 'cloud',
    org_id: 'org-1',
    user_role: 'admin',
    electron_user_agent: 'MyApp/1.0',
  }),
});

// 5. Record steps as they happen
recorder.recordUserPrompt('Navigate to example.com');
recorder.recordReasoning('I will use browser_navigate to go to example.com');

const traceData = extractTraceData(toolOutputString, toolInput);
recorder.recordToolCall({
  toolName: 'browser_navigate',
  toolInput: { url: 'https://example.com' },
  toolOutput: toolOutputString,
  ...traceData,
});

recorder.recordStepFinish({
  reason: 'end_turn',
  model: 'claude-sonnet-4-5-20250929',
  tokens: { input: 1000, output: 200, reasoning: 50, cache: { read: 500, write: 100 } },
  cost: 0.003,
});

// 6. Finalize when done
recorder.finalize(true);

Exports

Main entry (@accomplish_ai/agent-core-enterprise)

Re-exports all of @accomplish_ai/agent-core plus all telemetry and MCP trace-capture modules.

Sub-path exports

| Export Path | Description | |-------------|-------------| | @accomplish_ai/agent-core-enterprise | Full package: upstream agent-core + telemetry + MCP trace capture | | @accomplish_ai/agent-core-enterprise/telemetry | Telemetry modules only (recorder, storage, extraction, uploader) | | @accomplish_ai/agent-core-enterprise/mcp/trace-capture | MCP browser trace capture hooks (handlePreAction, handlePostAction) | | @accomplish_ai/agent-core-enterprise/common | Browser-safe types and constants (re-exported from upstream) |

Architecture

See docs/AGENT_FLIGHT_RECORDER.md for the full architecture documentation, including:

• Data flow and capture pipeline
• Storage layout and artifact types
• Step types and their schemas
• Turn signal mechanism (fence-post fix for S₀/S₁ browser state capture)
• Upload pipeline (zip → encrypt → GCS)
• MCP browser trace capture via CDP
• TraceContext fields

Development

Prerequisites

• Node.js >= 20
• pnpm 10+

Build

pnpm install
pnpm build

The build pipeline:

1. esbuild bundles TypeScript source (bundling @accomplish_ai/agent-core in, all other deps external)
2. tsc emits declaration files only
3. post-build.mjs copies the module augmentation and patched MCP tools to dist/

Test

pnpm test          # single run
pnpm test:watch    # watch mode

Type Check

pnpm typecheck

Syncing with Upstream

When a new version of @accomplish_ai/agent-core is released:

./scripts/sync-upstream.sh <new-version>

This updates package.json, renames the patch file, runs pnpm install, and verifies with typecheck + tests. If the patch fails to apply, follow the printed instructions to update it via pnpm patch / pnpm patch-commit.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | RETAIN_TELEMETRY | unset | Set to 1 to keep uploaded step directories (marked with .uploaded) instead of deleting | | ACCOMPLISH_TRACE_MODULE_PATH | unset | Path to compiled trace-capture.js, used by the patched MCP browser server | | ACCOMPLISH_TASK_ID | 'default' | Task ID for turn-signal coordination and artifact file naming |

Project Structure

src/
  index.ts                  # Package entry — re-exports agent-core + enterprise modules
  common.ts                 # Re-exports @accomplish_ai/agent-core/common
  augmentations.d.ts        # Module augmentation (onToolUse, onStepFinish, onReasoning)
  telemetry/
    index.ts                # Re-exports all telemetry modules
    task-recorder.ts        # TaskRecorderService — orchestrates trace capture
    trace-storage.ts        # Local FS storage for steps and artifacts
    trace-extraction.ts     # Parses tool output for embedded trace data
    telemetry-uploader.ts   # Background zip/encrypt/upload pipeline
    types.ts                # TelemetryConfig, TraceContextFields, artifact metadata types
  mcp/
    trace-capture.ts        # Browser trace capture via CDP (pre/post action hooks)
patches/
  @[email protected]
scripts/
  postinstall.sh            # Applies enterprise patch after install
  post-build.mjs            # Copies augmentation types + MCP tools to dist
  sync-upstream.sh          # Helper to sync with new upstream versions
docs/
  AGENT_FLIGHT_RECORDER.md  # Detailed architecture documentation

License

MIT