@ouro.bot/cli 0.1.0-alpha.880 → 0.1.0-alpha.882

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.882",
+      "changes": [
+        "Live phone calls work again on both the OpenAI SIP and Media Streams paths: every tool offered to OpenAI Realtime now has a Realtime-valid schema (a top-level oneOf in external_event_disposition had made Realtime reject the whole session setup, which dropped SIP calls and left Media Streams audio as noise), folded schemas explain their alternatives in the description, a tool that cannot be advertised is dropped with one warning per call and cannot be executed, and the bridge logs when Twilio reports a stream ended."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.881",
+      "changes": [
+        "Voice calls are authenticated end to end: the signed Twilio webhook records who is calling and hands the Media Stream (or the OpenAI SIP leg) a short-lived single-use token, and a stream or SIP call without a valid token is refused, so the caller identity, friend, direction and greeting come from server state and never from stream parameters. defaultFriendId no longer decides who an inbound caller is on any transport, friend ids are validated before they touch the friend store, the voice transport stays off without voice.twilioAuthToken, a call that cannot connect now hears a short failure line instead of dead air, and a failed transcript save or stray rejection no longer takes the voice process down. A malformed frame from an unauthenticated client no longer crashes the voice process, a second stream for the same call is refused even while the first is still starting, and a burst of more than five uncaught exceptions in a minute makes the voice process exit so its supervisor restarts it."
+      ]
+    },
     {
       "version": "0.1.0-alpha.880",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.880",
+  "runtimeVersion": "0.1.0-alpha.882",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.880</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.882</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/senses/voice/call-auth.js

@@ -0,0 +1,248 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecentIds = exports.PendingVoiceCalls = exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES = exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS = exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS = void 0;
+exports.newVoiceCallNonce = newVoiceCallNonce;
+exports.mintVoiceCallToken = mintVoiceCallToken;
+exports.verifyVoiceCallToken = verifyVoiceCallToken;
+const crypto = __importStar(require("node:crypto"));
+const runtime_1 = require("../../nerves/runtime");
+exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS = 60_000;
+exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS = 120_000;
+exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES = 256;
+const TOKEN_KEY_DOMAIN = "ouro-voice-stream-v1";
+function newVoiceCallNonce() {
+    return crypto.randomBytes(16).toString("hex");
+}
+function signingKey(secret) {
+    return crypto.createHmac("sha256", secret).update(TOKEN_KEY_DOMAIN).digest();
+}
+function sign(secret, payload) {
+    return crypto.createHmac("sha256", signingKey(secret)).update(payload).digest("base64url");
+}
+function mintVoiceCallToken(input) {
+    const claims = {
+        v: 1,
+        p: input.purpose,
+        a: input.agentName,
+        c: input.callSid,
+        d: input.direction,
+        e: input.nowMs + (input.ttlMs ?? exports.DEFAULT_VOICE_CALL_TOKEN_TTL_MS),
+        n: input.nonce ?? newVoiceCallNonce(),
+        ...(input.outboundId ? { o: input.outboundId } : {}),
+        ...(input.from ? { f: input.from } : {}),
+        ...(input.to ? { t: input.to } : {}),
+    };
+    const payload = Buffer.from(JSON.stringify(claims)).toString("base64url");
+    return `${payload}.${sign(input.secret, payload)}`;
+}
+function parseClaims(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const claims = parsed;
+    if (claims.v !== 1
+        || (claims.p !== "stream" && claims.p !== "sip")
+        || typeof claims.a !== "string"
+        || typeof claims.c !== "string"
+        || typeof claims.d !== "string"
+        || typeof claims.e !== "number"
+        || typeof claims.n !== "string")
+        return null;
+    return claims;
+}
+function verifyVoiceCallToken(input) {
+    const token = input.token.trim();
+    if (!token)
+        return { ok: false, reason: "missing" };
+    const parts = token.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return { ok: false, reason: "malformed" };
+    const [payload, signature] = parts;
+    const expected = Buffer.from(sign(input.secret, payload));
+    const actual = Buffer.from(signature);
+    if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
+        return { ok: false, reason: "bad_signature" };
+    }
+    const claims = parseClaims(payload);
+    if (!claims)
+        return { ok: false, reason: "malformed" };
+    if (input.nowMs > claims.e)
+        return { ok: false, reason: "expired" };
+    if (claims.p !== input.purpose)
+        return { ok: false, reason: "wrong_purpose" };
+    if (claims.a !== input.agentName)
+        return { ok: false, reason: "wrong_agent" };
+    if (claims.c !== input.callSid)
+        return { ok: false, reason: "wrong_call" };
+    return {
+        ok: true,
+        nonce: claims.n,
+        direction: claims.d,
+        ...(claims.o ? { outboundId: claims.o } : {}),
+        ...(claims.f ? { from: claims.f } : {}),
+        ...(claims.t ? { to: claims.t } : {}),
+    };
+}
+/**
+ * Bounded, TTL'd, in-memory record of calls the signed webhooks have admitted, keyed by CallSid.
+ * A call can hold several nonces at once (Twilio may retry the webhook while a greeting is being
+ * prepared); the first successful consume removes the whole entry, so the call connects once.
+ */
+class PendingVoiceCalls {
+    entries = new Map();
+    connected = new Map();
+    rejected = new Map();
+    ttlMs;
+    maxEntries;
+    now;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? exports.DEFAULT_PENDING_VOICE_CALL_TTL_MS;
+        this.maxEntries = options.maxEntries ?? exports.DEFAULT_PENDING_VOICE_CALL_MAX_ENTRIES;
+        this.now = options.now ?? Date.now;
+    }
+    record(identity, nonce) {
+        const existing = this.live(identity.callSid);
+        const nonces = existing?.nonces ?? new Set();
+        nonces.add(nonce);
+        // Re-insert so the Map's insertion order is least-recently-recorded first.
+        this.entries.delete(identity.callSid);
+        this.entries.set(identity.callSid, { identity, nonces, expiresAtMs: this.now() + this.ttlMs });
+        while (this.entries.size > this.maxEntries) {
+            const evicted = this.entries.keys().next().value;
+            this.entries.delete(evicted);
+            // An evicted call's stream will be refused, so make the pressure visible.
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_pending_call_evicted",
+                message: "evicted a pending voice call before its stream started",
+                meta: { callSid: evicted, maxEntries: this.maxEntries },
+            });
+        }
+    }
+    consume(callSid, nonce) {
+        const entry = this.live(callSid);
+        if (!entry || !entry.nonces.has(nonce))
+            return null;
+        this.entries.delete(callSid);
+        this.remember(this.connected, callSid);
+        return entry.identity;
+    }
+    /**
+     * Remember that a stream for this call was refused, so the call's end can say so. Ignored for a
+     * call that already connected: a replayed token must not turn a good call into a failure.
+     */
+    markRejected(callSid) {
+        if (this.recalls(this.connected, callSid))
+            return;
+        this.remember(this.rejected, callSid);
+    }
+    /**
+     * Called when the stream's `<Connect>` ends. Returns true when the call never connected to a
+     * session (still waiting, or its stream was refused); forgets everything known about the call.
+     */
+    settle(callSid) {
+        const failed = this.live(callSid) !== undefined || this.recalls(this.rejected, callSid);
+        this.entries.delete(callSid);
+        this.connected.delete(callSid);
+        this.rejected.delete(callSid);
+        return failed;
+    }
+    has(callSid) {
+        return this.live(callSid) !== undefined;
+    }
+    discard(callSid) {
+        return this.entries.delete(callSid);
+    }
+    size() {
+        return this.entries.size;
+    }
+    remember(marks, callSid) {
+        marks.delete(callSid);
+        marks.set(callSid, this.now() + this.ttlMs);
+        while (marks.size > this.maxEntries)
+            marks.delete(marks.keys().next().value);
+    }
+    recalls(marks, callSid) {
+        const expiresAtMs = marks.get(callSid);
+        if (expiresAtMs === undefined)
+            return false;
+        if (this.now() > expiresAtMs) {
+            marks.delete(callSid);
+            return false;
+        }
+        return true;
+    }
+    live(callSid) {
+        const entry = this.entries.get(callSid);
+        if (!entry)
+            return undefined;
+        if (this.now() > entry.expiresAtMs) {
+            this.entries.delete(callSid);
+            return undefined;
+        }
+        return entry;
+    }
+}
+exports.PendingVoiceCalls = PendingVoiceCalls;
+/** Bounded, TTL'd "have I seen this id" set, used to ignore replayed or duplicate webhooks. */
+class RecentIds {
+    options;
+    seen = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Returns true when the id is new (and remembers it), false when it was already seen. */
+    add(id) {
+        const now = (this.options.now ?? Date.now)();
+        const expiresAtMs = this.seen.get(id);
+        if (expiresAtMs !== undefined && now <= expiresAtMs)
+            return false;
+        this.seen.delete(id);
+        this.seen.set(id, now + (this.options.ttlMs ?? 600_000));
+        while (this.seen.size > (this.options.maxEntries ?? 1_024)) {
+            this.seen.delete(this.seen.keys().next().value);
+        }
+        return true;
+    }
+}
+exports.RecentIds = RecentIds;

