Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* The one active FaceTime Audio call.
*
* Phase 1 gave PortOS a control plane that can dial and hang up; the call-host
* page gives it ears and a mouth. This module owns the state in between: which
* call is up, whether anyone can hear it, when to give up, and what is written
* down afterwards.
*
* Four deliberate constraints:
*
* - **One call, one host.** A second call-host tab is refused rather than
* allowed to double-answer, mirroring the single-attach shell-session
* pattern. Without an attached host there is no call, because a call nobody
* can hear is worse than no call at all.
* - **The helper is the source of truth.** State follows what `probe()` reports
* about the real FaceTime window, not what PortOS believes it asked for — a
* call the user picked up or declined on their phone has to be observed.
* - **Only text is kept.** The transcript goes to the daily journal like any
* other voice turn. The audio is never persisted, and the configured handle
* never appears in what is written down.
* - **Answering is fail-closed, and reading is not answering.** The incoming
* watcher (`pollIncoming`) is only ever armed while a call-host tab is
* attached (`attachHost`/`detachHost`), so it never runs unobserved. Within
* a tick, `probe()` is a safe read — it never presses anything, and the
* native helper reports nothing distinguishing "no call" from "a caller who
* is not the configured identity" (fail-closed at the helper boundary), so
* this module never learns an unauthorized caller exists and never logs
* one. Only `answer()` — the press — is additionally gated on the host
* being attached *at press time*, because answering a call nobody can hear
* is worse than missing it.
*/
import { appendJournal, getToday } from '../brainJournal.js';
import * as facetimeBridge from './facetimeBridge.js';
import { getVoiceConfig } from './config.js';
import { getLocalMinutes, isWithinQuietHours } from './proactiveSpeech.js';
import { addNotification, NOTIFICATION_TYPES, PRIORITY_LEVELS } from '../notifications.js';
import { EventEmitter } from 'events';
export const CALL_STATES = ['idle', 'dialing', 'connected', 'listening', 'speaking', 'ended'];
export const PROBE_INTERVAL_MS = 2_000;
// A caller who has said nothing for this long has walked away or hung up
// somewhere PortOS cannot see.
export const SILENCE_HANGUP_MS = 60_000;
const DEFAULT_MAX_CALL_MINUTES = 15;
const initialState = () => ({
state: 'idle',
startedAt: null,
lastVoiceAt: null,
endedReason: null,
physicalDisconnect: null,
transcript: [],
// 'user' — PortOS placed this call on request. 'mind' — the Persistent Mind
// placed it (voice.call-user). 'inbound' — the user called PortOS and the
// autoAnswer watcher answered it. `origin` decides whether the transcript
// is handed back to the persistent mind afterwards; `openingLine` is what
// the call host speaks the moment the far end picks up (consumed once, so a
// state re-emit cannot make it say it twice).
origin: 'user',
openingLine: '',
context: null,
// Only meaningful for `origin === 'inbound'`: whether the Persistent Mind
// was running at the moment the call was answered. Captured once so a mind
// that starts or stops mid-call cannot flip the hangup handoff decision.
mindEnabled: false,
});
let session = initialState();
let host = null;
let timer = null;
let listener = null;
// Broadcast sink for anything other than the call-host socket — the Mind tab
// wants to show an active-call chip regardless of which tab is carrying the
// audio. `listener` above stays a single slot owned by the attached host
// (it also drives that socket's opening-line delivery); this is a plain
// multi-subscriber event, mirroring `notificationEvents` in notifications.js.
export const callStateEvents = new EventEmitter();
// Injectable so the state machine can be driven with stubs and fake timers
// instead of a real helper and a real call.
// Imported lazily: the persistent-mind supervisor pulls in a large service
// graph, and a call the mind did not place — or answer — never needs it.
const enqueueMindMessage = async (text) => {
const { enqueuePersistentMindMessage } = await import('../persistentMindSupervisor.js');
return enqueuePersistentMindMessage({ text });
};
const isMindEnabled = async () => {
const { getPersistentMindState } = await import('../persistentMindSupervisor.js');
const state = await getPersistentMindState();
return Boolean(state?.enabled);
};
const buildInboundContext = async () => {
const { buildInboundCallContext } = await import('../persistentMindCallCapability.js');
return buildInboundCallContext();
};
const MISSED_CALL_TITLES = {
'no-host': 'Missed call from you — the call host was not attached',
'helper-failed': 'Missed call from you — the FaceTime helper failed to answer',
};
const notifyMissedCall = async (reason) => addNotification({
type: NOTIFICATION_TYPES.AGENT_WARNING,
title: MISSED_CALL_TITLES[reason] || 'Missed call from you',
description: 'An incoming call from your configured identity rang and PortOS could not answer it automatically.',
priority: PRIORITY_LEVELS.MEDIUM,
metadata: { source: 'voice-facetime-incoming', reason },
});
const defaultDeps = () => ({
probe: facetimeBridge.probe,
call: facetimeBridge.call,
answer: facetimeBridge.answer,
hangup: facetimeBridge.hangup,
appendJournal,
enqueueMindMessage,
isMindEnabled,
buildInboundContext,
notifyMissedCall,
now: Date.now,
});
let deps = defaultDeps();
/** Test seam — override the helper/clock, or restore the real ones. */
export const __setCallSessionDeps = (overrides = {}) => {
deps = { ...defaultDeps(), ...overrides };
};
const publicState = () => ({
state: session.state,
active: session.state !== 'idle' && session.state !== 'ended',
hostAttached: Boolean(host),
startedAt: session.startedAt,
endedReason: session.endedReason,
physicalDisconnect: session.physicalDisconnect,
turns: session.transcript.length,
});
const emitState = () => {
const snapshot = publicState();
// The host page and the Mind tab both render call state, so it is broadcast
// rather than replied to whoever last acted.
try {
listener?.(snapshot);
} catch (error) {
console.error(`❌ voice call: state listener failed: ${error.message}`);
}
callStateEvents.emit('state', snapshot);
return snapshot;
};
/** Register the sink for `voice:call:state` broadcasts. */
export const setCallStateListener = (fn) => { listener = fn; };
export const getCallState = () => publicState();
export const getCallHost = () => host;
export const isCallActive = () => publicState().active;
/**
* The bounded briefing the caller-side turns run with, or null for a call the
* user placed themselves. Read per turn so the pipeline stays stateless.
*/
export const getCallContext = () => (publicState().active ? session.context : null);
/**
* Read the pending opening line without consuming it.
*
* Non-destructive on purpose: the delivery it feeds can fail (the TTS provider
* is down, rate-limited, or times out), and clearing before the line has
* actually been spoken loses it for good — the call then connects to silence
* permanently, which is the exact failure the opening line exists to prevent.
* The caller clears it with `clearCallOpeningLine` once delivery succeeded.
*/
export function peekCallOpeningLine() {
if (!publicState().active) return '';
return session.openingLine;
}
/** Retire the opening line once it has actually been delivered. */
export function clearCallOpeningLine() {
session.openingLine = '';
}
/**
* Take the pending opening line, clearing it. Consume-once on purpose: the
* host speaks it on the first `connected` observation, and `voice:call:state`
* is broadcast more than once per call.
*/
export function takeCallOpeningLine() {
if (!publicState().active) return '';
const line = peekCallOpeningLine();
clearCallOpeningLine();
return line;
}
/**
* Claim the single call-host slot.
*
* Returns `{ ok: false, reason: 'host-taken' }` rather than displacing the
* incumbent: two tabs reading the same BlackHole device would each answer, and
* the loser would have no way to know it had been silently muted.
*/
export function attachHost(socket) {
if (host && host !== socket && host.connected !== false) return { ok: false, reason: 'host-taken' };
host = socket;
console.log(`📞 voice call: host attached (${socket?.id ?? 'socket'})`);
// Arm the incoming-call watcher now that something could carry the audio.
// Idempotent on a reconnect of the same socket.
startIncomingWatcher();
return { ok: true, state: emitState() };
}
export async function detachHost(socket) {
if (host !== socket) return publicState();
host = null;
console.log('📞 voice call: host detached');
// Never poll for an incoming call with nothing attached to carry it.
stopIncomingWatcher();
// Losing the host loses the audio path, so an in-flight call is ended rather
// than left running deaf.
if (publicState().active) return endCall('host-detached');
return emitState();
}
const stopPolling = () => {
if (timer) clearInterval(timer);
timer = null;
};
const setState = (next) => {
if (session.state === next) return publicState();
session.state = next;
return emitState();
};
const maxCallMs = async () => {
const config = await getVoiceConfig();
const minutes = Number(config?.facetime?.maxCallMinutes);
return (Number.isFinite(minutes) && minutes > 0 ? minutes : DEFAULT_MAX_CALL_MINUTES) * 60_000;
};
/**
* One poll tick: reconcile with the helper, then apply the give-up rules.
*
* Exported so a test can step the machine deterministically rather than
* racing a real interval.
*/
export async function pollCall() {
if (!publicState().active) return publicState();
let observed = null;
try {
observed = await deps.probe();
} catch (error) {
// A helper that cannot answer is not evidence the call ended, so the poll
// is skipped rather than treated as a hangup.
console.error(`❌ voice call: probe failed: ${error.message}`);
return publicState();
}
// The probe can outlast the interval; the call may have ended meanwhile.
if (!publicState().active) return publicState();
if (observed?.state === 'ended' || observed?.state === 'idle') return endCall('remote-hangup', { disconnectObserved: true });
if (observed?.state === 'connected' && session.state === 'dialing') {
// Ringback is not the caller. Start the silence clock at pickup so a
// long ring neither expires the call while it is still dialing nor
// hangs up on the same tick the far end answers.
session.lastVoiceAt = deps.now();
setState('listening');
}
const now = deps.now();
if (session.state !== 'dialing'
&& now - (session.lastVoiceAt ?? session.startedAt) >= SILENCE_HANGUP_MS) {
return endCall('caller-silent');
}
if (now - session.startedAt >= await maxCallMs()) return endCall('max-duration');
return publicState();
}
const startPolling = () => {
stopPolling();
let inFlight = false;
timer = setInterval(() => {
// A probe can take far longer than the interval; skip rather than overlap.
if (inFlight) return;
inFlight = true;
// Runs outside the request lifecycle: an unhandled rejection here would
// take the process down rather than reach error middleware.
pollCall()
.catch((error) => console.error(`❌ voice call: poll failed: ${error.message}`))
.finally(() => { inFlight = false; });
}, PROBE_INTERVAL_MS);
timer.unref?.();
};
// ---------------------------------------------------------------------------
// Incoming watcher — armed only while a call-host tab is attached (see
// attachHost/detachHost above). Separate timer from the active-call poll
// above: this one runs while the session is *idle*, watching for a call
// PortOS did not place.
// ---------------------------------------------------------------------------
let incomingTimer = null;
// Edge-detected so a ring that keeps being reported "authorized" for several
// ticks in a row (waiting on a slow answer, or unanswerable because the host
// went away) produces exactly one notification/answer attempt per ring, not
// one every 2 seconds for as long as it rings.
let incomingRingActive = false;
const stopIncomingWatcher = () => {
if (incomingTimer) clearInterval(incomingTimer);
incomingTimer = null;
incomingRingActive = false;
};
const startIncomingWatcher = () => {
stopIncomingWatcher();
let inFlight = false;
incomingTimer = setInterval(() => {
if (inFlight) return;
inFlight = true;
pollIncoming()
.catch((error) => console.error(`❌ voice call: incoming poll failed: ${error.message}`))
.finally(() => { inFlight = false; });
}, PROBE_INTERVAL_MS);
incomingTimer.unref?.();
};
const recordMissedCall = async (reason) => {
try {
await deps.notifyMissedCall(reason);
} catch (error) {
console.error(`❌ voice call: missed-call notification failed: ${error.message}`);
}
};
/**
* Compute the greeting an answered call opens with. Quiet hours change the
* style only, per the decided approach — they never decide whether to
* answer; the user placed the call, so PortOS answers at any hour.
*/
async function buildInboundGreeting(config) {
const persona = config?.llm?.personality?.name?.trim() || 'PortOS';
const quietHours = config?.llm?.proactive?.quietHours;
let quiet = false;
if (quietHours?.enabled) {
const nowMinutes = await getLocalMinutes();
quiet = isWithinQuietHours({ start: quietHours.start, end: quietHours.end, nowMinutes });
}
return quiet
? `Hi, this is ${persona}. It's late, so I'll keep this brief — go ahead.`
: `Hi, this is ${persona}. Go ahead.`;
}
/**
* Take over the session for a call the helper just answered on our behalf.
* Skips `dialing` entirely — the helper already reports the call live — and
* reuses the same `listening` transition the outbound flow drives the
* opening-line delivery from (see `deliverOpeningLine` in sockets/voice.js).
*/
async function beginAnsweredCall(config) {
const greeting = await buildInboundGreeting(config);
let mindEnabled = false;
try {
mindEnabled = await deps.isMindEnabled();
} catch (error) {
console.error(`❌ voice call: mind status check failed: ${error.message}`);
}
let context = null;
if (mindEnabled) {
context = await deps.buildInboundContext().catch((error) => {
// A briefing that failed to assemble is not a reason to leave the call
// unanswered — the plain persona still carries the conversation.
console.error(`❌ voice call: inbound context assembly failed: ${error.message}`);
return null;
});
}
session = {
...initialState(),
state: 'connected',
startedAt: deps.now(),
lastVoiceAt: deps.now(),
origin: 'inbound',
openingLine: greeting,
context,
mindEnabled,
};
emitState();
setState('listening');
startPolling();
}
/**
* One incoming-watch tick. Exported so a test can drive it directly, exactly
* like `pollCall` — including with `host` unset, which the production timer
* itself never does (see attachHost/detachHost), but which is exactly the
* "no host attached" failure mode `pollIncoming` still has to handle
* defensively (a host that detaches in the gap between this tick starting
* and the answer attempt landing is a real, if narrow, race).
*/
export async function pollIncoming() {
const config = await getVoiceConfig();
if (!config?.facetime?.autoAnswer) {
incomingRingActive = false;
return { checked: false, reason: 'auto-answer-off' };
}
if (publicState().active) return { checked: false, reason: 'call-in-progress' };
let observed = null;
try {
observed = await deps.probe();
} catch (error) {
// Mirrors pollCall: a probe that cannot answer is unknown, not evidence
// of anything — and never carries caller identity, so this is safe to log.
console.error(`❌ voice call: incoming probe failed: ${error.message}`);
return { checked: false, reason: 'probe-failed' };
}
// The helper reports `dialing` only for a ringing notification whose caller
// matches the configured identity. An unmatched caller is indistinguishable
// from idle; `authorized` continues to mean the helper has AX permission.
const ringing = Boolean(observed?.authorized) && observed?.state === 'dialing';
if (!ringing) {
incomingRingActive = false;
return { checked: true, incoming: false };
}
if (incomingRingActive) return { checked: true, incoming: true, deduped: true };
incomingRingActive = true;
if (!host) {
await recordMissedCall('no-host');
return { checked: true, incoming: true, answered: false, reason: 'no-host' };
}
let result = null;
try {
result = await deps.answer();
} catch (error) {
console.error(`❌ voice call: incoming answer failed: ${error.message}`);
await recordMissedCall('helper-failed');
return { checked: true, incoming: true, answered: false, reason: 'helper-failed' };
}
if (!result?.ok) {
await recordMissedCall('helper-failed');
return { checked: true, incoming: true, answered: false, reason: 'helper-failed' };
}
// Reset the edge detector now: once answered, `publicState().active` short-
// circuits every tick for the rest of the call (see the top of this
// function), so the "ring stopped" branch above never runs again to clear
// it — leaving it stuck `true` would make the *next* genuine incoming call,
// after this one ends, look like a duplicate of this one and be silently
// skipped forever.
incomingRingActive = false;
await beginAnsweredCall(config);
return { checked: true, incoming: true, answered: true };
}
/**
* Place a call. Fails closed when nothing can carry the audio.
*/
export async function startCall({ openingLine = '', context = null, origin = 'user' } = {}) {
if (!host) return { ok: false, reason: 'no-call-host' };
if (publicState().active) return { ok: false, reason: 'call-in-progress' };
session = {
...initialState(),
state: 'dialing',
startedAt: deps.now(),
lastVoiceAt: deps.now(),
origin: origin === 'mind' ? 'mind' : 'user',
openingLine: typeof openingLine === 'string' ? openingLine.trim() : '',
context: typeof context === 'string' && context.trim() ? context : null,
};
emitState();
try {
await deps.call();
} catch (error) {
session.endedReason = 'dial-failed';
setState('idle');
return { ok: false, reason: 'dial-failed', message: error.message };
}
startPolling();
return { ok: true, state: publicState(), openingLine: session.openingLine, context: session.context };
}
/** Record one side of the conversation. Speaker labels only — never the handle. */
export function recordTurn(speaker, text) {
const trimmed = (text || '').trim();
if (!trimmed || !publicState().active) return publicState();
session.transcript.push({ speaker: speaker === 'assistant' ? 'assistant' : 'caller', text: trimmed });
if (speaker !== 'assistant') session.lastVoiceAt = deps.now();
return publicState();
}
/** The caller started talking — used for barge-in and the silence timer. */
export function noteCallerSpeech() {
if (!publicState().active) return publicState();
session.lastVoiceAt = deps.now();
return publicState();
}
// `dialing` is active, but ringback is not a turn, so these must not promote
// it. pollCall leaves dialing when the helper reports the far end connected
// (or when the ring ends / the duration cap hits). `connected` stays eligible
// so the opening line can still move the answered handoff into speaking.
const inLiveTurn = () => session.state === 'connected'
|| session.state === 'listening'
|| session.state === 'speaking';
export const markSpeaking = () => (inLiveTurn() ? setState('speaking') : publicState());
export const markListening = () => (inLiveTurn() ? setState('listening') : publicState());
const renderTranscript = (transcript) => transcript
.map((turn) => `${turn.speaker === 'assistant' ? 'PortOS' : 'Caller'}: ${turn.text}`)
.join('\n');
// Cap on the transcript handed back to the persistent mind. A call is short by
// construction (maxCallMinutes), but the mind's message queue is durable state,
// so the bound is enforced here rather than trusted.
const MIND_TRANSCRIPT_MAX_CHARS = 6_000;
/**
* End the call and write the transcript down.
*
* The journal append is best-effort: a failed write must not leave the session
* stuck `connected`, because the state is what gates placing the next call.
*/
export function endCall(reason = 'ended', options = {}) {
// Overlapping triggers (slow probes, a user hangup racing a poll rule) join
// the teardown already running instead of repeating hangup/journal/handoff.
if (endingCall) return endingCall;
if (session.state === 'idle') return Promise.resolve(publicState());
endingCall = runEndCall(reason, options).finally(() => { endingCall = null; });
return endingCall;
}
let endingCall = null;
async function runEndCall(reason, { disconnectObserved = false }) {
stopPolling();
const transcript = session.transcript;
const origin = session.origin;
const mindEnabled = session.mindEnabled;
session.endedReason = reason;
setState('ended');
// Ending PortOS's audio session is independent of confirming FaceTime's
// physical disconnect. Always finish cleanup, but retain that distinction.
let physicalDisconnect = 'confirmed';
try {
// A successful poll already observed idle/ended; pressing a vanished
// hang-up control would manufacture a failure after a real disconnect.
if (!disconnectObserved) await deps.hangup();
} catch (error) {
physicalDisconnect = error.code === 'state-unconfirmed' ? 'unconfirmed' : 'failed';
console.error(`❌ voice call: hangup failed: ${error.message}`);
await addNotification({
type: NOTIFICATION_TYPES.AGENT_WARNING,
title: 'Check FaceTime to confirm the call disconnected',
description: 'The PortOS audio session ended, but FaceTime disconnect could not be confirmed. Check FaceTime and end the call there if it is still active.',
priority: PRIORITY_LEVELS.HIGH,
metadata: { source: 'voice-facetime-disconnect', outcome: physicalDisconnect },
}).catch(notificationError => console.error(`❌ voice call: disconnect warning failed: ${notificationError.message}`));
}
if (transcript.length) {
try {
// getToday() is async (it reads the configured timezone) — unawaited it
// resolved to a pending Promise, which appendJournal's isIsoDate() guard
// always rejects, so the call transcript was silently never written.
await deps.appendJournal(await getToday(), `FaceTime Audio call\n${renderTranscript(transcript)}`, { source: 'voice' });
} catch (error) {
console.error(`❌ voice call: journal append failed: ${error.message}`);
}
}
// A call the mind placed is one half of a conversation it started, so the
// outcome goes back into its queue as a message. Without this the next wake
// would have no idea the call happened and could call again to say the same
// thing — including after a call nobody picked up, which is exactly when an
// empty transcript would otherwise leave it uninformed. Best-effort for the
// same reason the journal append is.
//
// An answered inbound call gets the same handoff, but only when the mind
// was actually running when it was answered — an inbound call answered
// with the mind off ran the plain voice persona, and telling a mind that
// never took part about a conversation it did not have would be noise, not
// continuity.
const handToMind = origin === 'mind' || (origin === 'inbound' && mindEnabled);
if (handToMind) {
const verb = origin === 'mind' ? 'placed' : 'answered';
try {
await deps.enqueueMindMessage(
`Outcome of the FaceTime Audio call you ${verb} (PortOS session ended: ${reason}; FaceTime disconnect ${physicalDisconnect}):\n${
transcript.length ? renderTranscript(transcript) : 'The PortOS session ended with nothing said.'
}`.slice(0, MIND_TRANSCRIPT_MAX_CHARS),
);
} catch (error) {
console.error(`❌ voice call: mind transcript handoff failed: ${error.message}`);
}
}
session = { ...initialState(), endedReason: reason, physicalDisconnect };
return emitState();
}
/** Test helper — drop all state between cases. */
export const __resetCallSession = () => {
stopPolling();
stopIncomingWatcher();
session = initialState();
host = null;
listener = null;
callStateEvents.removeAllListeners();
__setCallSessionDeps();
};