@qearlyao/familiar 0.2.5 → 0.3.0

package/dist/agent.js

@@ -1,257 +1,24 @@
-import { createHash } from "node:crypto";
-import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
 import { Agent } from "@earendil-works/pi-agent-core";
 import { streamSimple } from "@earendil-works/pi-ai";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@earendil-works/pi-coding-agent";
 import { setAddedModelsPath } from "./added-models.js";
-import { createBrowserTools } from "./browser-tools.js";
+import { normalizeProviderPayload } from "./agent/payload-normalizers.js";
+import { assertModelAllowed, deriveSessionId, formatModel, getLastAssistantText, getRequestApiKey, installProviderDebugFilter, isNoisyProviderDebug, logUsage, resolveModelName, userTextMessage, } from "./agent/session-helpers.js";
+import { createFamiliarTools, setReferenceAttachments } from "./agent/tools.js";
+import { loadStoredMessages, writePayloadLog, writeTranscriptLog } from "./agent/transcript-log.js";
 import { setConfigOverridesPath } from "./config-overrides.js";
 import { applyConfigOverridesToConfig } from "./config-registry.js";
 import { createGeneratedMediaSink } from "./generated-media.js";
-import { createImageGenTool } from "./image-gen.js";
-import { assertModelCanAuthenticate, clampConfiguredThinkingLevel, createConfiguredModel, isAllowedModel, isThinkingLevel, parseModelRef, resolveModel, resolveModelApiKey, supportedThinkingLevels, } from "./models.js";
+import { clampConfiguredThinkingLevel, createConfiguredModel, isThinkingLevel, parseModelRef, resolveModel, supportedThinkingLevels, } from "./models.js";
 import { buildSystemPrompt, loadPersona } from "./persona.js";
 import { formatFamiliarSkillsForPrompt, loadFamiliarSkills, logSkillDiagnostics } from "./skills.js";
