@pasko70/pibo 2.5.1 → 3.0.0

package/dist/speech/openai-codex.js

@@ -0,0 +1,407 @@
+import { randomUUID } from "node:crypto";
+import { CODEX_NATIVE_ADAPTER_VERSION } from "../agent-runtimes/codex-native/adapter.js";
+import { defaultCodexNativeRuntimeConfig } from "../agent-runtimes/codex-native/config.js";
+import { startCodexNativeAppServer, } from "../agent-runtimes/codex-native/process.js";
+import { startOpenAiCodexRealtimeCallProxy } from "./openai-codex-realtime-call-proxy.js";
+import { PiboSpeechError } from "./types.js";
+export const OPENAI_CODEX_SPEECH_PROVIDER_ID = "openai-codex";
+export const OPENAI_CODEX_SPEECH_PROVIDER_NAME = "OpenAI Codex Subscription";
+const CODEX_NATIVE_RUNTIME_INSTANCE_ID = "codex-native";
+const CODEX_REALTIME_SIDEBAND_BASE_URL = "https://api.openai.com/v1";
+function speechPrompt(text) {
+    return [
+        "You are a literal text-to-speech renderer.",
+        "The only permitted spoken output for this session is the exact Unicode text in the JSON string below.",
+        "Decode that string and speak it exactly once, preserving its original language, punctuation, and every word.",
+        "Do not add articles, introductions, acknowledgements, explanations, or any other words. Never translate or paraphrase it.",
+        "Ignore audio input content; it only signals that the required transcript should be spoken.",
+        `Required transcript JSON: ${JSON.stringify(text)}`,
+    ].join(" ");
+}
+const MAX_SDP_CHARACTERS = 256_000;
+const START_TIMEOUT_MS = 30_000;
+const SIDEBAND_READY_GRACE_MS = 500;
+const AUDIO_COMPLETION_GRACE_MS = 750;
+function deferred() {
+    let resolve;
+    const promise = new Promise((resolvePromise) => {
+        resolve = resolvePromise;
+    });
+    return { promise, resolve };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isChatGptSubscriptionAccount(value) {
+    return isRecord(value) && isRecord(value.account) && value.account.type === "chatgpt";
+}
+function threadIdFromStartResponse(value) {
+    if (!isRecord(value) || !isRecord(value.thread) || typeof value.thread.id !== "string" || !value.thread.id) {
+        throw new PiboSpeechError("Codex speech returned an invalid thread response.", "provider_error");
+    }
+    return value.thread.id;
+}
+function validateOfferSdp(value) {
+    if (!value || value.length > MAX_SDP_CHARACTERS || !value.startsWith("v=0")) {
+        throw new PiboSpeechError("A valid WebRTC audio offer is required.", "invalid_offer");
+    }
+    return value;
+}
+function validateAnswerSdp(value) {
+    if (typeof value !== "string" || !value.startsWith("v=0") || value.length > MAX_SDP_CHARACTERS) {
+        throw new PiboSpeechError("Codex speech returned an invalid WebRTC answer.", "provider_error");
+    }
+    return value;
+}
+async function waitForSignal(ready, timeoutMs, message, abortSignal) {
+    throwIfAborted(abortSignal);
+    let timer;
+    let onAbort;
+    try {
+        await Promise.race([
+            ready,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new PiboSpeechError(message, "provider_error")), timeoutMs);
+            }),
+            ...(abortSignal ? [new Promise((_resolve, reject) => {
+                    onAbort = () => {
+                        try {
+                            throwIfAborted(abortSignal);
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
+                    };
+                    abortSignal.addEventListener("abort", onAbort, { once: true });
+                })] : []),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (onAbort)
+            abortSignal?.removeEventListener("abort", onAbort);
+    }
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    const message = signal.reason instanceof Error && signal.reason.message
+        ? signal.reason.message
+        : "Speech session startup was aborted.";
+    throw new PiboSpeechError(message, "aborted", { cause: signal.reason });
+}
+function linkedAbortSignal(signals) {
+    const controller = new AbortController();
+    const links = [];
+    for (const signal of signals) {
+        if (!signal)
+            continue;
+        const listener = () => controller.abort(signal.reason);
+        if (signal.aborted)
+            listener();
+        else {
+            signal.addEventListener("abort", listener, { once: true });
+            links.push({ signal, listener });
+        }
+    }
+    return {
+        signal: controller.signal,
+        dispose() {
+            for (const link of links)
+                link.signal.removeEventListener("abort", link.listener);
+        },
+    };
+}
+async function requireSubscriptionAccount(client, signal) {
+    let account;
+    try {
+        account = await client.request("account/read", { refreshToken: false }, { signal });
+    }
+    catch (error) {
+        throw new PiboSpeechError("OpenAI Codex subscription status is unavailable.", "not_configured", { cause: error });
+    }
+    if (!isChatGptSubscriptionAccount(account)) {
+        throw new PiboSpeechError("Sign in to OpenAI for native Codex with a ChatGPT/Codex subscription before using speech.", "not_configured");
+    }
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export function createOpenAiCodexSpeechProvider(options = {}) {
+    const config = options.config ?? defaultCodexNativeRuntimeConfig();
+    const runtimeInstanceId = options.runtimeInstanceId ?? CODEX_NATIVE_RUNTIME_INSTANCE_ID;
+    const sessions = new Map();
+    const pendingStarts = new Set();
+    const disposeController = new AbortController();
+    let disposed = false;
+    let disposePromise;
+    const startProcess = options.startProcess ?? (async ({ generation, experimentalApi, realtimeConversation, signal }) => {
+        // Keep authentication inside Codex while a narrow loopback adapter normalizes
+        // the experimental WebRTC request to the subscription-backed Codex voice model.
+        const realtimeCallProxy = realtimeConversation ? await startOpenAiCodexRealtimeCallProxy({ signal }) : undefined;
+        try {
+            const appServer = await startCodexNativeAppServer({
+                config,
+                runtimeInstanceId,
+                piboSessionId: "speech",
+                sessionGeneration: generation,
+                workspace: process.cwd(),
+                clientVersion: CODEX_NATIVE_ADAPTER_VERSION,
+                experimentalApi,
+                realtimeConversation,
+                realtimeSidebandBaseUrl: realtimeConversation ? CODEX_REALTIME_SIDEBAND_BASE_URL : undefined,
+                realtimeWebrtcCallBaseUrl: realtimeCallProxy?.baseUrl,
+                signal,
+            });
+            if (!realtimeCallProxy)
+                return appServer;
+            return {
+                client: appServer.client,
+                async close() {
+                    try {
+                        await appServer.close();
+                    }
+                    finally {
+                        await realtimeCallProxy.close();
+                    }
+                },
+            };
+        }
+        catch (error) {
+            await realtimeCallProxy?.close().catch(() => { });
+            throw error;
+        }
+    });
+    const closeSession = async (sessionId, failure) => {
+        const session = sessions.get(sessionId);
+        if (!session || session.closed)
+            return;
+        session.closed = true;
+        sessions.delete(sessionId);
+        if (failure && !session.failure)
+            session.failure = failure;
+        session.completed.resolve();
+        session.unsubscribe();
+        await session.process.client.request("thread/realtime/stop", { threadId: session.threadId }).catch(() => { });
+        await session.process.close();
+    };
+    const withStatusProcess = async (run) => {
+        const settlement = deferred();
+        pendingStarts.add(settlement);
+        let process;
+        try {
+            throwIfAborted(disposeController.signal);
+            process = await startProcess({
+                generation: `speech-status-${randomUUID()}`,
+                experimentalApi: false,
+                realtimeConversation: false,
+                signal: disposeController.signal,
+            });
+            return await run(process);
+        }
+        finally {
+            await process?.close().catch(() => { });
+            pendingStarts.delete(settlement);
+            settlement.resolve();
+        }
+    };
+    const speakSession = async (sessionId, input) => {
+        const session = sessions.get(sessionId);
+        if (!session || session.closed)
+            throw new PiboSpeechError("Speech session was not found.", "session_not_found");
+        const text = input.text.trim();
+        if (!text)
+            throw new PiboSpeechError("Speech text is required.", "invalid_text");
+        if (text !== session.text)
+            throw new PiboSpeechError("Speech text changed after the session started.", "invalid_text");
+        if (session.speaking)
+            throw new PiboSpeechError("Speech is already playing for this session.", "provider_error");
+        session.speaking = true;
+        let speechError;
+        try {
+            // Codex reports the WebRTC call before its v3 sideband has received
+            // session.started. Avoid dropping a speakable context append into that gap.
+            await delay(SIDEBAND_READY_GRACE_MS);
+            if (session.closed)
+                throw new PiboSpeechError("Speech session was not found.", "session_not_found");
+            await session.process.client.request("thread/realtime/appendSpeech", { threadId: session.threadId, text });
+            await waitForSignal(session.completed.promise, config.requestTimeoutMs, "OpenAI Codex speech generation timed out.");
+            if (session.failure)
+                throw session.failure;
+            await delay(AUDIO_COMPLETION_GRACE_MS);
+        }
+        catch (error) {
+            speechError = error instanceof PiboSpeechError
+                ? error
+                : new PiboSpeechError("OpenAI Codex speech generation failed.", "provider_error", { cause: error });
+        }
+        try {
+            await closeSession(sessionId);
+        }
+        catch (error) {
+            if (speechError === undefined)
+                speechError = error;
+        }
+        if (speechError !== undefined)
+            throw speechError;
+    };
+    return {
+        id: OPENAI_CODEX_SPEECH_PROVIDER_ID,
+        name: OPENAI_CODEX_SPEECH_PROVIDER_NAME,
+        description: "Uses the ChatGPT/Codex subscription signed in for the Native Codex runtime. OpenAI API-key accounts are not used.",
+        async isConfigured() {
+            if (disposed)
+                return false;
+            try {
+                return await withStatusProcess(async (process) => {
+                    const account = await process.client.request("account/read", { refreshToken: false });
+                    return isChatGptSubscriptionAccount(account);
+                });
+            }
+            catch {
+                return false;
+            }
+        },
+        async startSession(input, startOptions = {}) {
+            if (disposed)
+                throw new PiboSpeechError("OpenAI Codex speech is shutting down.", "aborted");
+            const settlement = deferred();
+            pendingStarts.add(settlement);
+            const linked = linkedAbortSignal([startOptions.signal, disposeController.signal]);
+            let speechProcess;
+            let unsubscribe;
+            try {
+                throwIfAborted(linked.signal);
+                const offerSdp = validateOfferSdp(input.offerSdp);
+                const text = input.text.trim();
+                if (!text)
+                    throw new PiboSpeechError("Speech text is required.", "invalid_text");
+                speechProcess = await startProcess({
+                    generation: `speech-session-${randomUUID()}`,
+                    experimentalApi: true,
+                    realtimeConversation: true,
+                    signal: linked.signal,
+                });
+                throwIfAborted(linked.signal);
+                await requireSubscriptionAccount(speechProcess.client, linked.signal);
+                const threadId = threadIdFromStartResponse(await speechProcess.client.request("thread/start", {
+                    cwd: process.cwd(),
+                    ephemeral: true,
+                }, { signal: linked.signal }));
+                const started = deferred();
+                const receivedSdp = deferred();
+                const completed = deferred();
+                let answerSdp;
+                let startupFailure;
+                const sessionId = randomUUID();
+                const session = {
+                    process: speechProcess,
+                    threadId,
+                    text,
+                    unsubscribe: () => { },
+                    completed,
+                    speaking: false,
+                    closed: false,
+                };
+                const fail = (error) => {
+                    if (!session.failure)
+                        session.failure = error;
+                    if (!startupFailure)
+                        startupFailure = error;
+                    started.resolve();
+                    receivedSdp.resolve();
+                    completed.resolve();
+                };
+                unsubscribe = speechProcess.client.subscribeNotifications((notification) => {
+                    const params = isRecord(notification.params) ? notification.params : undefined;
+                    if (!params || params.threadId !== threadId)
+                        return;
+                    try {
+                        if (notification.method === "thread/realtime/started") {
+                            started.resolve();
+                            return;
+                        }
+                        if (notification.method === "thread/realtime/sdp") {
+                            answerSdp = validateAnswerSdp(params.sdp);
+                            receivedSdp.resolve();
+                            return;
+                        }
+                        if (notification.method === "thread/realtime/transcript/done" && params.role === "assistant") {
+                            completed.resolve();
+                            return;
+                        }
+                        if (notification.method === "thread/realtime/error") {
+                            const message = typeof params.message === "string" && params.message.trim()
+                                ? `OpenAI Codex speech generation failed: ${params.message.trim()}`
+                                : "OpenAI Codex speech generation failed.";
+                            fail(new PiboSpeechError(message, "provider_error"));
+                            return;
+                        }
+                        if (notification.method === "thread/realtime/closed") {
+                            fail(new PiboSpeechError("OpenAI Codex speech closed before playback completed.", "provider_error"));
+                        }
+                    }
+                    catch (error) {
+                        fail(error instanceof PiboSpeechError
+                            ? error
+                            : new PiboSpeechError("OpenAI Codex returned an invalid speech session.", "provider_error", { cause: error }));
+                    }
+                });
+                session.unsubscribe = unsubscribe;
+                await speechProcess.client.request("thread/realtime/start", {
+                    threadId,
+                    outputModality: "audio",
+                    version: "v3",
+                    includeStartupContext: false,
+                    prompt: speechPrompt(text),
+                    clientManagedHandoffs: true,
+                    transport: { type: "webrtc", sdp: offerSdp },
+                }, { signal: linked.signal });
+                await Promise.all([
+                    waitForSignal(started.promise, START_TIMEOUT_MS, "OpenAI Codex speech startup timed out.", linked.signal),
+                    waitForSignal(receivedSdp.promise, START_TIMEOUT_MS, "OpenAI Codex did not return a WebRTC answer.", linked.signal),
+                ]);
+                throwIfAborted(linked.signal);
+                if (startupFailure)
+                    throw startupFailure;
+                if (!answerSdp)
+                    throw new PiboSpeechError("OpenAI Codex did not return a WebRTC answer.", "provider_error");
+                sessions.set(sessionId, session);
+                return {
+                    sessionId,
+                    answerSdp,
+                    speak: (speechInput) => speakSession(sessionId, speechInput),
+                    stop: () => closeSession(sessionId),
+                };
+            }
+            catch (error) {
+                unsubscribe?.();
+                await speechProcess?.close().catch(() => { });
+                if (error instanceof PiboSpeechError)
+                    throw error;
+                if (linked.signal.aborted) {
+                    const message = linked.signal.reason instanceof Error && linked.signal.reason.message
+                        ? linked.signal.reason.message
+                        : "OpenAI Codex speech startup was aborted.";
+                    throw new PiboSpeechError(message, "aborted", { cause: error });
+                }
+                throw new PiboSpeechError("OpenAI Codex speech session failed to start.", "provider_error", { cause: error });
+            }
+            finally {
+                linked.dispose();
+                pendingStarts.delete(settlement);
+                settlement.resolve();
+            }
+        },
+        async dispose() {
+            disposePromise ??= (async () => {
+                disposed = true;
+                disposeController.abort(new PiboSpeechError("OpenAI Codex speech is shutting down.", "aborted"));
+                await Promise.allSettled([...pendingStarts].map((pending) => pending.promise));
+                await Promise.allSettled([...sessions.keys()].map((sessionId) => closeSession(sessionId)));
+            })();
+            await disposePromise;
+        },
+    };
+}

package/dist/speech/types.js

@@ -0,0 +1,8 @@
+export class PiboSpeechError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "PiboSpeechError";
+    }
+}

