Skip to content

Latest commit

 

History

History
260 lines (184 loc) · 14.2 KB

AGENTS.md

File metadata and controls

260 lines (184 loc) · 14.2 KB

Project Overview

opencode-observer is an OpenCode observability plugin written in TypeScript and developed, built, and tested with Bun. It observes OpenCode hooks/events and supported AI SDK lifecycle callbacks, creates OpenTelemetry spans, and exports traces over OTLP HTTP/JSON by default, with configurable HTTP/Protobuf and gRPC support. The current implementation covers run, interaction, LLM, tool, skill.load, compaction, and permission.check spans.

Goals

  • Describe task execution with accurate lifecycles, parent-child relationships, usage, and errors, following the expected Trace Schema and the OpenCode implementation schema. Omit or explicitly degrade unsupported measurements instead of inventing data; use the implementation schema for current export behavior and tests.
  • Keep OpenCode behavior recognition, observation contracts, and telemetry implementation separate, following the Architecture. The adapter and telemetry layers depend on the contract, never on each other; the contract is independent of third-party SDKs.
  • Keep observation from changing OpenCode's behavior: isolate telemetry failures, export asynchronously, and keep telemetry and content capture disabled by default.
  • Use captureContent for message bodies and LLM tool definitions. Model request/response HTTP headers require both captureContent and captureHttpHeaders; the extra header switch defaults to false. SDK output type is metadata and remains observable when content capture is disabled. Record text when an SDK callback confirms no output was configured; omit the type when the SDK snapshot or an explicit format is unavailable. Do not collect request seed.

See README.md for features, local loading, configuration, and usage limits. Use the Architecture for module boundaries, observation contracts, and runtime constraints, the Adapter Design for behavior recognition and collection mechanisms, the expected Trace Schema for target structure and attributes, and the OpenCode implementation schema for current exported data semantics and limitations.

Main Directory Structure

src/
├── index.ts             # Plugin entry point and dependency wiring
├── config.ts            # Plugin options and environment configuration
├── adapter/             # OpenCode hooks/events, behavior tracking, AI SDK integration
├── contract/            # SDK-independent observation interfaces and message types
├── user/                # User identity configuration, resolution, and HTTP lookup
└── telemetry/           # OpenTelemetry setup, contract implementation, export lifecycle
    └── spans/           # Span state and attribute/message encoding
tests/                   # Unit and in-process integration tests, including module boundaries
e2e/                     # Tests running real OpenCode CLI processes
└── support/             # Isolated fixtures, fake model server, OTLP receiver, assertions
docs/
├── architecture.md      # Architecture, responsibilities, and dependency constraints
├── adapter.md           # Behavior recognition, model capture, and coordination mechanisms
└── schemas/
    ├── trace.md          # Expected trace topology and span attribute semantics
    └── trace-opencode.md # Current OpenCode exports, sources, lifecycles, and limitations
dist/                    # Generated JavaScript, source maps, and type declarations

Branch Names

Use a short branch name of at most three words, separated by hyphens. Do not use slashes or type prefixes such as feat/ or fix/.

Examples: trace-export, content-capture, permission-spans.

Commits and PR Titles

Use conventional commit-style messages and PR titles: type(scope): summary.

Valid types are feat, fix, docs, chore, refactor, and test. Scopes are optional; use the affected area when helpful, e.g. adapter, contract, telemetry, config, or e2e.

Examples: fix(adapter): preserve tool ownership, docs: clarify trace lifecycle, test(e2e): cover permission denial.

Setup and Build

Use Bun 1.3.14 or newer and run commands from the repository root. Install dependencies before building or testing:

bun install --frozen-lockfile
bun run build

build runs both build:package and build:standalone. build:package bundles src/index.ts as Bun-targeted ESM with external package dependencies and a linked source map, then generates TypeScript declarations using tsconfig.build.json. Output is written to dist/; both package entry points (opencode-observer and opencode-observer/server) resolve to dist/index.js. build:standalone bundles third-party runtime dependencies into dist/standalone/opencode-observer.js, which users can copy directly into an OpenCode plugins/ directory without installing plugin dependencies.

