Merge branch 'pr-57'

This commit is contained in:
James Babcock committed 2026-11-01 00:29:16 -07:00
commit 7f3e3f2305
25 files changed
+1888 -41

No files matched your search

+21 -3
View File
@@ -116,12 +116,30 @@ provider; Faceclaw does not manage accounts or process billing information.
## AI Assistant Transcripts
Faceclaw has a builtin AI voice assistant. Using the voice assistant requires
providing an API key for a model provider such as Anthropic or OpenAI. Prompts
and responses are subject to that model provider's privacy policy:
Faceclaw has a builtin AI voice assistant. Using a cloud model requires
providing an API key for a model provider such as Anthropic, OpenAI, or Venice,
or configuring an OpenAI-compatible endpoint such as a private Open WebUI
server. Prompts and responses are subject to the selected provider or server
operator's privacy policy:
OpenAI: https://openai.com/policies/row-privacy-policy/
Anthropic: https://www.anthropic.com/legal/privacy
Venice: https://venice.ai/privacy
With an OpenAI-compatible provider, the configured server receives the
assistant system prompt, conversation history, available tool definitions, and
tool results needed to answer. Its URL, model ID, and optional API key are
stored on the phone. Faceclaw does not operate that server and cannot make
representations about its logging or retention; for a private Open WebUI
server, the server's operator controls those policies. If you choose Discover
models, Faceclaw also requests that server's model catalog using the same
configured URL and optional API key.
If you enable **Venice web search** for the official Venice API URL, supported
models may generate web-search queries from your assistant conversation. Those
queries and their results are processed by Venice's search service and are
subject to Venice's privacy policy and any applicable charges. This setting is
off by default and is never sent to Open WebUI or other compatible providers.
AI conversation histories and memory files may be stored on your phone.
Faceclaw does not transmit voice-assistant prompts or responses to any party
+47 -2
View File
@@ -65,8 +65,10 @@ import it into the new version (see [config transfer](scripts/config-transfer.md
* **A voice assistant** that wakes up when you say "Hey Even", transcribes
text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API,
and responds to queries and commands using an onboard model (Qwen3 4B,
slow) or with an Anthropic or OpenAI model (requires an API key), or using
your own long-running OpenClaw agent.
slow) or with an Anthropic, OpenAI, or OpenAI-compatible Chat Completions
model (including Venice and private Open WebUI servers; model ID and
usually an API key required), with optional Venice web search for supported
models, or using your own long-running OpenClaw agent.
* **Multitasking**, with an app-switcher sidebar and app launcher.
* **Glanceboard**, a dashboard with widgets that you can quickly view with a
* **Mostly-compatible with EvenHub.** Install and runapps from the Even app
@@ -96,6 +98,49 @@ import it into the new version (see [config transfer](scripts/config-transfer.md
the glasses, and you can use the phone touchscreen as an input device..
<!-- END GENERATED: features -->
## OpenAI-compatible assistant providers (Venice / Open WebUI)
The assistant can call an OpenAI-compatible **Chat Completions** endpoint directly
from the phone. This uses the same conversation history and glasses tool loop as
the built-in cloud providers; it does not require different glasses firmware.
In **Settings > Assistant**, set:
1. **Compatible API URL** — the explicit API root.
2. **Compatible model ID** — the exact model identifier accepted by the server.
3. **Compatible API key** — optional; when set, it is sent only to the configured
compatible endpoint as a Bearer token, not to OpenAI's Whisper service.
4. Optional: choose **Discover models**, then pick a model from the server catalog.
The picker shows tool capability when advertised and hides offline models by
default. Refresh never changes the saved model by itself.
5. **Assistant model** — choose **OpenAI-compatible**. Auto never selects it.
Provider examples:
| Provider | Compatible API URL | Notes |
| --- | --- | --- |
| Venice | `https://api.venice.ai/api/v1` | Use a current Venice model ID. Choose one with function-calling support if you want glasses tools. |
| Open WebUI | `https://your-openwebui-host/api` | This produces `/api/chat/completions`. Use the model ID exposed by your server and an Open WebUI API key if required. |
You may paste the full `/chat/completions` endpoint instead; Faceclaw removes
that suffix. It otherwise preserves the path you enter and does not guess `/v1`
or `/api`. Discovery requests `{API root}/models` only when you choose it; there
is no background discovery or automatic model selection. Manual model entry
remains available for servers without a compatible model-list endpoint.
For the official Venice URL, **Settings > Assistant** also shows **Venice web
search**. It is off by default and visible only for that URL. When enabled,
supported Venice models may search the web for current information; the search
model must support the feature. Open WebUI and other compatible servers never
receive Venice-specific parameters, including after an endpoint switch.
The same provider can supply Calculator's rewrite fallback and Translate.
Actual tool calling depends on the selected model and server. Use HTTPS where
possible; mobile cleartext policies may block plain HTTP. For a private server,
make it reachable from the phone (for example through your tailnet) without
exposing it publicly. Exported settings contain API keys and must be treated as
secrets.
## Watch remote (Wear OS)
The `wear/` directory holds a companion app for Wear OS 3+ watches that turns
+8 -3
View File
@@ -4,7 +4,7 @@ import { truncateText, wrapText } from "../../graphics/textwrap";
import { ASSISTANT_MODEL_CHOICES, assistantModelLabel, resolveAssistantModel } from "../../assistant/models";
import type { AssistantTranscriptEntry } from "../../assistant/session";
import type { AssistantConversations, ReasoningLevel } from "../../assistant/conversations";
import { anthropicApiKeySetting, assistantBackendSetting, openAiApiKeySetting } from "../../ui/dashboard-settings";
import { anthropicApiKeySetting, assistantBackendSetting, assistantOpenAiCompatibleKeySetting, assistantOpenAiCompatibleModelSetting, assistantOpenAiCompatibleUrlSetting, openAiApiKeySetting } from "../../ui/dashboard-settings";
import { GESTURE_CLICK, GESTURE_DOUBLE_CLICK, GESTURE_LONG_PRESS, gestureHints, type InputEvent } from "../../ui/gestures";
import type { Layer, LayerContext } from "../../ui/layers";
import type { MenuItem } from "../../ui/menu";
@@ -102,7 +102,7 @@ class AiChatLayer implements Layer {
}
case "long-press":
if (!this.conversations.current().session?.isTurnActive()) {
if (!shell.isAssistantAvailable()) { shell.showAlert(global.isIOS ? "Set an OpenAI or Anthropic API key in Settings." : "Set an API key or download the on-phone model in Settings."); return; }
if (!shell.isAssistantAvailable()) { shell.showAlert(global.isIOS ? "Configure an assistant model in Settings." : "Set an API key or download the on-phone model in Settings."); return; }
void this.draft.start();
}
return;
@@ -133,7 +133,12 @@ class AiChatLayer implements Layer {
onSelect: (pickCtx) => { if (this.conversations.configure(model, record.reasoning)) pickCtx.stack.clearToBase(); },
}))) },
{ label: `Reasoning: ${record.reasoning}`, disabled: () => {
const llm = resolveAssistantModel(record.model, { anthropic: anthropicApiKeySetting.get(), openai: openAiApiKeySetting.get() });
const llm = resolveAssistantModel(record.model, {
anthropic: anthropicApiKeySetting.get(), openai: openAiApiKeySetting.get(),
openAiCompatibleUrl: assistantOpenAiCompatibleUrlSetting.get(),
openAiCompatibleKey: assistantOpenAiCompatibleKeySetting.get(),
openAiCompatibleModel: assistantOpenAiCompatibleModelSetting.get(),
});
return external || busy() || !llm?.effort;
}, onSelect: (ctx) => submenu(ctx, "Reasoning", (["default", "low", "medium", "high"] as ReasoningLevel[]).map((reasoning) => ({
label: `${reasoning === record.reasoning ? "✓ " : ""}${reasoning === "default" ? "Model default" : reasoning}`,
+10
View File
@@ -9,11 +9,15 @@
import { streamAnthropicMessage } from "../../native/anthropic";
import { streamLocalModel } from "../../native/local-llm";
import { streamOpenAiResponse } from "../../native/openai";
import { streamOpenAiCompatibleChat } from "../../native/openai-chat";
import { resolveAssistantModel } from "../../assistant/models";
import { type LlmStreamOptions } from "../../assistant/llm-protocol";
import {
anthropicApiKeySetting,
assistantModelSetting,
assistantOpenAiCompatibleKeySetting,
assistantOpenAiCompatibleModelSetting,
assistantOpenAiCompatibleUrlSetting,
openAiApiKeySetting,
} from "../../ui/dashboard-settings";
import { CALCULATOR_REWRITE_SYSTEM_PROMPT, buildCalculatorRewriteUserMessage } from "../../prompts";
@@ -22,6 +26,9 @@ export function rewriteSpokenProblem(spoken: string): Promise<string | null> {
const resolved = resolveAssistantModel(assistantModelSetting.get(), {
anthropic: anthropicApiKeySetting.get(),
openai: openAiApiKeySetting.get(),
openAiCompatibleUrl: assistantOpenAiCompatibleUrlSetting.get(),
openAiCompatibleKey: assistantOpenAiCompatibleKeySetting.get(),
openAiCompatibleModel: assistantOpenAiCompatibleModelSetting.get(),
});
if (!resolved) return Promise.resolve(null);
@@ -40,6 +47,9 @@ export function rewriteSpokenProblem(spoken: string): Promise<string | null> {
case "openai":
streamOpenAiResponse(options);
break;
case "openai-compatible":
streamOpenAiCompatibleChat({ ...options, baseUrl: resolved.baseUrl ?? "" });
break;
case "local":
streamLocalModel(options);
break;
+2 -2
View File
@@ -28,8 +28,8 @@ const TRAY_ICON_ID = "translate";
const NO_PROVIDER_PROBLEM =
"Translate needs a transcription provider that understands any language: add an ElevenLabs, OpenAI, or Soniox API key (Settings > API Keys), or a Whisper server URL (Settings > Voice).";
const NO_MODEL_PROBLEM = global.isIOS
? "Translate needs a language model: add an Anthropic or OpenAI API key (Settings > API Keys)."
: "Translate needs a language model: add an Anthropic or OpenAI API key (Settings > API Keys), or download the on-phone model (Settings > Assistant).";
? "Translate needs a language model: configure a cloud or OpenAI-compatible model in Settings > Assistant."
: "Translate needs a language model: configure one in Settings > Assistant, or download the on-phone model.";
export type TranslateAppOptions = InProcessAppOptions & {
/** Begin (or retarget) continuous mic capture, kept on while the window is open. */
+10 -1
View File
@@ -6,9 +6,13 @@
import { streamAnthropicMessage } from "../../native/anthropic";
import { streamLocalModel } from "../../native/local-llm";
import { streamOpenAiResponse } from "../../native/openai";
import { streamOpenAiCompatibleChat } from "../../native/openai-chat";
import { resolveAssistantModel, type ResolvedAssistantModel } from "../../assistant/models";
import { type LlmStreamHandle, type LlmStreamOptions } from "../../assistant/llm-protocol";
import { anthropicApiKeySetting, assistantModelSetting, openAiApiKeySetting } from "../../ui/dashboard-settings";
import {
anthropicApiKeySetting, assistantModelSetting, assistantOpenAiCompatibleKeySetting,
assistantOpenAiCompatibleModelSetting, assistantOpenAiCompatibleUrlSetting, openAiApiKeySetting,
} from "../../ui/dashboard-settings";
import { TRANSLATE_SYSTEM_PROMPT, buildTranslateUserMessage } from "../../prompts";
import { type TranslationTurn } from "./translation-model";
@@ -23,6 +27,9 @@ export function resolveTranslationModel(): ResolvedAssistantModel | null {
return resolveAssistantModel(selection === "hermes" ? "auto" : selection, {
anthropic: anthropicApiKeySetting.get(),
openai: openAiApiKeySetting.get(),
openAiCompatibleUrl: assistantOpenAiCompatibleUrlSetting.get(),
openAiCompatibleKey: assistantOpenAiCompatibleKeySetting.get(),
openAiCompatibleModel: assistantOpenAiCompatibleModelSetting.get(),
});
}
@@ -54,6 +61,8 @@ export function streamTranslation(model: ResolvedAssistantModel, request: Transl
switch (model.provider) {
case "openai":
return streamOpenAiResponse(options);
case "openai-compatible":
return streamOpenAiCompatibleChat({ ...options, baseUrl: model.baseUrl ?? "" });
case "local":
return streamLocalModel(options);
default:
+7 -1
View File
@@ -2,6 +2,7 @@ import { streamAnthropicMessage } from "../native/anthropic";
import { streamHermesChat } from "../native/hermes";
import { streamLocalModel } from "../native/local-llm";
import { streamOpenAiResponse } from "../native/openai";
import { streamOpenAiCompatibleChat } from "../native/openai-chat";
import type {
LlmContentBlock,
LlmMessage,
@@ -40,6 +41,8 @@ export type DirectTurnOptions = {
effort?: "low" | "medium" | "high";
/** Hermes: the API root, and the server-side session this conversation maps to. */
baseUrl?: string;
/** Venice-only web search for this interactive turn. */
webSearch?: boolean;
sessionId?: string;
system: string;
/** Owned by the session; this loop appends assistant + tool_result messages. */
@@ -85,11 +88,12 @@ export class DirectAssistantBackend {
return;
}
const streamOptions: LlmStreamOptions = {
const streamOptions: LlmStreamOptions & { webSearch?: boolean } = {
apiKey: options.apiKey,
model: options.model,
system: options.system,
effort: options.effort,
webSearch: options.webSearch,
messages: options.messages,
// Hermes runs its own tools; Faceclaw's are not offered to it.
tools: options.provider === "hermes" ? [] : options.buildTools(),
@@ -143,6 +147,8 @@ export class DirectAssistantBackend {
streamHandle =
options.provider === "hermes"
? streamHermesChat({ ...streamOptions, baseUrl: options.baseUrl ?? "", sessionId: options.sessionId ?? "" })
: options.provider === "openai-compatible"
? streamOpenAiCompatibleChat({ ...streamOptions, baseUrl: options.baseUrl ?? "" })
: options.provider === "openai"
? streamOpenAiResponse(streamOptions)
: options.provider === "local"
+1 -1
View File
@@ -15,7 +15,7 @@ export type LlmContentBlock =
}
| { type: "tool_result"; tool_use_id: string; content: string; is_error?: boolean }
/** Opaque state required to continue a provider's stateless conversation. */
| { type: "provider_item"; provider: "openai"; item: any };
| { type: "provider_item"; provider: "openai" | "openai-compatible"; item: any };
export type LlmMessage = {
role: "user" | "assistant";
+25 -2
View File
@@ -1,4 +1,5 @@
import { isLocalModelReady, isLocalModelSupported, LOCAL_MODEL } from "../native/local-llm";
import { isVeniceApiBaseUrl } from "../native/openai-chat";
export const ASSISTANT_MODEL_VALUES = [
"auto",
@@ -11,6 +12,7 @@ export const ASSISTANT_MODEL_VALUES = [
"sol",
"qwen",
"hermes",
"openai-compatible",
] as const;
/**
@@ -26,7 +28,7 @@ export function supportedAssistantModel(value: AssistantModel): AssistantModel {
return value === "qwen" && !isLocalModelSupported() ? "auto" : value;
}
export type AssistantProvider = "anthropic" | "openai" | "local" | "hermes";
export type AssistantProvider = "anthropic" | "openai" | "local" | "hermes" | "openai-compatible";
export type AssistantApiKeys = {
anthropic: string;
@@ -34,6 +36,11 @@ export type AssistantApiKeys = {
/** A Hermes Agent API server; only the voice assistant passes these. */
hermesUrl?: string;
hermesKey?: string;
openAiCompatibleUrl?: string;
openAiCompatibleKey?: string;
openAiCompatibleModel?: string;
/** Venice web search, applied only when the resolved root is Venice. */
veniceWebSearch?: boolean;
};
export type ResolvedAssistantModel = {
@@ -42,8 +49,10 @@ export type ResolvedAssistantModel = {
model: string;
apiKey: string;
effort?: "low" | "medium" | "high";
/** API root for providers that are not fixed services (Hermes). */
/** API root for Hermes or an OpenAI-compatible provider. */
baseUrl?: string;
/** Whether Venice web search is enabled for this interactive assistant turn. */
webSearch?: boolean;
};
type ModelDefinition = {
@@ -69,6 +78,7 @@ const MODEL_DEFINITIONS: Record<Exclude<AssistantModel, "auto">, ModelDefinition
qwen: { label: `${LOCAL_MODEL.label} (on-phone)`, provider: "local", model: LOCAL_MODEL.id },
// Your own Hermes Agent (its API server), with its own tools and memory.
hermes: { label: "Hermes agent", provider: "hermes", model: "hermes-agent" },
"openai-compatible": { label: "OpenAI-compatible", provider: "openai-compatible", model: "custom" },
};
export function assistantModelLabel(value: AssistantModel): string {
@@ -112,6 +122,19 @@ export function resolveAssistantModel(
if (!baseUrl) return null;
return { selection, provider: "hermes", model: definition.model, apiKey: keys.hermesKey?.trim() ?? "", baseUrl };
}
if (definition.provider === "openai-compatible") {
const baseUrl = keys.openAiCompatibleUrl?.trim() ?? "";
const model = keys.openAiCompatibleModel?.trim() ?? "";
if (!baseUrl || !model) return null;
return {
selection,
provider: definition.provider,
model,
apiKey: keys.openAiCompatibleKey?.trim() ?? "",
baseUrl,
webSearch: isVeniceApiBaseUrl(baseUrl) && keys.veniceWebSearch === true,
};
}
if (definition.provider === "local") {
if (!isLocalModelReady()) return null;
return {
+9 -2
View File
@@ -95,14 +95,20 @@ export class AssistantSession {
// original model. Preserve visible conversation when switching engines.
if (this.config.kind !== config.kind ||
(this.config.kind === "direct" && config.kind === "direct" &&
(this.config.llm.model !== config.llm.model || this.config.llm.provider !== config.llm.provider))) {
(this.config.llm.model !== config.llm.model || this.config.llm.provider !== config.llm.provider ||
(this.config.llm.baseUrl ?? "") !== (config.llm.baseUrl ?? "")))) {
this.rebuildTextHistory();
}
this.config = config;
}
private engine(): string {
return this.config.kind === "direct" ? `${this.config.llm.provider}:${this.config.llm.model}` : "external";
if (this.config.kind !== "direct") return "external";
const llm = this.config.llm;
// Keep the legacy engine ID for built-in providers so upgrading does not
// discard their opaque history. Custom endpoints need endpoint isolation.
const endpoint = llm.provider === "openai-compatible" ? `:${llm.baseUrl ?? ""}` : "";
return `${llm.provider}:${llm.model}${endpoint}`;
}
private rebuildTextHistory(): void {
@@ -192,6 +198,7 @@ export class AssistantSession {
model: llm.model,
effort: llm.effort,
baseUrl: llm.baseUrl,
webSearch: llm.webSearch,
sessionId: this.hermesSessionId,
system: llm.provider === "hermes" ? HERMES_SYSTEM_PROMPT
: isLocal ? ASSISTANT_SYSTEM_PROMPT_BASE : buildAssistantSystemPrompt(ctx),
+159
View File
@@ -0,0 +1,159 @@
import { fetchTextWithUserAgent, type TextResponse } from "../util/http";
import { normalizeOpenAiCompatibleUrl } from "./openai-chat";
export type DiscoveredCompatibleModel = {
/** Exact identifier to send as model in Chat Completions. */
id: string;
/** Human-friendly catalog name, or id when the server supplies no name. */
name: string;
/** true/false when advertised; null means the server did not say. */
supportsTools: boolean | null;
offline: boolean;
deprecated: boolean;
beta: boolean;
};
type DiscoveryOptions = {
baseUrl: string;
apiKey: string;
/** Bypass the short-lived successful-response cache. */
forceRefresh?: boolean;
};
type DiscoveryResponse = Pick<TextResponse, "status" | "text">;
type DiscoveryHttp = (url: string, init: {
method: string;
headers: Record<string, string>;
timeoutMs: number;
dontFollowRedirects: boolean;
}) => Promise<DiscoveryResponse>;
type DiscoveryDependencies = {
http?: DiscoveryHttp;
now?: () => number;
};
type CacheEntry = {
apiKey: string;
fetchedAt: number;
models: DiscoveredCompatibleModel[];
};
export const COMPATIBLE_MODEL_DISCOVERY_TIMEOUT_MS = 10_000;
const CACHE_TTL_MS = 60_000;
const MAX_MODELS = 500;
const MAX_DISCOVERY_BODY_CHARS = 2_000_000;
const cache = new Map<string, CacheEntry>();
/**
* Discover models from the configured server's own /models endpoint. No URL
* probing, inference calls, disk persistence, or automatic model selection.
*/
export async function discoverOpenAiCompatibleModels(
options: DiscoveryOptions,
dependencies: DiscoveryDependencies = {},
): Promise<DiscoveredCompatibleModel[]> {
const baseUrl = normalizeOpenAiCompatibleUrl(options.baseUrl);
if (!baseUrl) throw new Error("Set a valid compatible API URL first");
const apiKey = options.apiKey.trim();
const now = dependencies.now ?? Date.now;
const cached = cache.get(baseUrl);
if (!options.forceRefresh && cached && cached.apiKey === apiKey && now() - cached.fetchedAt < CACHE_TTL_MS) {
return cached.models;
}
const http = dependencies.http ?? defaultHttp;
const headers: Record<string, string> = {};
if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
let response: DiscoveryResponse;
try {
response = await http(`${baseUrl}/models`, {
method: "GET",
headers,
timeoutMs: COMPATIBLE_MODEL_DISCOVERY_TIMEOUT_MS,
// Do not forward a credential to a redirect target.
dontFollowRedirects: true,
});
} catch {
throw new Error("Could not reach the configured server");
}
if (response.status < 200 || response.status >= 300) {
throw new Error(describeHttpError(response.status));
}
let body: any;
let rawBody: string;
try {
rawBody = await response.text();
if (rawBody.length > MAX_DISCOVERY_BODY_CHARS) throw new Error("too large");
body = JSON.parse(rawBody);
} catch {
throw new Error("The server returned an invalid model list");
}
if (!body || !Array.isArray(body.data)) {
throw new Error("The server did not return an OpenAI-compatible model list");
}
const models = parseModels(body.data);
cache.set(baseUrl, { apiKey, fetchedAt: now(), models });
return models;
}
/** Parse OpenAI data[] rows, retaining richer Venice metadata when present. */
export function parseDiscoveredCompatibleModels(rows: any[]): DiscoveredCompatibleModel[] {
return parseModels(rows);
}
function parseModels(rows: any[]): DiscoveredCompatibleModel[] {
const byId = new Map<string, DiscoveredCompatibleModel>();
for (const row of rows) {
if (!row || typeof row.id !== "string" || !row.id.trim()) continue;
const id = row.id.trim();
if (byId.has(id)) continue;
const spec = row.model_spec && typeof row.model_spec === "object" ? row.model_spec : null;
const capabilities = spec?.capabilities && typeof spec.capabilities === "object" ? spec.capabilities : null;
const catalogName = typeof spec?.name === "string" ? spec.name.trim() : "";
const genericName = typeof row.name === "string" ? row.name.trim() : "";
byId.set(id, {
id,
name: catalogName || genericName || id,
supportsTools: typeof capabilities?.supportsFunctionCalling === "boolean"
? capabilities.supportsFunctionCalling
: null,
offline: spec?.offline === true,
deprecated: Boolean(spec?.deprecation),
beta: spec?.betaModel === true || spec?.beta === true,
});
if (byId.size >= MAX_MODELS) break;
}
return Array.from(byId.values()).sort((a, b) => {
if (a.offline !== b.offline) return a.offline ? 1 : -1;
const aTools = a.supportsTools === true ? 0 : a.supportsTools === null ? 1 : 2;
const bTools = b.supportsTools === true ? 0 : b.supportsTools === null ? 1 : 2;
if (aTools !== bTools) return aTools - bTools;
return (a.name || a.id).localeCompare(b.name || b.id) || a.id.localeCompare(b.id);
});
}
async function defaultHttp(url: string, init: {
method: string;
headers: Record<string, string>;
timeoutMs: number;
dontFollowRedirects: boolean;
}): Promise<DiscoveryResponse> {
return fetchTextWithUserAgent(url, init);
}
function describeHttpError(status: number): string {
if (status === 401) return "The server rejected the API key (HTTP 401)";
if (status === 403) return "The API key cannot list these models (HTTP 403)";
if (status === 404) return "Model discovery is not supported at this URL (HTTP 404)";
if (status === 429) return "The server is rate limiting requests (HTTP 429)";
if (status >= 500) return `The server is unavailable (HTTP ${status})`;
if (status >= 300 && status < 400) return `The server redirected the request; use its direct API URL (HTTP ${status})`;
return `Model discovery failed (HTTP ${status})`;
}
/** Test hook; does not affect any saved setting. */
export function clearCompatibleModelDiscoveryCache(): void {
cache.clear();
}
+284
View File
@@ -0,0 +1,284 @@
import type {
LlmContentBlock,
LlmStreamHandle,
LlmStreamOptions,
} from "../assistant/llm-protocol";
import { openSseRequest, type SseListener } from "./sse";
/** True only for Venice's official API root, never for lookalike hosts. */
export function isVeniceApiBaseUrl(input: string): boolean {
return normalizeOpenAiCompatibleUrl(input) === "https://api.venice.ai/api/v1";
}
/** Streaming client for OpenAI-compatible Chat Completions APIs. */
export type OpenAiCompatibleStreamOptions = LlmStreamOptions & {
/** Explicit API root, for example https://api.venice.ai/api/v1 or https://host/api. */
baseUrl: string;
/** Venice-only web search; never sent to other compatible providers. */
webSearch?: boolean;
};
type PendingToolCall = {
id: string;
name: string;
inputJson: string;
};
/** Remove an optional endpoint suffix, but never guess a provider's /v1 or /api prefix. */
export function normalizeOpenAiCompatibleUrl(input: string): string {
let url = input.trim().replace(/\/+$/, "");
url = url.replace(/\/chat\/completions$/i, "").replace(/\/+$/, "");
return /^https?:\/\/[^/\s?#@\\]+(?:\/[^\s?#\\]*)?$/i.test(url) ? url : "";
}
export function streamOpenAiCompatibleChat(options: OpenAiCompatibleStreamOptions): LlmStreamHandle {
const apiKey = options.apiKey.trim();
const baseUrl = normalizeOpenAiCompatibleUrl(options.baseUrl);
let request: { cancel(): void } | null = null;
let settled = false;
let text = "";
let finishReason: string | null = null;
const toolCalls = new Map<number, PendingToolCall>();
const providerMetadata: Record<string, any> = {};
const fail = (message: string) => {
if (settled) return;
settled = true;
request?.cancel();
options.onError(message);
};
const done = () => {
if (settled) return;
const hasToolCalls = toolCalls.size > 0;
// Never execute calls from a truncated stream or a length-limited response.
if (hasToolCalls && finishReason !== "tool_calls" && finishReason !== "stop") {
fail("OpenAI-compatible stream ended before its tool calls completed");
return;
}
if (!text && !hasToolCalls) {
fail("OpenAI-compatible provider ended the turn without a reply");
return;
}
const content: LlmContentBlock[] = [];
if (text) content.push({ type: "text", text });
if (Object.keys(providerMetadata).length) {
content.push({ type: "provider_item", provider: "openai-compatible", item: providerMetadata });
}
for (const index of Array.from(toolCalls.keys()).sort((a, b) => a - b)) {
const call = toolCalls.get(index)!;
if (!call.name) {
fail("OpenAI-compatible provider returned a tool call without a name");
return;
}
let input: any = {};
if (call.inputJson.trim()) {
try {
input = JSON.parse(call.inputJson);
} catch {
fail("OpenAI-compatible provider returned malformed tool arguments");
return;
}
}
content.push({
type: "tool_use",
id: call.id || `call_${index + 1}`,
name: call.name,
input,
});
}
settled = true;
request?.cancel();
options.onDone({
text,
content,
stopReason: finishReason === "content_filter" ? "refusal"
: hasToolCalls ? "tool_use"
: finishReason === "length" ? "max_tokens" : "end_turn",
});
};
if (!baseUrl || !options.model.trim()) {
setTimeout(() => fail(!baseUrl
? "Set a valid OpenAI-compatible API URL"
: "Set an OpenAI-compatible model ID"), 0);
return { cancel: () => { settled = true; } };
}
const body: any = {
model: options.model.trim(),
messages: buildChatMessages(options),
stream: true,
};
// Let the provider choose its default unless a one-shot feature supplies a cap.
if (options.maxTokens !== undefined) body.max_tokens = options.maxTokens;
if (options.tools?.length) {
body.tools = options.tools.map((tool) => ({
type: "function",
function: {
name: tool.name,
description: tool.description,
parameters: tool.input_schema,
},
}));
}
// Provider-specific parameters must never leak to another endpoint, even
// when a saved Venice preference is still enabled.
if (options.webSearch === true && isVeniceApiBaseUrl(baseUrl)) {
body.venice_parameters = { enable_web_search: "on" };
}
// Do not send provider-specific reasoning fields by default. Compatible
// servers vary widely; advanced reasoning controls can be added separately.
const headers: Record<string, string> = { "Content-Type": "application/json" };
if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
const listener: SseListener = {
onLine: (line: string) => {
if (settled || !line.startsWith("data:")) return;
const payload = line.slice(5).trim();
if (!payload) return;
if (payload === "[DONE]") {
if (finishReason || (!toolCalls.size && text)) done();
else fail("OpenAI-compatible stream ended before the response completed");
return;
}
let event: any;
try {
event = JSON.parse(payload);
} catch {
return;
}
if (event?.error) {
fail(`OpenAI-compatible: ${String(event.error.message ?? event.error)}`);
return;
}
const choice = event?.choices?.[0];
if (!choice) return; // Usage and provider-metadata chunks may have no choices.
const delta = choice.delta ?? {};
if (typeof delta.content === "string" && delta.content) {
text += delta.content;
options.onTextDelta?.(delta.content, text);
}
// Reasoning is not displayed. Preserve provider metadata for replay in
// multi-turn tool loops when the service supplies it.
if (delta.reasoning_details !== undefined) providerMetadata.reasoning_details = delta.reasoning_details;
if (delta.thought_signature !== undefined) providerMetadata.thought_signature = delta.thought_signature;
if (Array.isArray(delta.tool_calls)) {
delta.tool_calls.forEach((call: any, position: number) => {
const index = Number.isInteger(call?.index) ? Number(call.index) : position;
const pending = toolCalls.get(index) ?? { id: "", name: "", inputJson: "" };
if (call?.id) pending.id = String(call.id);
if (call?.function?.name) pending.name = String(call.function.name);
if (typeof call?.function?.arguments === "string") pending.inputJson += call.function.arguments;
toolCalls.set(index, pending);
});
}
if (choice.finish_reason) finishReason = String(choice.finish_reason);
},
onHttpError: (code: number, errorBody: string) => fail(describeHttpError(Number(code), String(errorBody))),
onComplete: () => {
// Some compatible servers close after the finish chunk without [DONE].
if (finishReason) done();
else fail("OpenAI-compatible stream ended before the response completed");
},
onFailure: (message: string) => fail(`OpenAI-compatible connection failed: ${String(message)}`),
};
try {
request = openSseRequest(`${baseUrl}/chat/completions`, JSON.stringify(body), headers, listener);
} catch (error) {
setTimeout(() => fail(`OpenAI-compatible request failed: ${String((error as Error)?.message ?? error)}`), 0);
return { cancel: () => { settled = true; } };
}
return {
cancel: () => {
settled = true;
try { request?.cancel(); } catch { /* ignore */ }
},
};
}
/** Convert neutral conversation history to Chat Completions messages. */
function buildChatMessages(options: OpenAiCompatibleStreamOptions): any[] {
const messages: any[] = [];
if (options.system) messages.push({ role: "system", content: options.system });
for (const message of options.messages) {
if (typeof message.content === "string") {
messages.push({ role: message.role, content: message.content });
continue;
}
if (message.role === "assistant") {
let text = "";
const toolCalls: any[] = [];
let providerMetadata: Record<string, any> = {};
for (const block of message.content) {
if (block.type === "text") text += block.text;
else if (block.type === "tool_use") {
toolCalls.push({
id: block.id,
type: "function",
function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
});
} else if (block.type === "provider_item" && block.provider === "openai-compatible") {
providerMetadata = { ...providerMetadata, ...block.item };
}
}
if (text || toolCalls.length) {
messages.push({
role: "assistant",
content: text || (toolCalls.length ? null : ""),
...(toolCalls.length ? { tool_calls: toolCalls } : {}),
...providerMetadata,
});
}
continue;
}
let pendingText = "";
const flushText = () => {
if (!pendingText) return;
messages.push({ role: "user", content: pendingText });
pendingText = "";
};
for (const block of message.content) {
if (block.type === "text") pendingText += block.text;
else if (block.type === "tool_result") {
flushText();
messages.push({
role: "tool",
tool_call_id: block.tool_use_id,
content: block.is_error ? `Error: ${block.content}` : block.content,
});
}
}
flushText();
}
return messages;
}
function describeHttpError(code: number, body: string): string {
let detail = "";
try {
const parsed = JSON.parse(body);
detail = String(parsed?.error?.message ?? parsed?.error ?? parsed?.message ?? "");
} catch {
// Non-JSON error body.
}
switch (code) {
case 401: return "OpenAI-compatible: invalid API key";
case 403: return "OpenAI-compatible: API key lacks permission";
case 429: return "OpenAI-compatible: rate limited, try again shortly";
case 500:
case 502:
case 503:
case 504:
return "OpenAI-compatible: service unavailable, try again shortly";
default: return `OpenAI-compatible: HTTP ${code}${detail ? ` (${detail})` : ""}`;
}
}
+46 -2
View File
@@ -18,6 +18,7 @@ import {
} from "~/assistant/models";
import { isLocalModelReady } from "../native/local-llm";
import { normalizeWhisperServerUrl } from "../native/whisper-server-stt";
import { normalizeOpenAiCompatibleUrl } from "../native/openai-chat";
import { isValidSpotifyClientId, SPOTIFY_CLIENT_ID_KEY } from "../native/spotify-auth";
import { drawRightValueMenuItem, drawToggleMenuItem, MenuItem, openModalMenu } from "./menu";
import { ANIMATION_SPEEDS, animationSpeedLabel, scaleAnimationDuration, type AnimationSpeed } from "./animation-speed";
@@ -942,7 +943,7 @@ export const assistantBackendSetting = new ConfigSettingEnum<AssistantBackendKin
values: global.isIOS ? ["direct"] : ["direct", "external"],
formatValue: (value) => assistantBackendLabels[value] ?? value,
description:
global.isIOS ? "An LLM called from the phone: a cloud model with your OpenAI or Anthropic API key (Settings > API Keys), or Apple Intelligence's on-device model." : "Who answers assistant queries: an LLM called from the phone (a cloud API with your key, or the downloaded on-phone model), or your own long-running agent (e.g. OpenClaw) reached through the faceclaw-agent-bridge plugin.",
global.isIOS ? "An LLM called from the phone: a cloud model with your OpenAI or Anthropic API key (Settings > API Keys) or your configured OpenAI-compatible API, or Apple Intelligence's on-device model." : "Who answers assistant queries: an LLM called from the phone (a cloud API with your key, or the downloaded on-phone model), or your own long-running agent (e.g. OpenClaw) reached through the faceclaw-agent-bridge plugin.",
});
export const assistantHermesUrlSetting = new ConfigSettingString({
@@ -1008,6 +1009,48 @@ export const assistantAllowProactiveSetting = new ConfigSettingBoolean({
"Let the external agent use glasses tools outside of a conversation, e.g. showing an alert when a long-running job finishes. Rate-limited; only tools marked proactive-safe are allowed.",
});
export const assistantOpenAiCompatibleUrlSetting = new ConfigSettingString({
id: "assistant-openai-compatible-url",
label: "Compatible API URL",
storageKey: "assistant.openAiCompatibleUrl",
defaultValue: "",
editorTitle: "OpenAI-compatible API root",
glassesEditTitle: "Edit compatible API URL",
formatValue: (value) => value || "(not set)",
validate: (value) => (!value.trim() || normalizeOpenAiCompatibleUrl(value) ? null : "Enter an http:// or https:// API root."),
description: "Explicit API root for the OpenAI-compatible Chat Completions assistant. Venice: https://api.venice.ai/api/v1. Open WebUI: https://your-host/api. The provider's path is not guessed.",
});
export const assistantOpenAiCompatibleKeySetting = new ConfigSettingString({
id: "assistant-openai-compatible-key",
label: "Compatible API key",
storageKey: "assistant.openAiCompatibleKey",
defaultValue: "",
editorTitle: "OpenAI-compatible API key (optional)",
glassesEditTitle: "Edit compatible API key",
formatValue: (value) => (value ? `${value.slice(0, 6)}...` : "(none)"),
description: "Bearer key sent only to the compatible assistant URL above. Optional for private servers that do not require authentication.",
});
export const assistantOpenAiCompatibleModelSetting = new ConfigSettingString({
id: "assistant-openai-compatible-model",
label: "Compatible model ID",
storageKey: "assistant.openAiCompatibleModel",
defaultValue: "",
editorTitle: "OpenAI-compatible model ID",
glassesEditTitle: "Edit compatible model ID",
formatValue: (value) => value || "(not set)",
description: "Exact model ID sent to the compatible provider. For glasses tools, choose a model that supports function calling.",
});
export const veniceWebSearchSetting = new ConfigSettingBoolean({
id: "venice-web-search",
label: "Venice web search",
storageKey: "assistant.veniceWebSearch",
defaultValue: false,
description: "Allow supported Venice models to search the web for current information. Shown only for the official Venice API URL. Search queries are processed by Venice's search service and may incur additional charges.",
});
export const elevenLabsApiKeySetting = new ConfigSettingString({
id: "elevenlabs-api-key",
label: "ElevenLabs key",
@@ -1112,11 +1155,12 @@ export const assistantModelSetting = new ConfigSettingEnum<AssistantModel>({
if (provider === "anthropic") return anthropicApiKeySetting.get().trim().length === 0;
if (provider === "openai") return openAiApiKeySetting.get().trim().length === 0;
if (provider === "local") return !isLocalModelReady();
if (provider === "openai-compatible") return !assistantOpenAiCompatibleUrlSetting.get().trim() || !assistantOpenAiCompatibleModelSetting.get().trim();
if (provider === "hermes") return assistantHermesUrlSetting.get().trim().length === 0;
return false;
},
description:
global.isIOS ? "Model used by the voice assistant. Auto prefers Terra with an OpenAI key, then Sonnet with an Anthropic key, then Apple Intelligence's on-device model." : "Model used by the voice assistant. Auto prefers Terra when an OpenAI key is set, then Sonnet when an Anthropic key is set, then the downloaded on-phone model.",
global.isIOS ? "Model used by the assistant. Auto prefers Terra with an OpenAI key, then Sonnet with an Anthropic key, then Apple Intelligence's on-device model. OpenAI-compatible uses the URL, model ID, and optional key below; Auto never picks it." : "Model used by the assistant. Auto prefers Terra when an OpenAI key is set, then Sonnet when an Anthropic key is set, then the downloaded on-phone model. OpenAI-compatible uses the URL, model ID, and optional key below; Auto never picks it.",
});
export const mapboxApiKeySetting = new ConfigSettingString({
+36 -16
View File
@@ -42,7 +42,11 @@ import {
assistantBridgePortSetting,
assistantBridgeTokenSetting,
assistantModelSetting,
assistantOpenAiCompatibleKeySetting,
assistantOpenAiCompatibleModelSetting,
assistantOpenAiCompatibleUrlSetting,
assistantSkipConfirmationSetting,
veniceWebSearchSetting,
batteryDisplayModeSetting,
brightnessSetting,
autoBrightnessMinSetting,
@@ -94,6 +98,8 @@ import {
import { wearBridge } from "../../native/wear-bridge";
import { openSettingsSubMenu, SettingsPanelLayer, type SettingsSection } from "./settings-panel";
import { uiFontPickerMenuItem } from "../font-picker";
import { compatibleModelDiscoveryMenuItem } from "../openai-compatible-model-picker";
import { isVeniceApiBaseUrl } from "../../native/openai-chat";
/** The Settings app's master-detail panel (sections on the left, contents on the right). */
export function createSettingsPanelLayer(): SettingsPanelLayer {
@@ -142,22 +148,36 @@ function settingsSections(): SettingsSection[] {
},
{
label: "Assistant",
items: [
// iOS's on-phone model is Apple Intelligence; Android downloads one. Only Android has the bridge.
enumSettingMenuItem(assistantBackendSetting),
enumSettingMenuItem(assistantModelSetting),
textSettingMenuItem(assistantHermesUrlSetting),
textSettingMenuItem(assistantHermesKeySetting),
global.isIOS ? systemModelMenuItem() : localModelMenuItem(),
toggleSettingMenuItem(assistantSkipConfirmationSetting),
// iOS has no agent bridge yet.
...(!global.isIOS ? [
textSettingMenuItem(assistantBridgeHostSetting),
textSettingMenuItem(assistantBridgePortSetting),
textSettingMenuItem(assistantBridgeTokenSetting),
toggleSettingMenuItem(assistantAllowProactiveSetting),
] : []),
],
// Re-read on every paint so the Venice-only row follows URL edits.
get items() {
return [
// iOS's on-phone model is Apple Intelligence; Android downloads one. Only Android has the bridge.
enumSettingMenuItem(assistantBackendSetting),
enumSettingMenuItem(assistantModelSetting),
textSettingMenuItem(assistantHermesUrlSetting),
textSettingMenuItem(assistantHermesKeySetting),
textSettingMenuItem(assistantOpenAiCompatibleUrlSetting),
textSettingMenuItem(assistantOpenAiCompatibleKeySetting),
compatibleModelDiscoveryMenuItem({
getBaseUrl: () => assistantOpenAiCompatibleUrlSetting.get(),
getApiKey: () => assistantOpenAiCompatibleKeySetting.get(),
getModel: () => assistantOpenAiCompatibleModelSetting.get(),
setModel: (model) => assistantOpenAiCompatibleModelSetting.set(model),
}, assistantOpenAiCompatibleModelSetting),
textSettingMenuItem(assistantOpenAiCompatibleModelSetting),
...(isVeniceApiBaseUrl(assistantOpenAiCompatibleUrlSetting.get())
? [toggleSettingMenuItem(veniceWebSearchSetting)] : []),
global.isIOS ? systemModelMenuItem() : localModelMenuItem(),
toggleSettingMenuItem(assistantSkipConfirmationSetting),
// iOS has no agent bridge yet.
...(!global.isIOS ? [
textSettingMenuItem(assistantBridgeHostSetting),
textSettingMenuItem(assistantBridgePortSetting),
textSettingMenuItem(assistantBridgeTokenSetting),
toggleSettingMenuItem(assistantAllowProactiveSetting),
] : []),
];
},
},
{
label: "API Keys",
+232
View File
@@ -0,0 +1,232 @@
import { MenuLayer, type MenuItem } from "./menu";
import { EditTextSettingLayer } from "./dashboard-settings";
import type { LayerContext } from "./layers";
import {
discoverOpenAiCompatibleModels,
type DiscoveredCompatibleModel,
} from "../native/openai-chat-models";
export type ModelDiscoverySettings = {
getBaseUrl(): string;
getApiKey(): string;
getModel(): string;
setModel(model: string): void;
};
type Discover = typeof discoverOpenAiCompatibleModels;
type PickerState = "loading" | "models" | "error";
const DISCOVERY_EXPLANATION =
"Discover models queries only this server's /models endpoint. Choose an exact model ID, or keep using manual entry. This does not send an inference request.";
/** A cancellable, on-demand model picker embedded in Faceclaw's existing menus. */
export class OpenAiCompatibleModelPicker extends MenuLayer {
private state: PickerState = "loading";
private models: DiscoveredCompatibleModel[] = [];
private error = "";
private showOffline = false;
private requestGeneration = 0;
private endpointKey = "";
private removed = false;
private readonly modelIdByRow = new Map<MenuItem, string>();
constructor(
private readonly settings: ModelDiscoverySettings,
private readonly modelSetting: ConstructorParameters<typeof EditTextSettingLayer>[0],
private readonly discover: Discover = discoverOpenAiCompatibleModels,
viewport: { width: number; height: number } = { width: 640, height: 480 },
) {
super("Discover models", [], discoveryLayout(viewport));
}
open(ctx: LayerContext): void {
ctx.stack.push(this);
void this.refresh(ctx);
}
private currentEndpoint(): string {
return `${this.settings.getBaseUrl().trim()}\n${this.settings.getApiKey().trim()}`;
}
private async refresh(ctx: LayerContext, forceRefresh = false): Promise<void> {
const generation = ++this.requestGeneration;
const endpointKey = this.currentEndpoint();
this.endpointKey = endpointKey;
this.state = "loading";
this.error = "";
this.updateRows();
try {
const models = await this.discover({
baseUrl: this.settings.getBaseUrl(),
apiKey: this.settings.getApiKey(),
forceRefresh,
});
if (!this.isActive(generation)) return;
if (endpointKey !== this.currentEndpoint()) {
this.error = "API URL or key changed; discover again";
this.state = "error";
} else {
this.models = models;
this.state = "models";
}
} catch (error) {
if (!this.isActive(generation)) return;
this.error = endpointKey !== this.currentEndpoint()
? "API URL or key changed; discover again"
: error instanceof Error ? error.message : String(error);
this.state = "error";
}
this.updateRows();
ctx.actions.requestRender();
}
private isActive(generation: number): boolean {
// A temporary overlay may sit above this still-open picker. Removal, not
// top-of-stack status, determines whether the pending result is obsolete.
return !this.removed && generation === this.requestGeneration;
}
private updateRows(): void {
this.modelIdByRow.clear();
const rows: MenuItem[] = [];
if (this.state === "loading") {
rows.push({ label: "Discovering models...", disabled: true, description: DISCOVERY_EXPLANATION, onSelect: () => {} });
rows.push({
label: "Cancel discovery",
description: "Ignore the pending result and return to Assistant settings.",
onSelect: (innerCtx) => innerCtx.stack.pop(),
});
} else if (this.state === "error") {
rows.push({
label: `Failed: ${truncateModelLabel(this.error || "Discovery failed", 40)}`,
disabled: true,
description: `${this.error}. Manual model entry is still available.`,
onSelect: () => {},
});
rows.push({
label: "Try again",
description: "Query this server's /models endpoint again without changing the saved model.",
onSelect: (innerCtx) => { void this.refresh(innerCtx, true); },
});
} else {
const saved = this.settings.getModel().trim();
const listed = this.models.filter((model) => this.showOffline || !model.offline || model.id === saved);
const savedModel = saved ? this.models.find((model) => model.id === saved) : undefined;
if (saved && !savedModel) {
rows.push(this.modelRow({
id: saved, name: saved, supportsTools: null, offline: false, deprecated: false, beta: false,
}, "saved; not listed"));
}
if (!listed.length) {
rows.push({
label: this.models.length ? "No online models listed" : "No models listed",
disabled: true,
description: "Keep the saved model or use manual entry.",
onSelect: () => {},
});
} else {
rows.push(...listed.map((model) => this.modelRow(model)));
}
if (this.models.some((model) => model.offline)) {
rows.push({
label: this.showOffline ? "Hide offline models" : `Show offline (${this.models.filter((model) => model.offline).length})`,
description: "Offline models normally fail inference until the provider restores them.",
onSelect: (innerCtx) => {
this.showOffline = !this.showOffline;
this.updateRows();
innerCtx.actions.requestRender();
},
});
}
rows.push({
label: "Refresh models",
description: "Fetch a fresh catalog. This never changes the selected model by itself.",
onSelect: (innerCtx) => { void this.refresh(innerCtx, true); },
});
}
rows.push({
label: "Enter model manually",
description: "Use an exact model ID when discovery is unavailable or the desired model is not listed.",
onSelect: (innerCtx) => {
this.requestGeneration++; // Any late discovery result belongs to the closed picker.
void innerCtx.actions.startTextSettingEdit(this.modelSetting);
innerCtx.stack.popThrough(this);
innerCtx.stack.push(new EditTextSettingLayer(this.modelSetting));
},
});
const current = this.settings.getModel().trim();
const selected = Math.max(0, rows.findIndex((row) => this.modelIdByRow.get(row) === current));
this.setItems(rows, selected);
}
private modelRow(model: DiscoveredCompatibleModel, extraLabel?: string): MenuItem {
const flags: string[] = [];
if (model.supportsTools === true) flags.push("tools");
else if (model.supportsTools === false) flags.push("no tools");
else flags.push("tools unknown");
if (model.offline) flags.push("offline");
if (model.deprecated) flags.push("deprecated");
if (model.beta) flags.push("beta");
if (extraLabel) flags.push(extraLabel);
const selected = this.settings.getModel().trim() === model.id ? " *" : "";
const displayName = model.name === model.id ? model.id : `${model.name} (${model.id})`;
const toolFlag = model.supportsTools === true ? "tools" : model.supportsTools === false ? "no tools" : "tools?";
const visibleFlags = [toolFlag];
if (model.offline) visibleFlags.push("offline");
if (model.deprecated) visibleFlags.push("old");
if (model.beta) visibleFlags.push("beta");
if (extraLabel) visibleFlags.push("saved only");
const flagSuffix = ` [${visibleFlags.join("/")}]`;
const row: MenuItem = {
label: `${truncateModelLabel(displayName, Math.max(12, 44 - flagSuffix.length))}${flagSuffix}${selected}`,
description: `${model.name}: ${model.id} — ${flags.join(", ")}. Tool support unknown means the server did not advertise it; test before relying on glasses actions.`,
onSelect: (innerCtx) => {
// Re-read immediately before saving; a late catalog never overwrites a
// selection made against a different endpoint.
if (this.settings.getBaseUrl().trim() + "\n" + this.settings.getApiKey().trim() !== this.endpointKey) return;
this.settings.setModel(model.id);
innerCtx.stack.popThrough(this);
},
};
this.modelIdByRow.set(row, model.id);
return row;
}
onRemoved(): void {
this.removed = true;
this.requestGeneration++; // Invalidate the pending result immediately.
}
}
/** Kept separate so tests can verify the normal Faceclaw modal sizing contract. */
function discoveryLayout(viewport: { width: number; height: number }): ConstructorParameters<typeof MenuLayer>[2] {
return {
x: "center",
y: 8,
width: Math.min(320, viewport.width - 40),
minHeight: Math.min(160, viewport.height - 40),
maxHeight: Math.min(240, viewport.height - 40),
depth: 4,
};
}
function truncateModelLabel(value: string, maxLength = 44): string {
if (value.length <= maxLength) return value;
const tailLength = Math.min(19, Math.max(4, maxLength - 8));
const headLength = Math.max(1, maxLength - tailLength - 3);
return `${value.slice(0, headLength)}...${value.slice(-tailLength)}`;
}
/** One stable Assistant settings row; discovery state belongs to the pushed picker. */
export function compatibleModelDiscoveryMenuItem(
settings: ModelDiscoverySettings,
modelSetting: ConstructorParameters<typeof EditTextSettingLayer>[0],
discover: Discover = discoverOpenAiCompatibleModels,
): MenuItem {
return {
label: "Discover models",
description: DISCOVERY_EXPLANATION,
disabled: () => !settings.getBaseUrl().trim(),
onSelect: (ctx) => new OpenAiCompatibleModelPicker(settings, modelSetting, discover, ctx.stack.getBaseSize()).open(ctx),
};
}
+9 -1
View File
@@ -38,7 +38,11 @@ import {
assistantBridgePortSetting,
assistantBridgeTokenSetting,
assistantModelSetting,
assistantOpenAiCompatibleKeySetting,
assistantOpenAiCompatibleModelSetting,
assistantOpenAiCompatibleUrlSetting,
assistantSkipConfirmationSetting,
veniceWebSearchSetting,
batteryIndicatorSettingsKey,
brightnessSetting,
onAnySettingChanged,
@@ -1720,6 +1724,10 @@ class Shell {
openai: openAiApiKeySetting.get(),
hermesUrl: assistantHermesUrlSetting.get(),
hermesKey: assistantHermesKeySetting.get(),
openAiCompatibleUrl: assistantOpenAiCompatibleUrlSetting.get(),
openAiCompatibleKey: assistantOpenAiCompatibleKeySetting.get(),
openAiCompatibleModel: assistantOpenAiCompatibleModelSetting.get(),
veniceWebSearch: veniceWebSearchSetting.get(),
});
if (llm && reasoning !== "default" && llm.effort) llm.effort = reasoning;
return llm ? { kind: "direct", llm } : null;
@@ -1749,7 +1757,7 @@ class Shell {
this.showAlert(
assistantBackendSetting.get() === "external"
? "Configure the agent bridge host and token in Settings."
: global.isIOS ? "Set an OpenAI or Anthropic API key in Settings." : "Set an API key or download the on-phone model in Settings.",
: global.isIOS ? "Configure an assistant model in Settings." : "Set an API key or download the on-phone model in Settings.",
);
return;
}
+9 -1
View File
@@ -33,7 +33,13 @@ export interface TextResponse {
*/
export async function fetchTextWithUserAgent(
url: string,
init?: { method?: string; headers?: HeadersInit; body?: string },
init?: {
method?: string;
headers?: HeadersInit;
body?: string;
timeoutMs?: number;
dontFollowRedirects?: boolean;
},
): Promise<TextResponse> {
// Required lazily so the Node test harness can load this module (via
// fetchWithUserAgent's users) without mocking @nativescript/core. Only the
@@ -46,6 +52,8 @@ export async function fetchTextWithUserAgent(
method: init?.method ?? "GET",
headers: withUserAgent(init?.headers),
content: init?.body,
timeout: init?.timeoutMs,
dontFollowRedirects: init?.dontFollowRedirects,
});
const status = response.statusCode;
let body: string | undefined;
+309
View File
@@ -0,0 +1,309 @@
const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
const flush = () => new Promise(resolve => setImmediate(resolve));
function assistant({ apiKey = 'fixture-key', baseUrl = 'https://provider.example/api/v1' } = {}) {
const requests = [], calls = [], deltas = [], errors = [], done = [];
const registry = {
listTools: () => [
{ name: 'timer.set', description: 'Set a timer', inputSchema: { type: 'object', properties: { seconds: { type: 'number' } } } },
{ name: 'glasses.show_alert', description: 'Show an alert', inputSchema: { type: 'object', properties: { text: { type: 'string' } } } },
],
callTool: async (name, args) => {
calls.push({ name, args });
return { ok: true, content: `${name} completed` };
},
};
const load = loader({ global: { isIOS: false, isAndroid: true }, setTimeout, clearTimeout }, {
'./sse': { openSseRequest: (url, body, headers, listener) => {
const request = { url, body: JSON.parse(body), headers, listener, cancelled: false };
requests.push(request);
return { cancel: () => { request.cancelled = true; } };
} },
'../native/local-llm': { streamLocalModel: () => assert.fail('unexpected local model'), isLocalModelReady: () => false, isLocalModelSupported: () => true, LOCAL_MODEL: { id: 'qwen', label: 'Qwen' } },
'./bridge-client': { assistantBridge: {} },
'./tool-registry': { toolRegistry: registry },
'../prompts': {
ASSISTANT_SYSTEM_PROMPT_BASE: 'test',
buildAssistantSystemPrompt: () => 'glasses system',
describeAssistantContext: () => '',
},
});
const { AssistantSession } = load('app/assistant/session.ts');
const session = new AssistantSession({ kind: 'direct', llm: {
selection: 'openai-compatible', provider: 'openai-compatible', model: 'fixture-model', apiKey, baseUrl,
} }, registry);
const send = text => session.sendUtterance(text, {}, {
onTextDelta: (_delta, full) => deltas.push(full),
onToolActivity() {},
onError: error => errors.push(error),
onTurnDone: result => done.push(result),
});
const event = (request, value) => request.listener.onLine('data: ' + JSON.stringify(value));
const chunk = (request, delta, finishReason = null) => event(request, { choices: [{ index: 0, delta, finish_reason: finishReason }] });
const finish = (request, reason = 'stop', close = 'done') => {
chunk(request, {}, reason);
if (close === 'done') request.listener.onLine('data: [DONE]');
else request.listener.onComplete();
};
return { load, session, send, event, chunk, finish, requests, calls, deltas, errors, done };
}
test('compatible provider sends full history, nested tools, the exact API root and optional auth', () => {
const h = assistant();
h.send('Remember the blue door');
const first = h.requests[0];
assert.equal(first.url, 'https://provider.example/api/v1/chat/completions');
assert.equal(first.headers.Authorization, 'Bearer fixture-key');
assert.equal(first.headers['Content-Type'], 'application/json');
assert.equal(first.body.model, 'fixture-model');
assert.equal(first.body.stream, true);
assert.equal('max_tokens' in first.body, false, 'provider default output limit is preserved');
assert.equal('reasoning_effort' in first.body, false, 'custom models default to provider reasoning');
assert.deepEqual(first.body.messages.map(m => [m.role, m.content]), [
['system', 'glasses system'], ['user', 'Remember the blue door'],
]);
assert.equal(first.body.tools[0].type, 'function');
assert.equal(first.body.tools[0].function.name, 'timer_set');
assert.equal(first.body.tools[0].function.parameters.type, 'object');
h.chunk(first, { content: 'Remembered.' }); h.finish(first);
h.send('What color?');
assert.deepEqual(h.requests[1].body.messages.slice(-3).map(m => [m.role, m.content]), [
['user', 'Remember the blue door'], ['assistant', 'Remembered.'], ['user', 'What color?'],
]);
h.session.cancel();
const noKey = assistant({ apiKey: '' });
noKey.send('Private request');
assert.equal('Authorization' in noKey.requests[0].headers, false);
noKey.session.cancel();
});
test('Venice web search is opt-in and never leaks to other compatible providers', () => {
const defaultOff = assistant({ baseUrl: 'https://api.venice.ai/api/v1' });
defaultOff.send('Current weather');
assert.equal('venice_parameters' in defaultOff.requests[0].body, false);
defaultOff.session.cancel();
const { isVeniceApiBaseUrl } = defaultOff.load('app/native/openai-chat.ts');
assert.equal(isVeniceApiBaseUrl(' https://api.venice.ai/api/v1/ '), true);
assert.equal(isVeniceApiBaseUrl('https://api.venice.ai/api/v1/chat/completions'), true);
assert.equal(isVeniceApiBaseUrl('http://api.venice.ai/api/v1'), false);
assert.equal(isVeniceApiBaseUrl('https://api.venice.ai.evil.example/api/v1'), false);
assert.equal(isVeniceApiBaseUrl('https://openwebui.example/api'), false);
const enabled = assistant({ baseUrl: 'https://api.venice.ai/api/v1' });
enabled.session.configure({ kind: 'direct', llm: {
selection: 'openai-compatible', provider: 'openai-compatible', model: 'fixture-model',
apiKey: 'fixture-key', baseUrl: 'https://api.venice.ai/api/v1', webSearch: true,
} });
enabled.send('Current weather');
assert.deepEqual(JSON.parse(JSON.stringify(enabled.requests[0].body.venice_parameters)), {
enable_web_search: 'on',
});
enabled.session.cancel();
const openWebUi = assistant({ baseUrl: 'https://openwebui.example/api' });
openWebUi.session.configure({ kind: 'direct', llm: {
selection: 'openai-compatible', provider: 'openai-compatible', model: 'fixture-model',
apiKey: 'fixture-key', baseUrl: 'https://openwebui.example/api', webSearch: true,
} });
openWebUi.send('Current weather');
assert.equal('venice_parameters' in openWebUi.requests[0].body, false);
openWebUi.session.cancel();
});
test('Venice and Open WebUI roots are preserved; only a complete endpoint suffix is removed', () => {
const { normalizeOpenAiCompatibleUrl } = assistant().load('app/native/openai-chat.ts');
assert.equal(normalizeOpenAiCompatibleUrl(' https://api.venice.ai/api/v1/ '), 'https://api.venice.ai/api/v1');
assert.equal(normalizeOpenAiCompatibleUrl('https://api.venice.ai/api/v1/chat/completions'), 'https://api.venice.ai/api/v1');
assert.equal(normalizeOpenAiCompatibleUrl('http://100.64.0.1:3000/api'), 'http://100.64.0.1:3000/api');
assert.equal(normalizeOpenAiCompatibleUrl('https://openwebui.example/api/chat/completions/'), 'https://openwebui.example/api');
assert.equal(normalizeOpenAiCompatibleUrl('https://provider.example/custom/root'), 'https://provider.example/custom/root');
assert.equal(normalizeOpenAiCompatibleUrl('provider.example/v1'), '');
assert.equal(normalizeOpenAiCompatibleUrl('https://provider.example/v1?key=secret'), '');
assert.equal(normalizeOpenAiCompatibleUrl('https://provider.example/v1#fragment'), '');
assert.equal(normalizeOpenAiCompatibleUrl('https://user:secret@provider.example/v1'), '', 'credentials never belong in saved URLs');
});
test('compatible model resolves only with URL and model, and Auto remains unchanged', () => {
const { ASSISTANT_MODEL_CHOICES, resolveAssistantModel } = assistant().load('app/assistant/models.ts');
assert.equal(ASSISTANT_MODEL_CHOICES.includes('openai-compatible'), true);
assert.equal(resolveAssistantModel('openai-compatible', { anthropic: '', openai: '' }), null);
assert.equal(resolveAssistantModel('openai-compatible', {
anthropic: '', openai: '', openAiCompatibleUrl: 'https://provider.example/api/v1', openAiCompatibleModel: '',
}), null);
const resolved = resolveAssistantModel('openai-compatible', {
anthropic: '', openai: '',
openAiCompatibleUrl: ' https://provider.example/api/v1 ',
openAiCompatibleKey: ' secret ', openAiCompatibleModel: ' model-id ',
});
assert.equal(resolved.provider, 'openai-compatible');
assert.equal(resolved.model, 'model-id');
assert.equal(resolved.apiKey, 'secret');
assert.equal(resolved.baseUrl, 'https://provider.example/api/v1');
assert.equal(resolved.effort, undefined);
assert.equal(resolveAssistantModel('auto', {
anthropic: '', openai: '', openAiCompatibleUrl: 'https://provider.example/api/v1', openAiCompatibleModel: 'model-id',
}), null, 'Auto never selects a custom provider');
});
test('streamed tool calls execute through Faceclaw, results continue the turn, and history survives follow-up', async () => {
const h = assistant();
h.send('Set a one-minute timer');
const first = h.requests[0];
h.chunk(first, { content: 'Setting it now.' });
h.chunk(first, {
reasoning_content: 'hidden reasoning',
reasoning_details: [{ type: 'reasoning.encrypted', data: 'opaque-fixture' }],
tool_calls: [{ index: 0, id: 'call-1', type: 'function', function: { name: 'timer_set', arguments: '{"seconds":' } }],
});
h.chunk(first, { tool_calls: [{ index: 0, function: { arguments: '60}' } }] });
h.finish(first, 'tool_calls');
await flush();
assert.equal(h.calls.length, 1);
assert.equal(h.calls[0].name, 'timer.set');
assert.equal(h.calls[0].args.seconds, 60);
assert.equal(h.requests.length, 2);
const second = h.requests[1];
const assistantMessage = second.body.messages.find(m => m.role === 'assistant' && m.tool_calls);
assert.equal(assistantMessage.content, 'Setting it now.');
assert.equal(assistantMessage.tool_calls[0].id, 'call-1');
assert.equal(assistantMessage.tool_calls[0].function.name, 'timer_set');
assert.equal(assistantMessage.tool_calls[0].function.arguments, '{"seconds":60}');
assert.equal(assistantMessage.reasoning_details[0].data, 'opaque-fixture');
const toolMessage = second.body.messages.find(m => m.role === 'tool');
assert.equal(toolMessage.tool_call_id, 'call-1');
assert.equal(toolMessage.content, 'timer.set completed');
assert.equal(JSON.stringify(second.body).includes('hidden reasoning'), false);
h.chunk(second, { content: 'Your timer is running.' });
h.finish(second, 'stop', 'close');
assert.equal(h.session.isTurnActive(), false);
assert.equal(h.done.length, 1);
assert.deepEqual(h.errors, []);
assert.equal(h.deltas.includes('hidden reasoning'), false);
h.send('What did you set?');
assert.match(JSON.stringify(h.requests[2].body), /Your timer is running/);
h.session.cancel();
assert.equal(h.requests[2].cancelled, true);
});
test('changing the API endpoint preserves visible history but drops provider-specific state', () => {
const h = assistant();
const original = h.session.config;
const config = (baseUrl) => ({ kind: 'direct', llm: {
selection: 'openai-compatible', provider: 'openai-compatible', model: 'fixture-model', apiKey: 'fixture-key', baseUrl,
} });
h.session.sendUtterance('Remember the blue door', {}, {
onTextDelta() {}, onToolActivity() {}, onError: error => assert.fail(error), onTurnDone() {},
});
const first = h.requests[0];
h.chunk(first, { reasoning_details: [{ type: 'opaque', data: 'server-one-only' }], content: 'Remembered.' });
h.finish(first);
const history = JSON.parse(JSON.stringify(h.session.history()));
assert.equal(JSON.stringify(history).includes('server-one-only'), true);
h.session.configure(config('https://provider-two.example/api/v1'));
h.send('What color?');
const second = h.requests[1];
assert.equal(second.url, 'https://provider-two.example/api/v1/chat/completions');
assert.equal(JSON.stringify(second.body).includes('server-one-only'), false);
assert.equal(JSON.stringify(second.body).includes('Remember the blue door'), true);
h.session.cancel();
const restored = new h.session.constructor(config('https://provider-two.example/api/v1'), undefined, history);
restored.sendUtterance('What color?', {}, {
onTextDelta() {}, onToolActivity() {}, onError: error => assert.fail(error), onTurnDone() {},
});
assert.equal(JSON.stringify(h.requests.at(-1).body).includes('server-one-only'), false);
restored.cancel();
});
test('multiple interleaved tool calls are reassembled independently and all results are returned', async () => {
const h = assistant();
h.send('Set a timer and show an alert');
const first = h.requests[0];
h.chunk(first, { tool_calls: [
{ index: 0, id: 'timer-id', function: { name: 'timer_set', arguments: '{"sec' } },
{ index: 1, id: 'alert-id', function: { name: 'glasses_show_alert', arguments: '{"text":' } },
] });
h.chunk(first, { tool_calls: [
{ index: 0, function: { arguments: 'onds":30}' } },
{ index: 1, function: { arguments: '"Done"}' } },
] });
h.finish(first, 'tool_calls');
await flush();
// Values produced inside the VM have a different Object prototype.
assert.equal(JSON.stringify(h.calls.map(c => [c.name, c.args])), JSON.stringify([
['timer.set', { seconds: 30 }], ['glasses.show_alert', { text: 'Done' }],
]));
const second = h.requests[1];
const tools = second.body.messages.filter(m => m.role === 'tool');
assert.equal(JSON.stringify(tools.map(m => [m.tool_call_id, m.content])), JSON.stringify([
['timer-id', 'timer.set completed'], ['alert-id', 'glasses.show_alert completed'],
]));
h.chunk(second, { content: 'Both actions completed.' });
h.finish(second);
assert.equal(h.session.isTurnActive(), false);
assert.deepEqual(h.errors, []);
});
test('content-only streams work with [DONE], while empty and in-band error streams fail clearly', () => {
const h = assistant();
h.send('Hello');
h.chunk(h.requests[0], { role: 'assistant' });
h.chunk(h.requests[0], { reasoning_content: 'not for the lenses' });
h.chunk(h.requests[0], { content: 'Hello ' });
h.chunk(h.requests[0], { content: 'there' });
h.requests[0].listener.onLine('data: [DONE]');
assert.equal(h.done[0].stopReason, 'end_turn');
assert.equal(h.session.transcript.at(-1).text, 'Hello there');
h.send('Empty'); h.finish(h.requests[1]);
assert.match(h.errors.at(-1), /without a reply/);
h.send('Failure');
h.event(h.requests[2], { error: { message: 'model overloaded' } });
assert.match(h.errors.at(-1), /model overloaded/);
});
test('HTTP errors, malformed tool JSON and premature EOF never execute incomplete tools', async () => {
const h = assistant();
h.send('Unauthorized');
h.requests[0].listener.onHttpError(401, '{"error":{"message":"bad key"}}');
assert.match(h.errors.at(-1), /invalid API key/);
assert.equal(h.session.isTurnActive(), false);
h.send('Malformed');
h.chunk(h.requests[1], { tool_calls: [{ index: 0, id: 'bad', function: { name: 'timer_set', arguments: '{broken' } }] });
h.finish(h.requests[1], 'tool_calls');
await flush();
assert.match(h.errors.at(-1), /malformed tool arguments/);
assert.equal(h.calls.length, 0);
h.send('Truncated');
h.chunk(h.requests[2], { tool_calls: [{ index: 0, id: 'partial', function: { name: 'timer_set', arguments: '{"seconds":60}' } }] });
h.requests[2].listener.onComplete();
await flush();
assert.match(h.errors.at(-1), /before the response completed/);
assert.equal(h.calls.length, 0);
h.send('Length limited');
h.chunk(h.requests[3], { tool_calls: [{ index: 0, id: 'partial', function: { name: 'timer_set', arguments: '{"seconds":60}' } }] });
h.finish(h.requests[3], 'length');
await flush();
assert.match(h.errors.at(-1), /before its tool calls completed/);
assert.equal(h.calls.length, 0);
});
test('cancellation suppresses late deltas and tool side effects', async () => {
const h = assistant();
h.send('Cancel this');
const request = h.requests[0];
h.session.cancel();
h.chunk(request, { content: 'late text', tool_calls: [{ index: 0, id: 'late', function: { name: 'timer_set', arguments: '{}' } }] });
h.finish(request, 'tool_calls');
await flush();
assert.equal(h.calls.length, 0);
assert.equal(h.deltas.length, 0);
assert.equal(h.done.length, 0);
assert.equal(request.cancelled, true);
});
@@ -0,0 +1,160 @@
const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
function discoveryEnv(responder) {
const requests = [];
const load = loader({}, {
'../util/http': {
fetchTextWithUserAgent: async (url, init) => {
requests.push({ url, init });
return responder(url, init, requests.length);
},
},
'./sse': {},
});
const api = load('app/native/openai-chat-models.ts');
api.clearCompatibleModelDiscoveryCache();
return { api, requests };
}
const response = (body, status = 200) => ({ status, text: async () => typeof body === 'string' ? body : JSON.stringify(body) });
const veniceModel = (id, name, tools, extra = {}) => ({
id,
model_spec: {
name,
capabilities: { supportsFunctionCalling: tools },
...extra,
},
});
const options = {
baseUrl: 'https://api.venice.ai/api/v1',
apiKey: 'venice-key',
};
test('Venice discovery uses its exact API root, auth, timeout, no redirects, and capability metadata', async () => {
const env = discoveryEnv(async () => response({ data: [
veniceModel('chat-only', 'Chat only', false),
veniceModel('offline-tools', 'Offline tools', true, { offline: true }),
veniceModel('tools-model', 'Tools model', true, { betaModel: true }),
{ id: 'generic-model', name: 'Generic model' },
veniceModel('old-model', 'Old model', true, { deprecation: { date: '2027-01-01' } }),
] }));
const models = await env.api.discoverOpenAiCompatibleModels(options);
assert.equal(env.requests.length, 1);
assert.equal(env.requests[0].url, 'https://api.venice.ai/api/v1/models');
assert.equal(env.requests[0].init.method, 'GET');
assert.equal(env.requests[0].init.headers.Authorization, 'Bearer venice-key');
assert.equal(env.requests[0].init.timeoutMs, 10_000);
assert.equal(env.requests[0].init.dontFollowRedirects, true);
assert.equal(models.map(model => model.id).join(','), 'old-model,tools-model,generic-model,chat-only,offline-tools');
const tools = models.find(model => model.id === 'tools-model');
assert.equal(tools.name, 'Tools model');
assert.equal(tools.supportsTools, true);
assert.equal(tools.beta, true);
assert.equal(models.find(model => model.id === 'old-model').deprecated, true);
assert.equal(models.find(model => model.id === 'generic-model').supportsTools, null);
assert.equal(models.find(model => model.id === 'chat-only').supportsTools, false);
assert.equal(models.find(model => model.id === 'offline-tools').offline, true);
});
test('Open WebUI discovery uses /api/models, supports optional auth, and marks tool support unknown', async () => {
const env = discoveryEnv(async () => response({ data: [
{ id: 'qwen-local', name: 'Qwen local' },
{ id: 'second-model' },
] }));
const models = await env.api.discoverOpenAiCompatibleModels({
baseUrl: 'http://100.64.0.1:3000/api', apiKey: '',
});
assert.equal(env.requests[0].url, 'http://100.64.0.1:3000/api/models');
assert.equal('Authorization' in env.requests[0].init.headers, false);
assert.equal(JSON.stringify(models.map(model => [model.id, model.supportsTools])), JSON.stringify([
['qwen-local', null], ['second-model', null],
]));
});
test('successful catalogs are cached briefly per endpoint and credential; refresh bypasses the cache', async () => {
let now = 1000;
const env = discoveryEnv(async (_url, _init, count) => response({ data: [{ id: `model-${count}` }] }));
const deps = { now: () => now };
const first = await env.api.discoverOpenAiCompatibleModels(options, deps);
const cached = await env.api.discoverOpenAiCompatibleModels(options, deps);
assert.equal(first, cached);
assert.equal(env.requests.length, 1);
await env.api.discoverOpenAiCompatibleModels({ ...options, apiKey: 'other-key' }, deps);
assert.equal(env.requests.length, 2, 'a different credential cannot reuse the old response');
await env.api.discoverOpenAiCompatibleModels({ ...options, baseUrl: 'https://other.example/api' }, deps);
assert.equal(env.requests.length, 3, 'a different endpoint has its own catalog');
await env.api.discoverOpenAiCompatibleModels({ ...options, forceRefresh: true }, deps);
assert.equal(env.requests.length, 4, 'explicit refresh always fetches');
now += 61_000;
await env.api.discoverOpenAiCompatibleModels(options, deps);
assert.equal(env.requests.length, 5, 'the short-lived entry expires');
});
test('invalid URLs and unsupported or malformed responses fail without querying alternate endpoints', async () => {
const env = discoveryEnv(async (_url, _init, count) => {
if (count === 1) return response('<html>login</html>');
if (count === 2) return response({ models: [] });
return response({ data: [] });
});
await assert.rejects(env.api.discoverOpenAiCompatibleModels({ baseUrl: 'not-a-url', apiKey: '' }), /valid compatible API URL/);
assert.equal(env.requests.length, 0);
await assert.rejects(env.api.discoverOpenAiCompatibleModels(options), /invalid model list/);
await assert.rejects(env.api.discoverOpenAiCompatibleModels({ ...options, forceRefresh: true }), /did not return an OpenAI-compatible model list/);
assert.deepEqual(env.requests.map(request => request.url), [
'https://api.venice.ai/api/v1/models', 'https://api.venice.ai/api/v1/models',
]);
});
test('HTTP and reachability errors are actionable and never fall back to inference', async () => {
const statuses = [401, 403, 404, 429, 503, 302];
for (const status of statuses) {
const env = discoveryEnv(async () => response({}, status));
await assert.rejects(env.api.discoverOpenAiCompatibleModels(options), error => {
assert.match(error.message, new RegExp(String(status)));
return true;
});
assert.equal(env.requests.length, 1);
assert.equal(env.requests[0].init.method, 'GET');
}
const unreachable = discoveryEnv(async () => { throw new Error('socket details'); });
await assert.rejects(unreachable.api.discoverOpenAiCompatibleModels(options), /Could not reach the configured server/);
});
test('model parsing skips invalid rows, deduplicates IDs, and caps catalog size', () => {
const env = discoveryEnv(async () => response({ data: [] }));
const rows = [null, {}, { id: '' }, { id: 'same', name: 'First' }, { id: 'same', name: 'Duplicate' }];
for (let index = 0; index < 510; index++) rows.push({ id: `model-${String(index).padStart(3, '0')}` });
const parsed = env.api.parseDiscoveredCompatibleModels(rows);
assert.equal(parsed.length, 500);
assert.equal(parsed.filter(model => model.id === 'same').length, 1);
assert.equal(parsed.find(model => model.id === 'same').name, 'First');
});
test('native text HTTP forwards discovery timeout and redirect protections with the app User-Agent', async () => {
const requests = [];
const load = loader({ global: { isAndroid: false, isIOS: true } }, {
'../version': { USER_AGENT: 'Faceclaw/test' },
'@nativescript/core/http': {
request: async init => {
requests.push(init);
return { statusCode: 200, content: { toString: () => '{"data":[]}' } };
},
},
});
const { fetchTextWithUserAgent } = load('app/util/http.ts');
const result = await fetchTextWithUserAgent('https://provider.example/api/models', {
headers: { Authorization: 'Bearer secret' },
timeoutMs: 10_000,
dontFollowRedirects: true,
});
assert.equal(requests[0].timeout, 10_000);
assert.equal(requests[0].dontFollowRedirects, true);
assert.equal(requests[0].headers.Authorization, 'Bearer secret');
assert.equal(requests[0].headers['User-Agent'], 'Faceclaw/test');
assert.equal(JSON.stringify(await result.json()), JSON.stringify({ data: [] }));
});
@@ -0,0 +1,301 @@
const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
const flush = () => new Promise(resolve => setImmediate(resolve));
class FakeMenuLayer {
constructor(title, items, layout) {
this.title = title;
this.layout = layout;
this.setItems(items);
}
setItems(items, selectedIndex = 0) {
this.items = items;
this.selectedIndex = items.length
? Math.max(0, Math.min(selectedIndex ?? 0, items.length - 1))
: null;
}
get selectedItem() {
return this.selectedIndex === null ? null : this.items[this.selectedIndex];
}
}
class FakeEditTextSettingLayer {
constructor(setting) { this.setting = setting; }
}
function deferred() {
let resolve, reject;
const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
return { promise, resolve, reject };
}
function model(id, extra = {}) {
return {
id,
name: extra.name ?? id,
supportsTools: extra.supportsTools ?? null,
offline: extra.offline ?? false,
deprecated: extra.deprecated ?? false,
beta: extra.beta ?? false,
};
}
function pickerEnv({ models = [], saved = '', discover } = {}) {
const calls = [];
const settings = {
baseUrl: 'https://provider.example/api/v1',
apiKey: 'secret',
model: saved,
getBaseUrl() { return this.baseUrl; },
getApiKey() { return this.apiKey; },
getModel() { return this.model; },
setModel(value) { this.model = value; },
};
const modelSetting = { id: 'compatible-model' };
const renders = [];
const edits = [];
const layers = [{ id: 'settings-base' }];
const remove = layer => layer.onRemoved?.();
const stack = {
getBaseSize: () => ({ width: 320, height: 240 }),
push(layer) { layers.push(layer); },
topMatches(predicate) { return layers.length > 1 && predicate(layers.at(-1)); },
pop() { if (layers.length > 1) remove(layers.pop()); },
popThrough(layer) {
const index = layers.indexOf(layer);
if (index <= 0) return false;
for (const removed of layers.splice(index).reverse()) remove(removed);
return true;
},
};
const ctx = {
stack,
actions: {
requestRender: () => renders.push('render'),
startTextSettingEdit: setting => { edits.push(setting); },
},
};
const load = loader({}, {
'./menu': { MenuLayer: FakeMenuLayer },
'./dashboard-settings': { EditTextSettingLayer: FakeEditTextSettingLayer },
'../native/openai-chat-models': {},
});
const api = load('app/ui/openai-compatible-model-picker.ts');
const discoverImpl = discover ?? (async options => {
calls.push(options);
return models;
});
const picker = new api.OpenAiCompatibleModelPicker(
settings, modelSetting, discoverImpl, stack.getBaseSize(),
);
return {
api, picker, settings, modelSetting, discoverImpl,
calls, renders, edits, layers, ctx,
};
}
function row(picker, text) {
const found = picker.items.find(item => item.label.includes(text));
assert.ok(found, `Missing row ${text}; got: ${picker.items.map(item => item.label).join(' | ')}`);
return found;
}
test('catalog shows capabilities, hides offline models, and saves only an explicit selection', async () => {
const env = pickerEnv({
saved: 'generic-model',
models: [
model('tools-model', { name: 'Tools Model', supportsTools: true }),
model('generic-model', { name: 'Generic Model' }),
model('offline-model', { supportsTools: true, offline: true }),
],
});
env.picker.open(env.ctx);
assert.equal(row(env.picker, 'Discovering').disabled, true);
await flush();
assert.equal(env.settings.model, 'generic-model');
assert.equal(env.calls.length, 1);
assert.equal(env.calls[0].baseUrl, 'https://provider.example/api/v1');
assert.equal(env.calls[0].apiKey, 'secret');
assert.equal(env.calls[0].forceRefresh, false);
assert.equal(env.picker.items.some(item => item.label.includes('offline-model')), false);
assert.match(row(env.picker, 'Tools Model').label, /\[tools\]/);
assert.match(row(env.picker, 'Generic Model').label, /\[tools\?\]/);
assert.ok(row(env.picker, 'Generic Model').label.endsWith(' *'));
assert.equal(env.picker.selectedItem.label, row(env.picker, 'Generic Model').label);
assert.equal(env.picker.layout.width, 280);
assert.equal(env.picker.layout.maxHeight, 200);
await row(env.picker, 'Tools Model').onSelect(env.ctx, env.picker);
assert.equal(env.settings.model, 'tools-model');
assert.equal(env.layers.length, 1);
});
test('refresh bypasses cache and preserves an unlisted saved model without auto-selecting', async () => {
const env = pickerEnv({
saved: 'keep-model',
discover: async options => {
env.calls.push(options);
return [model(env.calls.length === 1 ? 'first-model' : 'second-model')];
},
});
env.picker.open(env.ctx);
await flush();
assert.match(row(env.picker, 'keep-model').label, /saved only/);
assert.equal(env.picker.selectedItem.label, row(env.picker, 'keep-model').label);
await row(env.picker, 'Refresh models').onSelect(env.ctx, env.picker);
await flush();
assert.equal(env.calls.length, 2);
assert.equal(env.calls[1].forceRefresh, true);
assert.equal(env.settings.model, 'keep-model');
assert.ok(row(env.picker, 'second-model'));
assert.ok(row(env.picker, 'keep-model'));
});
test('cancel invalidates a pending result and manual entry remains available while loading', async () => {
const pending = deferred();
const env = pickerEnv({
saved: 'original-model',
discover: options => { env.calls.push(options); return pending.promise; },
});
env.picker.open(env.ctx);
await row(env.picker, 'Cancel discovery').onSelect(env.ctx, env.picker);
assert.equal(env.layers.length, 1);
const renderCount = env.renders.length;
pending.resolve([model('late-model')]);
await flush();
assert.equal(env.settings.model, 'original-model');
assert.equal(env.renders.length, renderCount);
const second = deferred();
const manual = pickerEnv({
saved: 'original-model',
discover: () => second.promise,
});
manual.picker.open(manual.ctx);
await row(manual.picker, 'Enter model manually').onSelect(manual.ctx, manual.picker);
assert.equal(manual.edits.length, 1);
assert.equal(manual.edits[0], manual.modelSetting);
assert.equal(manual.layers.length, 2);
assert.ok(manual.layers[1] instanceof FakeEditTextSettingLayer);
second.resolve([model('late-model')]);
await flush();
assert.equal(manual.settings.model, 'original-model');
assert.ok(manual.layers[1] instanceof FakeEditTextSettingLayer);
});
test('offline models are optional but a saved offline model remains selectable', async () => {
const env = pickerEnv({
saved: 'saved-offline',
models: [
model('online-model'),
model('saved-offline', { offline: true }),
model('other-offline', { offline: true }),
],
});
env.picker.open(env.ctx);
await flush();
assert.ok(row(env.picker, 'saved-offline'));
assert.equal(env.picker.items.some(item => item.label.includes('other-offline')), false);
await row(env.picker, 'Show offline (2)').onSelect(env.ctx, env.picker);
assert.ok(row(env.picker, 'other-offline'));
assert.match(row(env.picker, 'other-offline').label, /offline/);
await row(env.picker, 'Hide offline models').onSelect(env.ctx, env.picker);
assert.equal(env.picker.items.some(item => item.label.includes('other-offline')), false);
assert.equal(env.settings.model, 'saved-offline');
});
test('errors retain the saved model and Try again reloads the current endpoint', async () => {
const first = deferred();
const env = pickerEnv({
saved: 'original-model',
discover: options => {
env.calls.push(options);
if (env.calls.length === 1) return first.promise;
return Promise.resolve([model('new-endpoint-model')]);
},
});
env.picker.open(env.ctx);
env.settings.baseUrl = 'https://other.example/api';
first.resolve([model('old-endpoint-model')]);
await flush();
assert.match(row(env.picker, 'Failed:').description, /URL or key changed/);
assert.equal(env.picker.items.some(item => item.label.includes('old-endpoint-model')), false);
assert.equal(env.settings.model, 'original-model');
await row(env.picker, 'Try again').onSelect(env.ctx, env.picker);
await flush();
assert.equal(env.calls[1].baseUrl, 'https://other.example/api');
assert.equal(env.calls[1].forceRefresh, true);
assert.ok(row(env.picker, 'new-endpoint-model'));
assert.equal(env.settings.model, 'original-model');
});
test('a stale catalog cannot be selected after the endpoint changes', async () => {
const env = pickerEnv({ models: [model('old-endpoint-model')] });
env.picker.open(env.ctx);
await flush();
const staleRow = row(env.picker, 'old-endpoint-model');
env.settings.baseUrl = 'https://other.example/api';
await staleRow.onSelect(env.ctx, env.picker);
assert.equal(env.settings.model, '');
assert.equal(env.layers.length, 2);
});
test('empty catalogs retain recovery actions and settings row requires a URL', async () => {
const env = pickerEnv({ saved: 'keep-model', models: [] });
env.picker.open(env.ctx);
await flush();
assert.ok(row(env.picker, 'No models listed'));
assert.ok(row(env.picker, 'Refresh models'));
assert.ok(row(env.picker, 'Enter model manually'));
env.ctx.stack.pop();
const item = env.api.compatibleModelDiscoveryMenuItem(
env.settings, env.modelSetting, async () => [],
);
env.settings.baseUrl = '';
assert.equal(item.disabled(), true);
env.settings.baseUrl = 'https://provider.example/api/v1';
assert.equal(item.disabled(), false);
item.onSelect(env.ctx);
assert.equal(env.layers.length, 2);
assert.equal(env.layers[1].layout.width, 280);
env.layers[1].onRemoved();
});
test('a temporary overlay does not invalidate a pending result while the picker remains open', async () => {
const pending = deferred();
const env = pickerEnv({ discover: () => pending.promise });
env.picker.open(env.ctx);
env.layers.push({ id: 'temporary-overlay' });
pending.resolve([model('available-model')]);
await flush();
assert.equal(env.picker.items.some(item => item.label.includes('available-model')), true);
assert.equal(env.layers.length, 3);
assert.ok(env.renders.length > 0);
});
test('a discovery error is visible in the modal row and retains manual recovery', async () => {
const env = pickerEnv({
discover: async () => { throw new Error('Model discovery is not supported at this URL (HTTP 404)'); },
});
env.picker.open(env.ctx);
await flush();
assert.match(row(env.picker, 'Failed:').label, /404/);
assert.match(row(env.picker, 'Failed:').description, /Manual model entry/);
assert.ok(row(env.picker, 'Try again'));
assert.ok(row(env.picker, 'Enter model manually'));
env.ctx.stack.pop();
});
test('long labels stay bounded while descriptions retain the exact model ID', async () => {
const longId = `provider/${'x'.repeat(90)}-model`;
const longName = `A very long model name ${'y'.repeat(70)}`;
const env = pickerEnv({
models: [model(longId, { name: longName, supportsTools: true })],
});
env.picker.open(env.ctx);
await flush();
const longRow = row(env.picker, '[tools]');
assert.ok(longRow.label.length <= 54);
assert.ok(longRow.description.includes(longId));
});
@@ -0,0 +1,86 @@
const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
function sharedEnv() {
const compatible = [], unexpected = [];
const localLlm = {
streamLocalModel: () => unexpected.push('local'),
isLocalModelReady: () => false,
isLocalModelSupported: () => true,
LOCAL_MODEL: { id: 'qwen', label: 'Qwen' },
};
const settings = {
anthropicApiKeySetting: { get: () => '' },
assistantModelSetting: { get: () => 'openai-compatible' },
assistantOpenAiCompatibleUrlSetting: { get: () => 'https://provider.example/api/v1' },
assistantOpenAiCompatibleKeySetting: { get: () => 'compatible-key' },
assistantOpenAiCompatibleModelSetting: { get: () => 'compatible-model' },
openAiApiKeySetting: { get: () => '' },
};
const fail = provider => () => { unexpected.push(provider); };
const load = loader({ global: { isIOS: false, isAndroid: true } }, {
'../../native/anthropic': { streamAnthropicMessage: fail('anthropic') },
'../../native/openai': { streamOpenAiResponse: fail('openai') },
'../../native/local-llm': localLlm,
'../native/local-llm': localLlm,
'../../native/openai-chat': {
streamOpenAiCompatibleChat: options => {
compatible.push(options);
return { cancel() {} };
},
},
'../../ui/dashboard-settings': settings,
'../../prompts': {
CALCULATOR_REWRITE_SYSTEM_PROMPT: 'calculator system',
buildCalculatorRewriteUserMessage: spoken => `rewrite: ${spoken}`,
TRANSLATE_SYSTEM_PROMPT: 'translate system',
buildTranslateUserMessage: speech => `translate: ${speech}`,
},
});
return { load, compatible, unexpected };
}
test('Calculator uses the configured compatible provider and preserves its small output cap', async () => {
const env = sharedEnv();
const { rewriteSpokenProblem } = env.load('app/apps/calculator/calculator-llm.ts');
const result = rewriteSpokenProblem('one plus one');
assert.equal(env.compatible.length, 1);
assert.deepEqual(env.unexpected, []);
const options = env.compatible[0];
assert.equal(options.baseUrl, 'https://provider.example/api/v1');
assert.equal(options.apiKey, 'compatible-key');
assert.equal(options.model, 'compatible-model');
assert.equal(options.maxTokens, 200);
assert.equal(options.messages[0].content, 'rewrite: one plus one');
options.onDone({ text: '1 + 1', content: [], stopReason: 'end_turn' });
assert.equal(await result, '1 + 1');
});
test('Translate resolves and streams through the compatible provider without changing its cancellation contract', () => {
const env = sharedEnv();
const { resolveTranslationModel, streamTranslation } = env.load('app/apps/translate/translate-llm.ts');
const model = resolveTranslationModel();
assert.equal(model.provider, 'openai-compatible');
assert.equal(model.baseUrl, 'https://provider.example/api/v1');
const progress = [], answers = [], errors = [];
const handle = streamTranslation(model, {
speech: 'Hola', context: [], language: 'Spanish',
onProgress: text => progress.push(text),
onDone: text => answers.push(text),
onError: error => errors.push(error),
});
assert.equal(typeof handle.cancel, 'function');
assert.equal(env.compatible.length, 1);
assert.deepEqual(env.unexpected, []);
const options = env.compatible[0];
assert.equal(options.baseUrl, 'https://provider.example/api/v1');
assert.equal(options.model, 'compatible-model');
assert.equal(options.maxTokens, 1024);
assert.equal(options.messages[0].content, 'translate: Hola');
options.onTextDelta('Hello', '<english>Hello</english>');
options.onDone({ text: '<english>Hello</english>', content: [], stopReason: 'end_turn' });
assert.deepEqual(progress, ['Hello']);
assert.deepEqual(answers, ['Hello']);
assert.deepEqual(errors, []);
});
+102
View File
@@ -0,0 +1,102 @@
const test = require('node:test');
const assert = require('node:assert/strict');
const { loader } = require('./helpers/load-typescript.cjs');
function settingsEnv(initialUrl = '') {
let url = initialUrl;
let webSearch = false;
const dummySetting = {
id: 'setting', label: 'Setting', get: () => '', set() {}, displayValue: () => '',
};
const urlSetting = {
id: 'compatible-url', label: 'Compatible API URL', get: () => url, set: value => { url = value; },
displayValue: () => url,
};
const searchSetting = {
id: 'venice-web-search', label: 'Venice web search', get: () => webSearch,
set: value => { webSearch = value; }, toggle: () => { webSearch = !webSearch; },
defaultValue: false, description: 'Venice-only web search.',
};
const row = setting => ({ label: setting.label, description: setting.description, onSelect() {} });
const dashboardSettings = new Proxy({
assistantOpenAiCompatibleUrlSetting: urlSetting,
veniceWebSearchSetting: searchSetting,
enumSettingMenuItem: row,
textSettingMenuItem: row,
toggleSettingMenuItem: row,
}, {
get(target, property) {
return property in target ? target[property] : dummySetting;
},
});
const load = loader({ global: { isIOS: false, isAndroid: true } }, {
'./remote-input-menu': { remoteInputMenuItem: () => ({ label: 'Remote input' }) },
'@nativescript/core': { knownFolders: {} },
'../../graphics/ui-fonts': { getDefaultSmallFont: () => ({}) },
'../../graphics/logo': { getDashboardLogo: () => null },
'../../graphics/textwrap': { wrapText: () => [] },
'../../version': { FACECLAW_VERSION: 'test' },
'../../native/local-llm': {
cancelLocalModelDownload() {}, deleteLocalModel() {}, startLocalModelDownload() {},
LOCAL_MODEL: { label: 'Qwen', sizeBytes: 1_000_000_000 },
localModelState: () => ({ status: 'missing' }), onLocalModelStateChanged: () => () => {},
},
'../../native/asr-model': {
ASR_MODELS: {
moonshine: { label: 'Moonshine', sizeBytes: 1 },
'whisper-base-en': { label: 'Whisper Base English', sizeBytes: 1 },
},
asrModelState: () => ({}), cancelAsrModelDownload() {},
deleteAsrModel() {}, startAsrModelDownload() {}, onAsrModelStateChanged: () => () => {},
},
'../../apps/files/text-viewer': { TextViewerLayer: class {} },
'../../analytics/privacy-disclosure': { IOS_PRIVACY_NOTICE: '' },
'../menu': {
drawRightValueMenuItem() {}, openModalMenu() {},
submenuItem: label => ({ label, onSelect() {} }),
},
'../shell/shell': { shell: { noteUserActivity() {} } },
'../dashboard-settings': dashboardSettings,
'../../native/wear-bridge': { wearBridge: {} },
'./settings-panel': {
SettingsPanelLayer: class { constructor(sections) { this.sections = sections; } },
openSettingsSubMenu() {},
},
'../font-picker': { uiFontPickerMenuItem: () => ({ label: 'Font' }) },
'../openai-compatible-model-picker': {
compatibleModelDiscoveryMenuItem: () => ({ label: 'Discover models' }),
},
'./sse': {},
});
const panel = load('app/ui/dashboard/settings-menus.ts').createSettingsPanelLayer();
const section = panel.sections.find(item => item.label === 'Assistant');
assert.ok(section);
return {
section,
labels: () => section.items.map(item => item.label),
setUrl: value => { url = value; },
searchSetting,
};
}
test('Venice web search row follows the current URL and never appears for other providers', () => {
const env = settingsEnv();
assert.equal(env.labels().includes('Venice web search'), false);
assert.equal(env.searchSetting.defaultValue, false);
assert.equal(env.searchSetting.get(), false);
env.setUrl(' https://api.venice.ai/api/v1/ ');
assert.equal(env.labels().includes('Venice web search'), true);
env.setUrl('https://openwebui.example/api');
assert.equal(env.labels().includes('Venice web search'), false);
env.setUrl('https://api.venice.ai/api/v1/chat/completions');
assert.equal(env.labels().includes('Venice web search'), true);
env.setUrl('https://api.venice.ai.evil.example/api/v1');
assert.equal(env.labels().includes('Venice web search'), false);
env.setUrl('http://api.venice.ai/api/v1');
assert.equal(env.labels().includes('Venice web search'), false);
});
+1 -1
View File
@@ -6,7 +6,7 @@
Inline markdown supported by the sync script: **bold**, [text](url), `code`.
-->
- **A voice assistant** that wakes up when you say "Hey Even", transcribes text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds to queries and commands using an onboard model (Qwen3 4B, slow) or with an Anthropic or OpenAI model (requires an API key), or using your own long-running OpenClaw agent.
- **A voice assistant** that wakes up when you say "Hey Even", transcribes text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds to queries and commands using an onboard model (Qwen3 4B, slow) or with an Anthropic, OpenAI, or OpenAI-compatible Chat Completions model (including Venice and private Open WebUI servers; model ID and usually an API key required), with optional Venice web search for supported models, or using your own long-running OpenClaw agent.
- **Multitasking**, with an app-switcher sidebar and app launcher.
- **Glanceboard**, a dashboard with widgets that you can quickly view with a
- **Mostly-compatible with EvenHub.** Install and runapps from the Even app store.
+1 -1
View File
@@ -89,7 +89,7 @@
<h2>Features</h2>
<!-- BEGIN GENERATED: features -->
<ul class="features">
<li><strong>A voice assistant</strong> that wakes up when you say "Hey Even", transcribes text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds to queries and commands using an onboard model (Qwen3 4B, slow) or with an Anthropic or OpenAI model (requires an API key), or using your own long-running OpenClaw agent.</li>
<li><strong>A voice assistant</strong> that wakes up when you say "Hey Even", transcribes text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds to queries and commands using an onboard model (Qwen3 4B, slow) or with an Anthropic, OpenAI, or OpenAI-compatible Chat Completions model (including Venice and private Open WebUI servers; model ID and usually an API key required), with optional Venice web search for supported models, or using your own long-running OpenClaw agent.</li>
<li><strong>Multitasking</strong>, with an app-switcher sidebar and app launcher.</li>
<li><strong>Glanceboard</strong>, a dashboard with widgets that you can quickly view with a</li>
<li><strong>Mostly-compatible with EvenHub.</strong> Install and runapps from the Even app store.</li>
+13 -2
View File
@@ -70,11 +70,14 @@
</ul>
<p>Third party data retention and privacy policies may differ based on the API key provided. API keys are part of a relationship between the user and the API provider; Faceclaw does not manage accounts or process billing information.</p>
<h2>AI Assistant Transcripts</h2>
<p>Faceclaw has a builtin AI voice assistant. Using the voice assistant requires providing an API key for a model provider such as Anthropic or OpenAI. Prompts and responses are subject to that model provider's privacy policy:</p>
<p>Faceclaw has a builtin AI voice assistant. Using a cloud model requires providing an API key for a model provider such as Anthropic, OpenAI, or Venice, or configuring an OpenAI-compatible endpoint such as a private Open WebUI server. Prompts and responses are subject to the selected provider or server operator's privacy policy:</p>
<ul class="links">
<li>OpenAI: <a href="https://openai.com/policies/row-privacy-policy/">https://openai.com/policies/row-privacy-policy/</a></li>
<li>Anthropic: <a href="https://www.anthropic.com/legal/privacy">https://www.anthropic.com/legal/privacy</a></li>
<li>Venice: <a href="https://venice.ai/privacy">https://venice.ai/privacy</a></li>
</ul>
<p>With an OpenAI-compatible provider, the configured server receives the assistant system prompt, conversation history, available tool definitions, and tool results needed to answer. Its URL, model ID, and optional API key are stored on the phone. Faceclaw does not operate that server and cannot make representations about its logging or retention; for a private Open WebUI server, the server's operator controls those policies. If you choose Discover models, Faceclaw also requests that server's model catalog using the same configured URL and optional API key.</p>
<p>If you enable <strong>Venice web search</strong> for the official Venice API URL, supported models may generate web-search queries from your assistant conversation. Those queries and their results are processed by Venice's search service and are subject to Venice's privacy policy and any applicable charges. This setting is off by default and is never sent to Open WebUI or other compatible providers.</p>
<p>AI conversation histories and memory files may be stored on your phone. Faceclaw does not transmit voice-assistant prompts or responses to any party other than a user-selected AI model provider. The voice assistant is given tools with which it is able to access most things on the user's phone, including all content displayed on the glasses, location, notifications, and content accessible through the Terminal app.</p>
<p>The AI assistant can take actions on the user's behalf, including sharing any information it has access to. The user is responsible for any instructions they give it.</p>
<h2>Location</h2>
@@ -82,7 +85,15 @@
<ul class="links">
<li>Mapbox: <a href="https://www.mapbox.com/legal/privacy">https://www.mapbox.com/legal/privacy</a></li>
</ul>
<p>The Weather app will retrieve the user's coarse location, and will use it to query a third-party weather information provider: the US National Weather Service, then <a href="https://open-meteo.com/en/terms">Open-Meteo</a> if the location is outside the US. Outside the US, it also asks the phone's built-in geocoder (Google's on most Android phones, Apple's on iOS) for the name of the place.</p>
<p>The Weather app will retrieve the user's coarse location, and will use it to query a third-party weather information provider: the US National Weather Service, then Open-Meteo if the location is outside the US. Outside the US, it also asks the phone's built-in geocoder (Google's on most Android phones, Apple's on iOS) for the name of the place.</p>
<ul class="links">
<li>Open-Meteo: <a href="https://open-meteo.com/en/terms">https://open-meteo.com/en/terms</a></li>
</ul>
<h2>Spotify</h2>
<p>On iOS, the Music app, Glanceboard and the voice assistant can show and control Spotify through Spotify's Web API, once the user has created their own Spotify developer app and signed in. Signing in happens on Spotify's website in the system's sign-in sheet; Faceclaw never sees the password, and stores the resulting sign-in tokens on the phone. While Spotify is shown or used, Faceclaw requests the user's playback state, queue, library and search results from Spotify and sends it playback commands, directly from the phone. This is subject to Spotify's privacy policy.</p>
<ul class="links">
<li>Spotify: <a href="https://www.spotify.com/legal/privacy-policy/">https://www.spotify.com/legal/privacy-policy/</a></li>
</ul>
<h2>EvenHub</h2>
<p>The EvenHub app store is subject to Even Realities' privacy policy: <a href="https://support.evenrealities.com/hc/en-us/articles/14127464826511-Privacy-Policy">https://support.evenrealities.com/hc/en-us/articles/14127464826511-Privacy-Policy</a>. Apps downloaded from the EvenHub app store come with their own privacy policies.</p>
<h2>Wear OS Watch</h2>