@zakstam/codex-local-component 0.8.0 → 0.9.0

package/dist/react/useCodexThreads.js

@@ -0,0 +1,65 @@
+"use client";
+import { useQuery } from "convex/react";
+import { useCallback, useMemo, useState } from "react";
+export function useCodexThreads(config) {
+    const listQueryArgs = config.list.args === "skip"
+        ? ["skip"]
+        : [config.list.args];
+    const listArgs = listQueryArgs;
+    const listed = useQuery(config.list.query, ...listArgs);
+    const [selectedThreadId, setSelectedThreadId] = useState(config.initialSelectedThreadId ?? null);
+    const [busyAction, setBusyAction] = useState(null);
+    const [error, setError] = useState(null);
+    const run = useCallback(async (action, fn) => {
+        setBusyAction(action);
+        setError(null);
+        try {
+            return await fn();
+        }
+        catch (nextError) {
+            const message = nextError instanceof Error ? nextError.message : String(nextError);
+            setError(message);
+            throw nextError;
+        }
+        finally {
+            setBusyAction((current) => (current === action ? null : current));
+        }
+    }, []);
+    const create = useCallback(async (args) => {
+        const createThread = config.controls?.createThread;
+        if (!createThread) {
+            return null;
+        }
+        return run("create", () => createThread(args));
+    }, [config.controls, run]);
+    const resolve = useCallback(async (localThreadId) => {
+        const resolveThread = config.controls?.resolveThread;
+        if (!resolveThread) {
+            return null;
+        }
+        const result = await run("resolve", () => resolveThread({ localThreadId }));
+        setSelectedThreadId(localThreadId);
+        return result;
+    }, [config.controls, run]);
+    const resume = useCallback(async (threadId) => {
+        const resumeThread = config.controls?.resumeThread;
+        if (!resumeThread) {
+            return null;
+        }
+        const result = await run("resume", () => resumeThread({ threadId }));
+        setSelectedThreadId(threadId);
+        return result;
+    }, [config.controls, run]);
+    return useMemo(() => ({
+        threads: listed,
+        selectedThreadId,
+        setSelectedThreadId,
+        busyAction,
+        isBusy: busyAction !== null,
+        error,
+        create,
+        resolve,
+        resume,
+    }), [busyAction, create, error, listed, resolve, resume, selectedThreadId]);
+}
+//# sourceMappingURL=useCodexThreads.js.map

package/dist/react/useCodexThreads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCodexThreads.js","sourceRoot":"","sources":["../../src/react/useCodexThreads.ts"],"names":[],"mappings":"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"}

package/dist/react-integration/index.d.ts

