@qearlyao/familiar 0.2.4 → 0.3.0

package/dist/discord/commands.js

@@ -0,0 +1,181 @@
+import { ApplicationCommandOptionType, ApplicationCommandType, ApplicationIntegrationType, ChannelType, InteractionContextType, MessageFlags, } from "discord.js";
+import { formatSetting } from "../settings.js";
+import { normalizeOutboundText } from "./send.js";
+export const FAMILIAR_COMMAND_NAME = "familiar";
+const THINKING_CHOICES = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const CHANNEL_TRIGGER_CHOICES = ["mention", "always"];
+export const EPHEMERAL_REPLY = MessageFlags.Ephemeral;
+export function getFamiliarApplicationCommand() {
+    const modelOption = {
+        name: "model",
+        description: "Provider/model id",
+        type: ApplicationCommandOptionType.String,
+        required: false,
+        autocomplete: true,
+    };
+    return {
+        name: FAMILIAR_COMMAND_NAME,
+        description: "Control Familiar",
+        type: ApplicationCommandType.ChatInput,
+        contexts: [InteractionContextType.Guild, InteractionContextType.BotDM],
+        integrationTypes: [ApplicationIntegrationType.GuildInstall],
+        options: [
+            {
+                name: "status",
+                description: "Show Familiar status for this channel",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "stop",
+                description: "Stop current work and clear the queue",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "new",
+                description: "Start a fresh agent transcript for this channel",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "reload",
+                description: "Reload persona prompt files and live agent settings",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "restart",
+                description: "Restart Familiar if this runtime has a restart handler",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "compact",
+                description: "Show compaction status",
+                type: ApplicationCommandOptionType.Subcommand,
+            },
+            {
+                name: "model",
+                description: "Show or set the model for this channel",
+                type: ApplicationCommandOptionType.Subcommand,
+                options: [modelOption],
+            },
+            {
+                name: "thinking",
+                description: "Show or set thinking level for this channel",
+                type: ApplicationCommandOptionType.Subcommand,
+                options: [
+                    {
+                        name: "level",
+                        description: "Thinking level",
+                        type: ApplicationCommandOptionType.String,
+                        required: false,
+                        choices: THINKING_CHOICES.map((level) => ({ name: level, value: level })),
+                    },
+                ],
+            },
+            {
+                name: "channel-trigger",
+                description: "Show or set when Familiar responds in this channel",
+                type: ApplicationCommandOptionType.Subcommand,
+                options: [
+                    {
+                        name: "trigger",
+                        description: "Channel trigger policy",
+                        type: ApplicationCommandOptionType.String,
+                        required: false,
+                        choices: CHANNEL_TRIGGER_CHOICES.map((trigger) => ({ name: trigger, value: trigger })),
+                    },
+                ],
+            },
+        ],
+    };
+}
+export async function registerFamiliarApplicationCommand(client) {
+    const command = getFamiliarApplicationCommand();
+    const commands = await client.application.commands.fetch({ force: true });
+    const existing = commands.find((candidate) => candidate.name === FAMILIAR_COMMAND_NAME && candidate.type === ApplicationCommandType.ChatInput);
+    if (existing) {
+        if (!existing.equals(command)) {
+            await client.application.commands.edit(existing.id, command);
+            console.log(`Updated Discord /${FAMILIAR_COMMAND_NAME} command`);
+        }
+        return;
+    }
+    await client.application.commands.create(command);
+    console.log(`Registered Discord /${FAMILIAR_COMMAND_NAME} command`);
+}
+export function commandTextFromInteraction(interaction) {
+    const subcommand = interaction.options.getSubcommand(true);
+    if (subcommand === "model") {
+        const model = interaction.options.getString("model");
+        return model ? `/model ${model}` : "/model";
+    }
+    if (subcommand === "thinking") {
+        const level = interaction.options.getString("level");
+        return level ? `/thinking ${level}` : "/thinking";
+    }
+    if (subcommand === "channel-trigger") {
+        const trigger = interaction.options.getString("trigger");
+        return trigger ? `/channel-trigger ${trigger}` : "/channel-trigger";
+    }
+    return `/${subcommand}`;
+}
+export function inboundInputFromInteraction(interaction) {
+    return {
+        messageId: interaction.id,
+        authorId: interaction.user.id,
+        authorName: interaction.user.username,
+        text: commandTextFromInteraction(interaction),
+        isBot: false,
+        mentionedBot: true,
+        remoteTimestamp: new Date(interaction.createdTimestamp || Date.now()).toISOString(),
+    };
+}
+export async function replyEphemeral(interaction, text) {
+    const content = normalizeOutboundText(text);
+    if (interaction.deferred || interaction.replied) {
+        await interaction.editReply({ content });
+    }
+    else {
+        await interaction.reply({ content, flags: EPHEMERAL_REPLY });
+    }
+    const reply = await interaction.fetchReply().catch(() => undefined);
+    return reply?.id ? [reply.id] : [];
+}
+export async function replyInteractionError(interaction, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error("Discord interaction handling failed", error);
+    await replyEphemeral(interaction, `I hit an error while handling that command.\n${message}`);
+}
+export function formatCommandResponse(command, runtime, familiarAgent, channelTrigger) {
+    if (command === "status") {
+        return [
+            runtime.formatStatus(),
+            `model: ${formatSetting(familiarAgent.getModel(runtime.channelKey))}`,
+            `thinking: ${formatSetting(familiarAgent.getThinkingLevel(runtime.channelKey))}`,
+            `channel_trigger: ${formatSetting(channelTrigger)}`,
+        ].join("\n");
+    }
+    return "Compact is not wired for this runtime yet. I logged the command, but I won't run lossy compaction here.";
+}
+export function getAutocompleteChoices(config, interaction) {
+    if (interaction.commandName !== FAMILIAR_COMMAND_NAME)
+        return [];
+    const subcommand = interaction.options.getSubcommand(false);
+    const focused = interaction.options.getFocused(true);
+    const value = String(focused.value ?? "").toLowerCase();
+    if (subcommand !== "model" || focused.name !== "model")
+        return [];
+    const candidates = config.models.allow.length > 0 ? config.models.allow : [config.agent.model];
+    return [...new Set(candidates)]
+        .filter((model) => !value || model.toLowerCase().includes(value))
+        .slice(0, 25)
+        .map((model) => ({ name: model, value: model }));
+}
+export function isAllowedInteractionChannel(config, interaction) {
+    if (interaction.user.id !== config.discord.ownerId)
+        return false;
+    const channel = interaction.channel;
+    if (!channel)
+        return false;
+    if (channel.type === ChannelType.DM)
+        return true;
+    return interaction.channelId ? config.discord.allowedChannels.includes(interaction.channelId) : false;
+}

