@fonoster/common 0.30.0 → 0.31.0

package/dist/protos/session.proto

@@ -0,0 +1,194 @@
+// Session: the per-call control stream the Roomr node opens to the session endpoint (in Fonoster,
+// AppBridge behind a Kubernetes Service). The node is the client: one new connection per call,
+// `Start` first, then commands from the app and events from the node, in order. Audio never
+// travels here; it is RTP between the two MediaEndpoints.
+// Spec: openspec/changes/redesign-roomr/specs/media-control ("Each call opens one control stream
+// to the session endpoint", "App audio is RTP negotiated on the control stream", "Transfer modes",
+// "Hold silences the app and plays hold audio", "Listeners fork audio by track", "Endings carry a
+// reason", "The app sends DTMF on the caller's leg"). Messages only grow: add fields, never
+// renumber or reuse them, and receivers ignore fields they do not know.
+//
+// Regenerate the Go code with go/roomr/api/generate.sh.
+syntax = "proto3";
+
+package session.v1;
+
+option go_package = "github.com/fonoster/roomr/api/session/v1;sessionv1";
+
+service Session {
+  rpc Connect(stream NodeMessage) returns (stream AppMessage);
+}
+
+// An RTP endpoint: `codec` is "L16/16000" on app legs; `srtp_key` (SDES, base64) when encrypted.
+message MediaEndpoint {
+  string ip = 1;
+  uint32 port = 2;
+  string codec = 3;
+  string srtp_key = 4;
+}
+
+message SipAuth {
+  string username = 1;
+  string password = 2;
+}
+
+// A SIP destination: `proxy` carries the transport in its URI (sip:host:port;transport=tcp).
+message SipTarget {
+  string uri = 1;
+  string proxy = 2;
+  map<string, string> headers = 3;
+  SipAuth auth = 4;
+}
+
+// ---- node to app
+
+message NodeMessage {
+  oneof msg {
+    Start start = 1;
+    Dtmf dtmf = 2;
+    Event event = 3;
+  }
+}
+
+message Start {
+  enum Direction {
+    INBOUND = 0;
+    OUTBOUND = 1;
+  }
+  string call_ref = 1;
+  Direction direction = 2;
+  string from = 3;
+  string to = 4;
+  // Every INVITE header, as received (inbound) or as sent (outbound).
+  map<string, string> headers = 5;
+  // Opaque to the node: CreateCall's metadata, passed through untouched.
+  map<string, string> metadata = 6;
+  string room_ref = 7;
+  // The node's RTP endpoint for this call's app leg.
+  MediaEndpoint media = 8;
+  string node_ref = 9;
+}
+
+message Dtmf {
+  string digit = 1;
+  // rfc4733, sip_info or inband
+  string source = 2;
+}
+
+message Event {
+  // 3 was operation_done (Play and Record left the node).
+  reserved 3;
+  reserved "operation_done";
+  oneof event {
+    ParticipantJoined participant_joined = 1;
+    ParticipantLeft participant_left = 2;
+    TransferResult transfer_result = 4;
+    Ended ended = 5;
+  }
+}
+
+message ParticipantJoined {
+  string participant_ref = 1;
+  uint32 track_id = 2;
+}
+
+message ParticipantLeft {
+  string participant_ref = 1;
+  string cause = 2;
+}
+
+message TransferResult {
+  // completed, referred or failed
+  string status = 1;
+  string cause = 2;
+  uint32 sip_status = 3;
+}
+
+// The call ended: `cause` is one of caller_hangup, callee_hangup, busy, no_answer, rejected,
+// media_timeout, node_error, max_duration, removed, app_gone; `sip_status` when SIP gave one.
+message Ended {
+  string cause = 1;
+  uint32 sip_status = 2;
+}
+
+// ---- app to node
+
+message AppMessage {
+  // 4, 5 and 13 were play, stop and record: the node is the SIP and media edge, not an app server
+  // (an app plays its own audio on its RTP leg; recording is a listener).
+  reserved 4, 5, 13;
+  reserved "play", "stop", "record";
+  oneof msg {
+    Answer answer = 1;
+    Ready ready = 2;
+    Reject reject = 3;
+    Transfer transfer = 6;
+    TransferComplete transfer_complete = 7;
+    Hold hold = 8;
+    Resume resume = 9;
+    SendDtmf send_dtmf = 10;
+    AddListener add_listener = 11;
+    RemoveListener remove_listener = 12;
+    Hangup hangup = 14;
+  }
+}
+
+// Inbound: the app takes the call; the node answers 200 OK.
+message Answer {
+  MediaEndpoint media = 1;
+  // Lowers the node's maximum call duration for this call (0: the node's).
+  uint32 max_duration_s = 2;
+}
+
+// Outbound: the app is ready for the answered call.
+message Ready {
+  MediaEndpoint media = 1;
+}
+
+// Inbound: the app refuses the call with this SIP status (4xx to 6xx).
+message Reject {
+  uint32 sip_status = 1;
+  string reason = 2;
+}
+
+message Transfer {
+  SipTarget to = 1;
+  // cold, warm or refer
+  string mode = 2;
+  // Warm: music for the caller while the new party is dialed.
+  string music = 3;
+  uint32 ring_timeout_s = 4;
+}
+
+message TransferComplete {}
+
+message Hold {
+  string music = 1;
+}
+
+message Resume {}
+
+// RFC 4733 events on the caller's leg, in order.
+message SendDtmf {
+  // 0-9, *, #, A-D.
+  string digits = 1;
+}
+
+message ListenTrack {
+  uint32 track_id = 1;
+  MediaEndpoint rtp = 2;
+}
+
+message AddListener {
+  string listener_ref = 1;
+  repeated ListenTrack listen = 2;
+}
+
+message RemoveListener {
+  string listener_ref = 1;
+}
+
+message Hangup {
+  uint32 sip_status = 1;
+  string reason = 2;
+}

