@archships/dim-plugin-devtools

@archships/dim-plugin-devtools

Official supported devtools inspector plugin for dim-agent-sdk.

What it does

• exposes a session-scoped controller through session.getPlugin('devtools')
• returns a local inspector URL through getInspectorUrl() and opens it in the default browser by default
• serves a tabbed web UI for agent overview, sessions, requests, runtime, context, plugins, and persistence
• journals runtime hook activity under <hostDataDir>/devtools/<instanceId>/events.jsonl
• merges provider-side request logs from <hostDataDir>/provider-http/*.jsonl by requestId
• keeps history across refreshes and process restarts when hostDataDir stays stable

Controller behavior

• getInspectorUrl(): lazily starts the local HTTP server, opens the inspector in the system default browser by default, and returns the inspector URL
• pass createDevtoolsPlugin({ autoOpenBrowser: false }) when the host only wants the URL without opening a browser window
• one agent owns one runtime; the local server is released after the last session controller is disposed

Usage

import { FileStateStore, createAgent, createModel } from '@archships/dim-agent-sdk'
import { createDevtoolsPlugin } from '@archships/dim-plugin-devtools'

const agent = createAgent({
  model: createModel(adapter),
  cwd: process.cwd(),
  hostDataDir: '.dim/host-data',
  stateStore: new FileStateStore({
    directory: '.dim/snapshots',
  }),
  plugins: [createDevtoolsPlugin()],
})

const session = await agent.createSession()
const devtools = session.getPlugin('devtools')
const inspectorUrl = await devtools?.getInspectorUrl()

console.log(inspectorUrl)

Runtime behavior

• hostDataDir is required; the plugin throws during setup if the host does not provide it
• the UI bootstrap uses REST plus live SSE updates from the same local server
• request details combine SDK hook journals with provider HTTP logs when those logs include the same requestId
• provider http_request entries are parsed into a readable request line plus per-field header/body views, so the Requests tab shows exactly what the transport sent
• provider debug logs are still expected to redact secrets, and the devtools merge path redacts sensitive keys again before serving JSON
• plugin config/state in the UI comes from the read-only inspect service and optional plugin inspector exports

Notes

• provider request log discovery defaults to <hostDataDir>/provider-http; override it with createDevtoolsPlugin({ providerHttpDir })
• browser auto-open is enabled by default; disable it with createDevtoolsPlugin({ autoOpenBrowser: false })
• default instanceId is derived from cwd or hostDataDir, so restarting the same host process can replay the same journal directory
• the plugin UI is built with Vite and served as static assets from the published package
• this plugin is opt-in and is not bundled into the SDK by default