package/dist/discord/inbound.js

@@ -0,0 +1,44 @@
+import { materializeInboundAttachments } from "../inbound-attachments.js";
+import { isDmChannel, messageMentionsBot } from "./channel.js";
+export function getDispatchMode(config, message) {
+    return isDmChannel(message.channel) ? config.discord.dmMode : config.discord.channelMode;
+}
+export function getChannelTriggerSetting(config, settings, channelKey, isDm) {
+    if (isDm)
+        return { value: "always", source: "config" };
+    return settings.getChannelTrigger(channelKey, config.discord.channelTrigger);
+}
+export function canSteerFromRecord(config, message, runtime, record, activeAgentOwner, channelTrigger) {
+    if (getDispatchMode(config, message) !== "steer")
+        return false;
+    if (!runtime.hasActiveJob() || activeAgentOwner !== runtime.channelKey)
+        return false;
+    if (isDmChannel(message.channel))
+        return record.authorId === config.discord.ownerId && !record.isBot;
+    if (channelTrigger === "always")
+        return true;
+    return record.mentionedBot;
+}
+export async function toInboundInput(config, message, botUserId) {
+    const attachments = await materializeInboundAttachments(config, [...message.attachments.values()].map((attachment) => ({
+        id: attachment.id,
+        name: attachment.name,
+        mimeType: attachment.contentType ?? undefined,
+        size: attachment.size,
+        url: attachment.url,
+        source: "discord",
+    })));
+    return {
+        messageId: message.id,
+        authorId: message.author.id,
+        authorName: message.author.username,
+        text: message.content || "",
+        isBot: message.author.bot,
+        mentionedBot: messageMentionsBot(message, botUserId),
+        remoteTimestamp: new Date(message.createdTimestamp || Date.now()).toISOString(),
+        checkpoint: {
+            messageId: message.id,
+        },
+        attachments,
+    };
+}