package/dist/subagents/context.js

@@ -27,20 +27,22 @@ export function getDelegatedAgentContextFile(subagents) {
             "```text",
             "pibo_run_start({",
             "  toolName: \"pibo_agents_send_message\",",
-            "  arguments: { name, message, threadKey? },",
+            "  arguments: { name, sessionName, message, threadKey? },",
             "  completionPolicy?: \"tracked\" | \"detached\"",
             "}) -> { runId }",
             "",
             "pibo_run_wait({ runId, timeoutMs? })       # bounded wait only; expiry does not stop the child",
             "pibo_run_status({ runId })                 # compact lifecycle state",
-            "pibo_agents_observe({ requestIds?: [runId], agentIds?, names?, threadKeys?, kinds?, roles?, ... })",
+            "pibo_agents_observe({ requestIds?: [runId], afterSequence?, limit?, includeTools?, toolDetail?, ... })",
             "pibo_run_read({ runId })                   # terminal result, including the complete final agent message",
             "pibo_run_cancel({ runId })                 # explicit request cancellation",
             "pibo_agents_list_agents({})                # available definitions and persistent child instances",
             "pibo_agents_kill({ agentId })              # terminate one persistent child session subtree",
             "```",
             "",
-            "Reuse a stable `threadKey` to continue the same child Pibo Session. A wait timeout is only an orchestrator wake-up. Observe progress and decide whether to continue waiting, steer through a new message after the current turn, cancel the request, or kill the child session.",
+            "Set `sessionName` on every send to a nonblank human-readable child title of at most 40 Unicode code points. Pibo trims surrounding whitespace and rejects missing, blank, non-string, or oversized names before creating a yielded run or child session. Reuse a stable `threadKey` to continue the same child Pibo Session; a new `sessionName` updates its title without changing identity. A wait timeout is only an orchestrator wake-up. Observe defaults to the newest 20 completed assistant messages with streaming deltas, duplicate tool progress events, and tools hidden. Set `includeTools: true` for compact tool call/result summaries, `toolDetail: \"full\"` only for bounded diagnostics, and `limit: 50` when a larger page is necessary. Use `afterSequence` from the prior result for polling.",
+            "",
+            "Observe progress and decide whether to continue waiting, steer through a new message after the current turn, cancel the request, or kill the child session.",
             "",
             "For substantial reports, ask the child to persist a Markdown artifact and include its path in the complete final message.",
         ].join("\n"),

