@qearlyao/familiar 0.1.1 → 0.2.0

package/dist/web.js

@@ -1,9 +1,16 @@
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { createServer } from "node:http";
+import { join } from "node:path";
+import { getProviders } from "@earendil-works/pi-ai";
+import { addModel, loadAddedModels, removeModel, setAddedModelsPath } from "./added-models.js";
 import { createAgentEventRecorder, storedAgentEventFromAgentEvent, thinkingDurationMs, updateAgentEventSummary, } from "./agent-events.js";
+import { clearConfigOverride, loadConfigOverrides, setConfigOverride } from "./config-overrides.js";
+import { CONFIG_KEYS, CONFIG_REGISTRY, getConfigDefault, isConfigKey } from "./config-registry.js";
+import { getContactNickname, refreshContactNote, setContactNotePath } from "./contact-note.js";
 import { publicAttachmentPath } from "./generated-media.js";
 import { materializeInboundAttachments } from "./inbound-attachments.js";
-import { supportedThinkingLevels } from "./models.js";
+import { PROVIDER_DEFAULTS, parseModelRef, supportedThinkingLevels } from "./models.js";
 import { loadPersona, parsePersonaName } from "./persona.js";
 import { createAuth, sessionCookie, verifyTotp } from "./web-auth.js";
 import { acceptWebSocket, decodeFrames, encodeFrame, replayEvents } from "./web-events.js";