package/dist/discord/send.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { Routes } from "discord.js";
+import { parseAgentReply as parseSilentMarker } from "../silent-marker.js";
+import { chunkDiscord } from "./chunking.js";
+const NEWLINE_BURST_DELAY_MS = 500;
+const DISCORD_ATTACHMENT_SEND_TIMEOUT_MS = 20_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function delayBetweenBurstChunks(config, channel) {
+    if (config.discord.chunkMode !== "newline")
+        return;
+    if (channel.isSendable()) {
+        void channel.sendTyping().catch(() => undefined);
+    }
+    await sleep(NEWLINE_BURST_DELAY_MS);
+}
+export function normalizeOutboundText(text) {
+    return text.trim() || "(empty response)";
+}
+function fallbackMimeType(name) {
+    return extname(name).toLowerCase() === ".mp3" ? "audio/mpeg" : "application/octet-stream";
+}
+export async function buildRawFiles(attachments) {
+    const files = [];
+    for (const attachment of attachments) {
+        if (!attachment.localPath)
+            continue;
+        const data = await readFile(attachment.localPath);
+        files.push({
+            name: attachment.name,
+            data,
+            contentType: attachment.mimeType || fallbackMimeType(attachment.name),
+        });
+    }
+    return files;
+}
+export async function postDiscordAttachments(rest, channelId, attachments) {
+    const files = await buildRawFiles(attachments);
+    if (files.length === 0)
+        return [];
+    const data = (await rest.post(Routes.channelMessages(channelId), {
+        files,
+        body: {},
+        signal: AbortSignal.timeout(DISCORD_ATTACHMENT_SEND_TIMEOUT_MS),
+    }));
+    if (!data.id)
+        throw new Error("Discord attachment send failed: no message id returned");
+    return [data.id];
+}
+export function parseOutboundReply(text) {
+    const parsed = parseSilentMarker(text);
+    if (parsed.silent)
+        return parsed;
+    return { text: normalizeOutboundText(parsed.text), silent: false };
+}
+async function sendChunkedMessage(config, rest, channel, channelId, normalizedText, attachments, sendChunk) {
+    const chunks = chunkDiscord(config, normalizedText);
+    const sentIds = [];
+    for (const [index, chunk] of chunks.entries()) {
+        if (index > 0)
+            await delayBetweenBurstChunks(config, channel);
+        const sent = await sendChunk(chunk, index);
+        sentIds.push(sent.id);
+    }
+    const attachmentIds = await sendDiscordAttachments(rest, channelId, attachments);
+    return [...sentIds, ...attachmentIds];
+}
+export async function sendReply(config, rest, message, text, replyToMessageId, attachments = []) {
+    const normalizedText = normalizeOutboundText(text);
+    return sendChunkedMessage(config, rest, message.channel, message.channelId, normalizedText, attachments, async (chunk, index) => {
+        if (!message.channel.isSendable()) {
+            throw new Error(`Discord channel is not sendable: ${message.channelId}`);
+        }
+        if (index === 0 && config.discord.replyMode === "reply") {
+            try {
+                const replyTarget = replyToMessageId || message.id;
+                const options = { content: chunk, reply: { messageReference: replyTarget } };
+                return await message.channel.send(options);
+            }
+            catch (error) {
+                console.error("Discord reply failed; falling back to channel send", error);
+            }
+        }
+        return message.channel.send(chunk);
+    });
+}
+export async function sendChannelMessage(config, rest, channel, text, attachments = []) {
+    if (!channel.isSendable()) {
+        throw new Error("Discord channel is not sendable");
+    }
+    const normalizedText = normalizeOutboundText(text);
+    return sendChunkedMessage(config, rest, channel, channel.id, normalizedText, attachments, (chunk) => channel.send(chunk));
+}
+export async function sendDiscordAttachments(rest, channelId, attachments) {
+    if (attachments.length === 0)
+        return [];
+    try {
+        return await postDiscordAttachments(rest, channelId, attachments);
+    }
+    catch (error) {
+        console.error("Discord attachment send failed", error);
+        return [];
+    }
+}

package/dist/discord/turn.js

@@ -0,0 +1,55 @@
+import { createAgentEventRecorder, storedAgentEventFromAgentEvent, updateAgentEventSummary, } from "../agent-events.js";
+import { messageId } from "../ids.js";
+import { isHeartbeatDue } from "../scheduler.js";
+import { parseOutboundReply } from "./send.js";
+export const HEARTBEAT_SKIPPED = Symbol("heartbeat-skipped");
+export const CRON_SKIPPED = Symbol("cron-skipped");
+export function isCanceledJob(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.name === "CanceledJobError" || error.name === "AbortError" || /aborted|abort/i.test(error.message);
+}
+export function canceledJobError() {
+    const error = new Error("Job was canceled before completion.");
+    error.name = "CanceledJobError";
+    return error;
+}
+export function scheduledUserMessage(text, timestamp) {
+    return { role: "user", content: [{ type: "text", text }], timestamp };
+}
+export function heartbeatStillDue(config, now, lastUserInteractionAt, lastHeartbeatAt) {
+    return isHeartbeatDue({
+        now,
+        lastUserInteractionAt,
+        lastHeartbeatAt,
+        idleThresholdMs: config.heartbeat.idleThresholdMs,
+        intervalMs: config.heartbeat.intervalMs,
+    });
+}
+export async function runAgentTurn(jobKey, runtime, prompt) {
+    const assistantMessageId = messageId();
+    const summary = { thinking: "" };
+    const recorder = createAgentEventRecorder((storedEvent) => runtime.noteAgentEvent(jobKey, assistantMessageId, storedEvent, { notify: false }));
+    let reply;
+    try {
+        reply = await prompt(async (event) => {
+            updateAgentEventSummary(summary, event);
+            const storedEvent = storedAgentEventFromAgentEvent(event);
+            if (storedEvent) {
+                runtime.publishAgentEvent(jobKey, assistantMessageId, storedEvent);
+                await recorder.record(storedEvent);
+            }
+        });
+    }
+    finally {
+        await recorder.flush();
+    }
+    if (reply === HEARTBEAT_SKIPPED || reply === CRON_SKIPPED)
+        return null;
+    return {
+        reply,
+        parsedReply: parseOutboundReply(reply.text),
+        summary,
+        assistantMessageId,
+    };
+}