@maximtop/opencode-debug-mode 0.1.0

package/dist/session/types.d.ts

@@ -0,0 +1,296 @@
+import { z } from "zod";
+export declare const EvidenceCountersSchema: z.ZodObject<{
+    accepted: z.ZodNumber;
+    rejected: z.ZodNumber;
+    sampled: z.ZodNumber;
+    truncated: z.ZodNumber;
+    dropped: z.ZodNumber;
+    requests: z.ZodNumber;
+}, z.core.$strict>;
+export declare const CollectorManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    host: z.ZodEnum<{
+        "127.0.0.1": "127.0.0.1";
+        "::1": "::1";
+    }>;
+    port: z.ZodNumber;
+    status: z.ZodEnum<{
+        draining: "draining";
+        failed: "failed";
+        ready: "ready";
+        starting: "starting";
+        stopped: "stopped";
+    }>;
+    startedAt: z.ZodString;
+    stoppedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const RunManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodEnum<{
+        "post-fix": "post-fix";
+        "pre-fix": "pre-fix";
+    }>;
+    reproduction: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        planned: "planned";
+        running: "running";
+        timed_out: "timed_out";
+        waiting: "waiting";
+    }>;
+    createdAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ProcessManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    runId: z.ZodString;
+    commandSummary: z.ZodString;
+    supervisorPid: z.ZodOptional<z.ZodNumber>;
+    targetPid: z.ZodOptional<z.ZodNumber>;
+    ownerNonceHash: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        exited: "exited";
+        failed: "failed";
+        running: "running";
+        starting: "starting";
+        terminated: "terminated";
+        timed_out: "timed_out";
+    }>;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const ProbeManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    runId: z.ZodString;
+    hypothesisId: z.ZodString;
+    sourceFile: z.ZodString;
+    sourceLine: z.ZodNumber;
+    sourceColumn: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodString;
+    transport: z.ZodEnum<{
+        "extension-background": "extension-background";
+        "extension-content": "extension-content";
+        "http-web": "http-web";
+        process: "process";
+    }>;
+    captures: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    sampling: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"every">;
+        n: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"aggregate">;
+        windowMs: z.ZodNumber;
+    }, z.core.$strict>], "mode">;
+    status: z.ZodEnum<{
+        active: "active";
+        ambiguous: "ambiguous";
+        planned: "planned";
+        registered: "registered";
+        removed: "removed";
+        validated: "validated";
+    }>;
+    validationStatus: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        validated: "validated";
+    }>;
+    markerStart: z.ZodString;
+    markerEnd: z.ZodString;
+    expectedBlock: z.ZodOptional<z.ZodString>;
+    expectedHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const OwnedFileManifestSchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    bytes: z.ZodNumber;
+    kind: z.ZodEnum<{
+        temporary: "temporary";
+        "transport-helper": "transport-helper";
+    }>;
+}, z.core.$strict>;
+export declare const PermissionChangeSchema: z.ZodObject<{
+    manifestPath: z.ZodString;
+    property: z.ZodEnum<{
+        host_permissions: "host_permissions";
+        permissions: "permissions";
+    }>;
+    matchPattern: z.ZodString;
+    addedBySession: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const CleanupProgressSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        complete: "complete";
+        not_started: "not_started";
+        partial: "partial";
+        running: "running";
+    }>;
+    completedResources: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const ManifestSchema: z.ZodObject<{
+    package: z.ZodLiteral<"opencode-debug-mode">;
+    schemaVersion: z.ZodLiteral<1>;
+    revision: z.ZodNumber;
+    sessionId: z.ZodString;
+    trustedSessionHash: z.ZodString;
+    projectRoot: z.ZodString;
+    sessionDir: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        cleaned: "cleaned";
+        cleaning: "cleaning";
+        partial: "partial";
+    }>;
+    createdAt: z.ZodString;
+    lastActivityAt: z.ZodString;
+    expiresAt: z.ZodString;
+    waitingForReproduction: z.ZodBoolean;
+    keepArtifacts: z.ZodBoolean;
+    retentionDestination: z.ZodOptional<z.ZodString>;
+    collector: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        host: z.ZodEnum<{
+            "127.0.0.1": "127.0.0.1";
+            "::1": "::1";
+        }>;
+        port: z.ZodNumber;
+        status: z.ZodEnum<{
+            draining: "draining";
+            failed: "failed";
+            ready: "ready";
+            starting: "starting";
+            stopped: "stopped";
+        }>;
+        startedAt: z.ZodString;
+        stoppedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodEnum<{
+            "post-fix": "post-fix";
+            "pre-fix": "pre-fix";
+        }>;
+        reproduction: z.ZodString;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            completed: "completed";
+            failed: "failed";
+            planned: "planned";
+            running: "running";
+            timed_out: "timed_out";
+            waiting: "waiting";
+        }>;
+        createdAt: z.ZodString;
+        completedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    processes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        runId: z.ZodString;
+        commandSummary: z.ZodString;
+        supervisorPid: z.ZodOptional<z.ZodNumber>;
+        targetPid: z.ZodOptional<z.ZodNumber>;
+        ownerNonceHash: z.ZodString;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            exited: "exited";
+            failed: "failed";
+            running: "running";
+            starting: "starting";
+            terminated: "terminated";
+            timed_out: "timed_out";
+        }>;
+        startedAt: z.ZodString;
+        completedAt: z.ZodOptional<z.ZodString>;
+        exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    probes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        runId: z.ZodString;
+        hypothesisId: z.ZodString;
+        sourceFile: z.ZodString;
+        sourceLine: z.ZodNumber;
+        sourceColumn: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodString;
+        transport: z.ZodEnum<{
+            "extension-background": "extension-background";
+            "extension-content": "extension-content";
+            "http-web": "http-web";
+            process: "process";
+        }>;
+        captures: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strict>>;
+        sampling: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            mode: z.ZodLiteral<"every">;
+            n: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            mode: z.ZodLiteral<"aggregate">;
+            windowMs: z.ZodNumber;
+        }, z.core.$strict>], "mode">;
+        status: z.ZodEnum<{
+            active: "active";
+            ambiguous: "ambiguous";
+            planned: "planned";
+            registered: "registered";
+            removed: "removed";
+            validated: "validated";
+        }>;
+        validationStatus: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            validated: "validated";
+        }>;
+        markerStart: z.ZodString;
+        markerEnd: z.ZodString;
+        expectedBlock: z.ZodOptional<z.ZodString>;
+        expectedHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    ownedFiles: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+        kind: z.ZodEnum<{
+            temporary: "temporary";
+            "transport-helper": "transport-helper";
+        }>;
+    }, z.core.$strict>>;
+    permissionChanges: z.ZodArray<z.ZodObject<{
+        manifestPath: z.ZodString;
+        property: z.ZodEnum<{
+            host_permissions: "host_permissions";
+            permissions: "permissions";
+        }>;
+        matchPattern: z.ZodString;
+        addedBySession: z.ZodBoolean;
+    }, z.core.$strict>>;
+    counters: z.ZodObject<{
+        accepted: z.ZodNumber;
+        rejected: z.ZodNumber;
+        sampled: z.ZodNumber;
+        truncated: z.ZodNumber;
+        dropped: z.ZodNumber;
+        requests: z.ZodNumber;
+    }, z.core.$strict>;
+    cleanup: z.ZodObject<{
+        status: z.ZodEnum<{
+            complete: "complete";
+            not_started: "not_started";
+            partial: "partial";
+            running: "running";
+        }>;
+        completedResources: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CleanupManifest = z.infer<typeof ManifestSchema>;
+export type ManifestProbe = z.infer<typeof ProbeManifestSchema>;
+export type ManifestRun = z.infer<typeof RunManifestSchema>;
+export type EvidenceCounters = z.infer<typeof EvidenceCountersSchema>;

package/dist/tools/cleanup-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { CleanupService } from "../cleanup/service.js";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+export declare function createCleanupTool(registry: SessionRegistry, cleanupFor: (session: DebugSession) => CleanupService): ToolDefinition;

package/dist/tools/collector-tools.d.ts

@@ -0,0 +1,17 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+export interface PublicCollectorService {
+    start(input: {
+        runtime: "web" | "extension-background";
+        transportTargetPath?: string;
+        extensionManifestPath?: string;
+    }): Promise<{
+        collectorId: string;
+        host: "127.0.0.1" | "::1";
+        port: number;
+        status: string;
+        helperImport?: string;
+        helperPath?: string;
+    }>;
+}
+export declare function createCollectorStartTool(registry: SessionRegistry, collectorFor: (session: DebugSession) => PublicCollectorService): ToolDefinition;

package/dist/tools/common.d.ts

@@ -0,0 +1,4 @@
+import { type ToolResultEnvelope } from "../core/result.js";
+export declare function jsonSuccess<T>(value: T): string;
+export declare function jsonFailure(error: unknown, fallback?: string): string;
+export declare function serializeEnvelope<T>(value: ToolResultEnvelope<T>): string;

package/dist/tools/evidence-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { EvidenceStore } from "../evidence/store.js";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+export declare function createEvidenceReadTool(registry: SessionRegistry, evidenceFor: (session: DebugSession) => EvidenceStore): ToolDefinition;

package/dist/tools/index.d.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+import type { CleanupService } from "../cleanup/service.js";
+import type { EvidenceStore } from "../evidence/store.js";
+import type { ProbeRegistry } from "../probes/registry.js";
+import type { RunService } from "../run/service.js";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+import { type PublicCollectorService } from "./collector-tools.js";
+import { type RunToolDependencies } from "./run-tools.js";
+export interface DebugToolDependencies extends RunToolDependencies {
+    registry: SessionRegistry;
+    runFor(session: DebugSession): RunService;
+    collectorFor(session: DebugSession): PublicCollectorService;
+    probesFor(session: DebugSession): ProbeRegistry;
+    evidenceFor(session: DebugSession): EvidenceStore;
+    cleanupFor(session: DebugSession): CleanupService;
+}
+export type DebugTools = {
+    debug_session_start: ToolDefinition;
+    debug_session_status: ToolDefinition;
+    debug_state_read: ToolDefinition;
+    debug_state_checkpoint: ToolDefinition;
+    debug_run_start: ToolDefinition;
+    debug_process_capture: ToolDefinition;
+    debug_collector_start: ToolDefinition;
+    debug_probe_prepare: ToolDefinition;
+    debug_probe_register: ToolDefinition;
+    debug_evidence_read: ToolDefinition;
+    debug_cleanup: ToolDefinition;
+};
+export declare function createDebugTools(dependencies: DebugToolDependencies): DebugTools;

package/dist/tools/probe-tools.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { ProbeRegistry } from "../probes/registry.js";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+export declare function createProbePrepareTool(registry: SessionRegistry, probesFor: (session: DebugSession) => ProbeRegistry): ToolDefinition;
+export declare function createProbeRegisterTool(registry: SessionRegistry, probesFor: (session: DebugSession) => ProbeRegistry): ToolDefinition;

package/dist/tools/run-tools.d.ts

@@ -0,0 +1,12 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { ProbeRegistry } from "../probes/registry.js";
+import type { ProcessService } from "../process/service.js";
+import type { RunService } from "../run/service.js";
+import type { DebugSession, SessionRegistry } from "../session/registry.js";
+export interface RunToolDependencies {
+    registry: Pick<SessionRegistry, "requireOwned">;
+    processFor(session: DebugSession): Pick<ProcessService, "capture">;
+    probesFor(session: DebugSession): Pick<ProbeRegistry, "validate" | "requireValidatedForRun">;
+}
+export declare function createProcessCaptureTool(dependencies: RunToolDependencies): ToolDefinition;
+export declare function createRunStartTool(registry: SessionRegistry, runFor: (session: DebugSession) => RunService): ToolDefinition;

package/dist/tools/session-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { SessionRegistry } from "../session/registry.js";
+export declare function createSessionStartTool(registry: SessionRegistry): ToolDefinition;
+export declare function createSessionStatusTool(registry: SessionRegistry): ToolDefinition;

package/dist/tools/state-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { SessionRegistry } from "../session/registry.js";
+export declare function createStateReadTool(registry: SessionRegistry): ToolDefinition;
+export declare function createStateCheckpointTool(registry: SessionRegistry): ToolDefinition;

package/docs/architecture.md

@@ -0,0 +1,15 @@
+# Architecture
+
+The package exports one OpenCode plugin. Its config hook installs the `debug` primary agent and routing-only command. Every public tool derives ownership from `ToolContext.sessionID`; public arguments cannot select a different session.
+
+Each session receives a random directory under the package OS-temporary base. The strict revisioned manifest inventories runs, processes, collectors, markers, helper hashes, permission entries, counters, and cleanup progress. The separate strict checkpoint stores conclusions and stable evidence references. A serialized NDJSON writer stores sanitized evidence within event and byte limits.
+
+CLI capture forks a package-owned Node supervisor over IPC. The supervisor starts the target detached without a shell, forwards bounded streams, and kills the descendant tree on timeout, explicit termination, or parent disconnect.
+
+Web and extension-background capture uses a Node HTTP server bound explicitly to `127.0.0.1`, with `::1` as the only availability fallback. Exact routes provide authenticated ingestion and minimal health. The per-session credential never appears in tool output.
+
+Probe preparation produces deterministic JS/TS marker blocks. Web/background credentials exist only in a newly created exact-hash helper. Extension content probes use messaging and never fetch loopback directly.
+
+Cleanup drains the collector, terminates processes, removes exact markers, removes session-added permissions and exact-hash helpers, runs an optional clean check, optionally stages a sanitized bundle, removes the secret, and deletes the ephemeral directory. Each resource reports success, already-clean, skipped, or failed.
+
+Future transports should implement the conceptual `EvidenceBackend` boundary—start, ingest/capture, status, and cleanup—without changing the canonical event, ownership, state, or tool contracts. v1 intentionally has no backend registry.

package/docs/lifecycle.md

@@ -0,0 +1,11 @@
+# Investigation lifecycle
+
+The durable phases are intake, hypotheses, baseline, instrumenting, waiting for reproduction, analyzing, fixing, verifying, cleaning, and a terminal completed/abandoned/escalated outcome.
+
+Every meaningful transition uses revision compare-and-swap. A resumed turn and compaction hook require state reading before another action. Missing, malformed, oversized, stale, or unsupported state returns an explicit recovery result; the package never invents lost conclusions.
+
+A process lease and an explicit waiting-for-reproduction lease suppress idle expiry. Unauthenticated collector traffic does not update activity. The next active tool action ends an obsolete wait. Idle unleased sessions are cleaned after 30 minutes.
+
+Normal completion and all terminal paths use the same idempotent cleanup. Session deletion, plugin disposal, collector failure, timeout, cancellation, and verified expired startup recovery also converge on teardown. Recovery scans only direct package-owned `session-*` children and ignores active, unrelated, invalid, or symlinked entries.
+
+With default deletion, the lifecycle ends with no session directory. With explicit retention, sanitized public files are staged before ephemeral deletion and finalized only after a secret scan.

package/examples/chrome-extension/background.js

@@ -0,0 +1,5 @@
+chrome.runtime.onMessage.addListener((message) => {
+  if (message.type !== "opencode-debug-event") return undefined
+  // The temporary package-owned background helper accepts the bounded event.
+  return globalThis.__opencodeDebugEmit?.(message.event)
+})

package/examples/chrome-extension/content.js

@@ -0,0 +1,3 @@
+export function relayDebugEvent(event) {
+  return chrome.runtime.sendMessage({ type: "opencode-debug-event", event })
+}

package/examples/cli/run.mjs

@@ -0,0 +1,3 @@
+// Start a debug session, create a pre-fix run, then let debug_process_capture
+// execute the target with an executable plus argument array.
+console.log("Run the target application's normal deterministic reproduction here")

package/examples/firefox-extension/background.js

@@ -0,0 +1,4 @@
+browser.runtime.onMessage.addListener((message) => {
+  if (message.type !== "opencode-debug-event") return undefined
+  return globalThis.__opencodeDebugEmit?.(message.event)
+})

package/examples/firefox-extension/content.js

@@ -0,0 +1,3 @@
+export function relayDebugEvent(event) {
+  return browser.runtime.sendMessage({ type: "opencode-debug-event", event })
+}

package/examples/web/app.js

@@ -0,0 +1,5 @@
+// The debug agent supplies this import only while the owned helper exists.
+// import { __opencodeDebugEmit } from "./debug-transport.mjs"
+export function reproduce(value) {
+  return value
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@maximtop/opencode-debug-mode",
+  "version": "0.1.0",
+  "description": "Hypothesis-driven runtime debugging agent for OpenCode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maximtop/opencode-debug-mode.git"
+  },
+  "homepage": "https://github.com/maximtop/opencode-debug-mode#readme",
+  "bugs": {
+    "url": "https://github.com/maximtop/opencode-debug-mode/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "examples",
+    "README.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "ATTRIBUTION.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.17.0 <2"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "zod": "^4.4.3"
+  },
+  "overrides": {
+    "esbuild": "0.28.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@opencode-ai/plugin": "^1.17.19",
+    "@types/node": "^20.19.25",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "coverage": "npm run build && vitest run --coverage",
+    "check": "npm run lint && npm run typecheck && npm run test && npm run build && npm run test:integration"
+  },
+  "keywords": [
+    "opencode",
+    "debugging",
+    "agent",
+    "runtime",
+    "observability"
+  ]
+}