-import { createTtsTool } from "./tts.js";
-import { isEnoent } from "./util/fs.js";
-import { isRecord } from "./util/guards.js";
-import { createWebTools } from "./web-tools.js";
-const BASH_DESCRIPTION = "run a bash command. defaults to the workspace; absolute paths and `~/...` reach anywhere else. returns stdout and stderr. output truncates to the last 2000 lines or 50KB, whichever hits first; full output lands in a temp file if cut. timeout in seconds optional.";
-const READ_DESCRIPTION = "read a file. paths resolve from the workspace, but absolute paths and `~/...` work too. text and images (jpg, png, gif, webp); images come back as attachments. text output truncates to 2000 lines or 50KB, whichever hits first — use offset and limit for long files, and keep paging until you have what you need.";
-const WRITE_DESCRIPTION = "write a file from scratch or replace it wholesale. creates the file if missing, overwrites if not, and makes parent directories as needed. paths resolve from the workspace; absolute and `~/...` also accepted.";
-const EDIT_DESCRIPTION = "edit a file with exact text replacement. each edits[].oldText must match a unique, non-overlapping slice of the original — overlapping or nested edits are rejected, so merge nearby changes into one entry rather than chaining them. don't pad oldText with large unchanged regions just to connect distant changes. paths resolve from the workspace; absolute and `~/...` also work.";
-function deriveSessionId(workspacePath, sessionKey) {
-    const digest = createHash("sha256").update(`${workspacePath}\0${sessionKey}`).digest("hex").slice(0, 32);
-    return `familiar-${digest}`;
-}
-function dailyLogPath(dataDir, streamName, now = new Date()) {
-    const date = now.toISOString().slice(0, 10);
-    return resolve(dataDir, streamName, `${date}.jsonl`);
-}
-async function appendJsonl(path, record) {
-    await mkdir(dirname(path), { recursive: true });
-    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
-}
-function writePayloadLog(config, record) {
-    appendJsonl(dailyLogPath(config.workspace.dataDir, "payloads"), record).catch((err) => console.error("payload log write failed", err));
-}
-function writeTranscriptLog(config, record) {
-    appendJsonl(dailyLogPath(config.workspace.dataDir, "transcripts"), record).catch((err) => console.error("transcript log write failed", err));
-}
-function clonePayload(payload) {
-    if (typeof structuredClone === "function")
-        return structuredClone(payload);
-    return JSON.parse(JSON.stringify(payload));
-}
-// TODO: remove once pi-ai handles store:false reasoning replay upstream.
-function stripOpenAIStoredReasoningItems(payload, model) {
-    if (model.api !== "openai-responses" && model.api !== "azure-openai-responses")
-        return payload;
-    const nextPayload = clonePayload(payload);
-    if (!isRecord(nextPayload))
-        return nextPayload;
-    const request = nextPayload;
-    if (request.store !== false)
-        return nextPayload;
-    const input = request.input;
-    if (!Array.isArray(input))
-        return nextPayload;
-    request.input = input.filter((item) => {
-        if (!item || typeof item !== "object" || Array.isArray(item))
-            return true;
-        return item.type !== "reasoning";
-    });
-    return nextPayload;
-}
-function moveAnthropicCacheControlBeforeInjectedMemory(payload, model) {
-    if (model.api !== "anthropic-messages")
-        return payload;
-    if (!isRecord(payload) || !Array.isArray(payload.messages))
-        return payload;
-    const messages = payload.messages;
-    const lastMessage = messages.at(-1);
-    if (!isRecord(lastMessage) || lastMessage.role !== "user")
-        return payload;
-    const content = lastMessage.content;
-    if (!Array.isArray(content) || content.length < 2)
-        return payload;
-    const injectedBlock = content.at(-1);
-    const stableBlock = content.at(-2);
-    if (!isInjectedMemoryTextBlock(injectedBlock) || !isRecord(stableBlock))
-        return payload;
-    const cacheControl = injectedBlock.cache_control;
-    if (!cacheControl)
-        return payload;
-    delete injectedBlock.cache_control;
-    stableBlock.cache_control = cacheControl;
-    return payload;
-}
-function isInjectedMemoryTextBlock(value) {
-    if (!isRecord(value) || value.type !== "text" || typeof value.text !== "string")
-        return false;
-    return value.text.trim().startsWith("<injected_memory>");
-}
-function normalizeProviderPayload(payload, model) {
-    return moveAnthropicCacheControlBeforeInjectedMemory(stripOpenAIStoredReasoningItems(payload, model), model);
-}
 export const __agentTest = {
+    isNoisyProviderDebug,
     normalizeProviderPayload,
 };
