diff --git a/README.md b/README.md index a78b3b9..7138377 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,19 @@ The Atomic agent: You never need to run `atomic add` or `atomic record` — the hooks handle it. +### Event timestamps + +Hook payloads carry RFC-3339 timestamps with millisecond precision. The plugin +forwards OpenCode's native event creation time (and v1 session/message creation +time) when available. Prompt/tool callbacks without a native timestamp use receipt +time captured before queueing or asynchronous lookups, not CLI dispatch time. +Missing or invalid native times also fall back to callback receipt time. +Turn/tool durations use these captured times; a retried Stop retains its original +timestamp and duration. Negative durations caused by clock skew are clamped to zero. + +Atomic's OpenCode adapter must preserve the supplied timestamp for this source +time to reach the provenance journal. Older adapters instead record receipt time. + ## Viewing provenance ```bash diff --git a/plugins/atomic-hooks.ts b/plugins/atomic-hooks.ts index f464645..03e1028 100644 --- a/plugins/atomic-hooks.ts +++ b/plugins/atomic-hooks.ts @@ -4,6 +4,17 @@ import { appendFileSync } from "node:fs"; const ATOMIC_AGENT_VERSION = "1.3.0"; +// OpenCode event/message times are epoch milliseconds. Hooks without a source +// time use callback receipt time, captured before any queue or async lookup. +function eventTimestamp(value?) { + const date = new Date( + typeof value === "number" || typeof value === "string" ? value : Date.now(), + ); + return Number.isFinite(date.getTime()) + ? date.toISOString() + : new Date(Date.now()).toISOString(); +} + function atomicEnabled(directory) { try { if ( @@ -42,6 +53,7 @@ const createTracker = (directory, invoke) => { provider: null, turns: 0, turnStartTime: null, + stopTimestamp: null, tools: new Map(), reasoning: new Map(), text: new Map(), @@ -60,12 +72,12 @@ const createTracker = (directory, invoke) => { ); } catch {} } - async function hook(sid, verb, payload = {}) { + async function hook(sid, verb, payload = {}, timestamp = eventTimestamp()) { const json = JSON.stringify({ ...payload, session_id: sid, cwd: directory, - timestamp: new Date().toISOString(), + timestamp, }); // Wait for the operation itself, not merely its background launcher. const result = await invoke(json, verb); @@ -76,36 +88,38 @@ const createTracker = (directory, invoke) => { } // Events can arrive while an earlier callback awaits I/O. Only callbacks // belonging to the same session wait on one another. - function enqueue(sid, operation, callback, strict = false) { + function enqueue(sid, operation, callback, strict = false, timestamp?) { if (typeof sid !== "string" || !sid) return Promise.resolve(); + const capturedTimestamp = eventTimestamp(timestamp); const state = stateFor(sid); const next = state.tail.then(async () => { - if (!state.closed) await callback(state); + if (!state.closed) await callback(state, capturedTimestamp); }); state.tail = next.catch((error) => logFailure(sid, operation, String(error)), ); return strict ? next : state.tail; } - async function start(sid, state) { + async function start(sid, state, timestamp) { if (!state.started) { - await hook(sid, "session-start", { source: "startup" }); + await hook(sid, "session-start", { source: "startup" }, timestamp); state.started = true; } } - async function beginTurn(sid, state, payload = {}) { - await start(sid, state); + async function beginTurn(sid, state, payload = {}, timestamp) { + await start(sid, state, timestamp); if (state.active) return; // Programmatic/subagent and resumed turns need not emit chat.message. // A tool or model step must activate the CLI turn before it can end. // Do not claim activation until the foreground hook has succeeded. - await hook(sid, "user-prompt", { - model: state.model, - provider: state.provider, - ...payload, - }); + await hook( + sid, + "user-prompt", + { model: state.model, provider: state.provider, ...payload }, + timestamp, + ); state.active = true; - state.turnStartTime = Date.now(); + state.turnStartTime = Date.parse(timestamp); } function reset(state) { state.reasoning.clear(); @@ -115,10 +129,13 @@ const createTracker = (directory, invoke) => { state.finishes.clear(); state.tools.clear(); state.turnStartTime = null; + state.stopTimestamp = null; } - async function stopTurn(sid, state) { + async function stopTurn(sid, state, timestamp) { if (!state.active) return; - await start(sid, state); + await start(sid, state, timestamp); + // A failed Stop retries the same turn boundary, not a later timestamp. + state.stopTimestamp ??= timestamp; const reasoning_blocks = [...state.reasoning.values()] .map((b) => ({ text: (b.text || "").trim(), @@ -158,7 +175,7 @@ const createTracker = (directory, invoke) => { provider: state.provider, turn_duration_ms: state.turnStartTime != null - ? Date.now() - state.turnStartTime + ? Math.max(0, Date.parse(state.stopTimestamp) - state.turnStartTime) : undefined, reasoning_blocks: reasoning_blocks.length ? reasoning_blocks @@ -171,16 +188,16 @@ const createTracker = (directory, invoke) => { step_count: state.steps.size, } : {}), - }); + }, state.stopTimestamp); state.turns = turn; state.active = false; state.completedSteps = new Set(state.steps); reset(state); } - async function endSession(sid) { + async function endSession(sid, timestamp) { const state = stateFor(sid); if (state.started) - await hook(sid, "session-end", { reason: "deleted" }); + await hook(sid, "session-end", { reason: "deleted" }, timestamp); state.closed = true; reset(state); sessions.delete(sid); @@ -208,7 +225,13 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { const props = event.properties ?? {}; if (event.type === "session.created") { const sid = props.sessionID ?? props.info?.id; - return enqueue(sid, event.type, (state) => start(sid, state)); + return enqueue( + sid, + event.type, + (state, timestamp) => start(sid, state, timestamp), + false, + props.info?.time?.created, + ); } if (event.type === "message.updated") { const info = props.info; @@ -222,7 +245,7 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { } if (event.type === "message.part.updated") { const part = props.part; - return enqueue(part?.sessionID, event.type, async (state) => { + return enqueue(part?.sessionID, event.type, async (state, timestamp) => { if (part.type === "reasoning") { state.reasoning.set(part.id, { text: part.text ?? "", @@ -235,7 +258,7 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { } else if (part.type === "step-start") { // OpenCode can resend the last step snapshot after idle. if (state.completedSteps.has(part.id)) return; - await beginTurn(part.sessionID, state); + await beginTurn(part.sessionID, state, {}, timestamp); state.steps.add(part.id); } else if (part.type === "step-finish") { // Updates are snapshots, not incremental token deltas. @@ -253,16 +276,20 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { } if (event.type === "session.idle") { const sid = props.sessionID; - return enqueue(sid, event.type, (state) => stopTurn(sid, state)); + return enqueue(sid, event.type, (state, timestamp) => + stopTurn(sid, state, timestamp), + ); } if (event.type === "session.deleted") { const sid = props.sessionID ?? props.info?.id; - return enqueue(sid, event.type, () => t.endSession(sid)); + return enqueue(sid, event.type, (_state, timestamp) => + t.endSession(sid, timestamp), + ); } }, "chat.message": async (input, output) => { const sid = input.sessionID; - return enqueue(sid, "chat.message", async (state) => { + return enqueue(sid, "chat.message", async (state, timestamp) => { if (input.model) { state.model = input.model.modelID; state.provider = input.model.providerID; @@ -276,31 +303,31 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { prompt: prompt || undefined, model: state.model, provider: state.provider, - }); - }); + }, timestamp); + }, false, output.message?.time?.created); }, "tool.execute.before": async (input, output) => { const sid = input.sessionID; return enqueue( sid, "before-tool", - async (state) => { - await beginTurn(sid, state); + async (state, timestamp) => { + await beginTurn(sid, state, {}, timestamp); const args = output.args || {}; - state.tools.set(input.callID, { start: Date.now(), args }); + state.tools.set(input.callID, { start: Date.parse(timestamp), args }); await t.hook(sid, "before-tool", { tool_name: input.tool, tool_call_id: input.callID, tool_input: args, - }); + }, timestamp); }, true, ); }, "tool.execute.after": async (input, output) => { const sid = input.sessionID; - return enqueue(sid, "after-tool", async (state) => { - await beginTurn(sid, state); + return enqueue(sid, "after-tool", async (state, timestamp) => { + await beginTurn(sid, state, {}, timestamp); const saved = state.tools.get(input.callID), args = saved?.args || {}; const raw = output.output; @@ -320,8 +347,10 @@ export const AtomicHooksPlugin = async ({ directory, $ }) => { file_path: args.filePath || args.path, exit_code: typeof exit === "number" ? exit : undefined, status: "completed", - duration: saved ? Date.now() - saved.start : undefined, - }); + duration: saved + ? Math.max(0, Date.parse(timestamp) - saved.start) + : undefined, + }, timestamp); state.tools.delete(input.callID); }); }, @@ -371,26 +400,24 @@ const setupV2 = async (ctx, invoke) => { const known = new Set(); const own = (sid) => typeof sid === "string" && !!sid && known.has(sid); - const userPrompt = (sid, payload) => - enqueue(sid, "user-prompt", (state) => t.beginTurn(sid, state, payload)); const toolBefore = (sid, tool, callID, args) => enqueue( sid, "before-tool", - async (state) => { - await t.beginTurn(sid, state); - state.tools.set(callID, { start: Date.now(), args }); + async (state, timestamp) => { + await t.beginTurn(sid, state, {}, timestamp); + state.tools.set(callID, { start: Date.parse(timestamp), args }); await t.hook(sid, "before-tool", { tool_name: tool, tool_call_id: callID, tool_input: args, - }); + }, timestamp); }, true, ); const toolAfter = (sid, tool, callID, args, toolOutput, status, exit) => - enqueue(sid, "after-tool", async (state) => { - await t.beginTurn(sid, state); + enqueue(sid, "after-tool", async (state, timestamp) => { + await t.beginTurn(sid, state, {}, timestamp); const saved = state.tools.get(callID); const truncated = toolOutput != null @@ -406,8 +433,10 @@ const setupV2 = async (ctx, invoke) => { file_path: args?.filePath || args?.path, exit_code: typeof exit === "number" ? exit : undefined, status, - duration: saved ? Date.now() - saved.start : undefined, - }); + duration: saved + ? Math.max(0, Date.parse(timestamp) - saved.start) + : undefined, + }, timestamp); state.tools.delete(callID); }); @@ -415,15 +444,17 @@ const setupV2 = async (ctx, invoke) => { await ctx.session.hook("prompt", async (event) => { const sid = event.sessionID; known.add(sid); - let model, provider; - try { - const info = await ctx.session.get({ sessionID: sid }); - model = info?.model?.id; - provider = info?.model?.providerID; - } catch {} - return userPrompt(sid, { - prompt: (event.prompt?.text ?? "").trim() || undefined, - ...(model ? { model, provider } : {}), + return enqueue(sid, "user-prompt", async (state, timestamp) => { + let model, provider; + try { + const info = await ctx.session.get({ sessionID: sid }); + model = info?.model?.id; + provider = info?.model?.providerID; + } catch {} + await t.beginTurn(sid, state, { + prompt: (event.prompt?.text ?? "").trim() || undefined, + ...(model ? { model, provider } : {}), + }, timestamp); }); }); await ctx.tool.hook("execute.before", (event) => { @@ -479,6 +510,7 @@ const setupV2 = async (ctx, invoke) => { const sid = data.sessionID; const loc = ev.location?.directory; if (loc !== undefined && loc !== directory) continue; + const timestamp = eventTimestamp(ev.created); switch (ev.type) { case "session.inbox.enqueued": case "session.inbox.delivered": @@ -486,28 +518,36 @@ const setupV2 = async (ctx, invoke) => { break; case "session.execution.started": if (own(sid)) - enqueue(sid, ev.type, (state) => t.beginTurn(sid, state)); + enqueue( + sid, + ev.type, + (state, timestamp) => t.beginTurn(sid, state, {}, timestamp), + false, + timestamp, + ); break; case "session.execution.succeeded": case "session.execution.failed": case "session.execution.interrupted": case "session.idle": if (own(sid)) - enqueue(sid, ev.type, (state) => stopTurn(sid, state)); + enqueue(sid, ev.type, (state, timestamp) => stopTurn(sid, state, timestamp), + false, timestamp); break; case "session.status": if (own(sid) && data.status?.type === "idle") - enqueue(sid, ev.type, (state) => stopTurn(sid, state)); + enqueue(sid, ev.type, (state, timestamp) => stopTurn(sid, state, timestamp), + false, timestamp); break; case "session.step.started": if (!own(sid)) break; - enqueue(sid, ev.type, async (state) => { + enqueue(sid, ev.type, async (state, timestamp) => { if (data.model?.id) state.model = data.model.id; if (data.model?.providerID) state.provider = data.model.providerID; - await t.beginTurn(sid, state); + await t.beginTurn(sid, state, {}, timestamp); state.steps.add(ev.id); - }); + }, false, timestamp); break; case "session.step.ended": case "session.step.failed": @@ -550,7 +590,14 @@ const setupV2 = async (ctx, invoke) => { }); break; case "session.deleted": - if (own(sid)) enqueue(sid, ev.type, () => t.endSession(sid)); + if (own(sid)) + enqueue( + sid, + ev.type, + (_state, timestamp) => t.endSession(sid, timestamp), + false, + timestamp, + ); known.delete(sid); break; } diff --git a/tests/session-isolation.test.ts b/tests/session-isolation.test.ts index be38fc6..9ef7b11 100644 --- a/tests/session-isolation.test.ts +++ b/tests/session-isolation.test.ts @@ -48,6 +48,44 @@ async function fixture( } describe("concurrent Atomic sessions", () => { + test("v1 preserves native session and message creation timestamps", async () => { + const f = await fixture(); + await f.event("session.created", { + info: { id: "source-time", time: { created: 1_792_920_379_100 } }, + }); + await f.plugin["chat.message"]( + { sessionID: "source-time" }, + { + message: { time: { created: 1_792_920_379_589 } }, + parts: [{ type: "text", text: "Keep the source time" }], + }, + ); + expect(f.calls[0].payload.timestamp).toBe("2026-10-25T09:26:19.100Z"); + expect(f.calls[1].payload.timestamp).toBe("2026-10-25T09:26:19.589Z"); + }); + + test("v1 captures tool receipt times before queueing and excludes queue delay from durations", async () => { + let now = 1_792_920_379_100; + spyOn(Date, "now").mockImplementation(() => now); + let release!: () => void; + const gate = new Promise((resolve) => { release = resolve; }); + const f = await fixture(async (verb) => { + if (verb === "session-start") await gate; + return { exitCode: 0, stderr: "" }; + }); + const input = { sessionID: "queued-time", callID: "tool", tool: "read" }; + const before = f.plugin["tool.execute.before"](input, { args: {} }); + now = 1_792_920_379_589; + const after = f.plugin["tool.execute.after"](input, { output: "Done" }); + now += 60_000; + release(); + await Promise.all([before, after]); + expect(f.calls.find((c) => c.verb === "before-tool").payload.timestamp) + .toBe("2026-10-25T09:26:19.100Z"); + expect(f.calls.find((c) => c.verb === "after-tool").payload) + .toMatchObject({ timestamp: "2026-10-25T09:26:19.589Z", duration: 489 }); + }); + for (const scenario of ["existing edits", "handoff after a recorded turn"]) { test(`${scenario} do not block later bash commands or Stop`, async () => { let file: string; @@ -491,6 +529,7 @@ describe("OpenCode v2 plugin", () => { return { calls, root, + ctx, bus, cleanup, hooks, @@ -519,6 +558,135 @@ describe("OpenCode v2 plugin", () => { expect(typeof pluginDefault.setup).toBe("function"); }); + test("v2 forwards native lifecycle times despite a blocked hook queue", async () => { + let release!: () => void; + const gate = new Promise((resolve) => { release = resolve; }); + const f = await fixtureV2(async (verb) => { + if (verb === "session-start") await gate; + return { exitCode: 0, stderr: "" }; + }); + f.event("session.inbox.enqueued", { sessionID: "native-time" }, { directory: f.root }); + f.event("session.execution.started", { sessionID: "native-time" }, undefined, 1_792_920_379_100); + f.event("session.execution.succeeded", { sessionID: "native-time" }, undefined, 1_792_920_379_589); + await until(() => f.calls.some((c) => c.verb === "session-start")); + release(); + await until(() => f.calls.some((c) => c.verb === "stop")); + expect(f.calls.find((c) => c.verb === "user-prompt").payload.timestamp) + .toBe("2026-10-25T09:26:19.100Z"); + expect(f.calls.find((c) => c.verb === "stop").payload) + .toMatchObject({ timestamp: "2026-10-25T09:26:19.589Z", turn_duration_ms: 489 }); + f.event("session.deleted", { sessionID: "native-time" }, undefined, 1_792_920_380_123); + await until(() => f.calls.some((c) => c.verb === "session-end")); + expect(f.calls.at(-1).payload.timestamp).toBe("2026-10-25T09:26:20.123Z"); + await f.cleanup?.(); + }); + + test("v2 captures prompt time before its asynchronous model lookup", async () => { + const source = 1_792_920_379_589; + let now = source; + spyOn(Date, "now").mockImplementation(() => now); + let release!: () => void; + const gate = new Promise((resolve) => { release = resolve; }); + const f = await fixtureV2(); + f.ctx.session.get = async () => { + await gate; + return { model: { id: "model", providerID: "provider" } }; + }; + const prompt = f.prompt("Capture before awaiting"); + now += 60_000; + release(); + await prompt; + expect(f.calls.find((c) => c.verb === "user-prompt").payload.timestamp) + .toBe("2026-10-25T09:26:19.589Z"); + await f.cleanup?.(); + }); + + test("v2 retries a failed Stop with its original source timestamp", async () => { + let fail = true; + const f = await fixtureV2(async (verb) => { + if (verb === "stop" && fail) { + fail = false; + return { exitCode: 1, stderr: "owner unavailable" }; + } + return { exitCode: 0, stderr: "" }; + }); + f.event("session.inbox.enqueued", { sessionID: "retry-time" }, { directory: f.root }); + f.event("session.execution.started", { sessionID: "retry-time" }, undefined, 1_792_920_379_100); + f.event("session.execution.succeeded", { sessionID: "retry-time" }, undefined, 1_792_920_379_589); + await until(() => f.calls.some((c) => c.verb === "stop")); + f.event("session.idle", { sessionID: "retry-time" }, undefined, 1_792_920_381_000); + await until(() => f.calls.filter((c) => c.verb === "stop").length === 2); + for (const stop of f.calls.filter((c) => c.verb === "stop")) { + expect(stop.payload).toMatchObject({ + timestamp: "2026-10-25T09:26:19.589Z", turn_duration_ms: 489, + }); + } + await f.cleanup?.(); + }); + + test("v2 captures tool receipt times before a blocked queue", async () => { + let now = 1_792_920_379_100; + spyOn(Date, "now").mockImplementation(() => now); + let release!: () => void; + const gate = new Promise((resolve) => { release = resolve; }); + const f = await fixtureV2(async (verb) => { + if (verb === "session-start") await gate; + return { exitCode: 0, stderr: "" }; + }); + const input = { sessionID: "tool-time", id: "tool", tool: "read", input: {} }; + const before = f.toolHooks["execute.before"](input); + now = 1_792_920_379_589; + const after = f.toolHooks["execute.after"]({ ...input, status: "completed" }); + now += 60_000; + release(); + await Promise.all([before, after]); + expect(f.calls.find((c) => c.verb === "before-tool").payload.timestamp) + .toBe("2026-10-25T09:26:19.100Z"); + expect(f.calls.find((c) => c.verb === "after-tool").payload) + .toMatchObject({ timestamp: "2026-10-25T09:26:19.589Z", duration: 489 }); + await f.cleanup?.(); + }); + + test("v2 missing or invalid native times fall back to receipt time", async () => { + const f = await fixtureV2(); + for (const created of [undefined, null, NaN, Infinity, "invalid"]) { + const sid = `fallback-${String(created)}`; + const before = Date.now(); + f.event("session.inbox.enqueued", { sessionID: sid }, { directory: f.root }); + f.bus.push({ type: "session.execution.started", data: { sessionID: sid }, created }); + await until(() => f.calls.some((c) => c.verb === "user-prompt" && c.payload.session_id === sid)); + const call = f.calls.find((c) => c.verb === "user-prompt" && c.payload.session_id === sid); + const captured = Date.parse(call.payload.timestamp); + expect(captured).toBeGreaterThanOrEqual(before); + expect(captured).toBeLessThanOrEqual(Date.now()); + } + await f.cleanup?.(); + }); + + test("v2 preserves skewed source timestamps without negative durations", async () => { + const f = await fixtureV2(); + f.event("session.inbox.enqueued", { sessionID: "skew-time" }, { directory: f.root }); + f.event("session.execution.started", { sessionID: "skew-time" }, undefined, 1_792_920_379_589); + f.event("session.execution.succeeded", { sessionID: "skew-time" }, undefined, 1_792_920_379_100); + await until(() => f.calls.some((c) => c.verb === "stop")); + expect(f.calls.find((c) => c.verb === "stop").payload) + .toMatchObject({ timestamp: "2026-10-25T09:26:19.100Z", turn_duration_ms: 0 }); + await f.cleanup?.(); + }); + + test("v2 step activation preserves explicit epoch milliseconds without unit inference", async () => { + const f = await fixtureV2(); + f.event("session.inbox.enqueued", { sessionID: "epoch-time" }, { directory: f.root }); + f.event("session.step.started", { sessionID: "epoch-time" }, undefined, 0); + f.event("session.execution.succeeded", { sessionID: "epoch-time" }, undefined, 489); + await until(() => f.calls.some((c) => c.verb === "stop")); + expect(f.calls.find((c) => c.verb === "user-prompt").payload.timestamp) + .toBe("1970-01-01T00:00:00.000Z"); + expect(f.calls.find((c) => c.verb === "stop").payload) + .toMatchObject({ timestamp: "1970-01-01T00:00:00.489Z", turn_duration_ms: 489 }); + await f.cleanup?.(); + }); + test("records a full v2 turn with tools, reasoning, tokens and response", async () => { const f = await fixtureV2(); await f.prompt("Create HELLO.md with hello");