@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/agent/session-helpers.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { assertModelCanAuthenticate, isAllowedModel, resolveModelApiKey } from "../models/index.js";
+const NOISY_GOOGLE_VERTEX_AUTH_DEBUG = "The user provided project/location will take precedence over the API key from the environment variables.";
+let providerDebugFilterInstalled = false;
+export function deriveSessionId(workspacePath, sessionKey) {
+    const digest = createHash("sha256").update(`${workspacePath}\0${sessionKey}`).digest("hex").slice(0, 32);
+    return `familiar-${digest}`;
+}
+export function isNoisyProviderDebug(args) {
+    return args.length === 1 && args[0] === NOISY_GOOGLE_VERTEX_AUTH_DEBUG;
+}
+export function installProviderDebugFilter() {
+    if (providerDebugFilterInstalled)
+        return;
+    providerDebugFilterInstalled = true;
+    const debug = console.debug;
+    console.debug = (...args) => {
+        if (isNoisyProviderDebug(args))
+            return;
+        debug.apply(console, args);
+    };
+}
+export function getRequestApiKey(config, model) {
+    const apiKey = resolveModelApiKey(config, model);
+    assertModelCanAuthenticate(config, model);
+    return apiKey;
+}
+export function formatModel(model) {
+    return `${model.provider}/${model.id}`;
+}
+export function resolveModelName(value, fallback) {
+    return value ?? formatModel(fallback);
+}
+export 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("");
+}
+export 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 "";
+}
+export 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,
+    }));
+}
+export function userTextMessage(text, timestamp = Date.now()) {
+    return {
+        role: "user",
+        content: [{ type: "text", text }],
+        timestamp,
+    };
+}

package/dist/agent/tool-descriptions.js

@@ -0,0 +1,4 @@
+export 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.";
+export 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.";
+export 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.";
+export 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.";

package/dist/agent/tools.js

@@ -0,0 +1,30 @@
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@earendil-works/pi-coding-agent";
+import { createImageGenTool } from "../media/image-gen.js";
+import { createTtsTool } from "../media/tts.js";
+import { createBrowserTools } from "../tools/browser-tools.js";
+import { createWebTools } from "../web-tools/index.js";
+import { BASH_DESCRIPTION, EDIT_DESCRIPTION, READ_DESCRIPTION, WRITE_DESCRIPTION } from "./tool-descriptions.js";
+export 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() ?? []),
+    ];
+}
+export function setReferenceAttachments(session, attachments = []) {
+    session.referenceAttachments.splice(0, session.referenceAttachments.length, ...attachments);
+}

package/dist/agent/transcript-log.js

@@ -0,0 +1,93 @@
+import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { isEnoent } from "../util/fs.js";
+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");
+}
+export function writePayloadLog(config, record) {
+    appendJsonl(dailyLogPath(config.workspace.dataDir, "payloads"), record).catch((err) => console.error("payload log write failed", err));
+}
+export function writeTranscriptLog(config, record) {
+    appendJsonl(dailyLogPath(config.workspace.dataDir, "transcripts"), record).catch((err) => console.error("transcript log write failed", err));
+}
+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";
+}
+function isStoredSupersedeRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.type === "supersede" &&
+        typeof record.ts === "string" &&
+        typeof record.sessionId === "string" &&
+        typeof record.messageTimestamp === "number");
+}
+export 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 jsonlFiles = files.filter((entry) => entry.endsWith(".jsonl")).sort();
+    const records = [];
+    for (const file of jsonlFiles) {
+        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) && !isStoredSupersedeRecord(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;
+    const superseded = new Set(activeRecords.flatMap((record) => "type" in record && record.type === "supersede" ? [record.messageTimestamp] : []));
+    return activeRecords.flatMap((record) => "message" in record && !superseded.has(record.message.timestamp) ? [record.message] : []);
+}

package/dist/cli.js

@@ -1,21 +1,23 @@
 #!/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 { loadConfig } from "./config.js";
-import { runDataRetention } from "./data-retention.js";
-import { startDiscordDaemon } from "./discord.js";
-import { cleanupGeneratedAttachments } from "./generated-media.js";
-import { startWorkspaceHotReload } from "./hot-reload.js";
+import { createFamiliarAgent } from "./agent/factory.js";
+import { loadConfig } from "./config/index.js";
+import { loadSettingsStore } from "./config/settings.js";
+import { loadOwnerIdentity } from "./conversation/owner-identity.js";
+import { startDiscordDaemon } from "./discord/daemon.js";
+import { runDataRetention } from "./lifecycle/data-retention.js";
+import { startWorkspaceHotReload } from "./lifecycle/hot-reload.js";
+import { formatServiceResult, installService, serviceStatus, uninstallService, upgradeFamiliar, } from "./lifecycle/service.js";
+import { cleanupGeneratedAttachments } from "./media/generated-media.js";
 import { memoryHelp, runMemoryOperator } from "./memory/operator.js";
 import { createMemoryService } from "./memory/service.js";
-import { formatServiceResult, installService, serviceStatus, uninstallService, upgradeFamiliar } from "./service.js";
-import { loadSettingsStore } from "./settings.js";
-import { startWebDaemon } from "./web.js";
+import { createAgentCore } from "./runtime/agent-core.js";
+import { startWebDaemon } from "./web/daemon.js";
 const SOURCE_DIR = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(SOURCE_DIR, "..");
 const DEFAULT_WORKSPACE_PATH = resolve(homedir(), ".familiar");
@@ -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;
     }

package/dist/config/enums.js

@@ -0,0 +1,35 @@
+export const CACHE_RETENTIONS = ["none", "short", "long"];
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+export const DISCORD_REPLY_MODES = ["plain", "reply"];
+export const DISCORD_CHUNK_MODES = ["simple", "paragraph", "newline"];
+export const DISCORD_DISPATCH_MODES = ["steer", "queue", "collect"];
+export const DISCORD_CHANNEL_TRIGGERS = ["mention", "always"];
+export const CRON_FREQUENCIES = [
+    "once",
+    "hourly",
+    "daily",
+    "weekly",
+    "monthly",
+];
+export const CRON_DELIVERY_MODES = ["queue", "follow_up"];
+export const WEB_AUTH_MODES = ["tailscale-only", "bearer", "public-2fa"];
+export const TTS_PROVIDERS = ["elevenlabs"];
+export const IMAGE_GEN_APIS = ["openrouter-images"];
+export const MEDIA_UNDERSTANDING_PROVIDERS = [
+    "groq",
+    "google",
+];
+export const MEMORY_EMBEDDING_FORMATS = [
+    "gemini",
+    "openai",
+    "voyage",
+];
+export const BROWSER_BACKENDS = ["opencli", "browser-harness"];
+export const BROWSER_WINDOW_MODES = ["foreground", "background"];