bun run check runs formatting, lint, and type checks. Use bun run format, bun run format:check, bun run lint, bun run lint:fix, or bun run typecheck for individual development tasks.

bun pm pack runs the prepack checks, unit tests, and build. The package includes dist/ except dist/standalone/, plus package.json, README, and the MIT license. Distribute the standalone JS separately, for example as a Release attachment.

Pushing a v* tag triggers .github/workflows/release.yml, which verifies the package version, runs checks and both test suites against a pinned OpenCode revision, and publishes the tested JS and npm tarball with checksums to GitHub Releases. See Releasing for the release procedure and retry behavior. Keep release details out of README.

Testing and Verification

Install dependencies as described above before running tests from the repository root.

Unit Tests (UT)

tests/ contains unit and in-process integration tests. Run the full suite with:

bun run test

For a focused run during development, use bun test ./tests/adapter.test.ts or bun run test --test-name-pattern 'pattern'.

End-to-End Tests (E2E)

e2e/ launches real OpenCode CLI processes, loads the built plugin, and verifies exported traces using local fake-model and OTLP HTTP servers. No model API key or external collector is required. Tests need permission to listen on loopback ports and launch subprocesses.

Prepare an OpenCode source checkout with its dependencies installed and set OPENCODE_E2E_ENTRY to its packages/opencode/src/index.ts entry before running E2E tests:

bun run test:e2e

test:e2e rebuilds the plugin before running tests, so it always tests the current code. For a focused run, use bun run test:e2e --test-name-pattern 'pattern'. Use the explicit UT and E2E scripts; bare bun test discovers both suites and does not rebuild the plugin.

Each E2E case uses isolated HOME/XDG temporary directories and random loopback ports, then cleans up processes, servers, and files. Set OPENCODE_E2E_TMPDIR to an existing parent directory to control temporary file placement. Each CLI invocation has a 45-second timeout; each test has a 60-second timeout. Missing OpenCode source or build output causes a failure rather than a skipped test. Failure diagnostics include CLI output, model requests, and OTLP payloads. E2E files participate in type checking but are excluded from the published build.

Coverage includes trace structure, content and usage, disabled telemetry/content capture, retries and terminal errors, repeated session runs, real tools and failures, permission denial, foreground subtasks, independent root traces, ignored legacy trace context configuration, collector headers, and compaction success/failure. Assertions must reflect current measurement limits: normal status is UNSET, LLM spans require model-step evidence, and retry counts or first-chunk timing must not be presented as measured without precise attempt boundaries.

Standalone coverage copies only the bundled JS into isolated project and user plugins/ directories, leaves plugin dependencies uninstalled, and verifies automatic discovery, all three OTLP protocols, AI SDK callback capture, and disabled telemetry/content defaults.

Required Checks After Changes

  • After changing source code, tests, build/test configuration, or dependencies, run all of the following before reporting the work complete:

    bun run check
    bun run test
    bun run test:e2e
  • Focused tests are useful while developing, but do not replace the full UT and E2E runs after the final code change. Fix failures and rerun the affected checks; if a fix changes code, run the full verification sequence again.

  • Add or update regression coverage when changing behavior or fixing a bug. Use UT for isolated logic and E2E for behavior that depends on actual OpenCode hooks, events, tool execution, or trace export.

  • For documentation-only changes, run bun run format:check; UT and E2E runs are not required.

  • If a required check cannot run, report the command and the concrete blocker. Do not silently skip tests or describe an unexecuted suite as passing. Include the checks run and their results in the final response.

Style Guide

