The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import { notifyChatDeliveryWork } from "../chat-work-notifications.js";
import { environmentService } from "../environments.js";
import { logger } from "../../middleware/logger.js";
import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
import { and, asc, desc, eq, gte, inArray, isNull, or, sql, type SQL } from "drizzle-orm";
import { activityLog, chatVoicePhoneLines, chatVoiceInboundCalls, chatVoiceCallbacks, chatEndpoints, chatConversations, chatDeliveries, chatPublications, chatVoiceSessions, chatVoiceToolCalls, chatVoiceReplies, companyMemberships, companySecrets, connectionGrants, connectionGrantMembers, toolConnectionInstalls, instanceUserRoles, issueThreadInteractions, issues, heartbeatRuns, toolConnections, type Db } from "@paperclipai/db";
import { LOW_TRUST_REVIEW_PRESET } from "@paperclipai/shared";
import type { ToolCredentialSecretRef, VoiceSession } from "@paperclipai/shared";
import { conflict, forbidden, notFound, HttpError } from "../../errors.js";
import { issueThreadInteractionService } from "../issue-thread-interactions.js";
import { evaluateIssueThreadInteractionResolverAudience } from "../issue-thread-interaction-resolution.js";
import { nativeSha256 } from "../native-runtime/canonical.js";
import { authorizationService, type AuthorizationActor } from "../authorization.js";
import type { SpekoToolEnvelope } from "./speko-protocol.js";
export type VoiceTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
export type VoiceSessionRow = typeof chatVoiceSessions.$inferSelect;
export interface VoiceCaller { id: string; authority: "member" | "instance_admin" | "local_board" }
export function voiceCredentialFingerprint(refs: ToolCredentialSecretRef[]) {
const stable = refs.map((ref) => ({ configPath: ref.configPath, secretId: ref.secretId, versionSelector: ref.versionSelector ?? "latest" }))
.sort((a, b) => `${a.configPath}:${a.secretId}:${a.versionSelector}`.localeCompare(`${b.configPath}:${b.secretId}:${b.versionSelector}`));
return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
}
/** Include resolved versions so rotating a `latest` ref retires old calls. */
export async function currentVoiceCredentialFingerprint(db: Db | VoiceTransaction, companyId: string, refs: ToolCredentialSecretRef[]) {
const resolved: ToolCredentialSecretRef[] = [];
for (const ref of refs) {
const [secret] = await db.select().from(companySecrets).where(and(eq(companySecrets.companyId, companyId),
eq(companySecrets.id, ref.secretId), eq(companySecrets.status, "active"), isNull(companySecrets.deletedAt)));
if (!secret) throw forbidden("Voice credentials are no longer available");
resolved.push({ ...ref, versionSelector: ref.versionSelector === undefined || ref.versionSelector === "latest" ? secret.latestVersion : ref.versionSelector });
}
return voiceCredentialFingerprint(resolved);
}
export const voiceTokenHash = (token: string) => createHash("sha256").update(token).digest("hex");
export function serializeVoiceSession(row: VoiceSessionRow): VoiceSession {
return { id: row.id, companyId: row.companyId, endpointId: row.endpointId, issueId: row.issueId, assignedAgentId: row.assignedAgentId, state: row.state, mode: row.mode, generation: row.generation, callerAuthority: row.callerAuthority, replyCursor: row.replyCursor, errorCode: row.errorCode, createdAt: row.createdAt.toISOString(), expiresAt: row.expiresAt.toISOString(), endedAt: row.endedAt?.toISOString() ?? null };
}
/** Server-owned bindings, not model-selected company/task IDs. */
export function voiceSessionStore(db: Db, options: { allowLocalBoard: boolean; nonblockingAuthority?: boolean }) {
async function authorizeCaller(tx: VoiceTransaction, companyId: string, caller: VoiceCaller) {
if (caller.authority === "local_board") {
if (options.allowLocalBoard && caller.id === "local-board") return;
throw forbidden("Local voice authority is unavailable");
}
const permitted = caller.authority === "instance_admin"
? await tx.select({ id: instanceUserRoles.id }).from(instanceUserRoles).where(and(eq(instanceUserRoles.userId, caller.id), eq(instanceUserRoles.role, "instance_admin"))).for("share", options.nonblockingAuthority ? { noWait: true } : undefined)
: await tx.select({ id: companyMemberships.id }).from(companyMemberships).where(and(eq(companyMemberships.companyId, companyId), eq(companyMemberships.principalId, caller.id), eq(companyMemberships.principalType, "user"), eq(companyMemberships.status, "active"), sql`${companyMemberships.membershipRole} is distinct from 'viewer'`)).for("share", options.nonblockingAuthority ? { noWait: true } : undefined);
if (!permitted.length) throw forbidden("Voice access is no longer available");
}
async function authorizeTask(tx: VoiceTransaction, companyId: string, issueId: string, caller: VoiceCaller, work = true) {
await authorizeCaller(tx, companyId, caller);
const [task] = await tx.select().from(issues).where(and(eq(issues.id, issueId), eq(issues.companyId, companyId))).for("share", options.nonblockingAuthority ? { noWait: true } : undefined);
if (!task) throw notFound("Voice task not found");
const actor: AuthorizationActor = { type: "board", userId: caller.id,
source: caller.authority === "local_board" ? "local_implicit" : "session",
isInstanceAdmin: caller.authority === "instance_admin" };
const authorization = authorizationService(tx);
// issue:comment does not itself apply the issue:read privacy projection.
// Check both explicitly before accepting instructions or exposing replies.
for (const action of work ? ["issue:read", "issue:comment"] as const : ["issue:read"] as const) {
const decision = await authorization.decide({ actor, action, resource: { type: "issue", companyId, issueId, status: task.status, assigneeAgentId: task.assigneeAgentId, assigneeUserId: task.assigneeUserId, projectId: task.projectId, originKind: task.originKind, originId: task.originId } });
if (!decision.allowed) throw forbidden("You no longer have access to this voice task");
}
if (work && (task.status === "cancelled" || task.hiddenAt)) throw forbidden("This voice task is no longer available for work");
return task;
}
async function endpointContext(tx: VoiceTransaction, companyId: string, endpointId: string) {
const endpoint = await tx.select().from(chatEndpoints).where(and(eq(chatEndpoints.id, endpointId), eq(chatEndpoints.companyId, companyId))).for("share", options.nonblockingAuthority ? { noWait: true } : undefined).then((rows) => rows[0]);
if (!endpoint || endpoint.provider !== "speko") throw notFound("Voice connection not found");
const connection = await tx.select().from(toolConnections).where(and(eq(toolConnections.id, endpoint.connectionId), eq(toolConnections.companyId, companyId))).for("share", options.nonblockingAuthority ? { noWait: true } : undefined).then((rows) => rows[0]);
if (!["active", "verifying"].includes(endpoint.status) || !connection?.enabled || connection.status !== "active" || connection.transport !== "voice") throw forbidden("Voice connection is not active");
const generation = Number((endpoint.setup as { runtimeGeneration?: number }).runtimeGeneration ?? 0);
return { endpoint, connection, generation, fingerprint: await currentVoiceCredentialFingerprint(tx, companyId, connection.credentialSecretRefs), runtimeFingerprint: voiceCredentialFingerprint(connection.credentialSecretRefs) };
}
async function authorizeConnection(tx: VoiceTransaction, context: Awaited<ReturnType<typeof endpointContext>>, caller: VoiceCaller) {
const { endpoint, connection } = context;
if (!endpoint.allowDirectMessages) throw forbidden("Voice conversations are disabled for this connection");
// Dedicated channel credentials predate connection grants; their agent is
// the endpoint assignment. Once grants/installs exist, honor those current
// restrictions, including revoked grants. Managed grants require a current
// install even after the final install is removed. Grant revocation keeps
// its durable row; only the dedicated legacy channel has neither.
const grants = await tx.select().from(connectionGrants).where(and(eq(connectionGrants.companyId, endpoint.companyId), eq(connectionGrants.connectionId, connection.id)));
const members = grants.length ? await tx.select().from(connectionGrantMembers).where(and(eq(connectionGrantMembers.companyId, endpoint.companyId), inArray(connectionGrantMembers.grantId, grants.map(g => g.id)))) : [];
if (grants.length && !grants.some(grant => {
if (grant.status !== "active") return false;
// The channel runtime uses connection refs; an unrelated identity's
// grant cannot authorize that credential.
if (voiceCredentialFingerprint(grant.credentialSecretRefs) !== voiceCredentialFingerprint(connection.credentialSecretRefs)) return false;
if (grant.kind === "user") return grant.subjectUserId === caller.id;
if (grant.kind !== "organization" || ["per_user", "per_agent"].includes(connection.credentialPolicy)) return false;
const audience = members.filter(member => member.grantId === grant.id);
return !audience.length || audience.some(member => member.subjectId === caller.id);
})) throw forbidden("You no longer have access to this voice connection's credential");
const installs = await tx.select().from(toolConnectionInstalls).where(and(eq(toolConnectionInstalls.companyId, endpoint.companyId), eq(toolConnectionInstalls.connectionId, connection.id)));
if ((grants.length || installs.length) && !installs.some(install => install.targetType === "company" && install.targetId === endpoint.companyId || install.targetType === "agent" && install.targetId === endpoint.assignedAgentId)) {
throw forbidden("The selected agent no longer has access to this voice connection");
}
}
/** Public phone authority is confined to the task created for this exact call. */
async function authorizeGuestTask(tx: VoiceTransaction, context: Awaited<ReturnType<typeof endpointContext>>, session: VoiceSessionRow) {
const { endpoint } = context;
const [call] = await tx.select().from(chatVoiceInboundCalls).where(and(eq(chatVoiceInboundCalls.companyId, endpoint.companyId), eq(chatVoiceInboundCalls.endpointId, endpoint.id), eq(chatVoiceInboundCalls.sessionId, session.id), eq(chatVoiceInboundCalls.intakeIssueId, session.issueId)));
const [line] = await tx.select().from(chatVoicePhoneLines).where(and(eq(chatVoicePhoneLines.companyId, endpoint.companyId), eq(chatVoicePhoneLines.endpointId, endpoint.id), eq(chatVoicePhoneLines.enabled, true), eq(chatVoicePhoneLines.guestIntake, true))).for("share");
const [task] = await tx.select().from(issues).where(and(eq(issues.companyId, endpoint.companyId), eq(issues.id, session.issueId))).for("share");
const policy = task?.executionPolicy?.authorizationPolicy as {trustPreset?: string; trustBoundary?: {mode?: string; companyId?: string; rootIssueId?: string; issueIds?: string[]; allowedAgentIds?: string[]; allowedToolClasses?: string[]; allowedSecretBindingIds?: string[]}} | undefined;
const boundary = policy?.trustBoundary;
if (!call || !line || !endpoint.allowDirectMessages || session.mode !== "inbound_phone" || session.callerId !== `guest:${call.id}` || call.providerSessionId !== session.providerSessionId || call.generation !== context.generation || call.credentialFingerprint !== context.fingerprint || call.toolTokenHash !== session.toolTokenHash || !["guest_intake", "ended"].includes(call.state)
|| !task || task.hiddenAt || task.status === "cancelled" || task.originKind !== "chat_channel" || task.originId !== endpoint.id || task.assigneeAgentId !== session.assignedAgentId || session.assignedAgentId !== endpoint.assignedAgentId
|| task.sourceTrust?.preset !== LOW_TRUST_REVIEW_PRESET || task.sourceTrust.disposition !== "quarantined" || policy?.trustPreset !== LOW_TRUST_REVIEW_PRESET || boundary?.mode !== LOW_TRUST_REVIEW_PRESET || boundary.companyId !== endpoint.companyId || boundary.rootIssueId !== task.id
|| boundary.issueIds?.length !== 1 || boundary.issueIds[0] !== task.id || boundary.allowedAgentIds?.length !== 1 || boundary.allowedAgentIds[0] !== session.assignedAgentId || boundary.allowedToolClasses?.length !== 0 || boundary.allowedSecretBindingIds?.length !== 0) throw forbidden("The low-trust phone task boundary is no longer available");
// The line selects environments for future calls. Accepted work keeps its
// task's saved sandbox, subject to current availability and company scope.
const savedSettings = task.executionWorkspaceSettings;
const savedEnvironmentId = typeof savedSettings?.environmentId === "string" ? savedSettings.environmentId : null;
const strategy = savedSettings?.workspaceStrategy as {type?: string} | undefined;
if (task.executionWorkspaceSettings?.mode !== "isolated_workspace"
|| strategy?.type !== "cloud_sandbox") throw forbidden("The phone task sandbox boundary changed");
if (savedEnvironmentId) {
const environments = environmentService(tx as unknown as Db);
const environment = await environments.getById(savedEnvironmentId);
const owners = await environments.listBoundCompanyIds(savedEnvironmentId);
if (!environment || environment.status !== "active" || environment.driver !== "sandbox"
|| environment.config?.provider === "fake" || owners.length && !owners.includes(endpoint.companyId)) throw forbidden("The saved phone task sandbox is unavailable");
}
// Honor managed credential/install revocation without impersonating a user.
const grants = await tx.select().from(connectionGrants).where(and(eq(connectionGrants.companyId, endpoint.companyId), eq(connectionGrants.connectionId, context.connection.id)));
if (grants.length && !grants.some(g => g.status === "active" && g.kind === "organization" && voiceCredentialFingerprint(g.credentialSecretRefs) === voiceCredentialFingerprint(context.connection.credentialSecretRefs))) throw forbidden("The company phone credential grant is unavailable");
const installs = await tx.select().from(toolConnectionInstalls).where(and(eq(toolConnectionInstalls.companyId, endpoint.companyId), eq(toolConnectionInstalls.connectionId, context.connection.id)));
if ((grants.length || installs.length) && !installs.some(i => i.targetType === "company" && i.targetId === endpoint.companyId || i.targetType === "agent" && i.targetId === endpoint.assignedAgentId)) throw forbidden("The phone agent connection was removed");
return task;
}
async function authorizeSession(tx: VoiceTransaction, companyId: string, sessionId: string, allowedStates: readonly string[] = ["connecting", "active"]) {
// Follow the existing endpoint → connection → session lock order.
const candidate = await tx.select().from(chatVoiceSessions).where(and(eq(chatVoiceSessions.id, sessionId), eq(chatVoiceSessions.companyId, companyId))).then((rows) => rows[0]);
if (!candidate) throw notFound("Voice session not found");
const context = await endpointContext(tx, companyId, candidate.endpointId);
const session = await tx.select().from(chatVoiceSessions).where(and(eq(chatVoiceSessions.id, sessionId), eq(chatVoiceSessions.companyId, companyId))).for("update").then((rows) => rows[0]);
if (!session || !allowedStates.includes(session.state) || session.expiresAt.getTime() <= Date.now()
|| session.generation !== context.generation || session.credentialFingerprint !== context.fingerprint) throw forbidden("Voice session is no longer current");
if (!["member", "instance_admin", "local_board", "guest_intake"].includes(session.callerAuthority)) throw forbidden("This call has not been approved for private work");
if (session.mode === "outbound_phone") {
const [optIn] = await tx.select({ id: chatVoiceCallbacks.id }).from(chatVoiceCallbacks).where(and(eq(chatVoiceCallbacks.companyId, companyId), eq(chatVoiceCallbacks.endpointId, session.endpointId), eq(chatVoiceCallbacks.userId, session.callerId), eq(chatVoiceCallbacks.enabled, true))).for("share");
if (!optIn) throw forbidden("Phone callbacks are no longer enabled");
}
const guest = session.callerAuthority === "guest_intake";
if (!guest) {
await authorizeCaller(tx, companyId, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
await authorizeConnection(tx, context, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
}
const task = guest ? await authorizeGuestTask(tx, context, session) : await authorizeTask(tx, companyId, session.issueId, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
const conversation = await tx.select().from(chatConversations).where(and(eq(chatConversations.id, session.conversationId), eq(chatConversations.companyId, companyId), eq(chatConversations.endpointId, session.endpointId), eq(chatConversations.issueId, session.issueId))).for("share", options.nonblockingAuthority ? { noWait: true } : undefined).then((rows) => rows[0]);
if (!task || !conversation || !["active", "waiting"].includes(conversation.state) || task.assigneeAgentId !== session.assignedAgentId || context.endpoint.assignedAgentId !== session.assignedAgentId) throw forbidden("The voice task binding changed");
return { ...context, session, conversation, task };
}
async function reserve(input: {
companyId: string; endpointId: string; caller: VoiceCaller; idempotencyKey: string; requestFingerprint: string; maxDurationSeconds: number; mode?: "browser" | "outbound_phone" | "inbound_phone"; providerSessionId?: string; toolToken?: string;
/** Runs only for a NEW request and in the same transaction as the session. */
prepareBinding(tx: VoiceTransaction): Promise<{ issueId: string; conversationId: string }>;
}) {
return db.transaction(async (tx) => {
await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`voice:${input.companyId}:${input.caller.id}:${input.idempotencyKey}`}, 0))`);
await authorizeCaller(tx, input.companyId, input.caller);
const previous = await tx.select().from(chatVoiceSessions).where(and(eq(chatVoiceSessions.companyId, input.companyId), eq(chatVoiceSessions.callerId, input.caller.id), eq(chatVoiceSessions.idempotencyKey, input.idempotencyKey))).then((rows) => rows[0]);
if (previous) {
if (previous.requestFingerprint !== input.requestFingerprint || previous.endpointId !== input.endpointId) throw conflict("Voice request key was already used for different work");
await authorizeConnection(tx, await endpointContext(tx, input.companyId, input.endpointId), input.caller);
await authorizeTask(tx, input.companyId, previous.issueId, input.caller);
return { session: previous, created: false as const };
}
const context = await endpointContext(tx, input.companyId, input.endpointId);
await authorizeConnection(tx, context, input.caller);
if (context.generation < 1 || input.maxDurationSeconds < 30 || input.maxDurationSeconds > 1800 || !Number.isInteger(input.maxDurationSeconds)) throw conflict("Voice setup or duration is invalid");
if (input.mode === "inbound_phone") {
const [admission] = await tx.select().from(chatVoiceInboundCalls).where(and(eq(chatVoiceInboundCalls.companyId, input.companyId), eq(chatVoiceInboundCalls.endpointId, input.endpointId), eq(chatVoiceInboundCalls.providerSessionId, input.providerSessionId ?? ""))).for("update");
if (!admission || admission.state !== "approving" || admission.approvedByUserId !== input.caller.id || admission.callerAuthority !== input.caller.authority || admission.expiresAt.getTime() <= Date.now() || admission.generation !== context.generation || admission.credentialFingerprint !== context.fingerprint || admission.toolTokenHash !== voiceTokenHash(input.toolToken ?? "") || input.idempotencyKey !== `inbound:${admission.id}`) throw forbidden("This live call has not been approved for private work");
}
const binding = await input.prepareBinding(tx);
const task = await authorizeTask(tx, input.companyId, binding.issueId, input.caller);
const conversation = await tx.select().from(chatConversations).where(and(eq(chatConversations.id, binding.conversationId), eq(chatConversations.companyId, input.companyId), eq(chatConversations.endpointId, input.endpointId), eq(chatConversations.issueId, binding.issueId))).then((rows) => rows[0]);
if (!task || !conversation || task.assigneeAgentId !== context.endpoint.assignedAgentId) throw conflict("The selected voice agent must be assigned to this task");
await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`voice-live:${input.companyId}:${input.caller.id}:${binding.issueId}`}, 0))`);
const [live] = await tx.select({ id: chatVoiceSessions.id }).from(chatVoiceSessions).where(and(
eq(chatVoiceSessions.companyId, input.companyId), eq(chatVoiceSessions.callerId, input.caller.id), eq(chatVoiceSessions.issueId, binding.issueId),
sql`${chatVoiceSessions.state} not in ('ended', 'failed', 'expired')`)).limit(1);
if (live) throw conflict("End the existing call before starting another", { code: "voice_call_already_active", sessionId: live.id });
if (input.mode === "inbound_phone") {
const [guest] = await tx.select().from(chatVoiceSessions).where(and(eq(chatVoiceSessions.companyId, input.companyId), eq(chatVoiceSessions.endpointId, input.endpointId), eq(chatVoiceSessions.providerSessionId, input.providerSessionId ?? ""), eq(chatVoiceSessions.callerAuthority, "guest_intake"))).for("update");
if (guest) {
if (!["connecting", "active"].includes(guest.state) || guest.expiresAt.getTime() <= Date.now() || guest.generation !== context.generation || guest.toolTokenHash !== voiceTokenHash(input.toolToken ?? "")) throw forbidden("Guest call is no longer available for approval");
const task = await authorizeTask(tx, input.companyId, binding.issueId, input.caller);
if (task.assigneeAgentId !== context.endpoint.assignedAgentId) throw conflict("The selected agent must be assigned to this task");
const [promoted] = await tx.update(chatVoiceSessions).set({...binding, callerId: input.caller.id, callerAuthority: input.caller.authority, approvedByUserId: input.caller.id, idempotencyKey: input.idempotencyKey, requestFingerprint: input.requestFingerprint, updatedAt: new Date()}).where(eq(chatVoiceSessions.id, guest.id)).returning();
await tx.insert(activityLog).values({companyId: input.companyId, actorType: "user", actorId: input.caller.id, action: "voice.guest.private_call_approved", entityType: "voice_session", entityId: guest.id, details: {issueId: binding.issueId}});
return {session: promoted, created: false as const};
}
}
const token = input.toolToken ?? randomBytes(32).toString("base64url"), createdAt = new Date();
const [session] = await tx.insert(chatVoiceSessions).values({ id: randomUUID(), companyId: input.companyId, endpointId: input.endpointId, ...binding, assignedAgentId: context.endpoint.assignedAgentId,
callerId: input.caller.id, callerAuthority: input.caller.authority, mode: input.mode ?? "browser", state: input.providerSessionId ? "connecting" : "reserved", providerSessionId: input.providerSessionId ?? null, approvedByUserId: input.mode === "inbound_phone" ? input.caller.id : null, generation: context.generation, credentialFingerprint: context.fingerprint,
toolTokenHash: voiceTokenHash(token), idempotencyKey: input.idempotencyKey, requestFingerprint: input.requestFingerprint, createdAt, expiresAt: new Date(createdAt.getTime() + input.maxDurationSeconds * 1000) }).returning();
await tx.insert(activityLog).values({ companyId: input.companyId, actorType: "user", actorId: input.caller.id, action: "voice.session.requested", entityType: "voice_session", entityId: session.id, details: { endpointId: input.endpointId, issueId: session.issueId, mode: input.mode ?? "browser" } });
return { session, created: true as const, token };
});
}
async function stageDelivery(tx: VoiceTransaction, context: Awaited<ReturnType<typeof authorizeSession>>, text: string, toolId: string) {
const { session, conversation } = context;
const prior = await tx.select({ id: chatVoiceToolCalls.id }).from(chatVoiceToolCalls).where(and(eq(chatVoiceToolCalls.sessionId, session.id), eq(chatVoiceToolCalls.tool, "submit_request"))).limit(1);
const threadId = conversation.externalThreadId;
const providerEventId = `${threadId}:${session.id}:${toolId}`;
const trigger = prior.length ? "subscribed_message" : "direct_message";
await notifyChatDeliveryWork(tx);
const [delivery] = await tx.insert(chatDeliveries).values({
companyId: session.companyId, endpointId: session.endpointId, conversationId: session.conversationId,
providerEventId, deduplicationKey: createHash("sha256").update(providerEventId).digest("hex"),
eventKind: prior.length ? "message" : "direct_message",
normalizedEvent: {
providerEventId, kind: prior.length ? "message" : "direct_message", trigger,
runtimeContext: { generation: session.generation, credentialFingerprint: context.runtimeFingerprint },
acknowledgement: { receiptReactionSupported: false },
principal: { externalId: `voice:${session.id}`, displayName: "Voice caller", handle: "voice-caller" },
resource: { type: "direct_message", providerResourceId: conversation.externalConversationId, label: "Voice conversation" },
conversation: { externalConversationId: conversation.externalConversationId, externalThreadId: threadId, label: "Voice conversation", isDirectMessage: true, providerUrl: null },
message: { providerMessageId: `${session.id}:${toolId}`, text, mentionedBot: false, attachments: [], providerSentAt: new Date().toISOString() },
},
}).returning({ id: chatDeliveries.id });
return delivery.id;
}
function priorCallDeliveryBarrier(session: VoiceSessionRow, publicationId: string | SQL) {
return sql<boolean>`not exists (select 1 from chat_publications p join issue_thread_interactions i
on i.id::text = p.payload->>'interactionId' and i.company_id = p.company_id and i.issue_id = p.issue_id
where p.id = ${publicationId} and p.company_id = ${session.companyId}
and i.kind = 'ask_user_questions' and i.status = 'pending')
and exists (select 1 from chat_voice_replies r join chat_voice_sessions s
on s.id = r.session_id and s.company_id = r.company_id
where r.company_id = ${session.companyId} and r.publication_id = ${publicationId}
and s.id <> ${session.id} and s.caller_id = ${session.callerId}
and s.endpoint_id = ${session.endpointId} and s.conversation_id = ${session.conversationId}
and s.issue_id = ${session.issueId}
and (r.delivered_at is not null or exists (
select 1 from chat_actions a where a.company_id = r.company_id
and a.endpoint_id = s.endpoint_id and a.kind = 'speko_voice_reply_push'
and a.payload->>'replyId' = r.id::text
and (a.status in ('dispatching', 'unknown') or
(a.status = 'completed' and coalesce(a.payload->>'questionNotification', 'false') = 'false'))
)))`;
}
async function collectMissedReplies(tx: VoiceTransaction, session: VoiceSessionRow) {
// Only publications since this caller joined this exact conversation are
// eligible. Transport acceptance in any prior call suppresses automatic
// replay; uncertain playback requires an explicit repeat, not an assumption.
const [first] = await tx.select({ createdAt: chatVoiceSessions.createdAt }).from(chatVoiceSessions)
.where(and(eq(chatVoiceSessions.companyId, session.companyId), eq(chatVoiceSessions.endpointId, session.endpointId),
eq(chatVoiceSessions.conversationId, session.conversationId), eq(chatVoiceSessions.callerId, session.callerId)))
.orderBy(asc(chatVoiceSessions.createdAt)).limit(1);
const missing = await tx.select({ id: chatPublications.id }).from(chatPublications).where(and(
eq(chatPublications.companyId, session.companyId), eq(chatPublications.endpointId, session.endpointId),
eq(chatPublications.conversationId, session.conversationId), eq(chatPublications.issueId, session.issueId),
eq(chatPublications.state, "published"), gte(chatPublications.createdAt, first?.createdAt ?? session.createdAt),
sql`(coalesce(${chatPublications.payload}->>'progressState', '') = '' or ${chatPublications.payload}->>'interactionId' is not null)`,
sql`not exists (select 1 from chat_voice_replies r where r.company_id = ${session.companyId}
and r.publication_id = ${chatPublications.id} and r.session_id = ${session.id})`,
sql`not (${priorCallDeliveryBarrier(session, sql`${chatPublications.id}`)})`,
)).orderBy(asc(chatPublications.createdAt), asc(chatPublications.id)).limit(100);
let cursor = session.replyCursor;
for (const publication of missing) {
await tx.insert(chatVoiceReplies).values({ companyId: session.companyId, sessionId: session.id, publicationId: publication.id, cursor: ++cursor });
}
if (cursor !== session.replyCursor) {
await tx.update(chatVoiceSessions).set({ replyCursor: cursor, updatedAt: new Date() }).where(eq(chatVoiceSessions.id, session.id));
session.replyCursor = cursor;
}
}
async function collectRepeatReply(tx: VoiceTransaction, session: VoiceSessionRow) {
// A caller may rejoin after an answer was retrieved but never heard. Only
// their own exact conversation's previously delivered publication qualifies.
const [previous] = await tx.select({ publicationId: chatVoiceReplies.publicationId }).from(chatVoiceReplies)
.innerJoin(chatVoiceSessions, and(eq(chatVoiceSessions.id, chatVoiceReplies.sessionId), eq(chatVoiceSessions.companyId, chatVoiceReplies.companyId)))
.innerJoin(chatPublications, and(eq(chatPublications.id, chatVoiceReplies.publicationId), eq(chatPublications.companyId, session.companyId)))
.where(and(eq(chatVoiceReplies.companyId, session.companyId), eq(chatVoiceSessions.callerId, session.callerId),
eq(chatVoiceSessions.endpointId, session.endpointId), eq(chatVoiceSessions.conversationId, session.conversationId),
eq(chatVoiceSessions.issueId, session.issueId), eq(chatPublications.endpointId, session.endpointId),
eq(chatPublications.conversationId, session.conversationId), eq(chatPublications.issueId, session.issueId),
eq(chatPublications.state, "published"), sql`${chatVoiceReplies.deliveredAt} is not null`))
.orderBy(desc(chatVoiceReplies.deliveredAt), desc(chatVoiceReplies.cursor)).limit(1);
if (!previous) return;
const [existing] = await tx.select().from(chatVoiceReplies).where(and(eq(chatVoiceReplies.sessionId, session.id), eq(chatVoiceReplies.publicationId, previous.publicationId)));
if (existing) return;
const cursor = session.replyCursor + 1;
await tx.insert(chatVoiceReplies).values({ companyId: session.companyId, sessionId: session.id, publicationId: previous.publicationId, cursor, deliveredAt: new Date() });
await tx.update(chatVoiceSessions).set({ replyCursor: cursor, updatedAt: new Date() }).where(eq(chatVoiceSessions.id, session.id));
session.replyCursor = cursor;
}
/** Neutral task-scoped status only; execution logs and private errors never reach the voice model. */
async function workStatus(tx: VoiceTransaction, context: Awaited<ReturnType<typeof authorizeSession>>) {
const { session, task } = context;
const [request] = await tx.select({ createdAt: chatVoiceToolCalls.createdAt, deliveryState: chatDeliveries.state })
.from(chatVoiceToolCalls).innerJoin(chatDeliveries, and(eq(chatDeliveries.id, chatVoiceToolCalls.deliveryId),
eq(chatDeliveries.companyId, session.companyId), eq(chatDeliveries.endpointId, session.endpointId),
eq(chatDeliveries.conversationId, session.conversationId)))
.where(and(eq(chatVoiceToolCalls.companyId, session.companyId), eq(chatVoiceToolCalls.sessionId, session.id),
eq(chatVoiceToolCalls.tool, "submit_request"))).orderBy(desc(chatVoiceToolCalls.createdAt)).limit(1);
if (!request) return { state: "idle", message: "No work request has been submitted in this call." };
if (task.status === "cancelled") return { state: "cancelled", message: "Work on this task was cancelled." };
if (["failed", "filtered"].includes(request.deliveryState)) return { state: "blocked", message: "The latest request could not be dispatched. Check the task in Paperclip." };
const awaitingDispatch = ["received", "processing", "retry"].includes(request.deliveryState);
const [run] = await tx.select({ status: heartbeatRuns.status }).from(heartbeatRuns).where(and(
eq(heartbeatRuns.companyId, session.companyId), eq(heartbeatRuns.agentId, session.assignedAgentId),
or(eq(heartbeatRuns.issueId, session.issueId), and(isNull(heartbeatRuns.issueId), sql`${heartbeatRuns.contextSnapshot}->>'issueId' = ${session.issueId}`)),
or(task.executionRunId ? eq(heartbeatRuns.id, task.executionRunId) : sql`false`, gte(heartbeatRuns.createdAt, request.createdAt)),
)).orderBy(desc(heartbeatRuns.createdAt)).limit(1);
if (run?.status === "running") return { state: "running", followUpQueued: awaitingDispatch, message: "The Paperclip agent is working on this task." };
if (awaitingDispatch || run?.status === "queued") return { state: "queued", message: "The request is saved and waiting for execution." };
if (run && ["failed", "timed_out"].includes(run.status)) return { state: "failed", message: "The latest execution failed. Check the task in Paperclip." };
if (run?.status === "cancelled") return { state: "cancelled", message: "The latest execution was cancelled." };
if (run?.status === "succeeded") return { state: "awaiting_reply", message: "No agent run is currently active. Use only approved updates for the answer. This does not prove the requested work or any background command completed." };
return { state: "pending", message: "The request is saved; execution status is not yet available." };
}
async function runTool(input: {
companyId: string; endpointId: string; sessionId: string; token: string; envelope: SpekoToolEnvelope; webhookId: string; fingerprint: string;
/** Stage the existing chat delivery. Execution drains after this transaction commits. */
accept(tx: VoiceTransaction, context: Awaited<ReturnType<typeof authorizeSession>>, text: string, providerToolCallId: string): Promise<string>;
}) {
return db.transaction(async (tx) => {
const context = await authorizeSession(tx, input.companyId, input.sessionId), { session } = context;
if (session.endpointId !== input.endpointId || session.providerSessionId !== input.envelope.session_id || !timingSafeEqual(Buffer.from(session.toolTokenHash, "hex"), Buffer.from(voiceTokenHash(input.token), "hex"))) throw forbidden("Voice tool scope does not match this session");
if (session.state === "connecting") {
await tx.update(chatVoiceSessions).set({ state: "active", updatedAt: new Date() }).where(eq(chatVoiceSessions.id, session.id));
await tx.insert(activityLog).values({ companyId: session.companyId, actorType: "system", actorId: "voice-session-service", action: "voice.session.connected", entityType: "voice_session", entityId: session.id, details: { endpointId: session.endpointId, issueId: session.issueId } });
}
const prior = await tx.select().from(chatVoiceToolCalls).where(and(eq(chatVoiceToolCalls.sessionId, session.id), eq(chatVoiceToolCalls.providerToolCallId, input.envelope.tool_call_id))).then((rows) => rows[0]);
if (prior) {
if (prior.fingerprint !== input.fingerprint) throw conflict("Voice tool retry changed its arguments");
if (prior.tool === "get_updates") {
const updates = Array.isArray(prior.response.updates) ? prior.response.updates : [];
for (const update of updates) {
if (!update || typeof update !== "object" || typeof update.publicationId !== "string") throw conflict("Invalid saved voice reply");
const [publication] = await tx.select().from(chatPublications).where(and(
eq(chatPublications.id, update.publicationId), eq(chatPublications.companyId, session.companyId),
eq(chatPublications.endpointId, session.endpointId), eq(chatPublications.conversationId, session.conversationId),
eq(chatPublications.issueId, session.issueId), eq(chatPublications.state, "published"))).for("share");
if (!publication || publication.payload.text !== update.text) throw conflict("This voice reply changed; retrieve current updates");
}
}
return prior.response;
}
const replay = await tx.select({ id: chatVoiceToolCalls.id }).from(chatVoiceToolCalls)
.where(and(eq(chatVoiceToolCalls.companyId, session.companyId), eq(chatVoiceToolCalls.webhookId, input.webhookId))).then((rows) => rows[0]);
if (replay) throw conflict("Voice webhook id was already used for a different tool call");
let deliveryId: string | null = null, response: Record<string, unknown>;
if (input.envelope.tool === "submit_request") {
if (context.task.status === "backlog") throw conflict("Move this task to Todo in Paperclip before requesting voice work.");
if (session.callerAuthority === "guest_intake") {
const requests = await tx.select({id: chatVoiceToolCalls.id}).from(chatVoiceToolCalls).where(and(eq(chatVoiceToolCalls.sessionId, session.id), eq(chatVoiceToolCalls.tool, "submit_request"))).limit(20);
if (requests.length >= 20) throw conflict("This call has reached its message limit. Continue in Paperclip.");
}
deliveryId = await input.accept(tx, context, input.envelope.args.text, input.envelope.tool_call_id);
const delivery = await tx.select({ id: chatDeliveries.id }).from(chatDeliveries).where(and(eq(chatDeliveries.id, deliveryId), eq(chatDeliveries.companyId, session.companyId), eq(chatDeliveries.endpointId, session.endpointId))).then((rows) => rows[0]);
if (!delivery) throw conflict("Voice request was not durably accepted");
response = { status: "accepted", requestId: deliveryId, message: "Your request is saved. Work continues on the same task." };
} else if (input.envelope.tool === "answer_question") {
if (session.callerAuthority === "guest_intake") throw forbidden("Public callers can clarify in conversation, but cannot resolve protected task questions or approvals");
const { interactionId, answers } = input.envelope.args;
const [published] = await tx.select({ id: chatVoiceReplies.id }).from(chatVoiceReplies)
.innerJoin(chatPublications, eq(chatPublications.id, chatVoiceReplies.publicationId))
.where(and(eq(chatVoiceReplies.companyId, session.companyId), eq(chatVoiceReplies.sessionId, session.id),
eq(chatPublications.companyId, session.companyId), eq(chatPublications.conversationId, session.conversationId),
eq(chatPublications.issueId, session.issueId), eq(chatPublications.state, "published"),
sql`${chatVoiceReplies.deliveredAt} is not null`, sql`${chatPublications.payload}->>'interactionId' = ${interactionId}`)).limit(1);
if (!published) throw forbidden("This question was not presented to this voice session");
const answered = await issueThreadInteractionService(tx as unknown as Db).answerQuestions(context.task, interactionId,
{ answers }, { userId: session.callerId });
response = { status: "answered", interactionId, resultSha256: nativeSha256(answered.result), message: "Your answer was saved." };
} else {
await collectMissedReplies(tx, session);
const cursor = input.envelope.args.cursor;
const repeat = input.envelope.args.repeat === true;
if (cursor > session.replyCursor) throw conflict("Voice reply cursor is ahead of this session");
if (repeat) await collectRepeatReply(tx, session);
// The durable delivered marker is authoritative. A later publication
// can finish before an earlier stream; a caller cursor must not hide
// that older, still-unclaimed answer when it eventually publishes.
const available = await tx.select({ reply: chatVoiceReplies, payload: chatPublications.payload, pushBlocked: sql<boolean>`exists (select 1 from chat_actions a where a.company_id = ${session.companyId} and a.endpoint_id = ${session.endpointId} and a.kind = 'speko_voice_reply_push' and a.payload->>'replyId' = ${chatVoiceReplies.id}::text and (a.status in ('dispatching', 'unknown') or (a.status = 'completed' and a.payload->>'questionNotification' = 'false')))` }).from(chatVoiceReplies).innerJoin(chatPublications, and(eq(chatPublications.id, chatVoiceReplies.publicationId), eq(chatPublications.companyId, session.companyId)))
.where(and(eq(chatVoiceReplies.sessionId, session.id), eq(chatVoiceReplies.companyId, session.companyId), repeat ? sql`${chatVoiceReplies.deliveredAt} is not null` : isNull(chatVoiceReplies.deliveredAt), eq(chatPublications.endpointId, session.endpointId), eq(chatPublications.conversationId, session.conversationId), eq(chatPublications.issueId, session.issueId), eq(chatPublications.state, "published")))
.orderBy(repeat ? desc(chatVoiceReplies.deliveredAt) : asc(chatVoiceReplies.cursor), desc(chatVoiceReplies.cursor)).limit(repeat ? 1 : 8);
// Never skip a partly pushed answer to retrieve later replies. The
// accepted prefix cannot be replayed, and its suffix remains ordered.
const pushBoundary = available.findIndex(row => row.pushBlocked);
if (!repeat && pushBoundary >= 0) available.splice(pushBoundary);
// Deliver a bounded burst in one voice turn. Separate typed hints would
// interrupt the preceding answer. Stop at a question so later answers
// cannot displace the clarification the caller must respond to.
const boundary = available.findIndex(({ payload }) => typeof payload.interactionId === "string");
if (boundary >= 0) available.splice(boundary + 1);
if (available.length && !repeat) await tx.update(chatVoiceReplies).set({ deliveredAt: new Date() }).where(and(inArray(chatVoiceReplies.id, available.map((row) => row.reply.id)), isNull(chatVoiceReplies.deliveredAt)));
const updates = [];
for (const { reply, payload } of available) {
let question: Record<string, unknown> | undefined;
const interactionId = typeof payload.interactionId === "string" ? payload.interactionId : null;
if (interactionId) {
const [interaction] = await tx.select().from(issueThreadInteractions).where(and(eq(issueThreadInteractions.companyId, session.companyId),
eq(issueThreadInteractions.issueId, session.issueId), eq(issueThreadInteractions.id, interactionId),
eq(issueThreadInteractions.kind, "ask_user_questions"), eq(issueThreadInteractions.status, "pending")));
if (interaction && evaluateIssueThreadInteractionResolverAudience({ actor: { type: "user", userId: session.callerId }, interaction }).allowed) {
question = { interactionId, questions: (interaction.payload as { questions?: unknown }).questions };
}
}
updates.push({ cursor: reply.cursor, publicationId: reply.publicationId, text: payload.text, ...(question ? { question } : {}) });
}
const work = updates.some(update => update.question)
? { state: "waiting_for_input", message: "The agent has a question for you in the approved updates." }
: await workStatus(tx, context);
const nextCursor = Math.max(cursor, available.at(-1)?.reply.cursor ?? 0);
response = { status: available.length ? "updates" : "pending", work, playback: "unknown", ...(repeat ? { repeated: true } : {}), cursor: nextCursor, updates,
...(session.mode !== "browser" ? {delivery: "Approved task answers are pushed into this live call. Keep conversing; no completion polling is required."} : {}),
};
}
await tx.insert(chatVoiceToolCalls).values({ companyId: session.companyId, sessionId: session.id, providerToolCallId: input.envelope.tool_call_id, webhookId: input.webhookId, fingerprint: input.fingerprint, tool: input.envelope.tool, deliveryId, response });
return response;
});
}
async function authorizePrincipal(tx: VoiceTransaction, companyId: string, endpointId: string, externalId: string) {
const id = /^voice:([0-9a-f-]{36})$/.exec(externalId)?.[1];
if (!id) throw forbidden("Invalid voice principal");
const context = await endpointContext(tx, companyId, endpointId);
const session = await tx.select().from(chatVoiceSessions).where(and(eq(chatVoiceSessions.id, id), eq(chatVoiceSessions.companyId, companyId), eq(chatVoiceSessions.endpointId, endpointId))).then((rows) => rows[0]);
if (!session || !session.providerSessionId || session.generation !== context.generation || session.credentialFingerprint !== context.fingerprint || session.assignedAgentId !== context.endpoint.assignedAgentId
|| !["member", "instance_admin", "local_board", "guest_intake"].includes(session.callerAuthority)) throw forbidden("Voice work authority is no longer current");
const accepted = await tx.select({ id: chatVoiceToolCalls.id }).from(chatVoiceToolCalls).where(and(eq(chatVoiceToolCalls.sessionId, id), eq(chatVoiceToolCalls.companyId, companyId), inArray(chatVoiceToolCalls.tool, ["submit_request", "answer_question"]))).limit(1);
if (!accepted.length) throw forbidden("No request was accepted for this voice principal");
// Accepted work survives hangup. Endpoint/identity revocation still takes
// effect at the ordinary work-queue authorization boundary.
const guest = session.callerAuthority === "guest_intake";
if (!guest) {
await authorizeCaller(tx, companyId, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
await authorizeConnection(tx, context, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
}
const task = guest ? await authorizeGuestTask(tx, context, session) : await authorizeTask(tx, companyId, session.issueId, { id: session.callerId, authority: session.callerAuthority as VoiceCaller["authority"] });
if (task.assigneeAgentId !== session.assignedAgentId) throw forbidden("The voice task assignment changed");
return { allowed: true, linkedDenied: false, userId: guest ? null : session.callerId };
}
async function enqueuePublication(companyId: string, publicationId: string) {
const publication = await db.select().from(chatPublications).where(and(eq(chatPublications.companyId, companyId), eq(chatPublications.id, publicationId), inArray(chatPublications.state, ["streaming", "published"]))).then((rows) => rows[0]);
if (!publication) throw conflict("Voice publication is not dispatchable");
// The voice persona already acknowledges accepted work. Synthetic chat
// progress must not interrupt that acknowledgment or delay the real answer.
if (publication.payload.progressState && !publication.payload.interactionId) {
logger.debug({event: "voice.reply.publication.skipped_progress", companyId, endpointId: publication.endpointId,
issueId: publication.issueId, publicationId}, "Synthetic working progress does not enqueue voice speech");
return { id: `voice:${publicationId}` };
}
const candidates = await db.select({ id: chatVoiceSessions.id }).from(chatVoiceSessions).where(and(eq(chatVoiceSessions.companyId, companyId), eq(chatVoiceSessions.endpointId, publication.endpointId), eq(chatVoiceSessions.conversationId, publication.conversationId), inArray(chatVoiceSessions.state, ["connecting", "active"]))).orderBy(asc(chatVoiceSessions.id));
for (const candidate of candidates) {
try {
await db.transaction(async (tx) => {
const { session } = await authorizeSession(tx, companyId, candidate.id);
const prior = await tx.select({ id: chatVoiceReplies.id }).from(chatVoiceReplies).where(and(eq(chatVoiceReplies.sessionId, session.id), eq(chatVoiceReplies.publicationId, publication.id))).then((rows) => rows[0]);
if (prior) return;
const [priorCall] = await tx.select({blocked: priorCallDeliveryBarrier(session, publication.id)})
.from(chatPublications).where(eq(chatPublications.id, publication.id)).limit(1);
if (priorCall?.blocked) return;
const cursor = session.replyCursor + 1;
await tx.insert(chatVoiceReplies).values({ companyId, sessionId: session.id, publicationId: publication.id, cursor });
await tx.update(chatVoiceSessions).set({ replyCursor: cursor, updatedAt: new Date() }).where(eq(chatVoiceSessions.id, session.id));
return {sessionId: session.id, providerSessionId: session.providerSessionId, replyCursor: cursor, mode: session.mode};
}).then(queued => {
if (queued) logger.info({...queued, event: "voice.reply.publication.enqueued", companyId, endpointId: publication.endpointId,
issueId: publication.issueId, publicationId}, "Approved publication queued for voice delivery");
});
} catch (error) { if (!(error instanceof HttpError && [403, 404].includes(error.status))) throw error; }
}
return { id: `voice:${publicationId}` };
}
async function notification(companyId: string, sessionId: string, callerId: string) {
return db.transaction(async (tx) => {
const { session } = await authorizeSession(tx, companyId, sessionId);
if (session.callerId !== callerId) throw forbidden("This voice session belongs to another caller");
await collectMissedReplies(tx, session);
const [next] = await tx.select({ publicationId: chatVoiceReplies.publicationId, createdAt: chatVoiceReplies.createdAt }).from(chatVoiceReplies).innerJoin(chatPublications, eq(chatPublications.id, chatVoiceReplies.publicationId))
.where(and(eq(chatVoiceReplies.companyId, companyId), eq(chatVoiceReplies.sessionId, sessionId), isNull(chatVoiceReplies.deliveredAt), eq(chatPublications.state, "published")))
.orderBy(asc(chatVoiceReplies.cursor)).limit(1);
return next ? { sessionId, generation: session.generation, publicationId: next.publicationId, attempt: Math.max(0, Math.floor((Date.now() - next.createdAt.getTime()) / 10_000)) } : null;
});
}
return { endpointContext, authorizeConnection, reserve, stageDelivery, runTool, authorizeSession, authorizeCaller, authorizeTask, authorizePrincipal, enqueuePublication, notification, collectMissedReplies };
}