package/dist/senses/voice/process-guards.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installVoiceProcessGuards = installVoiceProcessGuards;
+const runtime_1 = require("../../nerves/runtime");
+function describeError(error) {
+    return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+/**
+ * Keep one bad call from taking the voice process down for every other caller. A failure that
+ * escapes a call's own handlers is logged and the process keeps serving. A burst of uncaught
+ * exceptions means the process is no longer healthy, so it exits and lets the supervisor restart it.
+ */
+function installVoiceProcessGuards(proc, options = {}) {
+    const limit = options.limit ?? 5;
+    const windowMs = options.windowMs ?? 60_000;
+    const exit = options.exit ?? ((code) => proc.exit(code));
+    const now = options.now ?? Date.now;
+    const recent = [];
+    proc.on("unhandledRejection", (reason) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_process_error",
+            message: "Voice process caught an unhandled promise rejection and kept running",
+            meta: { kind: "unhandledRejection", error: describeError(reason) },
+        });
+    });
+    proc.on("uncaughtException", (error) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_process_error",
+            message: "Voice process caught an uncaught exception and kept running",
+            meta: { kind: "uncaughtException", error: describeError(error) },
+        });
+        const at = now();
+        recent.push(at);
+        while (recent.length > 0 && at - recent[0] > windowMs)
+            recent.shift();
+        if (recent.length > limit) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.voice_process_crash_budget_exhausted",
+                message: "Voice process exceeded its uncaught exception budget and is exiting for a supervisor restart",
+                meta: { limit, windowMs, count: recent.length },
+            });
+            exit(1);
+        }
+    });
+}