General Principles

  • Keep things in one function unless composable or reusable
  • Do not extract single-use helpers preemptively. Inline the logic at the call site unless the helper is reused, hides a genuinely complex boundary, or has a clear independent name that improves the caller.
  • Avoid try/catch where possible
  • Avoid using the any type
  • Group closely related statements together and separate distinct semantic phases with exactly one blank line. A declaration, assignment, assertion, or return does not create a separate phase by itself. Follow the Blank Lines rules below.
  • Use Bun APIs when possible, like Bun.file()
  • Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity
  • Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream

Reduce total variable count by inlining when a value is only used once.

// Good
const journal = await Bun.file(path.join(dir, "journal.json")).json();

// Bad
const journalPath = path.join(dir, "journal.json");
const journal = await Bun.file(journalPath).json();

Blank Lines

These rules apply to all source code, unit tests, E2E tests, and their helpers.

  • Keep a short branch's operation and its following return together, without a blank line between them. This includes if blocks, switch cases, and callbacks.
  • Keep a lookup, calculation, or assignment together with the return that immediately uses its result when they form one logical step. Do not insert a blank line merely because the next statement is return.
  • Judge grouping by meaning, not physical line count. A call or expression spanning several lines can still belong to the same group as the following return.
  • Use exactly one blank line between distinct phases, such as validation and the main processing path, separate event cases, or a longer preparation sequence and construction of a factory's returned object. In tests, retain the separation between setup, actions, assertions, and distinct lifecycle phases.
// Good: performing the operation and exiting form one branch.
if (partID !== undefined) {
  calls.get(messageID)?.texts.delete(partID);
  return;
}

// Bad: the blank line unnecessarily splits a short branch.
if (partID !== undefined) {
  calls.get(messageID)?.texts.delete(partID);

  return;
}

// Good: looking up a value and returning the derived result form one step.
function at(time: number) {
  const owner = inputs.findLast((input) => input.created <= time);
  return owner ? resolve(owner.id) : undefined;
}

// Good: validation and processing are separate phases.
if (!session) {
  return;
}

session.interactions.message(info);
session.tools.refresh();

Destructuring

Avoid unnecessary destructuring. Use dot notation to preserve context.

// Good
obj.a;
obj.b;

// Bad
const { a, b } = obj;

Imports

  • Never alias imports. Do not use import { foo as bar } from "..." or renamed imports like resolve as pathResolve.
  • Never use star imports. Do not use import * as Foo from "..." or import type * as Foo from "...".
  • Prefer dynamic imports for heavy modules that are only needed in selected code paths, especially in startup-sensitive entrypoints. Destructure dynamic import bindings near the top of the narrowest scope that needs them so they read like normal imports. Avoid inline chains such as await import("./module").then((mod) => mod.value()) or (await import("./module")).value(). Keep branch-specific imports inside the branch that needs them to preserve lazy loading.

Variables

Prefer const over let. Use ternaries or early returns instead of reassignment.

// Good
const foo = condition ? 1 : 2;

// Bad
let foo;

if (condition) {
  foo = 1;
} else {
  foo = 2;
}

Control Flow

Avoid else statements. Prefer early returns.

Always use braces for if, else, and loop bodies. Write each body on multiple lines, even for a single statement. Oxlint enforces braces with curly: ["error", "all"]; oxfmt expands blocks onto multiple lines.

// Good
function foo() {
  if (condition) {
    return 1;
  }

  return 2;
}

// Bad
function foo() {
  if (condition) {
    return 1;
  } else {
    return 2;
  }
}

Complex Logic

When a function has several validation branches or supporting details, make the main function read as the happy path and move supporting details into small helpers below it.

// Good
export function loadThing(input: unknown) {
  const config = requireConfig(input)
  const metadata = readMetadata(input)

  return createThing({ config, metadata })
}

function requireConfig(input: unknown) {
  ...
}
  • Keep helpers close to the code they support, below the main export when that improves readability.
  • Do not over-abstract simple expressions into many single-use helpers; extract only when it names a real concept like requireConfig or readMetadata.
  • Add comments for non-obvious constraints and surprising behavior, not for obvious assignments or control flow.