feat: add bounded diagnostics and improve UX feedback
Ask and Execute guidance, Runtime state, live announcements, loading states, retry paths, settings focus, and update failures now provide consistent and accessible feedback across the desktop experience. Add bounded redacted Desktop and Agent diagnostic logs, a read-only Agent diagnostics command, and an explicit opt-in for attaching a small Desktop diagnostic summary to in-app feedback. Diagnostics stay local by default and the existing feedback v1 service contract remains compatible. Release note: 新增可选桌面诊断反馈与 Agent 诊断导出，并统一 Ask/Execute 状态、错误恢复和无障碍反馈；诊断默认保留在本地，仅在用户明确勾选时附加桌面摘要。
This commit is contained in:
mesalogo
@@ -33,6 +33,7 @@ import {
|
||||
import { RuntimeBundleRegistry } from './runtime-bundle-registry'
|
||||
import type { VerifiedRuntimeBundle } from './runtime-bundle-verifier'
|
||||
import type { RemoteRuntimeLock } from '../shared/remote-runtime-launch-contracts'
|
||||
import { AgentDiagnosticLog } from './diagnostic-log'
|
||||
|
||||
const temporaryPaths: string[] = []
|
||||
|
||||
@@ -246,6 +247,58 @@ describe('Agent CLI fixed command contract', () => {
|
||||
expect(bootstrap).toHaveBeenCalledTimes(2)
|
||||
})
|
||||
|
||||
it('exports only bounded diagnostics for a fixed installation ID as JSONL', async () => {
|
||||
const root = privateTemporaryDirectory()
|
||||
const stateDirectory = resolve(root, 'state', 'install-1')
|
||||
mkdirSync(stateDirectory, { recursive: true, mode: 0o700 })
|
||||
if (process.platform !== 'win32') {
|
||||
chmodSync(resolve(root, 'state'), 0o700)
|
||||
chmodSync(stateDirectory, 0o700)
|
||||
}
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
log.record('daemon.ready', {
|
||||
daemonBootId: 'boot-1'
|
||||
})
|
||||
log.record('runtime.start.failed', {
|
||||
runtimeId: 'opencode',
|
||||
error: new Error('private Prompt and /private/path')
|
||||
})
|
||||
await log.flush()
|
||||
const io = cliIo()
|
||||
|
||||
const result = await runAgentCli(
|
||||
['diagnostics', '--installation-id', 'install-1'],
|
||||
{
|
||||
installationPaths: () => ({
|
||||
executablePath: resolve(root, 'agent', 'goodbuddy-agent'),
|
||||
stateDirectory,
|
||||
socketPath: resolve(root, 'run', 'agent.sock')
|
||||
}),
|
||||
io
|
||||
}
|
||||
)
|
||||
|
||||
expect(result, io.error.read()?.toString()).toBe(0)
|
||||
const output = io.output.read()!.toString()
|
||||
expect(output).not.toContain('private Prompt')
|
||||
expect(output).not.toContain('/private/path')
|
||||
expect(
|
||||
output.trimEnd().split('\n').map((line) => JSON.parse(line))
|
||||
).toEqual([
|
||||
expect.objectContaining({
|
||||
event: 'daemon.ready',
|
||||
daemonBootId: 'boot-1'
|
||||
}),
|
||||
expect.objectContaining({
|
||||
event: 'runtime.start.failed',
|
||||
runtimeId: 'opencode',
|
||||
error: { name: 'Error' }
|
||||
})
|
||||
])
|
||||
})
|
||||
|
||||
it('dispatches generated attach argv using only derived managed paths', async () => {
|
||||
const root = privateTemporaryDirectory()
|
||||
const paths: ManagedInstallationPaths = {
|
||||
|
||||
+23
-1
@@ -53,6 +53,7 @@ import {
|
||||
DetachedAgentLifecycle,
|
||||
type DetachedAgentLifecycleOptions
|
||||
} from './detached-agent-lifecycle'
|
||||
import { readAgentDiagnostics } from './diagnostic-log'
|
||||
|
||||
type CliIo = {
|
||||
input: Readable
|
||||
@@ -141,6 +142,9 @@ export async function runAgentCli(
|
||||
case 'doctor':
|
||||
await runDoctor(rest, dependencies, io)
|
||||
return 0
|
||||
case 'diagnostics':
|
||||
runDiagnostics(rest, dependencies, io)
|
||||
return 0
|
||||
case 'runtime':
|
||||
await runRuntime(rest, dependencies, io)
|
||||
return 0
|
||||
@@ -152,7 +156,7 @@ export async function runAgentCli(
|
||||
return 0
|
||||
}
|
||||
throw new Error(
|
||||
'Expected daemon, attach-or-bootstrap, doctor, a lifecycle action, runtime, or model-bridge-helper'
|
||||
'Expected daemon, attach-or-bootstrap, doctor, diagnostics, a lifecycle action, runtime, or model-bridge-helper'
|
||||
)
|
||||
}
|
||||
} catch (error) {
|
||||
@@ -353,6 +357,7 @@ async function runDaemon(
|
||||
runtimeFactory: async ({
|
||||
events,
|
||||
workspaces,
|
||||
diagnostics,
|
||||
outputSink,
|
||||
blobSink
|
||||
}) =>
|
||||
@@ -367,6 +372,7 @@ async function runDaemon(
|
||||
workspaces,
|
||||
outputSink,
|
||||
blobSink,
|
||||
diagnostics,
|
||||
agentExecutablePath: paths.executablePath,
|
||||
installationId
|
||||
})
|
||||
@@ -501,6 +507,22 @@ async function runDoctor(
|
||||
})}\n`)
|
||||
}
|
||||
|
||||
function runDiagnostics(
|
||||
argv: readonly string[],
|
||||
dependencies: AgentCliDependencies,
|
||||
io: CliIo
|
||||
): void {
|
||||
const options = parseOptions(argv, ['installation-id'])
|
||||
requireOptions(options, ['installation-id'])
|
||||
const installationId = validateInstallationId(
|
||||
options['installation-id']!
|
||||
)
|
||||
const paths = resolveInstallationPaths(installationId, dependencies)
|
||||
for (const record of readAgentDiagnostics(paths.stateDirectory)) {
|
||||
io.output.write(`${JSON.stringify(record)}\n`)
|
||||
}
|
||||
}
|
||||
|
||||
async function runLifecycle(
|
||||
argv: readonly string[],
|
||||
dependencies: AgentCliDependencies,
|
||||
|
||||
@@ -36,6 +36,7 @@ import { AgentUnsupportedError } from './errors'
|
||||
import { WorkspaceGitService } from './workspace-git-service'
|
||||
import { createWorkspaceProtocolMethods } from './workspace-protocol-methods'
|
||||
import { WorkspaceRegistry } from './workspace-registry'
|
||||
import { AgentDiagnosticLog } from './diagnostic-log'
|
||||
|
||||
export type AgentDaemonOptions = {
|
||||
installationId: string
|
||||
@@ -67,6 +68,7 @@ export type AgentDaemonOptions = {
|
||||
runtimeFactory?: (context: {
|
||||
events: EventJournal
|
||||
workspaces: WorkspaceRegistry
|
||||
diagnostics: AgentDiagnosticLog
|
||||
outputSink: (
|
||||
frame: AgentFrame,
|
||||
context: {
|
||||
@@ -109,6 +111,7 @@ export class AgentDaemon {
|
||||
readonly #runtimeProtocol?: AgentDaemonOptions['runtimeProtocol']
|
||||
readonly #runtimeFactory?: AgentDaemonOptions['runtimeFactory']
|
||||
readonly #reportError: (message: string, error: unknown) => void
|
||||
readonly #diagnostics: AgentDiagnosticLog
|
||||
#state: 'starting' | 'ready' | 'stopped' = 'stopped'
|
||||
#endpoint?: PrivateEndpoint
|
||||
#events?: EventJournal
|
||||
@@ -136,8 +139,11 @@ export class AgentDaemon {
|
||||
)
|
||||
this.#stateDirectory = resolve(options.stateDirectory)
|
||||
this.#socketPath = resolve(options.socketPath)
|
||||
this.#peerIdentityProvider = options.peerIdentityProvider
|
||||
this.#now = options.now ?? Date.now
|
||||
this.#diagnostics = new AgentDiagnosticLog(this.#stateDirectory, {
|
||||
now: this.#now
|
||||
})
|
||||
this.#peerIdentityProvider = options.peerIdentityProvider
|
||||
this.#gitExecutable = options.gitExecutable
|
||||
this.#workspaceRequestTimeoutMs = options.workspaceRequestTimeoutMs
|
||||
this.#runtimeProtocol = options.runtimeProtocol
|
||||
@@ -186,6 +192,9 @@ export class AgentDaemon {
|
||||
this.#state = 'starting'
|
||||
try {
|
||||
ensurePrivateDirectory(this.#stateDirectory)
|
||||
this.#diagnostics.tryRecord('daemon.starting', {
|
||||
daemonBootId: this.#bootId
|
||||
})
|
||||
ensurePrivateDirectoryTree(
|
||||
resolve(this.#stateDirectory, 'journal'),
|
||||
this.#stateDirectory
|
||||
@@ -234,6 +243,7 @@ export class AgentDaemon {
|
||||
await this.#runtimeFactory?.({
|
||||
events: this.#events,
|
||||
workspaces: this.#workspaces,
|
||||
diagnostics: this.#diagnostics,
|
||||
outputSink: async (frame) => {
|
||||
if (protocolBox.current === undefined) {
|
||||
throw new Error(
|
||||
@@ -277,6 +287,10 @@ export class AgentDaemon {
|
||||
connectionId,
|
||||
category
|
||||
}) => {
|
||||
this.#diagnostics.tryRecord('connection.failed', {
|
||||
daemonBootId: this.#bootId,
|
||||
reason: category
|
||||
})
|
||||
try {
|
||||
writePrivateFileAtomic(
|
||||
resolve(
|
||||
@@ -299,6 +313,20 @@ export class AgentDaemon {
|
||||
)
|
||||
}
|
||||
},
|
||||
onConnectionClose: ({ category }) => {
|
||||
if (category === undefined) {
|
||||
this.#diagnostics.tryRecord('connection.closed', {
|
||||
daemonBootId: this.#bootId,
|
||||
reason: 'peer-closed'
|
||||
})
|
||||
}
|
||||
},
|
||||
onRecovery: ({ outcome, reason }) => {
|
||||
this.#diagnostics.tryRecord(`recovery.${outcome}`, {
|
||||
daemonBootId: this.#bootId,
|
||||
...(reason === undefined ? {} : { reason })
|
||||
})
|
||||
},
|
||||
methods: mergeProtocolMethods(
|
||||
workspaceMethods,
|
||||
this.#activeRuntimeProtocol?.methods
|
||||
@@ -317,18 +345,40 @@ export class AgentDaemon {
|
||||
daemonBootId: this.#bootId,
|
||||
protocol: this.#protocol,
|
||||
onAttach: ({ socket, controller }) => {
|
||||
this.#diagnostics.tryRecord('connection.attached', {
|
||||
daemonBootId: this.#bootId
|
||||
})
|
||||
protocol.accept(socket, controller)
|
||||
},
|
||||
onConnectionFailure: (error) => {
|
||||
this.#diagnostics.tryRecord('connection.failed', {
|
||||
daemonBootId: this.#bootId,
|
||||
reason: 'authentication',
|
||||
error
|
||||
})
|
||||
}
|
||||
})
|
||||
await this.#endpoint.listen()
|
||||
this.#state = 'ready'
|
||||
this.#diagnostics.tryRecord('daemon.ready', {
|
||||
daemonBootId: this.#bootId
|
||||
})
|
||||
} catch (error) {
|
||||
this.#diagnostics.tryRecord('daemon.start.failed', {
|
||||
daemonBootId: this.#bootId,
|
||||
error
|
||||
})
|
||||
await this.stop()
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
async stop(): Promise<void> {
|
||||
if (this.#state !== 'stopped') {
|
||||
this.#diagnostics.tryRecord('daemon.stopping', {
|
||||
daemonBootId: this.#bootId
|
||||
})
|
||||
}
|
||||
const endpoint = this.#endpoint
|
||||
const events = this.#events
|
||||
const workspaces = this.#workspaces
|
||||
@@ -337,10 +387,14 @@ export class AgentDaemon {
|
||||
this.#events = undefined
|
||||
this.#workspaces = undefined
|
||||
this.#activeRuntimeProtocol = undefined
|
||||
let stopError: unknown
|
||||
try {
|
||||
if (endpoint !== undefined) {
|
||||
await endpoint.close()
|
||||
}
|
||||
} catch (error) {
|
||||
stopError = error
|
||||
throw error
|
||||
} finally {
|
||||
if (runtimeProtocol?.dispose !== undefined) {
|
||||
await Promise.resolve(runtimeProtocol.dispose()).catch(
|
||||
@@ -352,10 +406,25 @@ export class AgentDaemon {
|
||||
workspaces?.closeAll()
|
||||
events?.close()
|
||||
this.#state = 'stopped'
|
||||
this.#diagnostics.tryRecord(
|
||||
stopError === undefined
|
||||
? 'daemon.stopped'
|
||||
: 'daemon.stop.failed',
|
||||
{
|
||||
daemonBootId: this.#bootId,
|
||||
...(stopError === undefined ? {} : { error: stopError })
|
||||
}
|
||||
)
|
||||
await this.#diagnostics.dispose()
|
||||
}
|
||||
}
|
||||
|
||||
#reportRuntimeShutdownError(error: unknown): void {
|
||||
this.#diagnostics.tryRecord('daemon.stop.failed', {
|
||||
daemonBootId: this.#bootId,
|
||||
reason: 'runtime-dispose',
|
||||
error
|
||||
})
|
||||
try {
|
||||
this.#reportError('Agent Runtime shutdown failed', error)
|
||||
} catch (reportError) {
|
||||
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
} from './linux-process-identity'
|
||||
import { writePrivateFileAtomic } from './managed-paths'
|
||||
import type { VerifiedInstalledAgentBundle } from './installed-bundle-verifier'
|
||||
import { readAgentDiagnostics } from './diagnostic-log'
|
||||
|
||||
const parentPid = 1101
|
||||
const childPid = 2202
|
||||
@@ -73,6 +74,16 @@ describe('detached Agent lifecycle', () => {
|
||||
)
|
||||
expect(harness.unref).toHaveBeenCalledOnce()
|
||||
expect(harness.probe).toHaveBeenCalled()
|
||||
expect(
|
||||
readAgentDiagnostics(harness.stateDirectory).map(
|
||||
(record) => record.event
|
||||
)
|
||||
).toEqual(
|
||||
expect.arrayContaining([
|
||||
'detached.launching',
|
||||
'detached.spawned'
|
||||
])
|
||||
)
|
||||
})
|
||||
|
||||
it('creates the managed state parent before bootstrapping', async () => {
|
||||
|
||||
@@ -23,6 +23,7 @@ import {
|
||||
writePrivateFileAtomic
|
||||
} from './managed-paths'
|
||||
import type { AttachWelcome } from '../shared/agent-protocol'
|
||||
import { AgentDiagnosticLog } from './diagnostic-log'
|
||||
|
||||
const DEFAULT_READINESS_TIMEOUT_MS = 15_000
|
||||
const DEFAULT_STOP_TIMEOUT_MS = 5_000
|
||||
@@ -140,6 +141,7 @@ export class DetachedAgentLifecycle {
|
||||
readonly #retireLegacyInstallation?: (
|
||||
verified: VerifiedInstalledAgentBundle
|
||||
) => void | Promise<void>
|
||||
readonly #diagnostics: AgentDiagnosticLog
|
||||
|
||||
constructor(options: DetachedAgentLifecycleOptions) {
|
||||
this.#installationId = validateInstallationId(options.installationId)
|
||||
@@ -156,6 +158,10 @@ export class DetachedAgentLifecycle {
|
||||
this.#spawnDetached = options.spawnDetached ?? spawnDetachedProcess
|
||||
this.#currentPid = positivePid(options.currentPid ?? process.pid)
|
||||
this.#now = options.now ?? Date.now
|
||||
this.#diagnostics = new AgentDiagnosticLog(this.#stateDirectory, {
|
||||
now: this.#now,
|
||||
pid: this.#currentPid
|
||||
})
|
||||
this.#sleep =
|
||||
options.sleep ??
|
||||
(async (milliseconds) =>
|
||||
@@ -215,6 +221,7 @@ export class DetachedAgentLifecycle {
|
||||
|
||||
const launchArgv = ['daemon', '--installation-id', this.#installationId]
|
||||
const runtimePath = expectedRuntimePath(verified)
|
||||
this.#diagnostics.tryRecord('detached.launching')
|
||||
const child = this.#spawnDetached(this.#executablePath, launchArgv, {
|
||||
env: detachedEnvironment(this.#environment),
|
||||
detached: true,
|
||||
@@ -226,6 +233,7 @@ export class DetachedAgentLifecycle {
|
||||
throw new Error('Detached Agent spawn did not return a process ID')
|
||||
}
|
||||
child.unref()
|
||||
this.#diagnostics.tryRecord('detached.spawned')
|
||||
const processIdentity = await this.#waitForProcessIdentity(
|
||||
child.pid,
|
||||
runtimePath
|
||||
@@ -246,8 +254,18 @@ export class DetachedAgentLifecycle {
|
||||
throw new Error('Detached Agent readiness timed out')
|
||||
}
|
||||
return ready
|
||||
} catch (error) {
|
||||
this.#diagnostics.tryRecord('recovery.failed', {
|
||||
reason: 'bootstrap',
|
||||
error
|
||||
})
|
||||
throw error
|
||||
} finally {
|
||||
releaseLock()
|
||||
try {
|
||||
releaseLock()
|
||||
} finally {
|
||||
await this.#diagnostics.flush()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,314 @@
|
||||
import {
|
||||
chmodSync,
|
||||
existsSync,
|
||||
mkdtempSync,
|
||||
readdirSync,
|
||||
readFileSync,
|
||||
rmSync,
|
||||
statSync
|
||||
} from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import {
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME,
|
||||
AgentDiagnosticLog,
|
||||
readAgentDiagnostics
|
||||
} from './diagnostic-log'
|
||||
|
||||
const temporaryPaths: string[] = []
|
||||
|
||||
afterEach(() => {
|
||||
for (const path of temporaryPaths.splice(0)) {
|
||||
rmSync(path, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
|
||||
describe('Agent diagnostic log', () => {
|
||||
it('rotates within fixed file and byte bounds and remains readable after restart', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
let now = Date.UTC(2026, 7, 31)
|
||||
const first = new AgentDiagnosticLog(stateDirectory, {
|
||||
maximumFileBytes: 512,
|
||||
fileCount: 2,
|
||||
now: () => now,
|
||||
pid: 42
|
||||
})
|
||||
|
||||
for (let index = 0; index < 20; index += 1) {
|
||||
first.record('connection.failed', {
|
||||
daemonBootId: `boot-${index}`,
|
||||
reason: 'socket-error',
|
||||
error: Object.assign(new Error(`failure-${index}`), {
|
||||
code: 'ECONNRESET'
|
||||
})
|
||||
})
|
||||
now += 1_000
|
||||
}
|
||||
await first.flush()
|
||||
|
||||
const directory = resolve(
|
||||
stateDirectory,
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME
|
||||
)
|
||||
const files = readdirSync(directory)
|
||||
expect(files).toHaveLength(2)
|
||||
for (const file of files) {
|
||||
expect(statSync(resolve(directory, file)).size).toBeLessThanOrEqual(512)
|
||||
}
|
||||
|
||||
const restarted = new AgentDiagnosticLog(stateDirectory, {
|
||||
maximumFileBytes: 512,
|
||||
fileCount: 2,
|
||||
pid: 43
|
||||
})
|
||||
const records = restarted.read()
|
||||
expect(records.length).toBeGreaterThan(0)
|
||||
expect(records.at(-1)).toMatchObject({
|
||||
event: 'connection.failed',
|
||||
daemonBootId: 'boot-19',
|
||||
error: {
|
||||
name: 'Error',
|
||||
code: 'ECONNRESET'
|
||||
}
|
||||
})
|
||||
expect(records.some((record) => record.daemonBootId === 'boot-0')).toBe(
|
||||
false
|
||||
)
|
||||
})
|
||||
|
||||
it('persists only allowlisted metadata and never error messages or sensitive payloads', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const secretPrompt = 'accepted Prompt: summarize private-file.txt'
|
||||
const secretKey = 'sk-private-model-key'
|
||||
const secretConfig = '{"providerUrl":"https://private.invalid"}'
|
||||
const secretEnvironment = 'GOODBUDDY_SECRET=hidden'
|
||||
const secretSsh = 'ssh -i /home/user/private-key user@host'
|
||||
const secretOutput = 'MODEL_OUTPUT_PRIVATE'
|
||||
const error = Object.assign(
|
||||
new Error(
|
||||
[
|
||||
secretPrompt,
|
||||
secretKey,
|
||||
secretConfig,
|
||||
secretEnvironment,
|
||||
secretSsh,
|
||||
secretOutput
|
||||
].join(' ')
|
||||
),
|
||||
{
|
||||
code: secretKey,
|
||||
name: secretConfig
|
||||
}
|
||||
)
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
|
||||
log.record('runtime.start.failed', {
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'execute',
|
||||
error
|
||||
})
|
||||
await log.flush()
|
||||
|
||||
const raw = readdirSync(
|
||||
resolve(stateDirectory, AGENT_DIAGNOSTIC_DIRECTORY_NAME)
|
||||
)
|
||||
.map((name) =>
|
||||
readFileSync(
|
||||
resolve(
|
||||
stateDirectory,
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME,
|
||||
name
|
||||
),
|
||||
'utf8'
|
||||
)
|
||||
)
|
||||
.join('')
|
||||
for (const sensitive of [
|
||||
secretPrompt,
|
||||
secretKey,
|
||||
secretConfig,
|
||||
secretEnvironment,
|
||||
secretSsh,
|
||||
secretOutput
|
||||
]) {
|
||||
expect(raw).not.toContain(sensitive)
|
||||
}
|
||||
expect(JSON.parse(raw)).toEqual({
|
||||
formatVersion: 1,
|
||||
timestamp: expect.any(String),
|
||||
level: 'error',
|
||||
event: 'runtime.start.failed',
|
||||
pid: 42,
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'execute',
|
||||
error: {
|
||||
name: 'Error'
|
||||
}
|
||||
})
|
||||
expect(readAgentDiagnostics(stateDirectory)).toHaveLength(1)
|
||||
})
|
||||
|
||||
it('keeps a single-file configuration bounded', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
maximumFileBytes: 512,
|
||||
fileCount: 1,
|
||||
pid: 42
|
||||
})
|
||||
|
||||
for (let index = 0; index < 20; index += 1) {
|
||||
log.record('daemon.ready', {
|
||||
daemonBootId: `boot-${index}`
|
||||
})
|
||||
}
|
||||
await log.flush()
|
||||
|
||||
const files = readdirSync(
|
||||
resolve(stateDirectory, AGENT_DIAGNOSTIC_DIRECTORY_NAME)
|
||||
)
|
||||
expect(files).toHaveLength(1)
|
||||
expect(
|
||||
statSync(
|
||||
resolve(
|
||||
stateDirectory,
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME,
|
||||
files[0]!
|
||||
)
|
||||
).size
|
||||
).toBeLessThanOrEqual(512)
|
||||
})
|
||||
|
||||
it('keeps the default three 64 KiB private JSONL files bounded', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
|
||||
for (let batch = 0; batch < 50; batch += 1) {
|
||||
for (let index = 0; index < 60; index += 1) {
|
||||
log.record('connection.failed', {
|
||||
daemonBootId: `boot-${batch}-${index}`,
|
||||
reason: 'socket-error',
|
||||
error: Object.assign(new Error('private failure'), {
|
||||
code: 'ECONNRESET'
|
||||
})
|
||||
})
|
||||
}
|
||||
await log.flush()
|
||||
}
|
||||
|
||||
const directory = resolve(
|
||||
stateDirectory,
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME
|
||||
)
|
||||
const files = readdirSync(directory).sort()
|
||||
expect(files).toEqual([
|
||||
'agent-diagnostics.jsonl',
|
||||
'agent-diagnostics.jsonl.1',
|
||||
'agent-diagnostics.jsonl.2'
|
||||
])
|
||||
for (const file of files) {
|
||||
const path = resolve(directory, file)
|
||||
expect(statSync(path).size).toBeLessThanOrEqual(64 * 1024)
|
||||
for (const line of readFileSync(path, 'utf8').trimEnd().split('\n')) {
|
||||
expect(() => JSON.parse(line)).not.toThrow()
|
||||
}
|
||||
if (process.platform !== 'win32') {
|
||||
expect(statSync(path).mode & 0o777).toBe(0o600)
|
||||
}
|
||||
}
|
||||
if (process.platform !== 'win32') {
|
||||
expect(statSync(directory).mode & 0o777).toBe(0o700)
|
||||
}
|
||||
})
|
||||
|
||||
it('drops records beyond the fixed queue bound', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
maximumQueuedRecords: 4,
|
||||
pid: 42
|
||||
})
|
||||
|
||||
for (let index = 0; index < 20; index += 1) {
|
||||
log.tryRecord('daemon.ready', {
|
||||
daemonBootId: `boot-${index}`
|
||||
})
|
||||
}
|
||||
await log.flush()
|
||||
|
||||
expect(log.read().map((record) => record.daemonBootId)).toEqual([
|
||||
'boot-0',
|
||||
'boot-1',
|
||||
'boot-2',
|
||||
'boot-3'
|
||||
])
|
||||
})
|
||||
|
||||
it('serializes independent process writers without a size cache', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const daemonLog = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
const attachLog = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 43
|
||||
})
|
||||
|
||||
daemonLog.tryRecord('daemon.ready', {
|
||||
daemonBootId: 'daemon-boot'
|
||||
})
|
||||
attachLog.tryRecord('detached.spawned')
|
||||
await Promise.all([daemonLog.flush(), attachLog.flush()])
|
||||
|
||||
expect(
|
||||
readAgentDiagnostics(stateDirectory).map((record) => record.pid).sort()
|
||||
).toEqual([42, 43])
|
||||
})
|
||||
|
||||
it('does not touch the disk synchronously from tryRecord', async () => {
|
||||
const stateDirectory = temporaryStateDirectory()
|
||||
const log = new AgentDiagnosticLog(stateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
const directory = resolve(
|
||||
stateDirectory,
|
||||
AGENT_DIAGNOSTIC_DIRECTORY_NAME
|
||||
)
|
||||
|
||||
log.tryRecord('connection.attached')
|
||||
|
||||
expect(existsSync(directory)).toBe(false)
|
||||
await log.flush()
|
||||
expect(existsSync(directory)).toBe(true)
|
||||
})
|
||||
|
||||
it('isolates asynchronous write failures from runtime callers', async () => {
|
||||
const root = temporaryStateDirectory()
|
||||
const unavailableStateDirectory = resolve(root, 'missing-state')
|
||||
const log = new AgentDiagnosticLog(unavailableStateDirectory, {
|
||||
pid: 42
|
||||
})
|
||||
let runtimeContinued = false
|
||||
|
||||
expect(() => {
|
||||
log.tryRecord('runtime.start.failed', {
|
||||
error: new Error('private failure')
|
||||
})
|
||||
runtimeContinued = true
|
||||
}).not.toThrow()
|
||||
await expect(log.flush()).resolves.toBeUndefined()
|
||||
|
||||
expect(runtimeContinued).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
function temporaryStateDirectory(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'goodbuddy-diagnostics-'))
|
||||
temporaryPaths.push(root)
|
||||
if (process.platform !== 'win32') {
|
||||
chmodSync(root, 0o700)
|
||||
}
|
||||
return root
|
||||
}
|
||||
@@ -0,0 +1,608 @@
|
||||
import { constants } from 'node:fs'
|
||||
import {
|
||||
lstat,
|
||||
open,
|
||||
rename
|
||||
} from 'node:fs/promises'
|
||||
import { resolve } from 'node:path'
|
||||
import { agentIdentifierSchema } from '../shared/agent-protocol'
|
||||
import {
|
||||
boundedInteger,
|
||||
isNodeError,
|
||||
settleWithin
|
||||
} from './async-utils'
|
||||
import {
|
||||
assertPrivateRegularFile,
|
||||
ensurePrivateDirectory,
|
||||
ensurePrivateDirectoryTree,
|
||||
readPrivateFile,
|
||||
unlinkOwnedPrivateFile
|
||||
} from './managed-paths'
|
||||
|
||||
export const AGENT_DIAGNOSTIC_DIRECTORY_NAME = 'diagnostics'
|
||||
export const AGENT_DIAGNOSTIC_FILE_NAME = 'agent-diagnostics.jsonl'
|
||||
export const DEFAULT_AGENT_DIAGNOSTIC_MAXIMUM_FILE_BYTES = 64 * 1024
|
||||
export const DEFAULT_AGENT_DIAGNOSTIC_FILE_COUNT = 3
|
||||
export const DEFAULT_AGENT_DIAGNOSTIC_MAXIMUM_QUEUED_RECORDS = 64
|
||||
export const DEFAULT_AGENT_DIAGNOSTIC_FLUSH_TIMEOUT_MS = 1_000
|
||||
const AGENT_DIAGNOSTIC_LOCK_FILE_NAME = '.agent-diagnostics.lock'
|
||||
const AGENT_DIAGNOSTIC_LOCK_ATTEMPTS = 10
|
||||
const AGENT_DIAGNOSTIC_LOCK_RETRY_MS = 10
|
||||
|
||||
export type AgentDiagnosticEvent =
|
||||
| 'daemon.starting'
|
||||
| 'daemon.ready'
|
||||
| 'daemon.start.failed'
|
||||
| 'daemon.stopping'
|
||||
| 'daemon.stopped'
|
||||
| 'daemon.stop.failed'
|
||||
| 'detached.launching'
|
||||
| 'detached.spawned'
|
||||
| 'connection.attached'
|
||||
| 'connection.closed'
|
||||
| 'connection.failed'
|
||||
| 'recovery.started'
|
||||
| 'recovery.succeeded'
|
||||
| 'recovery.failed'
|
||||
| 'runtime.starting'
|
||||
| 'runtime.started'
|
||||
| 'runtime.start.failed'
|
||||
| 'runtime.exited'
|
||||
|
||||
export type AgentDiagnosticRecord = {
|
||||
formatVersion: 1
|
||||
timestamp: string
|
||||
level: 'info' | 'error'
|
||||
event: AgentDiagnosticEvent
|
||||
pid: number
|
||||
daemonBootId?: string
|
||||
reason?: string
|
||||
runtimeId?: string
|
||||
workMode?: 'ask' | 'execute'
|
||||
outcome?: 'completed' | 'failed' | 'cancelled' | 'interrupted' | 'outcome-unknown'
|
||||
error?: {
|
||||
name: string
|
||||
code?: string
|
||||
}
|
||||
}
|
||||
|
||||
export type AgentDiagnosticInput = {
|
||||
daemonBootId?: string
|
||||
reason?: string
|
||||
runtimeId?: string
|
||||
workMode?: 'ask' | 'execute'
|
||||
outcome?: AgentDiagnosticRecord['outcome']
|
||||
error?: unknown
|
||||
}
|
||||
|
||||
export type AgentDiagnosticLogOptions = {
|
||||
maximumFileBytes?: number
|
||||
fileCount?: number
|
||||
maximumQueuedRecords?: number
|
||||
now?: () => number
|
||||
pid?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* A small, process-safe-enough JSONL diagnostic trail for detached operation.
|
||||
*
|
||||
* Callers can provide only fixed operational metadata. Arbitrary error
|
||||
* messages are deliberately not persisted because they can contain prompts,
|
||||
* credentials, command lines, paths, environment values, or Runtime output.
|
||||
*/
|
||||
export class AgentDiagnosticLog {
|
||||
readonly directoryPath: string
|
||||
readonly currentFilePath: string
|
||||
readonly #maximumFileBytes: number
|
||||
readonly #fileCount: number
|
||||
readonly #maximumQueuedRecords: number
|
||||
readonly #now: () => number
|
||||
readonly #pid: number
|
||||
readonly #queuedLines: string[] = []
|
||||
#pendingRecordCount = 0
|
||||
#drainPromise?: Promise<void>
|
||||
#disposed = false
|
||||
|
||||
constructor(
|
||||
stateDirectoryInput: string,
|
||||
options: AgentDiagnosticLogOptions = {}
|
||||
) {
|
||||
const stateDirectory = resolve(stateDirectoryInput)
|
||||
this.directoryPath = diagnosticDirectoryForStateDirectory(stateDirectory)
|
||||
this.currentFilePath = resolve(
|
||||
this.directoryPath,
|
||||
AGENT_DIAGNOSTIC_FILE_NAME
|
||||
)
|
||||
this.#maximumFileBytes = boundedInteger(
|
||||
options.maximumFileBytes ??
|
||||
DEFAULT_AGENT_DIAGNOSTIC_MAXIMUM_FILE_BYTES,
|
||||
512,
|
||||
1024 * 1024,
|
||||
'Agent diagnostic file size'
|
||||
)
|
||||
this.#fileCount = boundedInteger(
|
||||
options.fileCount ?? DEFAULT_AGENT_DIAGNOSTIC_FILE_COUNT,
|
||||
1,
|
||||
8,
|
||||
'Agent diagnostic file count'
|
||||
)
|
||||
this.#maximumQueuedRecords = boundedInteger(
|
||||
options.maximumQueuedRecords ??
|
||||
DEFAULT_AGENT_DIAGNOSTIC_MAXIMUM_QUEUED_RECORDS,
|
||||
1,
|
||||
256,
|
||||
'Agent diagnostic queue size'
|
||||
)
|
||||
this.#now = options.now ?? Date.now
|
||||
this.#pid = boundedInteger(
|
||||
options.pid ?? process.pid,
|
||||
1,
|
||||
Number.MAX_SAFE_INTEGER,
|
||||
'Agent diagnostic process ID'
|
||||
)
|
||||
}
|
||||
|
||||
record(event: AgentDiagnosticEvent, input: AgentDiagnosticInput = {}): void {
|
||||
if (this.#disposed) {
|
||||
throw new Error('Agent diagnostic log is disposed')
|
||||
}
|
||||
const line = this.#normalizeLine(event, input)
|
||||
if (!this.#enqueue(line)) {
|
||||
throw new Error('Agent diagnostic queue is full')
|
||||
}
|
||||
}
|
||||
|
||||
tryRecord(
|
||||
event: AgentDiagnosticEvent,
|
||||
input: AgentDiagnosticInput = {}
|
||||
): void {
|
||||
try {
|
||||
if (this.#disposed) {
|
||||
return
|
||||
}
|
||||
// Normalize now so the queue retains only bounded JSON, never the
|
||||
// original Error object or any message that it may contain.
|
||||
this.#enqueue(this.#normalizeLine(event, input))
|
||||
} catch {
|
||||
// Diagnostics must never interfere with daemon, attach, or Runtime I/O.
|
||||
}
|
||||
}
|
||||
|
||||
async flush(
|
||||
timeoutMs = DEFAULT_AGENT_DIAGNOSTIC_FLUSH_TIMEOUT_MS
|
||||
): Promise<void> {
|
||||
const boundedTimeout = boundedInteger(
|
||||
timeoutMs,
|
||||
1,
|
||||
30_000,
|
||||
'Agent diagnostic flush timeout'
|
||||
)
|
||||
await settleWithin(this.#waitForIdle(), boundedTimeout)
|
||||
}
|
||||
|
||||
async dispose(
|
||||
timeoutMs = DEFAULT_AGENT_DIAGNOSTIC_FLUSH_TIMEOUT_MS
|
||||
): Promise<void> {
|
||||
this.#disposed = true
|
||||
await this.flush(timeoutMs)
|
||||
}
|
||||
|
||||
read(): AgentDiagnosticRecord[] {
|
||||
return readAgentDiagnostics(resolve(this.directoryPath, '..'), {
|
||||
maximumFileBytes: this.#maximumFileBytes,
|
||||
fileCount: this.#fileCount
|
||||
})
|
||||
}
|
||||
|
||||
#normalizeLine(
|
||||
event: AgentDiagnosticEvent,
|
||||
input: AgentDiagnosticInput
|
||||
): string {
|
||||
const record: AgentDiagnosticRecord = {
|
||||
formatVersion: 1,
|
||||
timestamp: new Date(this.#now()).toISOString(),
|
||||
level: event.endsWith('.failed') ? 'error' : 'info',
|
||||
event,
|
||||
pid: this.#pid,
|
||||
...optionalToken('daemonBootId', input.daemonBootId, 128),
|
||||
...optionalToken('reason', input.reason, 96),
|
||||
...optionalToken('runtimeId', input.runtimeId, 64),
|
||||
...(input.workMode === undefined
|
||||
? {}
|
||||
: { workMode: input.workMode }),
|
||||
...(input.outcome === undefined
|
||||
? {}
|
||||
: { outcome: input.outcome }),
|
||||
...(input.error === undefined
|
||||
? {}
|
||||
: { error: summarizeDiagnosticError(input.error) })
|
||||
}
|
||||
const line = `${JSON.stringify(record)}\n`
|
||||
if (Buffer.byteLength(line, 'utf8') > this.#maximumFileBytes) {
|
||||
throw new Error('Agent diagnostic record exceeds its file bound')
|
||||
}
|
||||
return line
|
||||
}
|
||||
|
||||
#enqueue(line: string): boolean {
|
||||
if (this.#pendingRecordCount >= this.#maximumQueuedRecords) {
|
||||
return false
|
||||
}
|
||||
this.#queuedLines.push(line)
|
||||
this.#pendingRecordCount += 1
|
||||
this.#scheduleDrain()
|
||||
return true
|
||||
}
|
||||
|
||||
#scheduleDrain(): void {
|
||||
if (this.#drainPromise !== undefined) {
|
||||
return
|
||||
}
|
||||
this.#drainPromise = Promise.resolve()
|
||||
.then(async () => await this.#drain())
|
||||
.catch(() => {
|
||||
// Diagnostic write failures are deliberately isolated from callers.
|
||||
})
|
||||
.finally(() => {
|
||||
this.#drainPromise = undefined
|
||||
if (this.#queuedLines.length > 0) {
|
||||
this.#scheduleDrain()
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
async #drain(): Promise<void> {
|
||||
while (this.#queuedLines.length > 0) {
|
||||
const lines = this.#queuedLines.splice(0)
|
||||
try {
|
||||
await this.#writeLines(lines)
|
||||
} catch {
|
||||
// Drop this bounded batch. Diagnostics may not affect the protocol.
|
||||
} finally {
|
||||
this.#pendingRecordCount -= lines.length
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async #waitForIdle(): Promise<void> {
|
||||
while (this.#pendingRecordCount > 0) {
|
||||
const drain = this.#drainPromise
|
||||
if (drain === undefined) {
|
||||
this.#scheduleDrain()
|
||||
} else {
|
||||
await drain
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async #writeLines(lines: readonly string[]): Promise<void> {
|
||||
ensurePrivateDirectory(resolve(this.directoryPath, '..'), {
|
||||
create: false
|
||||
})
|
||||
ensurePrivateDirectoryTree(
|
||||
this.directoryPath,
|
||||
resolve(this.directoryPath, '..')
|
||||
)
|
||||
const releaseLock = await acquireDiagnosticLock(
|
||||
resolve(this.directoryPath, AGENT_DIAGNOSTIC_LOCK_FILE_NAME)
|
||||
)
|
||||
try {
|
||||
let nextLine = 0
|
||||
while (nextLine < lines.length) {
|
||||
let currentBytes = await privateFileSize(this.currentFilePath)
|
||||
if (currentBytes >= this.#maximumFileBytes) {
|
||||
await this.#rotate()
|
||||
currentBytes = 0
|
||||
}
|
||||
const availableBytes = this.#maximumFileBytes - currentBytes
|
||||
let batchBytes = 0
|
||||
let batchEnd = nextLine
|
||||
while (batchEnd < lines.length) {
|
||||
const lineBytes = Buffer.byteLength(lines[batchEnd]!, 'utf8')
|
||||
if (batchBytes + lineBytes > availableBytes) {
|
||||
break
|
||||
}
|
||||
batchBytes += lineBytes
|
||||
batchEnd += 1
|
||||
}
|
||||
if (batchEnd === nextLine) {
|
||||
await this.#rotate()
|
||||
continue
|
||||
}
|
||||
await appendPrivateFile(
|
||||
this.currentFilePath,
|
||||
lines.slice(nextLine, batchEnd).join('')
|
||||
)
|
||||
nextLine = batchEnd
|
||||
}
|
||||
} finally {
|
||||
releaseLock()
|
||||
}
|
||||
}
|
||||
|
||||
async #rotate(): Promise<void> {
|
||||
const oldest = rotatedPath(
|
||||
this.currentFilePath,
|
||||
this.#fileCount - 1
|
||||
)
|
||||
try {
|
||||
unlinkOwnedPrivateFile(oldest)
|
||||
} catch (error) {
|
||||
if (!isNodeError(error) || error.code !== 'ENOENT') {
|
||||
throw error
|
||||
}
|
||||
}
|
||||
for (let index = this.#fileCount - 2; index >= 0; index -= 1) {
|
||||
const source = rotatedPath(this.currentFilePath, index)
|
||||
const target = rotatedPath(this.currentFilePath, index + 1)
|
||||
try {
|
||||
assertPrivateRegularFile(source)
|
||||
await rename(source, target)
|
||||
} catch (error) {
|
||||
if (!isNodeError(error) || error.code !== 'ENOENT') {
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function acquireDiagnosticLock(
|
||||
path: string
|
||||
): Promise<() => void> {
|
||||
for (
|
||||
let attempt = 0;
|
||||
attempt < AGENT_DIAGNOSTIC_LOCK_ATTEMPTS;
|
||||
attempt += 1
|
||||
) {
|
||||
try {
|
||||
const descriptor = await open(
|
||||
path,
|
||||
constants.O_CREAT |
|
||||
constants.O_EXCL |
|
||||
constants.O_WRONLY |
|
||||
(constants.O_NOFOLLOW ?? 0),
|
||||
0o600
|
||||
)
|
||||
try {
|
||||
if (process.platform !== 'win32') {
|
||||
await descriptor.chmod(0o600)
|
||||
}
|
||||
} finally {
|
||||
await descriptor.close()
|
||||
}
|
||||
assertPrivateRegularFile(path)
|
||||
return () => {
|
||||
unlinkOwnedPrivateFile(path)
|
||||
}
|
||||
} catch (error) {
|
||||
if (!isNodeError(error) || error.code !== 'EEXIST') {
|
||||
throw error
|
||||
}
|
||||
assertPrivateRegularFile(path)
|
||||
await new Promise<void>((resolveRetry) => {
|
||||
setTimeout(resolveRetry, AGENT_DIAGNOSTIC_LOCK_RETRY_MS)
|
||||
})
|
||||
}
|
||||
}
|
||||
throw new Error('Agent diagnostic file is busy')
|
||||
}
|
||||
|
||||
async function privateFileSize(path: string): Promise<number> {
|
||||
try {
|
||||
assertPrivateRegularFile(path)
|
||||
return (await lstat(path)).size
|
||||
} catch (error) {
|
||||
if (!isNodeError(error) || error.code !== 'ENOENT') {
|
||||
throw error
|
||||
}
|
||||
return 0
|
||||
}
|
||||
}
|
||||
|
||||
async function appendPrivateFile(
|
||||
path: string,
|
||||
contents: string
|
||||
): Promise<void> {
|
||||
const descriptor = await open(
|
||||
path,
|
||||
constants.O_CREAT |
|
||||
constants.O_APPEND |
|
||||
constants.O_WRONLY |
|
||||
(constants.O_NOFOLLOW ?? 0),
|
||||
0o600
|
||||
)
|
||||
try {
|
||||
if (process.platform !== 'win32') {
|
||||
await descriptor.chmod(0o600)
|
||||
}
|
||||
await descriptor.writeFile(contents, 'utf8')
|
||||
} finally {
|
||||
await descriptor.close()
|
||||
}
|
||||
assertPrivateRegularFile(path)
|
||||
}
|
||||
|
||||
export function diagnosticDirectoryForStateDirectory(
|
||||
stateDirectoryInput: string
|
||||
): string {
|
||||
return resolve(stateDirectoryInput, AGENT_DIAGNOSTIC_DIRECTORY_NAME)
|
||||
}
|
||||
|
||||
export function readAgentDiagnostics(
|
||||
stateDirectoryInput: string,
|
||||
options: Pick<
|
||||
AgentDiagnosticLogOptions,
|
||||
'maximumFileBytes' | 'fileCount'
|
||||
> = {}
|
||||
): AgentDiagnosticRecord[] {
|
||||
const directory = diagnosticDirectoryForStateDirectory(
|
||||
resolve(stateDirectoryInput)
|
||||
)
|
||||
const current = resolve(directory, AGENT_DIAGNOSTIC_FILE_NAME)
|
||||
const maximumFileBytes =
|
||||
boundedInteger(
|
||||
options.maximumFileBytes ??
|
||||
DEFAULT_AGENT_DIAGNOSTIC_MAXIMUM_FILE_BYTES,
|
||||
512,
|
||||
1024 * 1024,
|
||||
'Agent diagnostic file size'
|
||||
)
|
||||
const fileCount =
|
||||
boundedInteger(
|
||||
options.fileCount ?? DEFAULT_AGENT_DIAGNOSTIC_FILE_COUNT,
|
||||
1,
|
||||
8,
|
||||
'Agent diagnostic file count'
|
||||
)
|
||||
const output: AgentDiagnosticRecord[] = []
|
||||
for (let index = fileCount - 1; index >= 0; index -= 1) {
|
||||
const path = rotatedPath(current, index)
|
||||
let contents: string
|
||||
try {
|
||||
contents = readPrivateFile(path, maximumFileBytes).toString('utf8')
|
||||
} catch (error) {
|
||||
if (isNodeError(error) && error.code === 'ENOENT') {
|
||||
continue
|
||||
}
|
||||
throw error
|
||||
}
|
||||
for (const line of contents.split('\n')) {
|
||||
if (line.length === 0) {
|
||||
continue
|
||||
}
|
||||
const parsed = parseDiagnosticRecord(line)
|
||||
if (parsed !== undefined) {
|
||||
output.push(parsed)
|
||||
}
|
||||
}
|
||||
}
|
||||
return output
|
||||
}
|
||||
|
||||
export function summarizeDiagnosticError(error: unknown): {
|
||||
name: string
|
||||
code?: string
|
||||
} {
|
||||
const name = diagnosticErrorName(error)
|
||||
const candidate =
|
||||
error !== null && typeof error === 'object' && 'code' in error
|
||||
? (error as { code?: unknown }).code
|
||||
: undefined
|
||||
const code =
|
||||
typeof candidate === 'string' &&
|
||||
SAFE_DIAGNOSTIC_ERROR_CODES.has(candidate)
|
||||
? candidate
|
||||
: undefined
|
||||
return {
|
||||
name,
|
||||
...(code === undefined ? {} : { code })
|
||||
}
|
||||
}
|
||||
|
||||
function diagnosticErrorName(error: unknown): string {
|
||||
if (error instanceof TypeError) {
|
||||
return 'TypeError'
|
||||
}
|
||||
if (error instanceof RangeError) {
|
||||
return 'RangeError'
|
||||
}
|
||||
if (error instanceof SyntaxError) {
|
||||
return 'SyntaxError'
|
||||
}
|
||||
return error instanceof Error ? 'Error' : 'NonError'
|
||||
}
|
||||
|
||||
const SAFE_DIAGNOSTIC_ERROR_CODES = new Set([
|
||||
'EACCES',
|
||||
'EADDRINUSE',
|
||||
'ECONNREFUSED',
|
||||
'ECONNRESET',
|
||||
'EEXIST',
|
||||
'EIO',
|
||||
'EISDIR',
|
||||
'ELOOP',
|
||||
'EMFILE',
|
||||
'ENAMETOOLONG',
|
||||
'ENFILE',
|
||||
'ENOENT',
|
||||
'ENOSPC',
|
||||
'ENOTDIR',
|
||||
'EPERM',
|
||||
'EPIPE',
|
||||
'EROFS',
|
||||
'ESRCH',
|
||||
'ETIMEDOUT'
|
||||
] as const)
|
||||
|
||||
function parseDiagnosticRecord(line: string): AgentDiagnosticRecord | undefined {
|
||||
try {
|
||||
const value: unknown = JSON.parse(line)
|
||||
if (
|
||||
value === null ||
|
||||
typeof value !== 'object' ||
|
||||
Array.isArray(value)
|
||||
) {
|
||||
return undefined
|
||||
}
|
||||
const record = value as Partial<AgentDiagnosticRecord>
|
||||
if (
|
||||
record.formatVersion !== 1 ||
|
||||
typeof record.timestamp !== 'string' ||
|
||||
(record.level !== 'info' && record.level !== 'error') ||
|
||||
typeof record.event !== 'string' ||
|
||||
!isDiagnosticEvent(record.event) ||
|
||||
!Number.isSafeInteger(record.pid) ||
|
||||
(record.pid ?? 0) <= 0
|
||||
) {
|
||||
return undefined
|
||||
}
|
||||
return record as AgentDiagnosticRecord
|
||||
} catch {
|
||||
return undefined
|
||||
}
|
||||
}
|
||||
|
||||
function rotatedPath(currentPath: string, index: number): string {
|
||||
return index === 0 ? currentPath : `${currentPath}.${index}`
|
||||
}
|
||||
|
||||
function optionalToken<Key extends 'daemonBootId' | 'reason' | 'runtimeId'>(
|
||||
key: Key,
|
||||
value: string | undefined,
|
||||
maximumLength: number
|
||||
): Partial<Record<Key, string>> {
|
||||
if (
|
||||
value === undefined ||
|
||||
value.length > maximumLength ||
|
||||
!agentIdentifierSchema.safeParse(value).success
|
||||
) {
|
||||
return {}
|
||||
}
|
||||
return { [key]: value } as Record<Key, string>
|
||||
}
|
||||
|
||||
function isDiagnosticEvent(value: string): value is AgentDiagnosticEvent {
|
||||
return DIAGNOSTIC_EVENTS.has(value as AgentDiagnosticEvent)
|
||||
}
|
||||
|
||||
const DIAGNOSTIC_EVENTS = new Set<AgentDiagnosticEvent>([
|
||||
'daemon.starting',
|
||||
'daemon.ready',
|
||||
'daemon.start.failed',
|
||||
'daemon.stopping',
|
||||
'daemon.stopped',
|
||||
'daemon.stop.failed',
|
||||
'detached.launching',
|
||||
'detached.spawned',
|
||||
'connection.attached',
|
||||
'connection.closed',
|
||||
'connection.failed',
|
||||
'recovery.started',
|
||||
'recovery.succeeded',
|
||||
'recovery.failed',
|
||||
'runtime.starting',
|
||||
'runtime.started',
|
||||
'runtime.start.failed',
|
||||
'runtime.exited'
|
||||
])
|
||||
@@ -6,6 +6,7 @@ export * from './cli'
|
||||
export * from './controller-registry'
|
||||
export * from './daemon'
|
||||
export * from './detached-agent-lifecycle'
|
||||
export * from './diagnostic-log'
|
||||
export * from './direct-linux-stdio-process-owner'
|
||||
export * from './errors'
|
||||
export * from './entry'
|
||||
|
||||
@@ -76,6 +76,7 @@ export class PrivateEndpoint {
|
||||
readonly #challenge: InstallationChallengeVerifier
|
||||
readonly #controllers: ControllerRegistry
|
||||
readonly #onAttach: (attach: AuthenticatedAttach) => void | Promise<void>
|
||||
readonly #onConnectionFailure?: (error: unknown) => void
|
||||
readonly #installationId: string
|
||||
readonly #binaryDigest: string
|
||||
readonly #daemonBootId: string
|
||||
@@ -92,6 +93,7 @@ export class PrivateEndpoint {
|
||||
challenge: InstallationChallengeVerifier
|
||||
controllers: ControllerRegistry
|
||||
onAttach: (attach: AuthenticatedAttach) => void | Promise<void>
|
||||
onConnectionFailure?: (error: unknown) => void
|
||||
installationId: string
|
||||
binaryDigest: string
|
||||
daemonBootId: string
|
||||
@@ -103,6 +105,7 @@ export class PrivateEndpoint {
|
||||
this.#challenge = options.challenge
|
||||
this.#controllers = options.controllers
|
||||
this.#onAttach = options.onAttach
|
||||
this.#onConnectionFailure = options.onConnectionFailure
|
||||
this.#installationId = agentIdentifierSchema.parse(options.installationId)
|
||||
this.#binaryDigest = sha256DigestSchema.parse(options.binaryDigest)
|
||||
this.#daemonBootId = agentIdentifierSchema.parse(options.daemonBootId)
|
||||
@@ -141,7 +144,10 @@ export class PrivateEndpoint {
|
||||
socket.once('close', () => {
|
||||
this.#sockets.delete(socket)
|
||||
})
|
||||
void this.#authenticate(socket).catch(() => socket.destroy())
|
||||
void this.#authenticate(socket).catch((error: unknown) => {
|
||||
this.#onConnectionFailure?.(error)
|
||||
socket.destroy()
|
||||
})
|
||||
})
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const server = this.#server
|
||||
|
||||
@@ -122,6 +122,15 @@ export class AgentProtocolServer {
|
||||
connectionId: string
|
||||
category: AgentProtocolFailureCategory
|
||||
}) => void
|
||||
readonly #onConnectionClose?: (input: {
|
||||
connectionId: string
|
||||
category?: AgentProtocolFailureCategory
|
||||
}) => void
|
||||
readonly #onRecovery?: (input: {
|
||||
connectionId: string
|
||||
outcome: 'started' | 'succeeded' | 'failed'
|
||||
reason?: 'invalid-request' | 'identity-mismatch' | 'takeover-rejected'
|
||||
}) => void
|
||||
readonly #connections = new Map<string, ProtocolConnection>()
|
||||
|
||||
constructor(options: {
|
||||
@@ -148,6 +157,15 @@ export class AgentProtocolServer {
|
||||
connectionId: string
|
||||
category: AgentProtocolFailureCategory
|
||||
}) => void
|
||||
onConnectionClose?: (input: {
|
||||
connectionId: string
|
||||
category?: AgentProtocolFailureCategory
|
||||
}) => void
|
||||
onRecovery?: (input: {
|
||||
connectionId: string
|
||||
outcome: 'started' | 'succeeded' | 'failed'
|
||||
reason?: 'invalid-request' | 'identity-mismatch' | 'takeover-rejected'
|
||||
}) => void
|
||||
incomingQueueLimits?: Partial<IncomingQueueLimits>
|
||||
}) {
|
||||
this.#controllers = options.controllers
|
||||
@@ -159,6 +177,8 @@ export class AgentProtocolServer {
|
||||
this.#onBlobFrame = options.onBlobFrame
|
||||
this.#authorizeBlobFrame = options.authorizeBlobFrame
|
||||
this.#onProtocolFailure = options.onProtocolFailure
|
||||
this.#onConnectionClose = options.onConnectionClose
|
||||
this.#onRecovery = options.onRecovery
|
||||
this.#incomingQueueLimits = incomingQueueLimits(
|
||||
options.incomingQueueLimits
|
||||
)
|
||||
@@ -239,12 +259,33 @@ export class AgentProtocolServer {
|
||||
})
|
||||
},
|
||||
'controller/resume': async (params) => {
|
||||
const request = controllerResumeRequestSchema.parse(params)
|
||||
this.#onRecovery?.({
|
||||
connectionId: controller.connectionId,
|
||||
outcome: 'started'
|
||||
})
|
||||
let request: ReturnType<
|
||||
typeof controllerResumeRequestSchema.parse
|
||||
>
|
||||
try {
|
||||
request = controllerResumeRequestSchema.parse(params)
|
||||
} catch (error) {
|
||||
this.#onRecovery?.({
|
||||
connectionId: controller.connectionId,
|
||||
outcome: 'failed',
|
||||
reason: 'invalid-request'
|
||||
})
|
||||
throw error
|
||||
}
|
||||
const status = daemonStatusSchema.parse(await this.#status())
|
||||
if (
|
||||
request.daemonBootId !== status.daemonBootId ||
|
||||
request.previousGeneration >= controller.generation
|
||||
) {
|
||||
this.#onRecovery?.({
|
||||
connectionId: controller.connectionId,
|
||||
outcome: 'failed',
|
||||
reason: 'identity-mismatch'
|
||||
})
|
||||
return controllerResumeResultSchema.parse({
|
||||
resumed: false,
|
||||
generation: controller.generation,
|
||||
@@ -263,6 +304,11 @@ export class AgentProtocolServer {
|
||||
request
|
||||
)
|
||||
} catch {
|
||||
this.#onRecovery?.({
|
||||
connectionId: controller.connectionId,
|
||||
outcome: 'failed',
|
||||
reason: 'takeover-rejected'
|
||||
})
|
||||
return controllerResumeResultSchema.parse({
|
||||
resumed: false,
|
||||
generation: controller.generation,
|
||||
@@ -276,6 +322,10 @@ export class AgentProtocolServer {
|
||||
this.#connections
|
||||
.get(request.previousConnectionId)
|
||||
?.fence()
|
||||
this.#onRecovery?.({
|
||||
connectionId: controller.connectionId,
|
||||
outcome: 'succeeded'
|
||||
})
|
||||
return controllerResumeResultSchema.parse({
|
||||
resumed: true,
|
||||
generation: resumed.generation,
|
||||
@@ -293,6 +343,10 @@ export class AgentProtocolServer {
|
||||
onBlobFrame: this.#onBlobFrame,
|
||||
incomingQueueLimits: this.#incomingQueueLimits,
|
||||
onClose: (category) => {
|
||||
this.#onConnectionClose?.({
|
||||
connectionId: controller.connectionId,
|
||||
...(category === undefined ? {} : { category })
|
||||
})
|
||||
if (category !== undefined) {
|
||||
this.#onProtocolFailure?.({
|
||||
connectionId: controller.connectionId,
|
||||
|
||||
@@ -273,6 +273,7 @@ function harness(input: {
|
||||
dispatch: ReturnType<typeof vi.fn>
|
||||
finalizePrompt: ReturnType<typeof vi.fn>
|
||||
}
|
||||
launchError?: Error
|
||||
} = {}) {
|
||||
const workMode = input.workMode ?? 'ask'
|
||||
let now = input.now ?? 1_000
|
||||
@@ -284,6 +285,9 @@ function harness(input: {
|
||||
scratch: string
|
||||
}> = []
|
||||
const lifecycle: string[] = []
|
||||
const diagnostics = {
|
||||
tryRecord: vi.fn()
|
||||
}
|
||||
const bridgeCloses = vi.fn(async () => {
|
||||
if (input.bridgeCloseError) {
|
||||
throw new Error('broker close failed')
|
||||
@@ -315,6 +319,9 @@ function harness(input: {
|
||||
})),
|
||||
launchProcess: vi.fn(async (launch) => {
|
||||
lifecycle.push('launch')
|
||||
if (input.launchError !== undefined) {
|
||||
throw input.launchError
|
||||
}
|
||||
launchModelBridges.push(launch.modelBridge)
|
||||
launches.push({
|
||||
workMode: launch.workMode,
|
||||
@@ -325,6 +332,7 @@ function harness(input: {
|
||||
: process
|
||||
}),
|
||||
now: () => now,
|
||||
diagnostics,
|
||||
outputSink: vi.fn(async (frame) => {
|
||||
await input.outputGate
|
||||
outputFrames.push(Buffer.from(frame.payload).toString())
|
||||
@@ -366,6 +374,7 @@ function harness(input: {
|
||||
process,
|
||||
launches,
|
||||
lifecycle,
|
||||
diagnostics,
|
||||
bridgeCloses,
|
||||
blobSink,
|
||||
get bridgeDispatch() {
|
||||
@@ -876,6 +885,56 @@ describe('RuntimeAcpBackend', () => {
|
||||
)
|
||||
)
|
||||
expect(fixture.bridgeCloses).toHaveBeenCalledOnce()
|
||||
await vi.waitFor(() =>
|
||||
expect(fixture.diagnostics.tryRecord).toHaveBeenCalledWith(
|
||||
'runtime.exited',
|
||||
{
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'ask',
|
||||
outcome: 'failed'
|
||||
}
|
||||
)
|
||||
)
|
||||
expect(fixture.diagnostics.tryRecord).toHaveBeenCalledWith(
|
||||
'runtime.starting',
|
||||
{
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'ask'
|
||||
}
|
||||
)
|
||||
expect(fixture.diagnostics.tryRecord).toHaveBeenCalledWith(
|
||||
'runtime.started',
|
||||
{
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'ask'
|
||||
}
|
||||
)
|
||||
await fixture.backend.dispose()
|
||||
})
|
||||
|
||||
it('records a redacted Runtime launch failure at the unified preparation point', async () => {
|
||||
const launchError = new Error(
|
||||
'accepted Prompt and API key must never be persisted'
|
||||
)
|
||||
const fixture = harness({ launchError })
|
||||
await open(fixture)
|
||||
|
||||
await expect(
|
||||
invoke(
|
||||
fixture,
|
||||
'runtime/preparePrompt',
|
||||
fixture.preparation()
|
||||
)
|
||||
).rejects.toThrow('Runtime process launch failed')
|
||||
|
||||
expect(fixture.diagnostics.tryRecord).toHaveBeenCalledWith(
|
||||
'runtime.start.failed',
|
||||
{
|
||||
runtimeId: 'opencode',
|
||||
workMode: 'ask',
|
||||
error: launchError
|
||||
}
|
||||
)
|
||||
await fixture.backend.dispose()
|
||||
})
|
||||
|
||||
|
||||
@@ -22,6 +22,10 @@ import {
|
||||
type AgentFrame
|
||||
} from '../shared/agent-protocol'
|
||||
import { canonicalJson } from '../shared/agent-protocol/canonical'
|
||||
import type {
|
||||
AgentDiagnosticLog,
|
||||
AgentDiagnosticRecord
|
||||
} from './diagnostic-log'
|
||||
import {
|
||||
acpJournalCursorSchema,
|
||||
remoteOwnedPromptAttachRequestSchema,
|
||||
@@ -279,6 +283,7 @@ export type RuntimeAcpBackendOptions = {
|
||||
}) => ModelBridgeBrokerServer
|
||||
semanticPrompts?: SemanticPromptStore
|
||||
modelGateway?: AgentModelGateway
|
||||
diagnostics?: Pick<AgentDiagnosticLog, 'tryRecord'>
|
||||
now?: () => number
|
||||
limits?: Partial<RuntimeAcpBackendLimits>
|
||||
}
|
||||
@@ -1106,6 +1111,10 @@ export class RuntimeAcpBackend {
|
||||
|
||||
if (binding.process === undefined) {
|
||||
let process: RuntimeAcpProcessOwner
|
||||
this.#options.diagnostics?.tryRecord('runtime.starting', {
|
||||
runtimeId: verified.manifest.runtimeId,
|
||||
workMode: preparation.workMode
|
||||
})
|
||||
try {
|
||||
process = await this.#options.launchProcess({
|
||||
manifest: verified.manifest,
|
||||
@@ -1126,7 +1135,12 @@ export class RuntimeAcpBackend {
|
||||
})
|
||||
})
|
||||
assertProcessIdentity(process.identity)
|
||||
} catch {
|
||||
} catch (error) {
|
||||
this.#options.diagnostics?.tryRecord('runtime.start.failed', {
|
||||
runtimeId: verified.manifest.runtimeId,
|
||||
workMode: preparation.workMode,
|
||||
error
|
||||
})
|
||||
await this.#closeModelBridge(binding, false).catch(
|
||||
() => undefined
|
||||
)
|
||||
@@ -1199,6 +1213,10 @@ export class RuntimeAcpBackend {
|
||||
'process'
|
||||
)
|
||||
}
|
||||
this.#options.diagnostics?.tryRecord('runtime.started', {
|
||||
runtimeId: verified.manifest.runtimeId,
|
||||
workMode: preparation.workMode
|
||||
})
|
||||
} else {
|
||||
try {
|
||||
await binding.process.beginPrompt({
|
||||
@@ -2162,6 +2180,8 @@ export class RuntimeAcpBackend {
|
||||
)
|
||||
let state: 'completed' | 'failed' | 'cancelled' | 'interrupted' =
|
||||
'interrupted'
|
||||
let diagnosticOutcome: AgentDiagnosticRecord['outcome'] =
|
||||
'interrupted'
|
||||
try {
|
||||
const reconciliation = await binding.process.reconcile()
|
||||
if (
|
||||
@@ -2172,10 +2192,29 @@ export class RuntimeAcpBackend {
|
||||
reconciliation.processTree === 'empty'
|
||||
) {
|
||||
state = terminalState(reconciliation.state)
|
||||
diagnosticOutcome = state
|
||||
}
|
||||
} catch {
|
||||
} catch (error) {
|
||||
binding.state = 'outcome-unknown'
|
||||
diagnosticOutcome = 'outcome-unknown'
|
||||
this.#options.diagnostics?.tryRecord('runtime.exited', {
|
||||
runtimeId: binding.resolvedBundle.entry.runtimeId,
|
||||
...(binding.workMode === undefined
|
||||
? {}
|
||||
: { workMode: binding.workMode }),
|
||||
outcome: diagnosticOutcome,
|
||||
error
|
||||
})
|
||||
this.#finishBinding(binding, state)
|
||||
return
|
||||
}
|
||||
this.#options.diagnostics?.tryRecord('runtime.exited', {
|
||||
runtimeId: binding.resolvedBundle.entry.runtimeId,
|
||||
...(binding.workMode === undefined
|
||||
? {}
|
||||
: { workMode: binding.workMode }),
|
||||
outcome: diagnosticOutcome
|
||||
})
|
||||
this.#finishBinding(binding, state)
|
||||
}
|
||||
|
||||
|
||||
@@ -44,6 +44,7 @@ import {
|
||||
AgentModelCallLedger,
|
||||
AgentModelGateway
|
||||
} from './agent-model-gateway'
|
||||
import type { AgentDiagnosticLog } from './diagnostic-log'
|
||||
|
||||
const BWRAP_EXECUTABLE = '/usr/bin/bwrap'
|
||||
|
||||
@@ -93,6 +94,7 @@ export type ProductionRuntimeCompositionOptions = {
|
||||
verificationEnvironment?: 'production' | 'test'
|
||||
filesystemPlatform?: NodeJS.Platform
|
||||
reportError?: (message: string, error: unknown) => void
|
||||
diagnostics?: Pick<AgentDiagnosticLog, 'tryRecord'>
|
||||
}
|
||||
|
||||
export async function createProductionRuntimeProtocol(
|
||||
@@ -304,6 +306,7 @@ export async function createProductionRuntimeProtocol(
|
||||
outputSink: options.outputSink,
|
||||
semanticPrompts,
|
||||
modelGateway,
|
||||
diagnostics: options.diagnostics,
|
||||
...(options.blobSink === undefined
|
||||
? {}
|
||||
: { blobSink: options.blobSink })
|
||||
|
||||
Reference in New Issue
Block a user