Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

wip(capture): session speaker sidecar module (#8064)

garrytanf133bbfe5a22
diff --git a/src/core/context/corpus-segments.ts b/src/core/context/corpus-segments.ts
index 1c0c905970..070c64715a 100644
--- a/src/core/context/corpus-segments.ts
+++ b/src/core/context/corpus-segments.ts
@@ -134,6 +134,13 @@ export function seatFileName(sessionId: string): string {
return `${safeIdComponent(sessionId)}${SEAT_SIDECAR_SUFFIX}`;
}
+/** #8064 per-session speaker sidecar (context/session-speaker.ts owns its content): present only for agent-launched sessions. */
+export const SPEAKER_SIDECAR_SUFFIX = '.speaker.json';
+
+export function speakerFileName(sessionId: string): string {
+ return `${safeIdComponent(sessionId)}${SPEAKER_SIDECAR_SUFFIX}`;
+}
+
/** #6268: the per-session source record in the spool (context/corpus-source.ts owns its content and lock). */
export const SESSION_SOURCE_SUFFIX = '.source.json';
export const SESSION_SOURCE_LOCK_SUFFIX = '.source.lock';
@@ -853,7 +860,7 @@ export function gcCorpusArtifacts(
for (const name of names) {
const p = join(dir, name);
try {
- const perSession = [SEAT_SIDECAR_SUFFIX, SESSION_SOURCE_SUFFIX].find((suffix) => name.endsWith(suffix));
+ const perSession = [SEAT_SIDECAR_SUFFIX, SPEAKER_SIDECAR_SUFFIX, SESSION_SOURCE_SUFFIX].find((suffix) => name.endsWith(suffix));
if (perSession) {
if (!liveSessions.has(name.slice(0, -perSession.length)) && statSync(p).mtimeMs < Date.now() - SEAT_ORPHAN_GRACE_MS) {
rmSync(p, { force: true });
diff --git a/src/core/context/session-speaker.ts b/src/core/context/session-speaker.ts
new file mode 100644
index 0000000000..530126c5cc
--- /dev/null
+++ b/src/core/context/session-speaker.ts
@@ -0,0 +1,156 @@
+/**
+ * session-speaker.ts: who wrote a captured session's user turns (#8064).
+ *
+ * An orchestrator that launches headless workers (`claude -p`, `codex exec`)
+ * on the owner's account renders each worker's first user turn from a
+ * template. Without a marker the capture lanes save that brief as the
+ * owner's own preferences. ENGINE-FREE (pure fs + process reads), usable from
+ * the hook command.
+ *
+ * `GBRAIN_SESSION_AGENT`, set by the launcher on the worker's environment:
+ * - a label (seat-label charset): the user turns are agent <label>'s. The
+ * session is banked; extraction attributes them to that agent, never to
+ * the owner.
+ * - `off`: nothing from the session is banked.
+ * - `owner`: the turns are the owner's; automatic detection is skipped.
+ * - anything else: agent `agent`, reported as `speaker_label_invalid`.
+ * Unset: detection (`detectAgentLaunched`) — a headless harness process
+ * (claude `-p`/`--print`, codex `exec`) with a claude or codex process
+ * among its ancestors. Headless alone is not enough: the owner scripting
+ * `claude -p` is still the owner.
+ *
+ * Sidecar `<sessionId>.speaker.json` (0600, tmp+rename) beside the corpus
+ * files, written BEFORE any corpus file of the session; the first record is
+ * kept. Its absence means the owner.
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { speakerFileName } from './corpus-segments.ts';
+
+export const SESSION_AGENT_ENV = 'GBRAIN_SESSION_AGENT';
+/** Principal recorded for a session detection marked as agent-launched. */
+export const DETECTED_PRINCIPAL = 'agent-launched';
+const LABEL_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const RESERVED = new Set(['off', 'owner']);
+const ANCESTRY_MAX_DEPTH = 12;
+const ANCESTRY_BUDGET_MS = 300;
+
+export type SpeakerSource = 'env' | 'detected';
+export type SessionSpeaker =
+ | { kind: 'owner' }
+ | { kind: 'skip' }
+ | { kind: 'agent'; principal: string; source: SpeakerSource; invalid?: boolean };
+
+export interface SpeakerSidecar {
+ version: 1;
+ principal: string;
+ source: SpeakerSource;
+ harness: string;
+ first_seen: string;
+}
+
+/** One process in the hook's ancestry, nearest first: its pid and argv. */
+export interface AncestorProcess { pid: number; args: string[] }
+
+type Env = Record<string, string | undefined>;
+
+const base = (s: string) => s.split(/[\\/]/).pop() ?? s;
+
+/** Which harness an argv belongs to (claude-code native binary or node entry; codex), or null. */
+export function harnessOfArgs(args: readonly string[]): 'claude' | 'codex' | null {
+ for (const a of args.slice(0, 2)) {
+ const b = base(a).toLowerCase();
+ if (/^claude(\.exe)?$/.test(b) || a.includes('@anthropic-ai/claude-code')) return 'claude';
+ if (/^codex(\.exe)?$/.test(b) || a.includes('@openai/codex')) return 'codex';
+ }
+ return null;
+}
+
+function headless(harness: 'claude' | 'codex', args: readonly string[]): boolean {
+ if (harness === 'claude') return args.some((a) => a === '-p' || a === '--print' || a.startsWith('--print='));
+ return args.slice(1).some((a) => a === 'exec' || a === 'e');
+}
+
+/**
+ * True when the nearest harness process in `ancestry` (nearest first) runs
+ * headless and another claude or codex process sits above it.
+ */
+export function detectAgentLaunched(ancestry: readonly AncestorProcess[]): boolean {
+ const at = ancestry.findIndex((p) => harnessOfArgs(p.args) !== null);
+ if (at < 0) return false;
+ const harness = harnessOfArgs(ancestry[at].args)!;
+ if (!headless(harness, ancestry[at].args)) return false;
+ return ancestry.slice(at + 1).some((p) => harnessOfArgs(p.args) !== null);
+}
+
+function linuxParent(pid: number): AncestorProcess & { ppid: number } | null {
+ const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+ const ppid = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
+ const args = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+ return Number.isInteger(ppid) ? { pid, ppid, args } : null;
+}
+
+function psParent(pid: number, timeout: number): AncestorProcess & { ppid: number } | null {
+ const r = spawnSync('ps', ['-o', 'ppid=,args=', '-p', String(pid)], { encoding: 'utf8', timeout });
+ const m = /^\s*(\d+)\s+(.*)$/.exec((r.stdout ?? '').trim());
+ return m ? { pid, ppid: Number(m[1]), args: m[2].split(/\s+/) } : null;
+}
+
+/** The hook's ancestors, nearest first, bounded in depth and time; a read failure ends the walk. */
+export function readProcessAncestry(startPid: number = process.ppid): AncestorProcess[] {
+ const out: AncestorProcess[] = [];
+ const deadline = Date.now() + ANCESTRY_BUDGET_MS;
+ const procfs = existsSync('/proc/self/stat');
+ let pid = startPid;
+ try {
+ while (pid > 1 && out.length < ANCESTRY_MAX_DEPTH && Date.now() < deadline) {
+ const p = procfs ? linuxParent(pid) : psParent(pid, Math.max(1, deadline - Date.now()));
+ if (!p) break;
+ out.push({ pid: p.pid, args: p.args });
+ pid = p.ppid;
+ }
+ } catch { /* unreadable: what was read stands */ }
+ return out;
+}
+
+/** The session's speaker from the launcher env, else detection over the (lazily read) ancestry. */
+export function resolveSessionSpeaker(opts: { env: Env; ancestry?: () => readonly AncestorProcess[] }): SessionSpeaker {
+ const raw = opts.env[SESSION_AGENT_ENV]?.trim().toLowerCase();
+ if (raw) {
+ if (raw === 'off') return { kind: 'skip' };
+ if (raw === 'owner') return { kind: 'owner' };
+ return LABEL_RE.test(raw) && !RESERVED.has(raw)
+ ? { kind: 'agent', principal: raw, source: 'env' }
+ : { kind: 'agent', principal: 'agent', source: 'env', invalid: true };
+ }
+ const ancestry = (opts.ancestry ?? readProcessAncestry)();
+ return detectAgentLaunched(ancestry) ? { kind: 'agent', principal: DETECTED_PRINCIPAL, source: 'detected' } : { kind: 'owner' };
+}
+
+/** The recorded sidecar, or null when absent or not a valid v1 record (absent means the owner). */
+export function readSpeakerSidecar(dir: string, sessionId: string): SpeakerSidecar | null {
+ try {
+ const parsed = JSON.parse(readFileSync(join(dir, speakerFileName(sessionId)), 'utf8')) as Partial<SpeakerSidecar>;
+ return parsed?.version === 1 && typeof parsed.principal === 'string' && LABEL_RE.test(parsed.principal)
+ && (parsed.source === 'env' || parsed.source === 'detected') ? (parsed as SpeakerSidecar) : null;
+ } catch {
+ return null;
+ }
+}
+
+/** Record an agent speaker unless one is recorded. Throws on a write failure (the caller then banks nothing). */
+export function writeSpeakerSidecar(dir: string, sessionId: string, speaker: { principal: string; source: SpeakerSource }, harness: string): void {
+ if (readSpeakerSidecar(dir, sessionId)) return;
+ const record: SpeakerSidecar = { version: 1, principal: speaker.principal, source: speaker.source, harness, first_seen: new Date().toISOString() };
+ const file = join(dir, speakerFileName(sessionId));
+ const tmp = `${file}.tmp-${process.pid}`;
+ writeFileSync(tmp, JSON.stringify(record) + '\n', { mode: 0o600 });
+ renameSync(tmp, file);
+}
+
+/** The context note a fact from an agent session carries. */
+export function speakerContextNote(principal: string): string {
+ return `speaker: agent ${principal}, not the owner`;
+}