@@ -0,0 +1,101 @@
+import type { CodexDynamicToolHandler, CodexDynamicToolsQuery, CodexDynamicToolsRespond } from "../react/useCodexDynamicTools.js";
+import type { CodexMessagesQuery } from "../react/types.js";
+import type { CodexThreadActivityQuery } from "../react/useCodexThreadActivity.js";
+import type { CodexThreadActivity, CodexThreadActivityThreadState } from "../react/threadActivity.js";
+import type { CodexBranchActivityOptions } from "../react/branchActivity.js";
+import type { CodexConversationApprovalDecision, CodexConversationApprovalItem } from "../react/useCodexConversationController.js";
+export type CodexThreadScopeArgs<Actor extends Record<string, unknown>> = {
+    actor: Actor;
+    threadId: string;
+};
+export type CodexThreadTurnScopeArgs<Actor extends Record<string, unknown>> = CodexThreadScopeArgs<Actor> & {
+    turnId: string;
+};
+export type CodexReactHostHooks<Actor extends Record<string, unknown>> = {
+    listThreadMessagesForHooks: CodexMessagesQuery<{
+        actor: Actor;
+    }>;
+    threadSnapshotSafe: CodexThreadActivityQuery<{
+        actor: Actor;
+    }, CodexThreadActivityThreadState>;
+    listPendingServerRequestsForHooks?: CodexDynamicToolsQuery<{
+        actor: Actor;
+        threadId: string;
+        limit?: number;
+    }>;
+};
+export type CodexReactConversationControllerOptions = {
+    initialNumItems: number;
+    stream?: boolean;
+    branchOptions?: CodexBranchActivityOptions;
+    composer?: {
+        initialValue?: string;
+        onSend: (text: string) => Promise<unknown>;
+    };
+    approvals?: {
+        onResolve: (approval: CodexConversationApprovalItem, decision: CodexConversationApprovalDecision) => Promise<unknown>;
+    };
+    dynamicTools?: {
+        respond?: CodexDynamicToolsRespond;
+        handlers?: Record<string, CodexDynamicToolHandler>;
+        autoHandle?: boolean;
+        enabled?: boolean;
+        limit?: number;
+    };
+    interrupt?: {
+        onInterrupt: (activity: CodexThreadActivity) => Promise<unknown>;
+    };
+};
+export declare function codexThreadScopeArgs<Actor extends Record<string, unknown>>(actor: Actor, threadId: string | null | undefined): CodexThreadScopeArgs<Actor> | "skip";
+export declare function codexThreadTurnScopeArgs<Actor extends Record<string, unknown>>(actor: Actor, threadId: string | null | undefined, turnId: string | null | undefined): CodexThreadTurnScopeArgs<Actor> | "skip";
+export declare function createCodexReactConvexAdapter<Actor extends Record<string, unknown>>(config: {
+    actor: Actor;
+    hooks: CodexReactHostHooks<Actor>;
+}): {
+    threadArgs: (threadId: string | null | undefined) => "skip" | CodexThreadScopeArgs<Actor>;
+    threadTurnArgs: (threadId: string | null | undefined, turnId: string | null | undefined) => "skip" | CodexThreadTurnScopeArgs<Actor>;
+    useThreadMessages: (threadId: string | null | undefined, options: {
+        initialNumItems: number;
+        stream?: boolean;
+    }) => import("convex/react").UsePaginatedQueryResult<import("../index.js").CodexUIMessage>;
+    useThreadActivity: (threadId: string | null | undefined) => CodexThreadActivity;
+    useBranchActivity: (threadId: string | null | undefined, options?: CodexBranchActivityOptions) => CodexThreadActivity;
+    useIngestHealth: (threadId: string | null | undefined) => import("../react/ingestHealth.js").CodexIngestHealth;
+    useConversationController: (threadId: string | null | undefined, options: CodexReactConversationControllerOptions) => {
+        messages: import("convex/react").UsePaginatedQueryResult<import("../index.js").CodexUIMessage>;
+        activity: CodexThreadActivity;
+        ingestHealth: import("../react/ingestHealth.js").CodexIngestHealth;
+        branchActivity: CodexThreadActivity;
+        approvals: {
+            pending: CodexConversationApprovalItem[];
+            pendingCount: number;
+            approvingItemId: string | null;
+            error: string | null;
+            canResolve: boolean;
+            resolve: (approval: CodexConversationApprovalItem, decision: CodexConversationApprovalDecision) => Promise<void>;
+            accept: (approval: CodexConversationApprovalItem) => Promise<void>;
+            decline: (approval: CodexConversationApprovalItem) => Promise<void>;
+        };
+        dynamicTools: {
+            requests: never[] | import("../react/dynamicTools.js").CodexDynamicToolServerRequest[];
+            calls: import("../react/dynamicTools.js").CodexDynamicToolCall[];
+            pendingCount: number;
+            runningRequestIds: string[];
+            lastError: string | null;
+            runCall: (call: import("../react/dynamicTools.js").CodexDynamicToolCall) => Promise<boolean>;
+            respond: (call: import("../react/dynamicTools.js").CodexDynamicToolCall, result: import("../react/dynamicTools.js").CodexDynamicToolResponse) => Promise<void>;
+        };
+        composer: {
+            value: string;
+            setValue: import("react").Dispatch<import("react").SetStateAction<string>>;
+            error: string | null;
+            isSending: boolean;
+            canSend: boolean;
+            send: (overrideText?: string) => Promise<void>;
+        };
+        interrupt: () => Promise<void>;
+        canInterrupt: boolean;
+        isInterrupting: boolean;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/react-integration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react-integration/index.ts"],"names":[],"mappings":"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"}

package/dist/react-integration/index.js

@@ -0,0 +1,62 @@
+"use client";
+import { useCodexMessages } from "../react/useCodexMessages.js";
+import { useCodexBranchActivity } from "../react/useCodexBranchActivity.js";
+import { useCodexConversationController } from "../react/useCodexConversationController.js";
+import { useCodexIngestHealth } from "../react/useCodexIngestHealth.js";
+import { useCodexThreadActivity } from "../react/useCodexThreadActivity.js";
+export function codexThreadScopeArgs(actor, threadId) {
+    if (!threadId) {
+        return "skip";
+    }
+    return { actor, threadId };
+}
+export function codexThreadTurnScopeArgs(actor, threadId, turnId) {
+    if (!threadId || !turnId) {
+        return "skip";
+    }
+    return { actor, threadId, turnId };
+}
+export function createCodexReactConvexAdapter(config) {
+    return {
+        threadArgs: (threadId) => codexThreadScopeArgs(config.actor, threadId),
+        threadTurnArgs: (threadId, turnId) => codexThreadTurnScopeArgs(config.actor, threadId, turnId),
+        useThreadMessages: (threadId, options) => {
+            const args = codexThreadScopeArgs(config.actor, threadId);
+            return useCodexMessages(config.hooks.listThreadMessagesForHooks, args, options);
+        },
+        useThreadActivity: (threadId) => useCodexThreadActivity(config.hooks.threadSnapshotSafe, codexThreadScopeArgs(config.actor, threadId)),
+        useBranchActivity: (threadId, options) => useCodexBranchActivity(config.hooks.threadSnapshotSafe, codexThreadScopeArgs(config.actor, threadId), options),
+        useIngestHealth: (threadId) => useCodexIngestHealth(config.hooks.threadSnapshotSafe, codexThreadScopeArgs(config.actor, threadId)),
+        useConversationController: (threadId, options) => useCodexConversationController({
+            messages: {
+                query: config.hooks.listThreadMessagesForHooks,
+                args: codexThreadScopeArgs(config.actor, threadId),
+                initialNumItems: options.initialNumItems,
+                ...(options.stream !== undefined ? { stream: options.stream } : {}),
+            },
+            threadState: {
+                query: config.hooks.threadSnapshotSafe,
+                args: codexThreadScopeArgs(config.actor, threadId),
+                ...(options.branchOptions !== undefined ? { branchOptions: options.branchOptions } : {}),
+            },
+            ...(options.approvals !== undefined ? { approvals: options.approvals } : {}),
+            ...(options.dynamicTools !== undefined && config.hooks.listPendingServerRequestsForHooks !== undefined
+                ? {
+                    dynamicTools: {
+                        query: config.hooks.listPendingServerRequestsForHooks,
+                        args: threadId
+                            ? { actor: config.actor, threadId, ...(options.dynamicTools.limit !== undefined ? { limit: options.dynamicTools.limit } : {}) }
+                            : "skip",
+                        ...(options.dynamicTools.respond !== undefined ? { respond: options.dynamicTools.respond } : {}),
+                        ...(options.dynamicTools.handlers !== undefined ? { handlers: options.dynamicTools.handlers } : {}),
+                        ...(options.dynamicTools.autoHandle !== undefined ? { autoHandle: options.dynamicTools.autoHandle } : {}),
+                        ...(options.dynamicTools.enabled !== undefined ? { enabled: options.dynamicTools.enabled } : {}),
+                    },
+                }
+                : {}),
+            ...(options.composer !== undefined ? { composer: options.composer } : {}),
+            ...(options.interrupt !== undefined ? { interrupt: options.interrupt } : {}),
+        }),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/react-integration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react-integration/index.ts"],"names":[],"mappings":"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"}

package/docs/CLIENT_AND_REACT_HOOKS.md

@@ -1,6 +1,7 @@
 # Client Helpers and React Hooks
 
 Canonical default: runtime-owned host integration (`dispatchManaged: false`).
+Official recommendation: prefer React hooks over app-defined state composition.
 
 This doc defines client and hook contracts for the canonical path in `../LLMS.md`.
 
@@ -15,6 +16,7 @@ All hook/query/mutation args use `actor: { userId?: string }`.
 
 - `@zakstam/codex-local-component/client`
 - `@zakstam/codex-local-component/react`
+- `@zakstam/codex-local-component/react-integration`
 
 Host Convex wrappers should come from generated runtime-owned host surfaces (`convex/chat.generated.ts`) plus app-owned extensions (`convex/chat.extensions.ts`).
 
@@ -46,6 +48,14 @@ Common helpers used by consumers:
 - `useCodexStreamingReasoning`
 - `useCodexTurn`
 - `useCodexThreadState`
+- `useCodexThreadActivity`
+- `useCodexIngestHealth`
+- `useCodexBranchActivity`
+- `useCodexConversationController`
+- `useCodexDynamicTools`
+- `useCodexRuntimeBridge`
+- `useCodexAccountAuth`
+- `useCodexThreads`
 - `useCodexApprovals`
 - `useCodexInterruptTurn`
 - `useCodexAutoResume`
@@ -75,10 +85,63 @@ Return shape:
 
 - `useCodexMessages` -> `chat.listThreadMessagesForHooks`
 - `useCodexTurn` -> `chat.listTurnMessagesForHooks`
+- `useCodexThreadActivity` -> `chat.threadSnapshotSafe`
+- `useCodexIngestHealth` -> `chat.threadSnapshotSafe`
+- `useCodexBranchActivity` -> `chat.threadSnapshotSafe`
 - `useCodexApprovals` -> `chat.listPendingApprovalsForHooks` + `chat.respondApprovalForHooks`
+- `useCodexDynamicTools` -> `chat.listPendingServerRequestsForHooks` + host runtime `respondDynamicToolCall(...)`
+- `useCodexThreads` -> app thread-list query + thread lifecycle mutations
 - `useCodexInterruptTurn` -> `chat.interruptTurnForHooks`
 - `useCodexComposer` -> `chat.enqueueTurnDispatch`
 
+## Reference React Integration Adapter
+
+Use `@zakstam/codex-local-component/react-integration` to centralize endpoint mapping and actor/thread arg shaping.
+
+```tsx
+import { createCodexReactConvexAdapter } from "@zakstam/codex-local-component/react-integration";
+import { api } from "../convex/_generated/api";
+
+const actor = { userId: "demo-user" };
+const codex = createCodexReactConvexAdapter({
+  actor,
+  hooks: api.chat,
+});
+
+const messages = codex.useThreadMessages(threadId, { initialNumItems: 30, stream: true });
+const activity = codex.useThreadActivity(threadId);
+const ingestHealth = codex.useIngestHealth(threadId);
+const branchActivity = codex.useBranchActivity(threadId, { turnId: activeTurnId });
+const conversation = codex.useConversationController(threadId, {
+  initialNumItems: 30,
+  stream: true,
+  approvals: {
+    onResolve: async (approval, decision) =>
+      respondApproval({ actor, threadId: approval.threadId, turnId: approval.turnId, itemId: approval.itemId, decision }),
+  },
+  composer: { onSend: async (text) => sendUserTurn(text) },
+  interrupt: { onInterrupt: async () => interruptTurn() },
+});
+```
+
+## Blessed Example App
+
+The blessed production wiring reference is:
+
+- `apps/examples/tauri-app`
+
+It demonstrates generated host wrappers plus React-first hook composition (`useCodexConversationController` and thread snapshot hooks).
+
+## Strict State Authority Table
+
+| UI Signal | Source of truth | Ignore for this signal | Why |
+| --- | --- | --- | --- |
+| Thread activity badge (`idle/streaming/awaiting_approval/failed/interrupted`) | `useCodexThreadActivity(chat.threadSnapshotSafe, ...)` | Raw `messages`, `dispatches`, `turns`, `streamStats` stitching in app code | Prevents precedence bugs and "stuck streaming" regressions. |
+| Show "needs approval" UI | `activity.phase === "awaiting_approval"` (or `pendingApprovals` count if not using activity hook) | Dispatch status alone | Dispatch lifecycle does not encode approval waits. |
+| Render assistant text deltas | `useCodexMessages(..., { stream: true })` | `dispatches` and `turns` | Dispatch/turn state tracks orchestration, not message text continuity. |
+| Enable cancel/interruption affordance | `activity.phase === "streaming"` with `activity.activeTurnId` | `threadStatus`, `dispatches` alone | Active turn identity should come from normalized activity. |
+| Show terminal failure/interruption banner | `activity.phase === "failed"` / `"interrupted"` | Any single terminal row without recency precedence | Multiple terminal signals can coexist across turns. Use canonical merge logic. |
+
 ## Minimal Usage
 
 ```tsx

package/docs/HOST_PRESET_MATRIX.md

@@ -19,6 +19,7 @@ All focused preset builders include:
 - `getTurnDispatchState`
 - `getDispatchObservability`
 - `threadSnapshot`
+- `threadSnapshotSafe`
 - `persistenceStats`
 - `durableHistoryStats`
 - `listThreadMessagesForHooks`

package/docs/OPERATIONS_AND_ERRORS.md

@@ -30,6 +30,14 @@ This is an operations/runbook companion to `../LLMS.md`.
 
 Use `sync.ingestSafe` in host wrappers so recoverable conditions return structured status instead of hard-failing the loop.
 
+Public classifier utilities are available for consistent host/app fallback handling:
+
+- `parseErrorCode(error)`
+- `isThreadMissing(error)`
+- `isThreadForbidden(error)`
+- `isSessionForbidden(error)`
+- `isRecoverableIngestError(errorOrSafeEntry)`
+
 ## Terminal Status Parsing Errors
 
 - `E_TERMINAL_PAYLOAD_PARSE_FAILED`: could not decode terminal event payload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakstam/codex-local-component",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,6 +17,14 @@
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
     },
+    "./react-integration": {
+      "types": "./dist/react-integration/index.d.ts",
+      "import": "./dist/react-integration/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
     "./convex.config": {
       "types": "./dist/component/convex.config.d.ts",
       "import": "./dist/component/convex.config.js"