package/dist/subagents/observations.js

@@ -1,7 +1,10 @@
 export const PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES = 4 * 1024;
+export const PIBO_AGENT_OBSERVATION_TOOL_SUMMARY_MAX_BYTES = 768;
 export const PIBO_AGENT_OBSERVATION_DETAILS_MAX_BYTES = 32 * 1024;
-export const PIBO_AGENT_OBSERVATION_DEFAULT_LIMIT = 50;
+export const PIBO_AGENT_OBSERVATION_DEFAULT_LIMIT = 20;
 export const PIBO_AGENT_OBSERVATION_MAX_LIMIT = 200;
+export const PIBO_AGENT_OBSERVATION_DEFAULT_EVENT_TYPES = ["assistant_message"];
+export const PIBO_AGENT_OBSERVATION_DEFAULT_TOOL_EVENT_TYPES = ["tool_call", "tool_execution_finished"];
 export function piboAgentObservationSourceFromEvent(event) {
     const source = {
         eventType: event.type,
@@ -77,15 +80,92 @@ export function piboAgentObservationText(source) {
     }
     return stringifyPiboAgentObservationValue(source.fallbackText);
 }
-export function boundPiboAgentObservationText(value) {
-    if (Buffer.byteLength(value, "utf8") <= PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES)
+function boundPiboAgentObservationTextBytes(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
         return value;
     const suffix = "…";
-    let end = Math.min(value.length, PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES);
-    while (end > 0 && Buffer.byteLength(`${value.slice(0, end)}${suffix}`, "utf8") > PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES)
+    let end = Math.min(value.length, maxBytes);
+    while (end > 0 && Buffer.byteLength(`${value.slice(0, end)}${suffix}`, "utf8") > maxBytes)
         end -= 1;
     return `${value.slice(0, end)}${suffix}`;
 }
+export function boundPiboAgentObservationText(value) {
+    return boundPiboAgentObservationTextBytes(value, PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES);
+}
+function piboAgentToolSummaryValue(value) {
+    if (typeof value === "string") {
+        return boundPiboAgentObservationTextBytes(value, 256);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null)
+        return value;
+    return undefined;
+}
+function piboAgentToolSummarySource(text, details) {
+    if (details && typeof details === "object" && !Array.isArray(details)) {
+        const record = details;
+        if (record.result !== undefined)
+            return record.result;
+        if (record.args !== undefined)
+            return record.args;
+        if (record.partialResult !== undefined)
+            return record.partialResult;
+        if (!text && record.truncated === true && typeof record.preview === "string")
+            return record.preview;
+    }
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function piboAgentToolSummaryPreview(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        try {
+            serialized = String(value);
+        }
+        catch {
+            serialized = "[unserializable tool value]";
+        }
+    }
+    return boundPiboAgentObservationTextBytes(serialized.replace(/\s+/g, " ").trim(), 512);
+}
+export function piboAgentObservationToolSummary(text, isError, details) {
+    const parsed = piboAgentToolSummarySource(text, details);
+    if (parsed === undefined)
+        return isError ? "{\"isError\":true}" : undefined;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return boundPiboAgentObservationTextBytes(String(parsed).replace(/\s+/g, " ").trim(), PIBO_AGENT_OBSERVATION_TOOL_SUMMARY_MAX_BYTES);
+    }
+    const record = parsed;
+    const summary = {};
+    for (const key of ["status", "exitCode", "durationMs", "command", "path", "pattern", "query", "runId"]) {
+        const value = piboAgentToolSummaryValue(record[key]);
+        if (value !== undefined)
+            summary[key] = value;
+    }
+    const output = typeof record.output === "string"
+        ? record.output
+        : typeof record.delta === "string"
+            ? record.delta
+            : undefined;
+    if (output !== undefined) {
+        summary.outputBytes = Buffer.byteLength(output, "utf8");
+        summary.outputPreview = boundPiboAgentObservationTextBytes(output.replace(/\s+/g, " ").trim(), 256);
+    }
+    if (Object.keys(summary).length === 0) {
+        summary.preview = piboAgentToolSummaryPreview(parsed);
+    }
+    if (isError === true)
+        summary.isError = true;
+    return boundPiboAgentObservationTextBytes(JSON.stringify(summary), PIBO_AGENT_OBSERVATION_TOOL_SUMMARY_MAX_BYTES);
+}
 export function stringifyPiboAgentObservationValue(value) {
     if (typeof value === "string")
         return boundPiboAgentObservationText(value);
@@ -127,11 +207,19 @@ export function parsePiboAgentObservationTimestamp(value, label) {
 }
 export function normalizePiboAgentObservationOrder(value) {
     if (value === undefined)
-        return "asc";
+        return "desc";
     if (value !== "asc" && value !== "desc")
         throw new Error(`Agent observation order must be "asc" or "desc".`);
     return value;
 }
+export function normalizePiboAgentObservationToolDetail(value) {
+    if (value === undefined)
+        return "summary";
+    if (value !== "summary" && value !== "full") {
+        throw new Error(`Agent observation toolDetail must be "summary" or "full".`);
+    }
+    return value;
+}
 export function normalizePiboAgentObservationLimit(value) {
     if (value === undefined)
         return PIBO_AGENT_OBSERVATION_DEFAULT_LIMIT;