doer-agent 0.3.5 → 0.4.0

package/dist/agent.js

@@ -9,6 +9,8 @@ const DEFAULT_SERVER_BASE_URL = "https://doer.cranix.net";
 const AGENT_MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_PROJECT_DIR = path.join(AGENT_MODULE_DIR, "..");
 const AGENT_PACKAGE_JSON_PATH = path.join(AGENT_PROJECT_DIR, "package.json");
+const HEARTBEAT_INTERVAL_MS = 5_000;
+const HEARTBEAT_FAILURE_THRESHOLD = 3;
 let activeTaskLogContext = null;
 let workspaceRootOverride = null;
 const fsRpcCodec = StringCodec();
@@ -18,6 +20,7 @@ const codexAuthRpcCodec = StringCodec();
 const settingsRpcCodec = StringCodec();
 const gitRpcCodec = StringCodec();
 const skillRpcCodec = StringCodec();
+const runEventsCodec = StringCodec();
 const retainedRuns = new Map();
 const activeSessionWatchers = new Map();
 const sessionLineIndexCache = new Map();
@@ -30,6 +33,9 @@ function sanitizeUserId(userId) {
 function buildAgentRunRpcSubject(userId, agentId) {
     return `doer.agent.run.rpc.${sanitizeUserId(userId)}.${agentId.trim()}`;
 }
+function buildAgentRunEventsSubject(userId, agentId) {
+    return `doer.agent.run.events.${sanitizeUserId(userId)}.${agentId.trim()}`;
+}
 function buildAgentSessionRpcSubject(userId, agentId) {
     return `doer.agent.session.rpc.${sanitizeUserId(userId)}.${agentId.trim()}`;
 }
@@ -514,7 +520,7 @@ async function resolveRunStartLockPath(args) {
     if (typeof args.sessionId === "string" && args.sessionId.trim()) {
         return path.join(dir, `session__${sanitizeRunLockSegment(args.sessionId)}.lock`);
     }
-    return path.join(dir, `run__${sanitizeRunLockSegment(args.runId)}.lock`);
+    return path.join(dir, "pending_new_session.lock");
 }
 async function claimRunStartSlot(args) {
     const lockPath = await resolveRunStartLockPath(args);
@@ -601,10 +607,13 @@ function resolveAgentSettingsDir() {
 function resolveAgentSettingsFilePath() {
     return path.join(resolveAgentSettingsDir(), "config.json");
 }
+function resolveAgentModelInstructionsFilePath() {
+    return path.join(resolveAgentSettingsDir(), "model-instructions.md");
+}
 function createDefaultAgentSettingsConfig() {
     return {
         general: {
-            firstTurnPrompt: null,
+            personality: "pragmatic",
         },
         codex: {
             model: "gpt-5.4",
@@ -667,6 +676,9 @@ function normalizeNullableString(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed : null;
 }
+function normalizeCodexPersonality(value, fallback) {
+    return value === "friendly" || value === "pragmatic" ? value : fallback;
+}
 function normalizeAgentSettingsConfig(value, fallback) {
     const base = fallback ?? createDefaultAgentSettingsConfig();
     const raw = value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -681,7 +693,7 @@ function normalizeAgentSettingsConfig(value, fallback) {
     const figma = raw.figma && typeof raw.figma === "object" ? raw.figma : {};
     return {
         general: {
-            firstTurnPrompt: normalizeNullableString(general.firstTurnPrompt) ?? base.general.firstTurnPrompt,
+            personality: normalizeCodexPersonality(general.personality, base.general.personality),
         },
         codex: {
             model: typeof codex.model === "string" && codex.model.trim() ? codex.model.trim() : base.codex.model,
@@ -753,6 +765,20 @@ async function writeAgentSettingsConfig(config) {
     await mkdir(dir, { recursive: true });
     await writeFile(resolveAgentSettingsFilePath(), `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
+async function readAgentModelInstructions() {
+    const raw = await readFile(resolveAgentModelInstructionsFilePath(), "utf8").catch(() => "");
+    return raw.trim() ? raw : null;
+}
+async function writeAgentModelInstructions(value) {
+    const filePath = resolveAgentModelInstructionsFilePath();
+    const nextValue = typeof value === "string" ? value.trim() : "";
+    if (!nextValue) {
+        await unlink(filePath).catch(() => undefined);
+        return;
+    }
+    await mkdir(resolveAgentSettingsDir(), { recursive: true });
+    await writeFile(filePath, value ?? "", "utf8");
+}
 function maskSecretPreview(secret) {
     if (secret.length <= 6) {
         return `${secret.slice(0, 1)}***${secret.slice(-1)}`;
@@ -765,7 +791,7 @@ function toMaskedSecret(value) {
     }
     return { has: true, masked: maskSecretPreview(value), length: value.length };
 }
-function toAgentSettingsPublic(config) {
+async function toAgentSettingsPublic(config) {
     const realtimeKey = toMaskedSecret(config.realtime.apiKey);
     const gitOauth = toMaskedSecret(config.git.oauthToken);
     const awsSecret = toMaskedSecret(config.aws.secretAccessKey);
@@ -774,9 +800,11 @@ function toAgentSettingsPublic(config) {
     const notionToken = toMaskedSecret(config.notion.apiToken);
     const slackToken = toMaskedSecret(config.slack.botToken);
     const figmaToken = toMaskedSecret(config.figma.apiToken);
+    const customInstructions = await readAgentModelInstructions();
     return {
         general: {
-            firstTurnPrompt: config.general.firstTurnPrompt,
+            personality: config.general.personality,
+            customInstructions,
         },
         codex: {
             model: config.codex.model,
@@ -868,7 +896,7 @@ function normalizeAgentSettingsPatch(value) {
         assignNested(section, key, raw[flatKey]);
         delete patch[flatKey];
     };
-    move("firstTurnPrompt", "general", "firstTurnPrompt");
+    move("personality", "general", "personality");
     move("codexModel", "codex", "model");
     move("codexAuthMode", "codex", "authMode");
     move("realtimeModel", "realtime", "model");
@@ -976,34 +1004,136 @@ function cloneRunTask(task, _sinceSeq) {
         ...task,
     };
 }
-function extractCodexSessionMetadata(value) {
+function buildImmediateRunChangedEvent(task) {
+    return {
+        type: "run.changed",
+        agentId: task.agentId,
+        sessionId: task.sessionId,
+        filePath: task.sessionFilePath,
+        runId: task.id,
+        updatedAt: task.updatedAt,
+        status: task.status,
+        cancelRequested: task.cancelRequested,
+        resultExitCode: task.resultExitCode,
+        resultSignal: task.resultSignal,
+        error: task.error,
+        finishedAt: task.finishedAt,
+    };
+}
+function publishImmediateRunChangedEvent(args) {
+    args.nc.publish(buildAgentRunEventsSubject(args.userId, args.task.agentId), runEventsCodec.encode(JSON.stringify(buildImmediateRunChangedEvent(args.task))));
+}
+async function findSessionFilePathBySessionId(sessionId) {
+    const targetSessionId = sessionId.trim();
+    if (!targetSessionId) {
+        return null;
+    }
+    let sessionsRootStat;
     try {
-        const parsed = JSON.parse(value);
-        const lineType = typeof parsed.type === "string" ? parsed.type : "";
-        if (!parsed.payload || typeof parsed.payload !== "object" || Array.isArray(parsed.payload)) {
-            return { sessionId: null, sessionFilePath: null };
-        }
-        const payload = parsed.payload;
-        const sessionIdCandidate = typeof payload.sessionId === "string" && payload.sessionId.trim()
-            ? payload.sessionId.trim()
-            : typeof payload.session_id === "string" && payload.session_id.trim()
-                ? payload.session_id.trim()
-                : typeof payload.id === "string" && payload.id.trim() && (lineType === "session_meta" || lineType === "session.started")
-                    ? payload.id.trim()
-                    : null;
-        const filePathCandidate = typeof payload.rollout_path === "string" && payload.rollout_path.trim()
-            ? payload.rollout_path.trim()
-            : typeof payload.filePath === "string" && payload.filePath.trim()
-                ? payload.filePath.trim()
-                : null;
-        return {
-            sessionId: sessionIdCandidate,
-            sessionFilePath: filePathCandidate,
-        };
+        sessionsRootStat = await stat(getSessionsRootPath());
     }
     catch {
-        return { sessionId: null, sessionFilePath: null };
+        return null;
     }
+    if (!sessionsRootStat.isDirectory()) {
+        return null;
+    }
+    const files = await collectSessionJsonlFiles(getSessionsRootPath());
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs || a.filePath.localeCompare(b.filePath));
+    for (const file of files) {
+        let fileHandle = null;
+        try {
+            fileHandle = await open(file.filePath, "r");
+            const entryStat = await fileHandle.stat();
+            const firstLine = await readFirstLine(fileHandle, entryStat.size);
+            if (!firstLine) {
+                continue;
+            }
+            const parsed = JSON.parse(firstLine);
+            const candidateMeta = parsed && parsed.type === "session_meta" && isObjectRecord(parsed.payload)
+                ? parsed.payload
+                : isObjectRecord(parsed.session_meta)
+                    ? parsed.session_meta
+                    : isObjectRecord(parsed.sessionMeta)
+                        ? parsed.sessionMeta
+                        : isObjectRecord(parsed.meta)
+                            ? parsed.meta
+                            : isObjectRecord(parsed.payload)
+                                ? parsed.payload
+                                : parsed;
+            const candidateId = pickSessionString(candidateMeta.sessionId, candidateMeta.session_id, candidateMeta.id);
+            if (candidateId === targetSessionId) {
+                return file.filePath;
+            }
+        }
+        catch {
+            // ignore malformed session files
+        }
+        finally {
+            await fileHandle?.close().catch(() => undefined);
+        }
+    }
+    return null;
+}
+async function readSessionIdFromSessionFile(filePath) {
+    let fileHandle = null;
+    try {
+        fileHandle = await open(filePath, "r");
+        const entryStat = await fileHandle.stat();
+        const firstLine = await readFirstLine(fileHandle, entryStat.size);
+        if (!firstLine) {
+            return null;
+        }
+        const parsed = JSON.parse(firstLine);
+        const candidateMeta = parsed && parsed.type === "session_meta" && isObjectRecord(parsed.payload)
+            ? parsed.payload
+            : isObjectRecord(parsed.session_meta)
+                ? parsed.session_meta
+                : isObjectRecord(parsed.sessionMeta)
+                    ? parsed.sessionMeta
+                    : isObjectRecord(parsed.meta)
+                        ? parsed.meta
+                        : isObjectRecord(parsed.payload)
+                            ? parsed.payload
+                            : parsed;
+        return pickSessionString(candidateMeta.sessionId, candidateMeta.session_id, candidateMeta.id);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await fileHandle?.close().catch(() => undefined);
+    }
+}
+async function detectPendingRunSession(knownFilePaths) {
+    const sessionsRoot = getSessionsRootPath();
+    let sessionsRootStat;
+    try {
+        sessionsRootStat = await stat(sessionsRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!sessionsRootStat.isDirectory()) {
+        return null;
+    }
+    const files = await collectSessionJsonlFiles(sessionsRoot);
+    files.sort((a, b) => a.mtimeMs - b.mtimeMs || a.filePath.localeCompare(b.filePath));
+    for (const file of files) {
+        if (knownFilePaths.has(file.filePath)) {
+            continue;
+        }
+        const sessionId = await readSessionIdFromSessionFile(file.filePath);
+        if (!sessionId) {
+            continue;
+        }
+        knownFilePaths.add(file.filePath);
+        return {
+            sessionId,
+            sessionFilePath: file.filePath,
+        };
+    }
+    return null;
 }
 async function updateRunSessionMetadata(task, metadata) {
     let changed = false;
@@ -1016,11 +1146,25 @@ async function updateRunSessionMetadata(task, metadata) {
         task.sessionFilePath = metadata.sessionFilePath.trim();
         changed = true;
     }
+    if (!task.sessionFilePath && task.sessionId) {
+        const resolvedSessionFilePath = await findSessionFilePathBySessionId(task.sessionId).catch(() => null);
+        if (resolvedSessionFilePath) {
+            task.sessionFilePath = resolvedSessionFilePath;
+            changed = true;
+        }
+    }
     if (!changed) {
         return;
     }
     task.updatedAt = formatLocalTimestamp();
     await persistRunTask(task).catch(() => undefined);
+    if (metadata.nc) {
+        publishImmediateRunChangedEvent({
+            nc: metadata.nc,
+            userId: task.userId,
+            task,
+        });
+    }
     if (!previousSessionId && task.sessionId) {
         await updateRunStartSlotSession({
             runId: task.id,
@@ -1132,46 +1276,60 @@ async function startManagedRun(args) {
         startedAt: now,
         finishedAt: null,
     };
-    let stdoutBuffer = "";
-    const recordChunk = (stream, chunk) => {
-        writeRunStream(task.id, stream, chunk);
-        if (stream !== "stdout" || (task.sessionId && task.sessionFilePath)) {
+    let pendingSessionPollClosed = false;
+    let pendingSessionPollTimer = null;
+    const knownPendingSessionFiles = new Set();
+    const stopPendingSessionPoll = () => {
+        pendingSessionPollClosed = true;
+        if (pendingSessionPollTimer) {
+            clearInterval(pendingSessionPollTimer);
+            pendingSessionPollTimer = null;
+        }
+    };
+    const pollPendingSession = async () => {
+        if (pendingSessionPollClosed || task.sessionId) {
+            stopPendingSessionPoll();
             return;
         }
-        stdoutBuffer += chunk;
-        const lines = stdoutBuffer.split(/\r?\n/);
-        stdoutBuffer = lines.pop() ?? "";
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed) {
-                continue;
-            }
-            const metadata = extractCodexSessionMetadata(trimmed);
-            if (metadata.sessionId || metadata.sessionFilePath) {
-                void updateRunSessionMetadata(task, metadata);
-            }
+        const detected = await detectPendingRunSession(knownPendingSessionFiles).catch(() => null);
+        if (!detected) {
+            return;
+        }
+        await updateRunSessionMetadata(task, {
+            sessionId: detected.sessionId,
+            sessionFilePath: detected.sessionFilePath,
+            nc: args.nc,
+        }).catch(() => undefined);
+        if (task.sessionId) {
+            stopPendingSessionPoll();
         }
     };
-    child.stdout.on("data", (chunk) => recordChunk("stdout", chunk));
-    child.stderr.on("data", (chunk) => recordChunk("stderr", chunk));
+    if (!task.sessionId) {
+        const existingFiles = await collectSessionJsonlFiles(getSessionsRootPath()).catch(() => []);
+        for (const file of existingFiles) {
+            knownPendingSessionFiles.add(file.filePath);
+        }
+        pendingSessionPollTimer = setInterval(() => {
+            void pollPendingSession();
+        }, 1000);
+    }
+    child.stdout.on("data", (chunk) => writeRunStream(task.id, "stdout", chunk));
+    child.stderr.on("data", (chunk) => writeRunStream(task.id, "stderr", chunk));
     child.once("error", (error) => {
+        stopPendingSessionPoll();
         const message = error instanceof Error ? error.message : String(error);
         task.status = "failed";
         task.error = message;
         task.finishedAt = formatLocalTimestamp();
         persistRetainedRun(task);
+        publishImmediateRunChangedEvent({ nc: args.nc, userId: task.userId, task });
         void removeRunTask(task.id).catch(() => undefined);
         void releaseRunStartSlot({ runId: task.id, sessionId: task.sessionId }).catch(() => undefined);
         void prepared.codexAuthCleanup().catch(() => undefined);
         writeRunStatus(task.id, `failed error=${message}`);
     });
     child.once("close", async (code, signal) => {
-        if (stdoutBuffer.trim() && (!task.sessionId || !task.sessionFilePath)) {
-            const metadata = extractCodexSessionMetadata(stdoutBuffer.trim());
-            if (metadata.sessionId || metadata.sessionFilePath) {
-                void updateRunSessionMetadata(task, metadata);
-            }
-        }
+        stopPendingSessionPoll();
         const latest = await getStoredRun(task.id).catch(() => null);
         if (latest?.cancelRequested) {
             task.cancelRequested = true;
@@ -1182,6 +1340,7 @@ async function startManagedRun(args) {
         task.status = task.cancelRequested ? "canceled" : (task.resultExitCode ?? 1) === 0 ? "completed" : "failed";
         task.error = task.status === "failed" ? `Command exited with code ${task.resultExitCode ?? "null"}` : null;
         persistRetainedRun(task);
+        publishImmediateRunChangedEvent({ nc: args.nc, userId: task.userId, task });
         void removeRunTask(task.id).catch(() => undefined);
         void releaseRunStartSlot({ runId: task.id, sessionId: task.sessionId }).catch(() => undefined);
         void prepared.codexAuthCleanup().catch(() => undefined);
@@ -1189,7 +1348,11 @@ async function startManagedRun(args) {
     });
     persistRetainedRun(task);
     void persistRunTask(task).catch(() => undefined);
+    publishImmediateRunChangedEvent({ nc: args.nc, userId: task.userId, task });
     writeRunStatus(task.id, `started requestId=${args.requestId} cwd=${prepared.taskWorkspace}`);
+    if (!task.sessionId) {
+        void pollPendingSession();
+    }
     return cloneRunTask(task);
 }
 function shellSingleQuote(value) {
@@ -1202,12 +1365,22 @@ function normalizeCodexModel(value) {
     const normalized = typeof value === "string" ? value.trim() : "";
     return normalized || "gpt-5.4";
 }
+function toTomlStringLiteral(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
 function buildManagedCodexArgs(args) {
     const promptArgs = ["--", args.prompt];
     const fixedArgs = ["--dangerously-bypass-approvals-and-sandbox"];
+    const configArgs = [
+        ...(args.personality ? ["--config", `personality=${toTomlStringLiteral(args.personality)}`] : []),
+        ...(args.modelInstructionsFile
+            ? ["--config", `model_instructions_file=${toTomlStringLiteral(args.modelInstructionsFile)}`]
+            : []),
+    ];
     const imageArgs = args.imagePaths.flatMap((imagePath) => ["--image", imagePath]);
     return [
         ...fixedArgs,
+        ...configArgs,
         "--model",
         args.model,
         ...(args.sessionId
@@ -1578,6 +1751,14 @@ async function handleSettingsRpcMessage(args) {
         const next = request.action === "update" ? normalizeAgentSettingsConfig(request.patch, existing) : existing;
         if (request.action === "update") {
             await writeAgentSettingsConfig(next);
+            const customInstructions = typeof request.patch.customInstructions === "string"
+                ? request.patch.customInstructions
+                : request.patch.customInstructions === null
+                    ? null
+                    : undefined;
+            if (customInstructions !== undefined) {
+                await writeAgentModelInstructions(customInstructions);
+            }
         }
         else if (request.defaults) {
             const filePath = resolveAgentSettingsFilePath();
@@ -1592,7 +1773,7 @@ async function handleSettingsRpcMessage(args) {
             payload: {
                 requestId,
                 ok: true,
-                settings: toAgentSettingsPublic(next),
+                settings: await toAgentSettingsPublic(next),
             },
         });
     }
@@ -2198,18 +2379,23 @@ async function handleRunRpcMessage(args) {
             const runId = request.runId ?? requestId;
             await claimRunStartSlot({ runId, sessionId: request.sessionId });
             try {
+                const localAgentSettings = await readAgentSettingsConfig(null);
+                const customInstructions = await readAgentModelInstructions();
                 const task = await startManagedRun({
                     requestId,
                     runId,
                     serverBaseUrl: args.serverBaseUrl,
                     userId: args.userId,
                     agentId: args.agentId,
+                    nc: args.jetstream.nc,
                     sessionId: request.sessionId,
                     codexArgs: buildManagedCodexArgs({
                         prompt: request.prompt ?? "",
                         imagePaths: request.imagePaths,
                         sessionId: request.sessionId,
                         model: request.model,
+                        personality: localAgentSettings.general.personality,
+                        modelInstructionsFile: customInstructions ? resolveAgentModelInstructionsFilePath() : null,
                     }),
                     cwd: request.cwd,
                     runtimeEnvPatch: request.runtimeEnvPatch,
@@ -2253,6 +2439,7 @@ async function handleRunRpcMessage(args) {
             target.cancelRequested = true;
             target.updatedAt = formatLocalTimestamp();
             await persistRunTask(target);
+            publishImmediateRunChangedEvent({ nc: args.jetstream.nc, userId: target.userId, task: target });
             writeRunStatus(target.id, `cancel requested pid=${target.processPid}`);
             sendSignalToPid(target.processPid, "SIGINT");
             const task = cloneRunTask(target);
@@ -3749,7 +3936,8 @@ function persistEventOrFatal(args) {
         }
     })();
 }
-async function heartbeatAgent(args) {
+async function heartbeatAgentSession(args) {
+    await args.nc.flush();
     await postJson(`${args.serverBaseUrl}/api/agent/heartbeat`, {
         userId: args.userId,
         agentToken: args.agentToken,
@@ -4189,23 +4377,45 @@ async function main() {
         else {
             writeAgentInfraError(`nats session restored agentId=${initialAgentId} servers=${jetstream.servers.join(",")} at=${formatLocalTimestamp()}`);
         }
-        let heartbeatHealthy = null;
+        let heartbeatFailures = 0;
+        let heartbeatInFlight = false;
+        let sessionInvalidated = false;
+        const invalidateAgentSession = (reason) => {
+            if (sessionInvalidated) {
+                return;
+            }
+            sessionInvalidated = true;
+            writeAgentInfraError(`closing nats session: ${reason}`);
+            void jetstream.nc.close().catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                writeAgentInfraError(`failed to close nats session: ${message}`);
+            });
+        };
         const heartbeatTimer = setInterval(() => {
-            void heartbeatAgent({ serverBaseUrl, userId, agentToken })
+            if (heartbeatInFlight || sessionInvalidated) {
+                return;
+            }
+            heartbeatInFlight = true;
+            void heartbeatAgentSession({ nc: jetstream.nc, serverBaseUrl, userId, agentToken })
                 .then(() => {
-                if (heartbeatHealthy === false) {
+                heartbeatInFlight = false;
+                if (heartbeatFailures > 0) {
                     writeAgentInfraError(`heartbeat reconnected at=${formatLocalTimestamp()}`);
                 }
-                heartbeatHealthy = true;
+                heartbeatFailures = 0;
             })
                 .catch((error) => {
+                heartbeatInFlight = false;
                 const message = error instanceof Error ? error.message : String(error);
-                if (heartbeatHealthy !== false) {
-                    writeAgentInfraError(`heartbeat failed: ${message}`);
+                heartbeatFailures += 1;
+                if (heartbeatFailures > 1) {
+                    writeAgentInfraError(`heartbeat failed: ${message} (count=${heartbeatFailures}/${HEARTBEAT_FAILURE_THRESHOLD})`);
+                }
+                if (heartbeatFailures >= HEARTBEAT_FAILURE_THRESHOLD) {
+                    invalidateAgentSession(`heartbeat failure threshold reached at=${formatLocalTimestamp()}`);
                 }
-                heartbeatHealthy = false;
             });
-        }, 10_000);
+        }, HEARTBEAT_INTERVAL_MS);
         subscribeToFsRpc({
             jetstream,
             serverBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doer-agent",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Reverse-polling agent runtime for doer",
   "type": "module",
   "main": "dist/agent.js",