@@ -23,6 +30,30 @@ function messageId(prefix = "msg") {
 function isUserVisibleRuntimeRecord(record) {
     return record.type !== "runtime" || !["armed", "reset", "stopped"].includes(record.event);
 }
+function parseMemeCatalog(markdown) {
+    const families = [];
+    let currentFamily;
+    for (const line of markdown.split(/\r?\n/)) {
+        const familyMatch = line.match(/^## (.+)$/);
+        if (familyMatch) {
+            currentFamily = { name: familyMatch[1]?.trim() ?? "", memes: [] };
+            families.push(currentFamily);
+            continue;
+        }
+        if (!currentFamily || !line.startsWith("- ") || !line.includes(" — "))
+            continue;
+        const separator = line.indexOf(" — ");
+        const name = line.slice(2, separator).trim();
+        const suffix = line.slice(separator + " — ".length).trim();
+        if (!name || !suffix)
+            continue;
+        currentFamily.memes.push({ name, url: `https://files.catbox.moe/${suffix}` });
+    }
+    return families;
+}
+function memeCatalogPath(config) {
+    return join(config.workspacePath, "skills", "memes", "SKILL.md");
+}
 function isWebUploadAttachment(value) {
     return !!value && typeof value === "object" && Buffer.isBuffer(value.buffer);
 }
@@ -258,7 +289,7 @@ function webMessageFromRecord(config, record, assistantName) {
         return {
             id: record.messageId,
             role: "user",
-            who: record.authorName || WEB_USER_NAME,
+            who: record.authorName || getContactNickname(WEB_USER_NAME),
             text: [record.text, attachmentText].filter(Boolean).join("\n"),
             attachments: webAttachments(config, record.attachments),
             ts: toUnixMs(record.ts),
@@ -323,6 +354,9 @@ function sessionDto(session) {
     };
 }
 export async function startWebDaemon(config, familiarAgent, discordDaemon, options = {}) {
+    setAddedModelsPath(config.workspace.dataDir);
+    setContactNotePath(config.persona.contact);
+    await refreshContactNote();
     const persona = await loadPersona(config);
     const personaName = parsePersonaName(persona.soul);
     const auth = createAuth(config);
@@ -397,7 +431,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     channelKey: runtime.channelKey,
                     messageId: record.messageId,
                     role: "user",
-                    who: record.authorName || WEB_USER_NAME,
+                    who: record.authorName || getContactNickname(WEB_USER_NAME),
                     ts: toUnixMs(record.ts),
                 });
                 publishDelta(runtime.channelKey, record.messageId, "text", record.text, toUnixMs(record.ts));
@@ -465,11 +499,50 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             return body.channelKey;
         return undefined;
     };
+    const getAgentModelsPayload = () => {
+        const models = [];
+        const added = [];
+        const seen = new Set();
+        for (const model of config.models.allow) {
+            if (seen.has(model))
+                continue;
+            seen.add(model);
+            models.push(model);
+        }
+        for (const model of loadAddedModels()) {
+            if (seen.has(model))
+                continue;
+            seen.add(model);
+            models.push(model);
+            added.push(model);
+        }
+        return { models, added };
+    };
+    const getConfigPayload = () => {
+        const overrides = loadConfigOverrides();
+        const values = {};
+        for (const key of CONFIG_KEYS) {
+            const entry = CONFIG_REGISTRY[key];
+            values[key] = {
+                value: entry.read(config),
+                source: key in overrides ? "override" : "config",
+            };
+        }
+        return { values };
+    };
+    const parseRequestedModel = (value) => {
+        if (typeof value !== "string")
+            return { ok: false, error: "format must be provider/model-id" };
+        const ref = parseModelRef(value);
+        if (!ref)
+            return { ok: false, error: "format must be provider/model-id" };
+        return { ok: true, model: ref.key, ref };
+    };
     const replay = (client, channelKey, lastEventId) => {
         const events = eventsByChannel.get(channelKey) ?? [];
         replayEvents(client, events, lastEventId, () => publish({ type: "replay_window_lost", channelKey }));
     };
-    const promptForRuntime = async (runtime, jobId, prompt, attachments = []) => {
+    const promptForRuntime = async (runtime, jobId, prompt, attachments = [], onTurnEnd) => {
         const assistantMessageId = messageId();
         const summary = { thinking: "" };
         const recorder = createAgentEventRecorder((storedEvent) => runtime.noteAgentEvent(jobId, assistantMessageId, storedEvent, { notify: false }));
@@ -486,7 +559,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     runtime.publishAgentEvent(jobId, assistantMessageId, storedEvent);
                     await recorder.record(storedEvent);
                 }
-            });
+            }, onTurnEnd);
         }
         finally {
             await recorder.flush();
@@ -524,7 +597,13 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
             if (!dispatch)
                 return;
             try {
-                const reply = await promptForRuntime(runtime, dispatch.job.jobId, dispatch.prompt, dispatch.attachments);
+                const reply = await promptForRuntime(runtime, dispatch.job.jobId, dispatch.prompt, dispatch.attachments, () => {
+                    publish({
+                        type: "status",
+                        channelKey: runtime.channelKey,
+                        kind: "idle",
+                    });
+                });
                 await runtime.completeActiveJob({
                     text: reply.text,
                     messageIds: [reply.messageId],
@@ -547,15 +626,8 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
     };
     const applyControlCommand = async (runtime, control) => {
         if (control.command === "stop") {
-            discordDaemon.abortWebRuntime(runtime);
-            await runtime.resetConversation("stop requested");
-            publish({
-                type: "status",
-                channelKey: runtime.channelKey,
-                kind: "idle",
-                detail: "Stopped current work and cleared the chat queue.",
-            });
-            return "Stopped current work and cleared the chat queue.";
+            familiarAgent.requestSoftStop(runtime.channelKey);
+            return "Stopped after current step. Conversation preserved.";
         }
         if (control.command === "new") {
             await familiarAgent.reset(runtime.channelKey);
@@ -628,7 +700,114 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                 return true;
             }
             if (request.method === "GET" && url.pathname === "/api/web/agent/models") {
-                sendJson(response, 200, { models: config.models.allow });
+                sendJson(response, 200, getAgentModelsPayload());
+                return true;
+            }
+            if (request.method === "POST" && url.pathname === "/api/web/agent/models") {
+                const body = await readJsonBody(request);
+                if (!isObject(body)) {
+                    sendJson(response, 400, { error: "body is required" });
+                    return true;
+                }
+                const parsed = parseRequestedModel(body.model);
+                if (!parsed.ok) {
+                    sendJson(response, 400, { error: parsed.error });
+                    return true;
+                }
+                if (!Object.hasOwn(PROVIDER_DEFAULTS, parsed.ref.provider) &&
+                    !getProviders().includes(parsed.ref.provider)) {
+                    sendJson(response, 400, { error: `unsupported provider: ${parsed.ref.provider}` });
+                    return true;
+                }
+                if (config.models.allow.includes(parsed.model) || loadAddedModels().includes(parsed.model)) {
+                    sendJson(response, 200, getAgentModelsPayload());
+                    return true;
+                }
+                await addModel(parsed.model);
+                sendJson(response, 200, getAgentModelsPayload());
+                return true;
+            }
+            if (request.method === "DELETE" && url.pathname === "/api/web/agent/models") {
+                const body = await readJsonBody(request);
+                if (!isObject(body)) {
+                    sendJson(response, 400, { error: "body is required" });
+                    return true;
+                }
+                const parsed = parseRequestedModel(body.model);
+                if (!parsed.ok) {
+                    sendJson(response, 400, { error: parsed.error });
+                    return true;
+                }
+                if (!loadAddedModels().includes(parsed.model)) {
+                    sendJson(response, 400, { error: "model is not user-added" });
+                    return true;
+                }
+                await removeModel(parsed.model);
+                sendJson(response, 200, getAgentModelsPayload());
+                return true;
+            }
+            if (request.method === "GET" && url.pathname === "/api/web/config") {
+                sendJson(response, 200, getConfigPayload());
+                return true;
+            }
+            if (request.method === "POST" && url.pathname === "/api/web/config") {
+                const body = await readJsonBody(request);
+                if (!isObject(body) || typeof body.key !== "string") {
+                    sendJson(response, 400, { error: "key is required" });
+                    return true;
+                }
+                if (!isConfigKey(body.key)) {
+                    sendJson(response, 400, { error: `unknown config key: ${body.key}` });
+                    return true;
+                }
+                const entry = CONFIG_REGISTRY[body.key];
+                try {
+                    const validated = entry.validate(body.value, config);
+                    entry.write(config, validated);
+                    await setConfigOverride(body.key, validated);
+                    await entry.apply?.({ config, discordDaemon });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    sendJson(response, 400, { error: message });
+                    return true;
+                }
+                sendJson(response, 200, getConfigPayload());
+                return true;
+            }
+            if (request.method === "DELETE" && url.pathname === "/api/web/config") {
+                const body = await readJsonBody(request);
+                if (!isObject(body) || typeof body.key !== "string") {
+                    sendJson(response, 400, { error: "key is required" });
+                    return true;
+                }
+                if (!isConfigKey(body.key)) {
+                    sendJson(response, 400, { error: `unknown config key: ${body.key}` });
+                    return true;
+                }
+                const entry = CONFIG_REGISTRY[body.key];
+                try {
+                    const fallback = getConfigDefault(body.key);
+                    entry.write(config, fallback);
+                    await clearConfigOverride(body.key);
+                    await entry.apply?.({ config, discordDaemon });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    sendJson(response, 400, { error: message });
+                    return true;
+                }
+                sendJson(response, 200, getConfigPayload());
+                return true;
+            }
+            if (request.method === "GET" && url.pathname === "/api/web/memes") {
+                try {
+                    const markdown = await readFile(memeCatalogPath(config), "utf8");
+                    sendJson(response, 200, { families: parseMemeCatalog(markdown) });
+                }
+                catch {
+                    sendJson(response, 500, { error: "memes catalog unavailable" });
+                }
                 return true;
             }
             if (request.method === "POST" && url.pathname === "/api/web/send") {
@@ -659,7 +838,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                 const input = {
                     messageId: id,
                     authorId: config.discord.ownerId,
-                    authorName: WEB_USER_NAME,
+                    authorName: getContactNickname(WEB_USER_NAME),
                     text: body.text,
                     isBot: false,
                     mentionedBot: true,
@@ -728,7 +907,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                 const input = {
                     messageId: messageId("control"),
                     authorId: config.discord.ownerId,
-                    authorName: WEB_USER_NAME,
+                    authorName: getContactNickname(WEB_USER_NAME),
                     text: `/${body.command}${args ? ` ${args}` : ""}`,
                     isBot: false,
                     mentionedBot: true,
@@ -804,14 +983,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
                     }
                     if (isObject(message) && message.type === "abort") {
                         void getRuntime(client.channelKey).then(async (runtime) => {
-                            discordDaemon.abortWebRuntime(runtime);
-                            await runtime.resetConversation("web abort requested");
-                            publish({
-                                type: "error",
-                                channelKey: runtime.channelKey,
-                                code: "abort",
-                                message: "Aborted current work.",
-                            });
+                            familiarAgent.requestSoftStop(runtime.channelKey);
                         });
                     }
                 }
@@ -847,3 +1019,7 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon, optio
         },
     };
 }
+export const __webTest = {
+    memeCatalogPath,
+    parseMemeCatalog,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -19,6 +19,7 @@
 		"USER.md",
 		"MEMORY.md",
 		"HEARTBEAT.md",
+		"CONTACT.md",
 		"skills/**",
 		"scripts/install.sh",
 		"scripts/install.ps1",
@@ -40,9 +41,9 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@earendil-works/pi-agent-core": "^0.74.1",
-		"@earendil-works/pi-ai": "^0.74.1",
-		"@earendil-works/pi-coding-agent": "^0.74.1",
+		"@earendil-works/pi-agent-core": "^0.75.3",
+		"@earendil-works/pi-ai": "^0.75.3",
+		"@earendil-works/pi-coding-agent": "^0.75.3",
 		"better-sqlite3": "^12.10.0",
 		"discord.js": "^14.26.3",
 		"dotenv": "^16.4.5",

package/scripts/install.ps1

@@ -3,6 +3,7 @@ param(
 	[string]$Package = "@qearlyao/familiar@latest",
 	[string]$BrowserHarnessDir = (Join-Path (Join-Path $HOME "Developer") "browser-harness"),
 	[switch]$WithBrowser,
+	[switch]$InstallBrowserDeps,
 	[switch]$SkipInit
 )
 
@@ -14,6 +15,47 @@ function Require-Command($Name) {
 	}
 }
 
+function Update-BrowserDepPath {
+	$candidates = @((Join-Path $HOME ".local\bin"), (Join-Path $HOME ".cargo\bin"))
+	foreach ($candidate in $candidates) {
+		if ((Test-Path $candidate) -and (($env:PATH -split [IO.Path]::PathSeparator) -notcontains $candidate)) {
+			$env:PATH = "$candidate$([IO.Path]::PathSeparator)$env:PATH"
+		}
+	}
+}
+
+function Confirm-BrowserDepInstall($Message) {
+	if ($InstallBrowserDeps) {
+		return $true
+	}
+	try {
+		$answer = Read-Host "$Message Install it now? [y/N]"
+		return $answer -match '^(y|yes)$'
+	} catch {
+		return $false
+	}
+}
+
+function Install-Uv {
+	Write-Host "Installing uv for browser-harness..."
+	irm https://astral.sh/uv/install.ps1 | iex
+	Update-BrowserDepPath
+	if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+		throw "uv installer finished, but uv is not on PATH. Open a new terminal or add $HOME\.local\bin to PATH."
+	}
+}
+
+function Ensure-Uv {
+	if (Get-Command uv -ErrorAction SilentlyContinue) {
+		return
+	}
+	if (Confirm-BrowserDepInstall "uv is required for browser-harness but was not found.") {
+		Install-Uv
+		return
+	}
+	throw "Missing required command: uv. Rerun with -WithBrowser -InstallBrowserDeps to install uv and Python 3.11 automatically."
+}
+
 function Test-Python311($Command, $PythonArgs = @()) {
 	& $Command @PythonArgs -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)" *> $null
 	return $LASTEXITCODE -eq 0
@@ -32,15 +74,31 @@ function Resolve-Python311 {
 	if ($py -and (Test-Python311 $py.Source @("-3.11"))) {
 		return @{ Command = $py.Source; Args = @("-3.11"); UvPython = "3.11" }
 	}
-	throw "browser-harness requires Python 3.11 or newer. Install Python 3.11+ and rerun with -WithBrowser."
+	return $null
+}
+
+function Ensure-Python311 {
+	$python311 = Resolve-Python311
+	if ($python311) {
+		return $python311
+	}
+	if (Confirm-BrowserDepInstall "Python 3.11+ is required for browser-harness but was not found.") {
+		Write-Host "Installing Python 3.11 with uv for browser-harness..."
+		& uv python install 3.11
+		if ($LASTEXITCODE -ne 0) {
+			throw "Python 3.11 install failed."
+		}
+		return @{ Command = "uv"; Args = @("python", "find", "3.11"); UvPython = "3.11" }
+	}
+	throw "browser-harness requires Python 3.11 or newer. Rerun with -WithBrowser -InstallBrowserDeps to install uv-managed Python 3.11 automatically."
 }
 
 Require-Command node
 Require-Command npm
 if ($WithBrowser) {
 	Require-Command git
-	Require-Command uv
-	$Python311 = Resolve-Python311
+	Ensure-Uv
+	$Python311 = Ensure-Python311
 }
 
 $nodeVersion = (& node -p "process.versions.node").Trim()
@@ -105,15 +163,10 @@ if (-not (Get-Command familiar -ErrorAction SilentlyContinue)) {
 }
 
 if (-not $SkipInit) {
-	$configPath = Join-Path $Workspace "config.toml"
-	if (Test-Path $configPath) {
-		Write-Host "Workspace already exists at $Workspace; leaving files unchanged."
-	} else {
-		Write-Host "Initializing workspace at $Workspace..."
-		& familiar init $Workspace
-		if ($LASTEXITCODE -ne 0) {
-			throw "familiar init failed."
-		}
+	Write-Host "Initializing or refreshing workspace defaults at $Workspace..."
+	& familiar init $Workspace
+	if ($LASTEXITCODE -ne 0) {
+		throw "familiar init failed."
 	}
 }
 

package/scripts/install.sh

@@ -5,6 +5,7 @@ PACKAGE="@qearlyao/familiar@latest"
 WORKSPACE="${HOME}/.familiar"
 BROWSER_HARNESS_DIR="${HOME}/Developer/browser-harness"
 WITH_BROWSER=0
+INSTALL_BROWSER_DEPS=0
 SKIP_INIT=0
 
 usage() {
@@ -14,6 +15,8 @@ Usage: install.sh [options]
 Options:
   --workspace <path>   Workspace path to initialize. Defaults to ~/.familiar.
   --with-browser       Also install optional OpenCLI and browser-harness helpers.
+  --install-browser-deps
+                       With --with-browser, install missing uv/Python 3.11 browser deps without prompting.
   --skip-init          Install familiar but do not run familiar init.
   --package <spec>     npm package spec to install. Defaults to @qearlyao/familiar@latest.
                        Advanced: installs the exact npm spec provided; use trusted specs only.
@@ -35,6 +38,10 @@ while [ "$#" -gt 0 ]; do
 			WITH_BROWSER=1
 			shift
 			;;
+		--install-browser-deps)
+			INSTALL_BROWSER_DEPS=1
+			shift
+			;;
 		--skip-init)
 			SKIP_INIT=1
 			shift
@@ -66,6 +73,63 @@ need_command() {
 	fi
 }
 
+refresh_browser_dep_path() {
+	for candidate in "${HOME}/.local/bin" "${HOME}/.cargo/bin"; do
+		if [ -d "$candidate" ]; then
+			case ":${PATH}:" in
+				*":${candidate}:"*) ;;
+				*) PATH="${candidate}:${PATH}" ;;
+			esac
+		fi
+	done
+	export PATH
+}
+
+confirm_browser_dep_install() {
+	if [ "$INSTALL_BROWSER_DEPS" -eq 1 ]; then
+		return 0
+	fi
+	if [ -r /dev/tty ] && [ -w /dev/tty ]; then
+		printf "%s Install it now? [y/N] " "$1" >/dev/tty
+		read -r answer </dev/tty || answer=""
+		case "$answer" in
+			y | Y | yes | YES) return 0 ;;
+		esac
+	fi
+	return 1
+}
+
+install_uv() {
+	echo "Installing uv for browser-harness..."
+	if command -v curl >/dev/null 2>&1; then
+		curl -LsSf https://astral.sh/uv/install.sh | sh
+	elif command -v wget >/dev/null 2>&1; then
+		wget -qO- https://astral.sh/uv/install.sh | sh
+	else
+		echo "Missing curl or wget, which is required to install uv automatically." >&2
+		echo "Install uv manually from https://docs.astral.sh/uv/ and rerun with --with-browser." >&2
+		exit 1
+	fi
+	refresh_browser_dep_path
+	if ! command -v uv >/dev/null 2>&1; then
+		echo "uv installer finished, but uv is not on PATH. Open a new terminal or add ~/.local/bin to PATH." >&2
+		exit 1
+	fi
+}
+
+ensure_uv() {
+	if command -v uv >/dev/null 2>&1; then
+		return 0
+	fi
+	if confirm_browser_dep_install "uv is required for browser-harness but was not found."; then
+		install_uv
+		return 0
+	fi
+	echo "Missing required command: uv" >&2
+	echo "Rerun with --with-browser --install-browser-deps to install uv and Python 3.11 automatically." >&2
+	exit 1
+}
+
 find_python() {
 	PYTHON_PATH=""
 	for candidate in python3 python; do
@@ -77,7 +141,21 @@ find_python() {
 			fi
 		fi
 	done
-	echo "browser-harness requires Python 3.11 or newer. Install Python 3.11+ and rerun with --with-browser." >&2
+	return 1
+}
+
+ensure_python() {
+	if find_python; then
+		return 0
+	fi
+	if confirm_browser_dep_install "Python 3.11+ is required for browser-harness but was not found."; then
+		echo "Installing Python 3.11 with uv for browser-harness..."
+		uv python install 3.11
+		PYTHON_PATH="3.11"
+		return 0
+	fi
+	echo "browser-harness requires Python 3.11 or newer." >&2
+	echo "Rerun with --with-browser --install-browser-deps to install uv-managed Python 3.11 automatically." >&2
 	exit 1
 }
 
@@ -85,8 +163,8 @@ need_command node
 need_command npm
 if [ "$WITH_BROWSER" -eq 1 ]; then
 	need_command git
-	need_command uv
-	find_python
+	ensure_uv
+	ensure_python
 fi
 
 NODE_VERSION="$(node -p "process.versions.node")"
@@ -127,12 +205,8 @@ if ! command -v familiar >/dev/null 2>&1; then
 fi
 
 if [ "$SKIP_INIT" -eq 0 ]; then
-	if [ -f "${WORKSPACE}/config.toml" ]; then
-		echo "Workspace already exists at ${WORKSPACE}; leaving files unchanged."
-	else
-		echo "Initializing workspace at ${WORKSPACE}..."
-		familiar init "$WORKSPACE"
-	fi
+	echo "Initializing or refreshing workspace defaults at ${WORKSPACE}..."
+	familiar init "$WORKSPACE"
 fi
 
 cat <<EOF