@agimon-ai/po-voice 0.0.0-alpha.0

package/dist/apiContracts.mjs

@@ -0,0 +1,805 @@
+import { defineApiContract, jsonApiResponses } from "@agimon-ai/po-core/apiContracts";
+import { Type } from "typebox";
+import { defineDoomPluginMethod } from "@agimon-ai/po-core/pluginProtocol";
+//#region src/schemas/voiceControl.ts
+const voiceControlMethod = defineDoomPluginMethod({
+	service: "voice",
+	method: "control",
+	scope: "session",
+	direction: "client-to-server",
+	input: Type.Object({
+		action: Type.Union([
+			"status",
+			"manual",
+			"activate",
+			"deactivate",
+			"mute",
+			"unmute",
+			"interrupt",
+			"transfer"
+		].map((value) => Type.Literal(value))),
+		target: Type.Optional(Type.Integer({ minimum: 1 })),
+		revision: Type.Optional(Type.String({
+			minLength: 1,
+			maxLength: 128
+		}))
+	}, { additionalProperties: false }),
+	output: Type.Object({
+		state: Type.String(),
+		mode: Type.String(),
+		manual: Type.String(),
+		muted: Type.Boolean(),
+		error: Type.Optional(Type.String())
+	}, { additionalProperties: false })
+});
+//#endregion
+//#region src/schemas/apiContracts.ts
+const S = Type.String();
+const N = Type.Number();
+const B = Type.Boolean();
+const O = Type.Optional;
+const values = (items) => Type.Union(items.map((item) => Type.Literal(item)));
+const Client = {
+	clientId: S,
+	connectionId: S
+};
+const Configuration = Type.Object({
+	mode: values(["manual", "autonomous"]),
+	activityControl: values(["host", "client"]),
+	endpointSilenceMs: O(Type.Integer({ minimum: 250 }))
+});
+const Playback = {
+	playbackId: S,
+	outcome: values([
+		"completed",
+		"stopped",
+		"aborted",
+		"failed"
+	]),
+	error: O(S)
+};
+const Sequence = { sequence: N };
+const Control = values([
+	"mute",
+	"unmute",
+	"interrupt"
+]);
+const Browser = Type.Object({
+	connection: values([
+		"connecting",
+		"connected",
+		"closed",
+		"failed"
+	]),
+	listening: B,
+	speaking: B,
+	muted: B,
+	error: O(S)
+});
+const VoiceMediaEventSchema = Type.Union([
+	Type.Object({
+		...Sequence,
+		type: Type.Literal("capture-start"),
+		captureId: S,
+		sampleRate: Type.Literal(16e3),
+		channels: Type.Literal(1),
+		bitsPerSample: Type.Literal(16),
+		configuration: Configuration
+	}),
+	Type.Object({
+		...Sequence,
+		type: values(["capture-stop", "capture-abort"]),
+		captureId: S
+	}),
+	Type.Object({
+		...Sequence,
+		type: Type.Literal("playback-start"),
+		playbackId: S,
+		text: S,
+		delivery: O(values(["client", "streamed"])),
+		voice: O(S),
+		rate: O(N)
+	}),
+	Type.Object({
+		...Sequence,
+		type: values(["playback-stop", "playback-abort"]),
+		playbackId: S
+	}),
+	Type.Object({
+		...Sequence,
+		type: values(["realtime-start", "realtime-stop"]),
+		activationId: S
+	}),
+	Type.Object({
+		...Sequence,
+		type: Type.Literal("realtime-control"),
+		activationId: S,
+		action: Control
+	}),
+	Type.Object({
+		...Sequence,
+		type: Type.Literal("realtime-send"),
+		activationId: S,
+		messages: Type.Array(S)
+	})
+]);
+const RealtimeEvent = Type.Union([
+	Type.Object({ type: Type.Literal("ready") }),
+	Type.Object({
+		type: Type.Literal("transcript"),
+		role: values(["user", "assistant"]),
+		text: S,
+		complete: B
+	}),
+	Type.Object({
+		type: Type.Literal("request"),
+		requestId: S,
+		text: S
+	}),
+	Type.Object({
+		type: Type.Literal("error"),
+		code: S
+	})
+]);
+const RealtimeSnapshot = Type.Object({
+	activationId: S,
+	state: values([
+		"connecting",
+		"active",
+		"closed",
+		"failed"
+	]),
+	cursor: N,
+	events: Type.Array(Type.Object({
+		sequence: N,
+		event: RealtimeEvent
+	})),
+	browser: O(Browser)
+});
+const Wake = Type.Object({
+	eventEpoch: S,
+	sequence: N
+});
+const GlobalLiveStatus = Type.Object({
+	version: Type.Literal(1),
+	state: values([
+		"disabled",
+		"starting",
+		"active",
+		"draining",
+		"shuttingDown"
+	]),
+	activeSessionId: Type.Union([S, Type.Null()]),
+	muted: B,
+	error: O(S),
+	media: Type.Object({
+		client: B,
+		realtime: B
+	})
+});
+const Version = { version: Type.Literal(3) };
+const Targets = Type.Array(Type.Object({
+	handle: S,
+	label: S,
+	order: N
+}), { maxItems: 32 });
+const OwnershipAction = values([
+	"catalog",
+	"prepare",
+	"activate",
+	"deactivate",
+	"readiness",
+	"fence"
+]);
+const Acknowledgement = Type.Object({
+	...Version,
+	commandId: S,
+	action: OwnershipAction,
+	ok: B,
+	active: B,
+	error: O(S)
+});
+const Command = Type.Object({
+	...Version,
+	commandId: S,
+	action: OwnershipAction,
+	targets: O(Targets),
+	catalogRevision: O(S),
+	handoffId: O(S),
+	controllerId: O(S),
+	leaseId: O(S),
+	revision: O(N)
+});
+const Snapshot = Type.Object({
+	registration: O(Type.Object({
+		...Version,
+		leaseId: S,
+		revision: N,
+		label: S,
+		eligible: B,
+		active: B
+	})),
+	targets: Targets,
+	catalogRevision: O(S),
+	activation: O(Type.Object({
+		...Version,
+		requestId: S
+	})),
+	handoff: O(Type.Object({
+		...Version,
+		requestId: S,
+		handle: S,
+		catalogRevision: S
+	})),
+	acknowledgement: O(Acknowledgement)
+});
+const Errors = Object.fromEntries([
+	400,
+	404,
+	409,
+	410,
+	413,
+	415,
+	429,
+	500,
+	502,
+	503,
+	504
+].map((status) => [status, {
+	description: "Voice request failed.",
+	schema: Type.Object({
+		error: S,
+		code: O(S)
+	})
+}]));
+const route = (path, method, output, input, query = [], status = 200) => ({
+	id: `voice.${path.slice(1).replaceAll("/", ".")}`,
+	scope: "session",
+	basePath: "voice-media",
+	path,
+	method,
+	authentication: "owner",
+	description: `Voice media ${path}.`,
+	...path.startsWith("/host/") || path.startsWith("/hub/") ? { availability: "Internal broker route; requires the host-issued bearer token for this route namespace." } : {},
+	parameters: [...query.map((name) => ({
+		name,
+		in: "query",
+		required: !["after", "wait"].includes(name),
+		schema: S
+	})), ...path.startsWith("/host/") || path.startsWith("/hub/") ? [{
+		name: "Authorization",
+		in: "header",
+		required: true,
+		schema: Type.String({ pattern: "^Bearer .+" })
+	}] : []],
+	...input ? { body: {
+		required: true,
+		contentType: "application/json",
+		schema: input
+	} } : {},
+	responses: {
+		...Errors,
+		[output ? status : 204]: {
+			description: output ? "Voice response." : "Accepted with no response body.",
+			...output ? { schema: output } : {}
+		}
+	}
+});
+const pcm = (path, method, query) => {
+	const result = route(path, method, void 0, void 0, query);
+	result.description = "PCM signed 16-bit little-endian, 16000 Hz, mono. Chunks contain complete samples. Activity headers carry state, level, elapsed time, epoch and speech duration. A 204 response carries x-po-capture-state or x-po-playback-state when applicable.";
+	if (method === "POST") result.body = {
+		required: true,
+		contentType: "application/vnd.po.pcm-s16le",
+		schema: S
+	};
+	else result.responses["200"] = {
+		description: "PCM bytes.",
+		contentType: "application/vnd.po.pcm-s16le",
+		schema: S
+	};
+	return result;
+};
+const apiContracts = defineApiContract({
+	version: 1,
+	protocols: {
+		"voice-media": "6",
+		"voice-ownership": "3"
+	},
+	dynamic: ["Realtime event strings and SDP are provider-defined protocol documents passed through the media broker."],
+	http: [
+		{
+			id: "voice.status",
+			scope: "session",
+			basePath: "voice",
+			path: "/status",
+			method: "GET",
+			authentication: "owner",
+			description: "Voice session status and media readiness.",
+			responses: jsonApiResponses(Type.Object({
+				...voiceControlMethod.output.properties,
+				media: Type.Object({
+					closed: B,
+					capture: B,
+					playback: B,
+					realtime: B
+				}),
+				readiness: Type.Object({
+					configured: B,
+					transcription: B,
+					error: O(S),
+					engine: O(S),
+					mode: O(S),
+					correctionModel: O(S)
+				})
+			}))
+		},
+		{
+			id: "voice.control.http",
+			scope: "session",
+			basePath: "voice",
+			path: "/control",
+			method: "POST",
+			authentication: "owner",
+			description: "Control the voice session.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: voiceControlMethod.input
+			},
+			responses: jsonApiResponses(voiceControlMethod.output)
+		},
+		route("/client/connect", "POST", Type.Object({
+			version: Type.Literal(6),
+			cursor: N,
+			eventEpoch: O(S),
+			heartbeatMs: O(N)
+		}), Type.Object({
+			version: Type.Literal(6),
+			...Client,
+			clientKind: values(["browser", "native"]),
+			controlLocation: values(["local", "remote"]),
+			capabilities: Type.Object({
+				capture: B,
+				playback: B,
+				captureActivity: B,
+				autonomousOrchestration: B,
+				playbackDucking: O(B),
+				realtime: O(B)
+			})
+		})),
+		route("/client/disconnect", "POST", void 0, Type.Object(Client)),
+		route("/client/heartbeat", "POST", Wake, Type.Object(Client)),
+		{
+			...route("/client/events", "GET", VoiceMediaEventSchema, void 0, [
+				"clientId",
+				"connectionId",
+				"after",
+				"wait"
+			]),
+			responses: {
+				...Errors,
+				"200": {
+					description: "Next event.",
+					schema: VoiceMediaEventSchema
+				},
+				"204": { description: "No pending event." }
+			}
+		},
+		pcm("/client/audio", "POST", [
+			"clientId",
+			"connectionId",
+			"captureId"
+		]),
+		route("/client/capture-stopped", "POST", void 0, Type.Object({
+			...Client,
+			captureId: S,
+			error: O(S)
+		})),
+		pcm("/client/playback-audio", "GET", [
+			"clientId",
+			"connectionId",
+			"playbackId"
+		]),
+		route("/client/playback-result", "POST", void 0, Type.Object({
+			...Client,
+			...Playback
+		})),
+		route("/host/capture/start", "POST", Type.Object({ configuration: Configuration }), Type.Object({
+			captureId: S,
+			configuration: O(Configuration)
+		}), [], 201),
+		pcm("/host/capture/audio", "GET", ["captureId"]),
+		...["stop", "abort"].map((action) => route(`/host/capture/${action}`, "POST", void 0, Type.Object({ captureId: S }))),
+		route("/host/playback/start", "POST", Type.Object({ delivery: values(["client", "streamed"]) }), Type.Object({
+			playbackId: S,
+			text: S,
+			voice: O(S),
+			rate: O(N)
+		}), [], 201),
+		pcm("/host/playback/audio", "POST", ["playbackId"]),
+		route("/host/playback/audio-end", "POST", void 0, Type.Object({
+			playbackId: S,
+			error: O(S)
+		})),
+		{
+			...route("/host/playback/result", "GET", Type.Object(Playback), void 0, ["playbackId"]),
+			responses: {
+				...Errors,
+				"200": {
+					description: "Playback outcome.",
+					schema: Type.Object(Playback)
+				},
+				"204": { description: "Playback is pending." }
+			}
+		},
+		...["stop", "abort"].map((action) => route(`/host/playback/${action}`, "POST", void 0, Type.Object({ playbackId: S }))),
+		route("/hub/ownership/state", "GET", Snapshot),
+		route("/hub/ownership/command", "POST", Acknowledgement, Command),
+		route("/host/ownership/sync", "POST", Type.Object({ command: O(Command) }), Snapshot),
+		route("/host/realtime/start", "POST", Type.Object({}), Type.Object({
+			activationId: S,
+			instructions: Type.String({ maxLength: 16384 })
+		}), [], 201),
+		route("/host/realtime/stop", "POST", void 0, Type.Object({ activationId: S })),
+		route("/host/realtime/poll", "GET", RealtimeSnapshot, void 0, ["activationId", "after"]),
+		route("/host/realtime/send", "POST", void 0, Type.Object({
+			activationId: S,
+			messages: Type.Array(S, { maxItems: 64 })
+		})),
+		route("/host/realtime/control", "POST", void 0, Type.Object({
+			activationId: S,
+			action: Control
+		})),
+		route("/client/realtime/negotiate", "POST", Type.Object({ sdp: S }), Type.Object({
+			...Client,
+			activationId: S,
+			sdp: S
+		})),
+		route("/client/realtime/event", "POST", void 0, Type.Object({
+			...Client,
+			activationId: S,
+			event: S
+		})),
+		route("/client/realtime/state", "POST", void 0, Type.Object({
+			...Client,
+			activationId: S,
+			state: Browser
+		})),
+		{
+			id: "voice.manual",
+			scope: "session",
+			basePath: "voice-media",
+			path: "/manual/transcribe",
+			method: "POST",
+			authentication: "owner",
+			description: "Transcribe at most 4 MiB of WebM/Opus or MP4/AAC audio, at most 300000 milliseconds.",
+			parameters: [{
+				name: "x-doom-audio-duration-ms",
+				in: "header",
+				required: true,
+				schema: Type.Integer({
+					minimum: 0,
+					maximum: 3e5
+				})
+			}],
+			body: {
+				required: true,
+				contentType: "audio/webm",
+				contentTypes: ["audio/webm", "audio/mp4"],
+				schema: S
+			},
+			responses: {
+				...Errors,
+				"200": {
+					description: "Transcript.",
+					schema: Type.Object({ transcript: S })
+				}
+			}
+		},
+		...[
+			[
+				"readiness",
+				"/live/agent",
+				"GET"
+			],
+			[
+				"prepare",
+				"/live/agent/prepare",
+				"POST"
+			],
+			[
+				"admit",
+				"/live/agent/admit",
+				"POST"
+			],
+			[
+				"results",
+				"/live/agent/results",
+				"GET"
+			],
+			[
+				"ack",
+				"/live/agent/results/ack",
+				"POST"
+			],
+			[
+				"fence",
+				"/live/agent/fence",
+				"POST"
+			],
+			[
+				"select",
+				"/live/agent/select",
+				"POST"
+			],
+			[
+				"revoke",
+				"/live/agent/revoke",
+				"POST"
+			]
+		].map(([name, path, method]) => ({
+			id: `voice.agent.${name}`,
+			scope: "session",
+			basePath: "voice",
+			path,
+			method,
+			authentication: "owner",
+			description: `Native Voice agent ${name}. Only the host-issued hub bearer can access this route.`,
+			parameters: [{
+				name: "Authorization",
+				in: "header",
+				required: true,
+				schema: Type.String({ pattern: "^Bearer .+" })
+			}, ...name === "results" ? [
+				"activationId",
+				"routeGeneration",
+				"sessionIncarnation",
+				"after"
+			].map((key) => ({
+				name: key,
+				in: "query",
+				required: key !== "after",
+				schema: S
+			})) : []],
+			...method === "POST" ? { body: {
+				required: true,
+				contentType: "application/json",
+				schema: name === "select" ? Type.Object({
+					activationId: S,
+					routeGeneration: Type.Integer({ minimum: 1 }),
+					transactionId: S,
+					sessionIncarnation: S,
+					nativeTransferAllowed: B,
+					catalog: Type.Object({
+						revision: S,
+						targets: Type.Array(Type.Object({
+							order: Type.Integer({ minimum: 1 }),
+							label: S
+						}), { maxItems: 256 })
+					})
+				}) : name === "revoke" ? Type.Object({
+					activationId: S,
+					routeGeneration: Type.Integer({ minimum: 1 }),
+					transactionId: S,
+					sessionIncarnation: S
+				}) : Type.Unknown()
+			} } : {},
+			responses: {
+				...jsonApiResponses(Type.Unknown()),
+				"204": { description: "Agent result acknowledged or route fenced." }
+			}
+		})),
+		{
+			id: "voice.peer",
+			scope: "global",
+			basePath: "voice",
+			path: "/peer",
+			method: "POST",
+			authentication: "none",
+			description: "Accept an HMAC-authenticated bounded Voice media relay request from a configured peer.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Unknown()
+			},
+			responses: jsonApiResponses(Type.Unknown())
+		},
+		{
+			id: "voice.peerOwnership",
+			scope: "global",
+			basePath: "voice",
+			path: "/peer-ownership",
+			method: "POST",
+			authentication: "none",
+			description: "Discover and stage Voice ownership through an HMAC-authenticated paired host.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Unknown()
+			},
+			responses: jsonApiResponses(Type.Unknown())
+		},
+		{
+			id: "voice.peerAgent",
+			scope: "global",
+			basePath: "voice",
+			path: "/peer-agent",
+			method: "POST",
+			authentication: "none",
+			description: "Accept a signed, replay-guarded, grant-scoped native Voice agent request from a configured peer.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Unknown()
+			},
+			responses: jsonApiResponses(Type.Unknown())
+		},
+		{
+			id: "voice.relayBinding",
+			scope: "global",
+			basePath: "voice",
+			path: "/relay-binding",
+			method: "POST",
+			authentication: "owner",
+			description: "Issue an expiring controller-bound handle for a granted paired Voice session.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Object({
+					target: S,
+					connectionId: S
+				})
+			},
+			responses: jsonApiResponses(Type.Object({
+				binding: S,
+				expiresAt: N
+			}))
+		},
+		{
+			id: "voice.relay",
+			scope: "global",
+			basePath: "voice",
+			path: "/relay",
+			method: "POST",
+			authentication: "owner",
+			description: "Relay a browser Voice media operation through an expiring controller-bound handle.",
+			parameters: [{
+				name: "binding",
+				in: "query",
+				required: true,
+				schema: S
+			}],
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Unknown()
+			},
+			responses: jsonApiResponses(Type.Unknown())
+		},
+		{
+			id: "voice.nativeTransfer",
+			scope: "global",
+			basePath: "voice",
+			path: "/live/native-transfer",
+			method: "POST",
+			authentication: "owner",
+			description: "Host-only revision-bound native Live transfer. Requires the host hub bearer.",
+			parameters: [{
+				name: "Authorization",
+				in: "header",
+				required: true,
+				schema: Type.String({ pattern: "^Bearer .+" })
+			}],
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Object({
+					sourceSessionId: S,
+					activationId: S,
+					routeGeneration: Type.Integer({ minimum: 0 }),
+					sessionIncarnation: S,
+					ordinal: Type.Integer({ minimum: 1 }),
+					catalogRevision: S
+				})
+			},
+			responses: {
+				...Errors,
+				"202": {
+					description: "Transfer requested; source work drains before commit.",
+					schema: Type.Object({ requested: Type.Literal(true) })
+				}
+			}
+		},
+		{
+			id: "voice.liveStatus",
+			scope: "global",
+			basePath: "voice",
+			path: "/live/status",
+			method: "GET",
+			authentication: "owner",
+			description: "Read the host-global live companion state without activating media.",
+			responses: jsonApiResponses(GlobalLiveStatus)
+		},
+		{
+			id: "voice.liveControl",
+			scope: "global",
+			basePath: "voice",
+			path: "/live/control",
+			method: "POST",
+			authentication: "owner",
+			description: "Explicitly activate, transfer, mute, interrupt or end the host-global live companion.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: Type.Object({
+					action: values([
+						"activate",
+						"transfer",
+						"mute",
+						"unmute",
+						"interrupt",
+						"end"
+					]),
+					sessionId: O(S),
+					expectedSourceSessionId: O(S)
+				})
+			},
+			responses: jsonApiResponses(GlobalLiveStatus)
+		},
+		{
+			id: "voice.readiness",
+			scope: "global",
+			basePath: "voice",
+			path: "/readiness",
+			method: "GET",
+			authentication: "owner",
+			description: "Read configured voice readiness.",
+			responses: jsonApiResponses(Type.Object({
+				configured: B,
+				transcription: B,
+				error: O(S),
+				engine: O(S),
+				mode: O(S),
+				correctionModel: O(S)
+			}))
+		}
+	],
+	sockets: [{
+		id: "voice.control",
+		scope: "session",
+		service: voiceControlMethod.service,
+		member: voiceControlMethod.method,
+		kind: "method",
+		direction: "client-to-server",
+		description: "Voice session control through the scoped plugin service.",
+		input: voiceControlMethod.input,
+		output: voiceControlMethod.output
+	}, ...["global", "workspace"].flatMap((scope) => [{
+		id: "voice.wake",
+		scope,
+		service: "po.hub.v1",
+		member: "voice_media_wake",
+		kind: "channel",
+		direction: "server-to-client",
+		description: "Voice media wake channel payload.",
+		input: Wake
+	}, {
+		id: "voice.ownership",
+		scope,
+		service: "po.hub.v1",
+		member: "voice_ownership",
+		kind: "channel",
+		direction: "server-to-client",
+		description: "Browser media ownership channel payload.",
+		input: Type.Object({
+			type: Type.Literal("browser-media-session"),
+			...Version,
+			activeSessionId: Type.Union([S, Type.Null()])
+		})
+	}])]
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map