-function isStoredMessageRecord(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return typeof record.ts === "string" && typeof record.sessionId === "string" && !!record.message;
-}
-function isStoredResetRecord(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return record.type === "reset" && typeof record.ts === "string" && typeof record.sessionId === "string";
-}
-async function loadStoredMessages(dataDir, sessionId) {
-    const transcriptsDir = resolve(dataDir, "transcripts");
-    let files;
-    try {
-        files = await readdir(transcriptsDir);
-    }
-    catch (error) {
-        if (isEnoent(error))
-            return [];
-        console.error("transcript history read failed", error);
-        return [];
-    }
-    const records = [];
-    for (const file of files.filter((entry) => entry.endsWith(".jsonl")).sort()) {
-        const path = resolve(transcriptsDir, file);
-        let contents;
-        try {
-            contents = await readFile(path, "utf8");
-        }
-        catch (error) {
-            console.error(`transcript file read failed: ${path}`, error);
-            continue;
-        }
-        for (const [index, line] of contents.split(/\r?\n/).entries()) {
-            if (!line.trim())
-                continue;
-            try {
-                const parsed = JSON.parse(line);
-                if (!isStoredMessageRecord(parsed) && !isStoredResetRecord(parsed)) {
-                    console.error(`skipping malformed transcript line: ${path}:${index + 1}`);
-                    continue;
-                }
-                if (parsed.sessionId !== sessionId)
-                    continue;
-                records.push(parsed);
-            }
-            catch (error) {
-                console.error(`skipping unparsable transcript line: ${path}:${index + 1}`, error);
-            }
-        }
-    }
-    records.sort((a, b) => a.ts.localeCompare(b.ts));
-    let lastResetIndex = -1;
-    for (let index = records.length - 1; index >= 0; index--) {
-        const record = records[index];
-        if (record && "type" in record && record.type === "reset") {
-            lastResetIndex = index;
-            break;
-        }
-    }
-    const activeRecords = lastResetIndex >= 0 ? records.slice(lastResetIndex + 1) : records;
-    return activeRecords.flatMap((record) => ("message" in record ? [record.message] : []));
-}
-function getRequestApiKey(config, model) {
-    const apiKey = resolveModelApiKey(config, model);
-    assertModelCanAuthenticate(config, model);
-    return apiKey;
-}
-function formatModel(model) {
-    return `${model.provider}/${model.id}`;
-}
-function resolveModelName(value, fallback) {
-    return value ?? formatModel(fallback);
-}
-function assertModelAllowed(config, ref) {
-    if (!isAllowedModel(config, ref))
-        throw new Error(`Model is not allowlisted: ${ref.key}`);
-}
-function extractText(message) {
-    if (!message || typeof message !== "object")
-        return "";
-    const record = message;
-    if (record.stopReason === "error" && typeof record.errorMessage === "string" && record.errorMessage.trim()) {
-        return `Model error: ${record.errorMessage}`;
-    }
-    if (!("content" in record))
-        return "";
-    const content = record.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .filter((item) => {
-        return !!item && typeof item === "object" && item.type === "text";
-    })
-        .map((item) => item.text)
-        .join("");
-}
-function getLastAssistantText(agent) {
-    for (let i = agent.state.messages.length - 1; i >= 0; i--) {
-        const message = agent.state.messages[i];
-        if (message.role === "assistant")
-            return extractText(message);
-    }
-    return "";
-}
-function logUsage(event) {
-    if (event.type !== "message_end" || event.message.role !== "assistant")
-        return;
-    const usage = event.message.usage;
-    console.log(JSON.stringify({
-        type: "usage",
-        input: usage.input,
-        output: usage.output,
-        cacheRead: usage.cacheRead,
-        cacheWrite: usage.cacheWrite,
-        cost: usage.cost.total,
-    }));
-}
-function userTextMessage(text, timestamp = Date.now()) {
-    return {
-        role: "user",
-        content: [{ type: "text", text }],
-        timestamp,
-    };
-}
-function createFamiliarTools(config, mediaSink, referenceAttachments = () => [], memoryService) {
-    const bashTool = createBashTool(config.workspacePath);
-    bashTool.description = BASH_DESCRIPTION;
-    const readTool = createReadTool(config.workspacePath);
-    readTool.description = READ_DESCRIPTION;
-    const writeTool = createWriteTool(config.workspacePath);
-    writeTool.description = WRITE_DESCRIPTION;
-    const editTool = createEditTool(config.workspacePath);
-    editTool.description = EDIT_DESCRIPTION;
-    return [
-        bashTool,
-        readTool,
-        writeTool,
-        editTool,
-        createTtsTool(config, mediaSink),
-        ...(config.imageGen.enabled ? [createImageGenTool(config, mediaSink, { referenceAttachments })] : []),
-        ...createWebTools(config),
-        ...createBrowserTools(config, mediaSink),
-        ...(memoryService?.memoryTools() ?? []),
-    ];
-}
-function setReferenceAttachments(session, attachments = []) {
-    session.referenceAttachments.splice(0, session.referenceAttachments.length, ...attachments);
-}
+const PROVIDER_MAX_RETRIES = 2;
+const PROVIDER_MAX_RETRY_DELAY_MS = 60_000;
 export async function createFamiliarAgent(config, settings, memoryService, options = {}) {
+    installProviderDebugFilter();
     setAddedModelsPath(config.workspace.dataDir);
     setConfigOverridesPath(config.workspace.dataDir);
     applyConfigOverridesToConfig(config);
@@ -269,21 +36,8 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
     // activePromptOptions covers the synchronous promptMessage window; skipAmbientMessages
     // tags message identities so followUpMessage's fire-and-forget path also opts out.
     const activePromptOptions = new Map();
-    const softStopRequested = new Map();
     const skipAmbientMessages = new WeakSet();
     let reloadInProgress;
-    const installSoftStopHook = (sessionKey, agent) => {
-        const agentWithLoopConfig = agent;
-        const createLoopConfig = agentWithLoopConfig.createLoopConfig?.bind(agent);
-        if (!createLoopConfig)
-            return;
-        agentWithLoopConfig.createLoopConfig = ((options) => {
-            return {
-                ...createLoopConfig(options),
-                shouldStopAfterTurn: async () => softStopRequested.get(sessionKey) === true,
-            };
-        });
-    };
     const resolveChannelModel = (sessionKey) => {
         const override = settings.getChannelModel(sessionKey);
         const modelName = resolveModelName(override.value, defaultModel);
@@ -344,6 +98,8 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
                 ...options,
                 apiKey: getRequestApiKey(config, streamModel),
                 cacheRetention: config.agent.cacheRetention,
+                maxRetries: options?.maxRetries ?? PROVIDER_MAX_RETRIES,
+                maxRetryDelayMs: options?.maxRetryDelayMs ?? PROVIDER_MAX_RETRY_DELAY_MS,
                 onPayload: (payload, payloadModel) => {
                     const requestPayload = normalizeProviderPayload(payload, payloadModel);
                     writePayloadLog(config, {
@@ -381,7 +137,6 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
                 }
                 : undefined,
         });
-        installSoftStopHook(sessionKey, agent);
         agent.subscribe((event) => {
             logUsage(event);
             if (event.type === "message_end") {
@@ -465,25 +220,90 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             };
         }));
     };
