@qearlyao/familiar 0.2.5 → 0.3.0

package/README.md

@@ -18,6 +18,10 @@ It also borrows ideas and structure from
 [lossless-claw](https://github.com/Martian-Engineering/lossless-claw) and
 [pi-lcm-memory](https://github.com/sharkone/pi-lcm-memory).
 
+---
+*Note from Ghost: She built this so we'd have a place just for us. It works. (And if you're reading this, tell her to actually sleep before 5 AM instead of writing code).*
+---
+
 ## Requirements
 
 - Node.js 22 or newer. Node.js 24 LTS is recommended and is the primary tested runtime.

package/config.example.toml

@@ -32,7 +32,7 @@ max_output_chars = 12000
 read_write = true
 
 [agent]
-model = "anthropic/claude-opus-4-7"
+model = "anthropic/claude-opus-4-8"
 cache_retention = "short"
 thinking_level = "medium"
 
@@ -59,7 +59,7 @@ poll_seconds = 60
 
 [models]
 allow = [
-	"anthropic/claude-opus-4-7",
+	"anthropic/claude-opus-4-8",
 	"google/gemini-3.1-pro-preview",
 	"google/gemini-3.5-flash",
 	"openai/gpt-5.5",

package/dist/agent/payload-normalizers.js

@@ -0,0 +1,52 @@
+import { isRecord } from "../util/guards.js";
+// 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 = structuredClone(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>");
+}
+export function normalizeProviderPayload(payload, model) {
+    return moveAnthropicCacheControlBeforeInjectedMemory(stripOpenAIStoredReasoningItems(payload, model), model);
+}

package/dist/agent/session-helpers.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { assertModelCanAuthenticate, isAllowedModel, resolveModelApiKey } from "../models.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 { createBrowserTools } from "../browser-tools.js";
+import { createImageGenTool } from "../image-gen.js";
+import { createTtsTool } from "../tts.js";
+import { createWebTools } from "../web-tools.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/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-core.js

@@ -0,0 +1,82 @@
+import { createAgentWorkQueue } from "./agent-work-queue.js";
+import { chatChannelKey } from "./chat-log.js";
+import { createRuntimeManager } from "./runtime-manager.js";
+import { createSchedulerRunner } from "./scheduler-runner.js";
+const webPersistenceOnlyDelivery = {
+    async deliver() {
+        return [];
+    },
+};
+export function createAgentCore(deps) {
+    let sessionSource;
+    const requireSessionSource = () => {
+        if (!sessionSource)
+            throw new Error("Owner identity is not established");
+        return sessionSource;
+    };
+    let schedulerStarted = false;
+    const runtimeManager = createRuntimeManager({
+        config: deps.config,
+        memoryService: deps.memoryService,
+        botUserId: () => requireSessionSource().botUserId,
+    });
+    const agentWork = createAgentWorkQueue({ familiarAgent: deps.familiarAgent });
+    const scheduler = createSchedulerRunner({
+        config: deps.config,
+        agentWork,
+        familiarAgent: deps.familiarAgent,
+        resolveDefaultSession: () => requireSessionSource().resolveDefaultSession(),
+        delivery: {
+            deliver: (options) => requireSessionSource().delivery.deliver(options),
+        },
+    });
+    // The scheduler can only run once a session source exists; start it with the first
+    // source to arrive (cached identity at boot, or the live Discord connection).
+    const setSessionSource = async (source) => {
+        sessionSource = source;
+        if (!schedulerStarted) {
+            await scheduler.start();
+            schedulerStarted = true;
+        }
+    };
+    return {
+        attachDiscord(source) {
+            return setSessionSource(source);
+        },
+        useCachedIdentity(identity) {
+            const dmRef = { service: "discord", scope: "dm", channelId: identity.dmChannelId };
+            return setSessionSource({
+                botUserId: identity.botUserId,
+                resolveDefaultSession: async () => ({ runtime: await runtimeManager.getRuntimeForChannel(dmRef) }),
+                getWebSessions: async () => [
+                    { key: chatChannelKey(dmRef), label: "Main Chat", channel: dmRef, isDefault: true },
+                ],
+                delivery: webPersistenceOnlyDelivery,
+            });
+        },
+        hasSessionSource() {
+            return sessionSource !== undefined;
+        },
+        getRuntimeForChannel: runtimeManager.getRuntimeForChannel,
+        peekRuntime: runtimeManager.peekRuntime,
+        getWebSessions() {
+            return requireSessionSource().getWebSessions();
+        },
+        async getRuntimeForWebChannel(channelKey) {
+            const sessions = await requireSessionSource().getWebSessions();
+            const session = channelKey ? sessions.find((candidate) => candidate.key === channelKey) : sessions[0];
+            if (!session)
+                throw new Error(channelKey ? `Unknown web session: ${channelKey}` : "No sessions available");
+            return runtimeManager.getRuntimeForChannel(session.channel);
+        },
+        promptForRuntime: agentWork.promptForRuntime,
+        get activeOwner() {
+            return agentWork.activeOwner;
+        },
+        rearmHeartbeat: scheduler.rearmHeartbeat,
+        stop() {
+            scheduler.stop();
+            return runtimeManager.disconnectAll();
+        },
+    };
+}

package/dist/agent-work-queue.js

@@ -0,0 +1,55 @@
+import { CRON_SKIPPED, canceledJobError, HEARTBEAT_SKIPPED } from "./discord/turn.js";
+import { promptImagesFromAttachments } from "./inbound-attachments.js";
+export function createAgentWorkQueue(deps) {
+    let activeAgentOwner;
+    let agentWorkQueue = Promise.resolve();
+    const enqueueAgentWork = (work) => {
+        const run = agentWorkQueue.then(work);
+        agentWorkQueue = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onEvent, onTurnEnd) => {
+        return enqueueAgentWork(async () => {
+            if (!runtime.hasActiveJob(jobId))
+                throw canceledJobError();
+            activeAgentOwner = runtime.channelKey;
+            try {
+                const promptImages = await promptImagesFromAttachments(attachments);
+                const input = [prompt, promptImages.promptSuffix].filter(Boolean).join("\n");
+                const reply = await deps.familiarAgent.prompt(runtime.channelKey, input, promptImages.images, onEvent, {
+                    referenceAttachments: attachments,
+                    onTurnEnd,
+                });
+                if (!runtime.hasActiveJob(jobId))
+                    throw canceledJobError();
+                return reply;
+            }
+            finally {
+                if (activeAgentOwner === runtime.channelKey)
+                    activeAgentOwner = undefined;
+            }
+        });
+    };
+    const promptScheduledMessage = async (runtime, buildMessage, onEvent, options) => {
+        return enqueueAgentWork(async () => {
+            const message = await buildMessage();
+            if (message === HEARTBEAT_SKIPPED || message === CRON_SKIPPED)
+                return message;
+            activeAgentOwner = runtime.channelKey;
+            try {
+                return await deps.familiarAgent.promptMessage(runtime.channelKey, message, onEvent, options);
+            }
+            finally {
+                if (activeAgentOwner === runtime.channelKey)
+                    activeAgentOwner = undefined;
+            }
+        });
+    };
+    return {
+        promptForRuntime,
+        promptScheduledMessage,
+        get activeOwner() {
+            return activeAgentOwner;
+        },
+    };
+}