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.tsindex 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.tsnew file mode 100644index 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`;+}