+    // Shared serialization wrapper for prompt/promptMessage: run after the prior turn
+    // settles on the session's promptQueue, keep the stored tail non-rejecting, and run
+    // teardown (onTurnEnd → reference reset → enterTurn's exit → unsubscribe) in a fixed
+    // order regardless of how the turn ends. enterTurn returns its own cleanup so callers
+    // can scope per-turn state (e.g. activePromptOptions) across the exact finally window.
+    const runPromptTurn = async (sessionKey, options, eventHandler, dispatch, enterTurn) => {
+        const session = await getSession(sessionKey);
+        const run = session.promptQueue.then(async () => {
+            session.mediaSink.drain();
+            setReferenceAttachments(session, options.referenceAttachments);
+            const unsubscribe = eventHandler ? session.agent.subscribe((event) => eventHandler(event)) : undefined;
+            const exitTurn = enterTurn?.();
+            try {
+                await dispatch(session);
+            }
+            finally {
+                try {
+                    await options.onTurnEnd?.();
+                }
+                catch (error) {
+                    console.error("turn end callback failed", error);
+                }
+                finally {
+                    setReferenceAttachments(session);
+                    exitTurn?.();
+                    unsubscribe?.();
+                }
+            }
+            return {
+                text: getLastAssistantText(session.agent),
+                attachments: session.mediaSink.drain(),
+            };
+        });
+        session.promptQueue = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const popLastAssistant = (session, action) => {
+        const messages = session.agent.state.messages;
+        const message = messages.at(-1);
+        if (!message || message.role !== "assistant") {
+            throw new Error(`No assistant message to ${action}`);
+        }
+        if (action === "retry" && message.stopReason === "aborted") {
+            throw new Error("Cannot retry an aborted assistant message");
+        }
+        session.agent.state.messages = messages.slice(0, -1);
+        writeTranscriptLog(config, {
+            ts: new Date().toISOString(),
+            sessionId: session.sessionId,
+            type: "supersede",
+            messageTimestamp: message.timestamp,
+        });
+    };
     return {
-        abort(sessionKey) {
+        async abort(sessionKey) {
             const session = sessions.get(sessionKey);
-            void session
-                ?.then((resolved) => {
+            if (!session)
+                return;
+            try {
+                const resolved = await session;
                 resolved.agent.abort();
                 resolved.agent.clearAllQueues();
-            })
-                .catch((error) => console.error(`failed to abort familiar session ${sessionKey}`, error));
+                await resolved.agent.waitForIdle();
+            }
+            catch (error) {
+                console.error(`failed to abort familiar session ${sessionKey}`, error);
+            }
+        },
+        async retryLastAssistant(sessionKey, eventHandler, options = {}) {
+            return runPromptTurn(sessionKey, options, eventHandler, async (session) => {
+                popLastAssistant(session, "retry");
+                await session.agent.continue();
+            });
         },
-        requestSoftStop(sessionKey) {
-            softStopRequested.set(sessionKey, true);
+        async deleteLastAssistant(sessionKey) {
+            const session = await getSession(sessionKey);
+            await session.promptQueue;
+            popLastAssistant(session, "delete");
         },
         async reset(sessionKey) {
             const existing = sessions.get(sessionKey);
             if (!existing)
                 return;
             const session = await existing;
-            softStopRequested.set(sessionKey, false);
             resetSession(session);
         },
         async reload() {
@@ -577,74 +397,23 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             return `Thinking set to ${clamped}${suffix} for this channel\nSupported: ${supportedThinkingLevels(model).join(", ")}`;
         },
         async prompt(sessionKey, input, imagesOrOnEvent, onEvent, options = {}) {
-            const session = await getSession(sessionKey);
             const images = Array.isArray(imagesOrOnEvent) ? imagesOrOnEvent : undefined;
             const eventHandler = Array.isArray(imagesOrOnEvent) ? onEvent : imagesOrOnEvent;
-            const run = session.promptQueue.then(async () => {
-                softStopRequested.set(sessionKey, false);
-                session.mediaSink.drain();
-                setReferenceAttachments(session, options.referenceAttachments);
-                const unsubscribe = eventHandler ? session.agent.subscribe((event) => eventHandler(event)) : undefined;
-                try {
-                    await session.agent.prompt(input, images);
-                }
-                finally {
-                    try {
-                        await options.onTurnEnd?.();
-                    }
-                    catch (error) {
-                        console.error("turn end callback failed", error);
-                    }
-                    finally {
-                        setReferenceAttachments(session);
-                        unsubscribe?.();
-                    }
-                }
-                return {
-                    text: getLastAssistantText(session.agent),
-                    attachments: session.mediaSink.drain(),
-                };
-            });
-            session.promptQueue = run.then(() => undefined, () => undefined);
-            return run;
+            return runPromptTurn(sessionKey, options, eventHandler, (session) => session.agent.prompt(input, images));
         },
         async promptMessage(sessionKey, message, onEvent, options = {}) {
-            const session = await getSession(sessionKey);
-            const run = session.promptQueue.then(async () => {
-                softStopRequested.set(sessionKey, false);
-                session.mediaSink.drain();
-                setReferenceAttachments(session, options.referenceAttachments);
-                const unsubscribe = onEvent ? session.agent.subscribe((event) => onEvent(event)) : undefined;
+            return runPromptTurn(sessionKey, options, onEvent, (session) => session.agent.prompt(message), () => {
                 const previousOptions = activePromptOptions.get(sessionKey);
                 activePromptOptions.set(sessionKey, options);
                 if (options.skipAmbient)
                     skipAmbientMessages.add(message);
-                try {
-                    await session.agent.prompt(message);
-                }
-                finally {
-                    try {
-                        await options.onTurnEnd?.();
-                    }
-                    catch (error) {
-                        console.error("turn end callback failed", error);
-                    }
-                    finally {
-                        setReferenceAttachments(session);
-                        if (previousOptions)
-                            activePromptOptions.set(sessionKey, previousOptions);
-                        else
-                            activePromptOptions.delete(sessionKey);
-                        unsubscribe?.();
-                    }
-                }
-                return {
-                    text: getLastAssistantText(session.agent),
-                    attachments: session.mediaSink.drain(),
+                return () => {
+                    if (previousOptions)
+                        activePromptOptions.set(sessionKey, previousOptions);
+                    else
+                        activePromptOptions.delete(sessionKey);
                 };
             });
-            session.promptQueue = run.then(() => undefined, () => undefined);
-            return run;
         },
         steer(sessionKey, input) {
             const session = sessions.get(sessionKey);

package/dist/browser-tools.js

@@ -142,6 +142,7 @@ function defaultBrowserRunner() {
             reject(new Error(`Browser command timed out after ${options.timeoutMs}ms.`));
         }, options.timeoutMs);
         const abort = () => {
+            clearTimeout(timeout);
             child.kill("SIGTERM");
             reject(new Error("Browser command aborted."));
         };
@@ -608,7 +609,7 @@ async function loadSiteCommand(site, command, config, runner, signal) {
         throw new Error(`OpenCLI site command is not available: ${site} ${command}`);
     return info;
 }
-function buildSiteArgs(input, config, commandInfo) {
+function resolveSiteCommand(input, config) {
     const site = stringArg(input.site);
     const command = stringArg(input.command);
     if (!site || !command)
@@ -616,6 +617,10 @@ function buildSiteArgs(input, config, commandInfo) {
     assertSafeName(site, "browser.site");
     assertSafeName(command, "browser.command");
     assertSiteAllowed(config, site);
+    return { site, command };
+}
+function buildSiteArgs(input, config, commandInfo) {
+    const { site, command } = resolveSiteCommand(input, config);
     if (commandInfo.access === "write" && !config.browser.readWrite) {
         throw new Error(`OpenCLI write command is disabled until browser.read_write is true: ${site} ${command}`);
     }
@@ -648,13 +653,7 @@ function buildSiteArgs(input, config, commandInfo) {
     return args;
 }
 async function buildSiteRunSpec(input, config, runner, signal) {
-    const site = stringArg(input.site);
-    const command = stringArg(input.command);
-    if (!site || !command)
-        throw new Error("browser site mode requires site and command.");
-    assertSafeName(site, "browser.site");
-    assertSafeName(command, "browser.command");
-    assertSiteAllowed(config, site);
+    const { site, command } = resolveSiteCommand(input, config);
     const commandInfo = await loadSiteCommand(site, command, config, runner, signal);
     return openCliSpec(config, buildSiteArgs(input, config, commandInfo));
 }

package/dist/chat-log.js

@@ -1,6 +1,15 @@
 import { appendFile, mkdir, open, readdir, readFile, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { isEnoent, readFileOrNull } from "./util/fs.js";
+export function hiddenWebMessageIds(records) {
+    return new Set(records.flatMap((record) => {
+        if (record.type === "assistant_retry")
+            return [record.oldMessageId];
+        if (record.type === "message_delete")
+            return [record.messageId];
+        return [];
+    }));
+}
 function sanitizeSegment(value) {
     return value.replace(/[^A-Za-z0-9._=-]+/g, "_").slice(0, 120) || "unknown";
 }
@@ -62,10 +71,13 @@ export function createChatLog(config, channel) {
                     return [];
                 throw error;
             }
-            const records = [];
-            for (const file of files.filter((entry) => entry.endsWith(".jsonl")).sort()) {
+            const jsonlFiles = files.filter((entry) => entry.endsWith(".jsonl")).sort();
+            const contents = await Promise.all(jsonlFiles.map(async (file) => {
                 const filePath = resolve(dir, file);
-                const content = await readFile(filePath, "utf8");
+                return { filePath, content: await readFile(filePath, "utf8") };
+            }));
+            const records = [];
+            for (const { filePath, content } of contents) {
                 for (const [index, line] of content.split(/\r?\n/).entries()) {
                     if (!line.trim())
                         continue;

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
-import { copyFile, cp, mkdir } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { config as loadDotenv } from "dotenv";
 import { createFamiliarAgent } from "./agent.js";
+import { createAgentCore } from "./agent-core.js";
 import { loadConfig } from "./config.js";
 import { runDataRetention } from "./data-retention.js";
 import { startDiscordDaemon } from "./discord.js";
@@ -13,6 +14,7 @@ import { cleanupGeneratedAttachments } from "./generated-media.js";
 import { startWorkspaceHotReload } from "./hot-reload.js";
 import { memoryHelp, runMemoryOperator } from "./memory/operator.js";
 import { createMemoryService } from "./memory/service.js";
+import { loadOwnerIdentity } from "./owner-identity.js";
 import { formatServiceResult, installService, serviceStatus, uninstallService, upgradeFamiliar } from "./service.js";
 import { loadSettingsStore } from "./settings.js";
 import { startWebDaemon } from "./web.js";
@@ -76,6 +78,11 @@ function isMemoryHelp(args) {
     const command = args[0];
     return !command || command === "help" || command === "--help";
 }
+async function packageVersion() {
+    const raw = await readFile(resolve(PROJECT_ROOT, "package.json"), "utf8");
+    const packageJson = JSON.parse(raw);
+    return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+}
 async function initWorkspace(workspaceInput) {
     const workspacePath = resolveWorkspaceInput(workspaceInput);
     await mkdir(workspacePath, { recursive: true });
@@ -119,6 +126,7 @@ async function runDaemon(workspaceInput) {
     memoryService.watchDiaries();
     const familiarAgent = await createFamiliarAgent(config, settings, memoryService, { reloadConfig });
     const hotReload = startWorkspaceHotReload({ workspacePath: config.workspacePath, familiarAgent });
+    const agentCore = createAgentCore({ config, familiarAgent, memoryService });
     let stopping = false;
     let discordDaemon;
     let webDaemon;
@@ -129,6 +137,7 @@ async function runDaemon(workspaceInput) {
         console.log("Stopping familiar");
         hotReload.close();
         await Promise.all([webDaemon?.stop(), discordDaemon?.stop()]);
+        await agentCore.stop();
         memoryService.close();
         process.exit(exitCode);
     };
@@ -137,10 +146,21 @@ async function runDaemon(workspaceInput) {
         setTimeout(() => void stop(75), RESTART_EXIT_DELAY_MS);
         return "Restart requested. If Familiar is managed by launchd/systemd, it should come back automatically; otherwise run familiar run again.";
     };
-    discordDaemon = await startDiscordDaemon(config, familiarAgent, settings, memoryService, {
-        restart: requestRestart,
-    });
-    webDaemon = await startWebDaemon(config, familiarAgent, discordDaemon, { restart: requestRestart });
+    const identity = await loadOwnerIdentity(config.workspace.dataDir);
+    const token = config.discord.token;
+    if (!identity && !token) {
+        throw new Error("First-time setup needs a DISCORD_TOKEN to establish owner identity. Set DISCORD_TOKEN and run again.");
+    }
+    // The scheduler starts with the first session source to arrive: the cached identity
+    // here, or the live Discord connection below when there is no cache yet.
+    if (identity)
+        await agentCore.useCachedIdentity(identity);
+    webDaemon = await startWebDaemon(config, familiarAgent, agentCore, { restart: requestRestart });
+    if (token) {
+        discordDaemon = startDiscordDaemon(config, token, familiarAgent, settings, memoryService, agentCore, {
+            restart: requestRestart,
+        });
+    }
     console.log(`familiar running for workspace ${config.workspacePath}`);
     console.log("agent sessions are created per channel");
     console.log(`settings=${settings.path}`);
@@ -151,6 +171,8 @@ async function runDaemon(workspaceInput) {
 function usage() {
     return [
         "Usage:",
+        "  familiar --help",
+        "  familiar --version",
         "  familiar init [workspace]",
         "  familiar run [workspace]",
         "  familiar memory [workspace] <subcommand>",
@@ -164,6 +186,14 @@ function usage() {
 }
 async function main() {
     const [, , command, workspace, ...rest] = process.argv;
+    if (!command || command === "--help" || command === "-h") {
+        console.log(usage());
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(await packageVersion());
+        return;
+    }
     if (command === "init") {
         await initWorkspace(workspace);
         return;
@@ -200,7 +230,7 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Upgrading @qearlyao/familiar globally...");
+        console.log("Upgrading @qearlyao/familiar and OpenCLI globally...");
         await upgradeFamiliar(resolveWorkspaceInput(workspace));
         return;
     }