package/dist/senses/voice/realtime-tool-schema.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRealtimeToolSchema = normalizeRealtimeToolSchema;
+exports.realtimeToolParameters = realtimeToolParameters;
+exports.realtimeToolsFromDefinitions = realtimeToolsFromDefinitions;
+exports.createRealtimeToolReporter = createRealtimeToolReporter;
+exports.createRealtimeToolAdvertiser = createRealtimeToolAdvertiser;
+// OpenAI Realtime rejects the whole session (invalid_function_parameters) when any
+// tool's parameters schema lacks top-level `type: "object"` or carries a top-level
+// oneOf/anyOf/allOf/enum/const/not. Other providers' handling of those keywords is not relied
+// on here, so every tool is normalized before it is advertised to a Realtime session.
+// Argument validation still runs against the original schema when a tool call arrives.
+const runtime_1 = require("../../nerves/runtime");
+const COMBINATORS = ["oneOf", "anyOf", "allOf"];
+const FORBIDDEN_TOP_LEVEL = [...COMBINATORS, "enum", "const", "not"];
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a)) {
+        return Array.isArray(b) && a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (isRecord(a) && isRecord(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((key) => key in b && deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+function describeDefinition(value) {
+    if (isRecord(value) && typeof value.type === "string")
+        return value.type;
+    if (isRecord(value) && Array.isArray(value.type))
+        return value.type.join("|");
+    return JSON.stringify(value);
+}
+/** Resolves a branch that is a local `$ref`; returns undefined when it cannot be resolved. */
+function resolveBranch(root, branch) {
+    let current = branch;
+    const seen = new Set();
+    while (isRecord(current) && typeof current.$ref === "string") {
+        const ref = current.$ref;
+        if (seen.has(ref))
+            return undefined;
+        seen.add(ref);
+        const match = /^#\/(\$defs|definitions)\/([^/]+)$/.exec(ref);
+        const container = match ? root[match[1]] : undefined;
+        const name = match ? match[2].replace(/~1/g, "/").replace(/~0/g, "~") : "";
+        if (!isRecord(container) || !(name in container))
+            return undefined;
+        current = container[name];
+    }
+    return current;
+}
+/**
+ * Normalizes a tool schema for Realtime. Returns null when the schema cannot be expressed
+ * as an object (the caller should drop that tool).
+ */
+function normalizeRealtimeToolSchema(schema, onConflict = () => { }) {
+    if (schema === undefined)
+        return { parameters: { type: "object", properties: {} } };
+    if (!isRecord(schema))
+        return null;
+    if (schema.type !== undefined && schema.type !== "object")
+        return null;
+    const needsRewrite = schema.type === undefined || FORBIDDEN_TOP_LEVEL.some((key) => key in schema);
+    if (!needsRewrite)
+        return { parameters: schema };
+    // Fold the alternatives into one object whose properties are the union (all
+    // optional beyond the merged `required`), so the model can still call the tool.
+    const properties = isRecord(schema.properties) ? { ...schema.properties } : {};
+    const mergedRequired = [];
+    const alternatives = new Map();
+    const notes = [];
+    for (const key of COMBINATORS) {
+        const branches = schema[key];
+        if (!Array.isArray(branches))
+            continue;
+        const objectBranches = [];
+        for (const raw of branches) {
+            const branch = resolveBranch(schema, raw);
+            if (isRecord(raw) && typeof raw.$ref === "string" && branch === undefined)
+                return null;
+            if (isRecord(branch) && isRecord(branch.properties))
+                objectBranches.push(branch);
+        }
+        for (const branch of objectBranches) {
+            for (const [name, value] of Object.entries(branch.properties)) {
+                if (!(name in properties)) {
+                    properties[name] = value;
+                }
+                else if (!deepEqual(properties[name], value)) {
+                    const others = alternatives.get(name) ?? new Set();
+                    if (others.size === 0)
+                        onConflict(name);
+                    others.add(describeDefinition(value));
+                    alternatives.set(name, others);
+                }
+            }
+        }
+        const required = (branch) => Array.isArray(branch.required) ? branch.required.filter((n) => typeof n === "string") : [];
+        if (key === "allOf" || objectBranches.length === 1) {
+            for (const branch of objectBranches)
+                mergedRequired.push(...required(branch));
+        }
+        else if (objectBranches.length > 1) {
+            const parts = objectBranches.map((branch, i) => {
+                const names = required(branch);
+                return names.length > 0
+                    ? `(${i + 1}) ${names.join(", ")} (all required)`
+                    : `(${i + 1}) no required fields`;
+            });
+            notes.push(`Provide ${key === "oneOf" ? "exactly one of" : "one or more of"}: ${parts.join("; ")}.`);
+        }
+    }
+    for (const [name, others] of alternatives)
+        notes.push(`\`${name}\` may also be: ${[...others].join(", ")}.`);
+    const rewritten = { ...schema, type: "object", properties };
+    for (const key of FORBIDDEN_TOP_LEVEL)
+        delete rewritten[key];
+    const baseRequired = Array.isArray(schema.required) ? schema.required : [];
+    const required = [...new Set([...baseRequired, ...mergedRequired.filter((name) => name in properties)])];
+    if (required.length > 0)
+        rewritten.required = required;
+    return { parameters: rewritten, ...(notes.length > 0 ? { note: notes.join(" ") } : {}) };
+}
+function realtimeToolParameters(schema) {
+    return normalizeRealtimeToolSchema(schema)?.parameters ?? null;
+}
+function realtimeToolsFromDefinitions(definitions, reporter = createRealtimeToolReporter()) {
+    const tools = [];
+    for (const { function: fn } of definitions) {
+        const result = normalizeRealtimeToolSchema(fn.parameters, (property) => reporter.conflict(fn.name, property));
+        if (result === null) {
+            reporter.dropped(fn.name);
+            continue;
+        }
+        const description = [fn.description, result.note].filter(Boolean).join(" ");
+        tools.push({
+            type: "function",
+            name: fn.name,
+            ...(description ? { description } : {}),
+            parameters: result.parameters,
+        });
+    }
+    return tools;
+}
+/** Emits warn events carrying the given context (agent, call id); each distinct finding is emitted once. */
+function createRealtimeToolReporter(context = {}) {
+    const reported = new Set();
+    return {
+        dropped(toolName) {
+            const key = `drop:${toolName}`;
+            if (reported.has(key))
+                return;
+            reported.add(key);
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_realtime_tool_dropped",
+                message: "tool schema is not valid for OpenAI Realtime; tool omitted from the voice session",
+                meta: { ...context, toolName },
+            });
+        },
+        conflict(toolName, property) {
+            const key = `conflict:${toolName}:${property}`;
+            if (reported.has(key))
+                return;
+            reported.add(key);
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_realtime_tool_schema_conflict",
+                message: "tool schema branches define the same property differently; first definition kept for OpenAI Realtime",
+                meta: { ...context, toolName, property },
+            });
+        },
+    };
+}
+/**
+ * Per-call advertiser: normalizes selections, reports each finding once per call, and
+ * answers which tool names were actually advertised to the model.
+ */
+function createRealtimeToolAdvertiser(context = {}) {
+    const reporter = createRealtimeToolReporter(context);
+    return {
+        tools(definitions) {
+            return realtimeToolsFromDefinitions(definitions, reporter);
+        },
+        isAdvertised(definitions, name) {
+            return realtimeToolsFromDefinitions(definitions, reporter).some((tool) => tool.name === name);
+        },
+    };
+}

package/dist/senses/voice/twilio-phone-runtime.js

@@ -516,6 +516,19 @@ async function startConfiguredTwilioPhoneTransport(options, deps = defaultTwilio
         });
         return { status: "disabled", reason };
     }
+    if (!settings.twilioAuthToken?.trim()) {
+        // Call tokens and webhook signatures are keyed by the Twilio auth token; without it the bridge
+        // could not tell a real Twilio call from a forged one, so it does not listen at all.
+        const reason = "voice.twilioAuthToken is required for inbound calls";
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_twilio_transport_disabled",
+            message: "Twilio phone voice transport is not attached because the Twilio auth token is missing",
+            meta: { agentName: options.agentName, reason },
+        });
+        return { status: "disabled", reason };
+    }
     await deps.cacheSelectedProviderCredentials(options.agentName);
     if (settings.openaiRealtime?.apiKeySource === "integrations.openaiEmbeddingsApiKey") {
         (0, runtime_1.emitNervesEvent)({