package/dist/protos/usage.proto

@@ -0,0 +1,59 @@
+/*
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+syntax = "proto3";
+
+package fonoster.usage.v1beta2;
+
+// What the workspace consumed: quantities only, never money (usage-metering spec).
+service Usage {
+  // Gets usage totals for a range of days, grouped as requested
+  rpc GetUsage (GetUsageRequest) returns (GetUsageResponse) {}
+}
+
+message GetUsageRequest {
+  // First day of the range, YYYY-MM-DD (UTC), inclusive
+  string from_day = 1;
+  // Last day of the range, YYYY-MM-DD (UTC), inclusive
+  string to_day = 2;
+  // Dimensions to group by: day | workspace | meter | provider | model | key_source | origin.
+  // Totals are always split by meter, so meter is implied.
+  repeated string group_by = 3;
+  // Owners only: every workspace the caller owns, instead of the caller's workspace
+  bool all_owned = 4;
+}
+
+message UsageRow {
+  // Set only for the dimensions requested in group_by
+  string day = 1;
+  string workspace_ref = 2;
+  string meter = 3;
+  // second | character | token | count | byte
+  string unit = 4;
+  string provider = 5;
+  string model = 6;
+  // platform | workspace; empty for meters that call no vendor
+  string key_source = 7;
+  // call | browser_test | eval | api
+  string origin = 8;
+  double quantity = 9;
+}
+
+message GetUsageResponse {
+  repeated UsageRow rows = 1;
+}

package/dist/registry/Registry.d.ts

@@ -1,4 +1,4 @@
-import { Capability, CatalogEntry, ItemKind, ModelEntry, ProviderEntry, RegistryStore, Usage, UsageSource, VoiceEntry } from "./types";
+import { Capability, CatalogEntry, ItemKind, ModelEntry, ProviderEndpoints, ProviderEntry, RegistryStore, Usage, UsageSource, VoiceEntry } from "./types";
 /** Adapters that ship with this version (add-provider-registry, P2). */
 export declare const BUILT_IN_ADAPTERS: string[];
 export declare class RegistryError extends Error {
@@ -17,8 +17,6 @@ export type RegistryOptions = {
     store: RegistryStore;
     usages?: UsageSource;
     actor?: string;
-    /** Allows the fake adapter (test deployments only; conformance "Implementations ship fake adapters"). */
-    testMode?: boolean;
     now?: () => Date;
     /** The command line that made the change, stored in every audit entry (spec "Every write is audited"). */
     commandLine?: string;
@@ -32,13 +30,21 @@ export declare class Registry {
     private audit;
     /** Rejects anything that looks like a credential (the catalog never holds a secret). */
     private assertNoSecrets;
+    /**
+     * A provider names a built-in adapter, a credentialRef name when it needs a key (none:
+     * keyless), and plain endpoint URLs.
+     */
+    private assertProvider;
     private assertNew;
     private require;
     addProvider(input: {
         id: string;
         adapter: string;
         capabilities: Capability[];
-        credentialRef: string;
+        /** Omitted: a keyless provider (no key needed). */
+        credentialRef?: string;
+        endpoints?: ProviderEndpoints;
+        label?: string;
     } & Record<string, unknown>): ProviderEntry;
     addModel(input: {
         id: string;
@@ -46,6 +52,7 @@ export declare class Registry {
         features?: string[];
         languages?: string[];
         settings?: string[];
+        label?: string;
     } & Record<string, unknown>): ModelEntry;
     addVoice(input: {
         id: string;
@@ -53,13 +60,14 @@ export declare class Registry {
         language?: string;
         gender?: string;
         ownerWorkspace?: string;
+        label?: string;
     } & Record<string, unknown>): VoiceEntry;
     private requireProviderFor;
     /** What moving the usages of `id` to `replacement` would do (shared by deprecate and retire). */
     impact(id: string, replacement: string, voiceMap?: Record<string, string>): Impact;
     deprecate(kind: ItemKind, id: string, replacement: string, retireOn: string): Impact;
     retire(kind: ItemKind, id: string, voiceMap?: Record<string, string>): Impact;
-    /** What the gateway does with an id at session start: retired ids resolve to their replacement. */
+    /** What AppBridge does with an id at session start: retired ids resolve to their replacement. */
     resolve(id: string): {
         id: string;
         event?: "provider.deprecated_used" | "provider.retired_used";

package/dist/registry/Registry.js

@@ -19,8 +19,10 @@ exports.Registry = exports.RegistryError = exports.BUILT_IN_ADAPTERS = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+const url_1 = require("url");
 const yaml_1 = require("yaml");
 const features_1 = require("./features");
+const types_1 = require("./types");
 /** Adapters that ship with this version (add-provider-registry, P2). */
 exports.BUILT_IN_ADAPTERS = [
     "deepgram",
@@ -31,8 +33,10 @@ exports.BUILT_IN_ADAPTERS = [
     "anthropic",
     "groq",
     "ollama",
+    "aicoustics",
     "fake"
 ];
+const ENDPOINT_SCHEMES = ["http:", "https:", "ws:", "wss:"];
 // provider/name; the name may have its own slashes, as hosted models do (groq/openai/gpt-oss-120b).
 const CATALOG_ID = /^[a-z0-9-]+(\/[A-Za-z0-9._-]+)+$/;
 const REF = /^[a-z0-9][a-z0-9-]*$/;
@@ -76,6 +80,35 @@ class Registry {
             }
         }
     }
+    /**
+     * A provider names a built-in adapter, a credentialRef name when it needs a key (none:
+     * keyless), and plain endpoint URLs.
+     */
+    assertProvider(p) {
+        var _a, _b;
+        if (!exports.BUILT_IN_ADAPTERS.includes(p.adapter))
+            throw new RegistryError(`unknown adapter: ${p.adapter}`);
+        for (const c of (_a = p.capabilities) !== null && _a !== void 0 ? _a : [])
+            if (!types_1.CAPABILITIES.includes(c))
+                throw new RegistryError(`unknown capability: ${c}`);
+        if (p.credentialRef !== undefined && !REF.test(p.credentialRef))
+            throw new RegistryError("credentialRef must be a name such as deepgram-default");
+        for (const [capability, url] of Object.entries((_b = p.endpoints) !== null && _b !== void 0 ? _b : {})) {
+            if (!types_1.CAPABILITIES.includes(capability))
+                throw new RegistryError(`unknown endpoint capability: ${capability}`);
+            let parsed;
+            try {
+                parsed = new url_1.URL(String(url));
+            }
+            catch (_c) {
+                throw new RegistryError(`endpoints.${capability} must be a URL`);
+            }
+            if (!ENDPOINT_SCHEMES.includes(parsed.protocol))
+                throw new RegistryError(`endpoints.${capability} must be an http, https, ws or wss URL`);
+            if (parsed.username || parsed.password)
+                throw new RegistryError(`secrets cannot be stored in the catalog (endpoints.${capability} has user information)`);
+        }
+    }
     assertNew(id) {
         if (!CATALOG_ID.test(id) && !REF.test(id))
             throw new RegistryError(`invalid catalog id ${id}`);
@@ -93,21 +126,10 @@ class Registry {
     addProvider(input) {
         this.assertNoSecrets(input);
         this.assertNew(input.id);
-        if (!exports.BUILT_IN_ADAPTERS.includes(input.adapter))
-            throw new RegistryError(`unknown adapter: ${input.adapter}`);
-        if (input.adapter === "fake" && !this.options.testMode) {
-            throw new RegistryError("the fake adapter is only available in test mode");
-        }
-        if (!REF.test(input.credentialRef))
-            throw new RegistryError("credentialRef must be a name such as deepgram-default");
-        const entry = {
-            kind: "provider",
-            id: input.id,
-            adapter: input.adapter,
-            capabilities: input.capabilities,
-            credentialRef: input.credentialRef,
-            state: "active"
-        };
+        this.assertProvider(input);
+        const entry = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "provider", id: input.id }, (input.label ? { label: input.label } : {})), { adapter: input.adapter, capabilities: input.capabilities }), (input.credentialRef ? { credentialRef: input.credentialRef } : {})), (input.endpoints && Object.keys(input.endpoints).length
+            ? { endpoints: input.endpoints }
+            : {})), { state: "active" });
         this.store.put(entry);
         this.audit("add-provider", entry.id, { entry, before: null, after: entry });
         return entry;
@@ -120,15 +142,7 @@ class Registry {
         const unknown = (0, features_1.unknownFeatures)(input.type, (_a = input.features) !== null && _a !== void 0 ? _a : []);
         if (unknown.length)
             throw new RegistryError(`unknown ${input.type} features: ${unknown.join(", ")}`);
-        const entry = {
-            kind: "model",
-            id: input.id,
-            type: input.type,
-            features: (_b = input.features) !== null && _b !== void 0 ? _b : [],
-            languages: (_c = input.languages) !== null && _c !== void 0 ? _c : [],
-            settings: (_d = input.settings) !== null && _d !== void 0 ? _d : [],
-            state: "active"
-        };
+        const entry = Object.assign(Object.assign({ kind: "model", id: input.id }, (input.label ? { label: input.label } : {})), { type: input.type, features: (_b = input.features) !== null && _b !== void 0 ? _b : [], languages: (_c = input.languages) !== null && _c !== void 0 ? _c : [], settings: (_d = input.settings) !== null && _d !== void 0 ? _d : [], state: "active" });
         this.store.put(entry);
         this.audit("add-model", entry.id, { entry, before: null, after: entry });
         return entry;
@@ -141,15 +155,7 @@ class Registry {
             if (model.type !== "tts")
                 throw new RegistryError(`${m} is not a tts model`);
         }
-        const entry = {
-            kind: "voice",
-            id: input.id,
-            models: input.models,
-            language: input.language,
-            gender: input.gender,
-            ownerWorkspace: input.ownerWorkspace,
-            state: "active"
-        };
+        const entry = Object.assign(Object.assign({ kind: "voice", id: input.id }, (input.label ? { label: input.label } : {})), { models: input.models, language: input.language, gender: input.gender, ownerWorkspace: input.ownerWorkspace, state: "active" });
         this.store.put(entry);
         this.audit("add-voice", entry.id, { entry, before: null, after: entry });
         return entry;
@@ -317,7 +323,7 @@ class Registry {
         });
         return report;
     }
-    /** What the gateway does with an id at session start: retired ids resolve to their replacement. */
+    /** What AppBridge does with an id at session start: retired ids resolve to their replacement. */
     resolve(id) {
         const e = this.store.get(id);
         if (!e)
@@ -386,6 +392,8 @@ class Registry {
         const out = [];
         for (const want of target) {
             this.assertNoSecrets(want);
+            if (want.kind === "provider")
+                this.assertProvider(want);
             const have = this.store.get(want.id);
             if (!have)
                 out.push({ line: `+ add ${want.kind} ${want.id}`, entry: want });
@@ -414,5 +422,11 @@ exports.Registry = Registry;
 function canonical(e) {
     return Object.fromEntries(Object.entries(e)
         .filter(([, v]) => v !== undefined)
-        .sort(([a], [b]) => a.localeCompare(b)));
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => k === "endpoints"
+        ? [k, sortedKeys(v)]
+        : [k, v]));
+}
+function sortedKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
 }

package/dist/registry/cli.js

@@ -118,11 +118,14 @@ const str = (v, name) => {
         throw new Registry_1.RegistryError(`--${name} is required`);
     return v;
 };
+/** An optional string flag (`--label` given without a value is ignored). */
+const opt = (v) => typeof v === "string" && v ? v : undefined;
 const HELP = `fonoster-registry <command>
 
-  add-provider <id> --adapter <a> --capabilities stt,tts --credential-ref <name>
+  add-provider <id> --adapter <a> --capabilities stt,tts,llm,nc [--credential-ref <name>] [--endpoints tts=<url>,stt=<url>]
   add-model <provider/model> --type stt|tts|llm [--features a,b] [--languages en,es] [--settings s]
   add-voice <provider/voice> --models <m1,m2> [--language en] [--gender female]
+                          add-* take [--label "<display name>"]; no --credential-ref: keyless
   deprecate-provider|deprecate-model|deprecate-voice <id> --replacement <id> --retire-on YYYY-MM-DD
   retire-provider|retire-model|retire-voice <id> [--voice-map old=new,...] --yes
   usage <id> | list [provider|model|voice] | show <id> | history [<id>]
@@ -137,6 +140,8 @@ const OPTIONS = {
         "adapter",
         "capabilities",
         "credential-ref",
+        "endpoints",
+        "label",
         "type",
         "features",
         "languages",
@@ -156,7 +161,6 @@ function run(argv, out = console.log) {
         delete flags[f];
     const registry = new Registry_1.Registry({
         store: new stores_1.FileRegistryStore((_a = process.env.FONOSTER_REGISTRY_FILE) !== null && _a !== void 0 ? _a : "registry.json"),
-        testMode: process.env.FONOSTER_TEST_MODE === "true",
         commandLine: commandLine(argv)
     });
     return execute(registry, command, positional, flags, out);
@@ -206,7 +210,6 @@ function runWithDatabase(argv_1) {
                 store,
                 usages,
                 actor: deps.actor,
-                testMode: process.env.FONOSTER_TEST_MODE === "true",
                 commandLine: commandLine(argv)
             });
             const sessions = command === "usage" && positional[0]
@@ -263,7 +266,14 @@ function execute(registry, command, positional, flags, out, sessions) {
                     id,
                     adapter: str(flags.adapter, "adapter"),
                     capabilities: list(flags.capabilities),
-                    credentialRef: str(flags["credential-ref"], "credential-ref")
+                    credentialRef: opt(flags["credential-ref"]),
+                    label: opt(flags.label),
+                    endpoints: Object.fromEntries(list(flags.endpoints).map((pair) => {
+                        const at = pair.indexOf("=");
+                        if (at <= 0)
+                            throw new Registry_1.RegistryError("--endpoints takes capability=url pairs, e.g. tts=http://fakes:7001");
+                        return [pair.slice(0, at), pair.slice(at + 1)];
+                    }))
                 });
                 break;
             }
@@ -273,7 +283,8 @@ function execute(registry, command, positional, flags, out, sessions) {
                     type: str(flags.type, "type"),
                     features: list(flags.features),
                     languages: list(flags.languages),
-                    settings: list(flags.settings)
+                    settings: list(flags.settings),
+                    label: opt(flags.label)
                 });
                 break;
             case "add-voice":
@@ -281,7 +292,8 @@ function execute(registry, command, positional, flags, out, sessions) {
                     id,
                     models: list(flags.models),
                     language: flags.language,
-                    gender: flags.gender
+                    gender: flags.gender,
+                    label: opt(flags.label)
                 });
                 break;
             case "deprecate-provider":
@@ -312,7 +324,7 @@ function execute(registry, command, positional, flags, out, sessions) {
                     break;
                 }
                 // With the database: per workspace, its sessions that resolved the id in the last 30
-                // days (from the gateways' registry.used events, LO-B11), then its configs.
+                // days (from the AppBridge replicas' registry.used events, LO-B11), then its configs.
                 const workspaces = [
                     ...new Set([
                         ...usages.map((u) => u.workspace),

package/dist/registry/features.d.ts

@@ -23,8 +23,8 @@ import { Capability } from "./types";
  */
 export declare const FEATURES: Record<Capability, Record<string, "hard" | "soft">>;
 export declare function unknownFeatures(type: Capability, features: string[]): string[];
-/** Hard requirements derived from an assistant config: tools need tool calling, replies stream. */
-export declare function assistantRequirements(assistant: {
+/** Hard requirements derived from an agent config: tools need tool calling, replies stream. */
+export declare function agentRequirements(agent: {
     languageModel?: {
         tools?: unknown[];
     };

package/dist/registry/features.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FEATURES = void 0;
 exports.unknownFeatures = unknownFeatures;
-exports.assistantRequirements = assistantRequirements;
+exports.agentRequirements = agentRequirements;
 /**
  * The feature vocabulary (add-provider-registry, P8). Hard features are needed for a config to
  * work at all; soft ones only degrade it (and their settings are dropped on retirement).
@@ -21,16 +21,18 @@ exports.FEATURES = {
         "word-timings": "soft",
         "turn-detection": "soft",
         multilingual: "soft"
-    }
+    },
+    // Noise cancelling has no model entries yet; the provider itself is the unit.
+    nc: {}
 };
 function unknownFeatures(type, features) {
     return features.filter((f) => !(f in exports.FEATURES[type]));
 }
-/** Hard requirements derived from an assistant config: tools need tool calling, replies stream. */
-function assistantRequirements(assistant) {
+/** Hard requirements derived from an agent config: tools need tool calling, replies stream. */
+function agentRequirements(agent) {
     var _a, _b;
     const req = ["streaming"];
-    if (((_b = (_a = assistant.languageModel) === null || _a === void 0 ? void 0 : _a.tools) !== null && _b !== void 0 ? _b : []).length)
+    if (((_b = (_a = agent.languageModel) === null || _a === void 0 ? void 0 : _a.tools) !== null && _b !== void 0 ? _b : []).length)
         req.push("tool-calling");
     return req;
 }

package/dist/registry/prisma.d.ts

@@ -23,8 +23,8 @@ export type PrismaUsageSourceOptions = {
     onNotice?: (workspace: string, notice: Record<string, unknown>) => void;
 };
 /**
- * Usages of catalog ids in apps (speech defaults: voice, TTS and STT models) and assistants (the
- * Autopilot assistant in an app's Intelligence config: `languageModel.model`, and
+ * Usages of catalog ids in apps (speech defaults: voice, TTS and STT models) and agents (the
+ * Autopilot agent in an app's Intelligence config: `languageModel.model`, and
  * `conversationSettings.voice`). Legacy rows with raw vendor names are not usages until migrated
  * to catalog ids (task 5.1).
  */