opal-zero 1.2.3 → 1.2.5

package/README.md

@@ -1,4 +1,7 @@
-# opal-zero
+<div align="center">
+  <img src="logo.svg" width="64" alt="OpalZero" />
+  <h1>opal-zero</h1>
+</div>
 
 TypeScript SDK for [OpalZero](https://github.com/albertobarnabo/opal-zero-engine) — a self-hosted multi-agent intelligence kernel. Give it a plain-English intent; get back structured results streamed in real time.
 
@@ -41,7 +44,7 @@ yarn add opal-zero         # yarn
 pnpm add opal-zero         # pnpm
 ```
 
-React (`useMission`) is a peer dependency — install React separately if you haven't already:
+React (`useOpalZero`) is a peer dependency — install React separately if you haven't already:
 
 ```bash
 npm install react react-dom
@@ -53,13 +56,13 @@ npm install react react-dom
 
 ```tsx
 import { OpalZeroClient } from "opal-zero";
-import { useMission } from "opal-zero/react";
+import { useOpalZero } from "opal-zero/react";
 
 const client = new OpalZeroClient({ baseUrl: "http://localhost:8000" });
 
 export function MissionRunner() {
   const { run, status, cards, activeAgent, error, missionId, refine } =
-    useMission({ client });
+    useOpalZero({ client });
 
   return (
     <div>
@@ -324,10 +327,10 @@ import type {
 
 ---
 
-### `useMission(options)` · `opal-zero/react`
+### `useOpalZero(options)` · `opal-zero/react`
 
 ```ts
-import { useMission } from "opal-zero/react";
+import { useOpalZero } from "opal-zero/react";
 
 const {
   run,          // (intent: string, model?: string) => Promise<void>
@@ -339,7 +342,7 @@ const {
   missionId,    // string | null — pass to refine()
   missionState, // MissionState | null — raw payload for custom renderers
   reset,        // () => void — reset to idle
-} = useMission({
+} = useOpalZero({
   client,       // OpalZeroClient instance
   model?,       // default model string
   onEvent?,     // (event: MissionEvent) => void — tap every event for side effects
@@ -360,7 +363,7 @@ const {
 
 ### `parseBentoCards(state, options?)`
 
-Converts a raw `MissionState` into an ordered `BentoCard[]`. Used internally by `useMission` — export it when building a custom renderer.
+Converts a raw `MissionState` into an ordered `BentoCard[]`. Used internally by `useOpalZero` — export it when building a custom renderer.
 
 ```ts
 import { parseBentoCards } from "opal-zero";
@@ -405,11 +408,11 @@ interface BentoCard {
 
 ### Mission refinement
 
-Refinement runs a second pass on an existing mission with a narrower intent. New results are merged into the original `data_payload` — keys that didn't exist before are added, keys that changed are updated. The `useMission` hook marks changed cards `isRefined: true` so you can highlight them.
+Refinement runs a second pass on an existing mission with a narrower intent. New results are merged into the original `data_payload` — keys that didn't exist before are added, keys that changed are updated. The `useOpalZero` hook marks changed cards `isRefined: true` so you can highlight them.
 
 ```tsx
 // After a mission completes:
-const { missionId, refine } = useMission({ client });
+const { missionId, refine } = useOpalZero({ client });
 
 // First run
 await run("Compare the top 3 EVs under $60k");
@@ -465,7 +468,7 @@ if (!tavily) {
 Use `onEvent` to tap the SSE stream for cross-cutting concerns without coupling them to component state:
 
 ```tsx
-useMission({
+useOpalZero({
   client,
   onEvent(event) {
     analytics.track("opalzero_event", { type: event.type });
@@ -512,8 +515,8 @@ import type {
 
   // Bento / React hook
   BentoCard,
-  UseMissionOptions,
-  UseMissionReturn,
+  UseOpalZeroOptions,
+  UseOpalZeroReturn,
 } from "opal-zero";
 ```
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { OpalZeroClient } from "./client";
 export { parseBentoCards } from "./parseBentoCards";
-export type { OpalZeroClientConfig, MissionEvent, TaskStartedEvent, TaskCompletedEvent, TaskFailedEvent, GovernorExpandEvent, MissionCompleteEvent, MissionFailedEvent, MissionPausedEvent, AwaitingFeedbackEvent, UnknownEvent, MissionSnapshot, MissionSummary, MissionState, Task, MissionStatus, UploadResult, ConfigStatus, BentoCard, UseMissionOptions, UseMissionReturn, } from "./types";
+export type { OpalZeroClientConfig, MissionEvent, TaskStartedEvent, TaskCompletedEvent, TaskFailedEvent, GovernorExpandEvent, MissionCompleteEvent, MissionFailedEvent, MissionPausedEvent, AwaitingFeedbackEvent, UnknownEvent, MissionSnapshot, MissionSummary, MissionState, Task, MissionStatus, UploadResult, ConfigStatus, BentoCard, UseOpalZeroOptions, UseOpalZeroReturn, } from "./types";

package/dist/react/index.d.ts

@@ -1 +1 @@
-export { useMission } from './useMission';
+export { useOpalZero } from './useOpalZero';

package/dist/react/index.js

@@ -1 +1 @@
-export { useMission } from './useMission';
+export { useOpalZero } from './useOpalZero';

package/dist/react/useOpalZero.d.ts

@@ -0,0 +1,2 @@
+import type { UseOpalZeroOptions, UseOpalZeroReturn } from '../types';
+export declare function useOpalZero({ client, model: defaultModel, onEvent }: UseOpalZeroOptions): UseOpalZeroReturn;

package/dist/react/useOpalZero.js

@@ -0,0 +1,101 @@
+import { useState, useRef, useCallback } from 'react';
+import { parseBentoCards } from '../parseBentoCards';
+export function useOpalZero({ client, model: defaultModel, onEvent }) {
+    const [status, setStatus] = useState('idle');
+    const [cards, setCards] = useState([]);
+    const [activeAgent, setActiveAgent] = useState(null);
+    const [error, setError] = useState(null);
+    const [missionId, setMissionId] = useState(null);
+    const [missionState, setMissionState] = useState(null);
+    const refinedKeysRef = useRef(new Set());
+    function reset() {
+        setStatus('idle');
+        setCards([]);
+        setActiveAgent(null);
+        setError(null);
+        setMissionId(null);
+        setMissionState(null);
+        refinedKeysRef.current = new Set();
+    }
+    async function drainStream(stream, isRefinement, previousKeys) {
+        setStatus('running');
+        setActiveAgent(null);
+        setError(null);
+        try {
+            for await (const event of stream) {
+                onEvent?.(event);
+                switch (event.type) {
+                    case 'task_started': {
+                        const e = event;
+                        setActiveAgent({ role: e.role, intent: e.intent });
+                        break;
+                    }
+                    case 'task_completed':
+                    case 'task_failed':
+                        setActiveAgent(null);
+                        break;
+                    case 'mission_complete': {
+                        const e = event;
+                        setMissionId(e.mission_id);
+                        const state = e.mission_state ?? null;
+                        setMissionState(state);
+                        if (state) {
+                            const ms = state;
+                            if (isRefinement) {
+                                const newKeys = new Set(Object.keys(ms.data_payload ?? {}));
+                                previousKeys.forEach(k => newKeys.delete(k));
+                                newKeys.forEach(k => refinedKeysRef.current.add(k));
+                            }
+                            const parsed = parseBentoCards(ms, { refinedKeys: refinedKeysRef.current });
+                            if (isRefinement) {
+                                setCards(prev => {
+                                    const merged = [...prev];
+                                    for (const card of parsed) {
+                                        const idx = merged.findIndex(c => c.key === card.key);
+                                        if (idx >= 0)
+                                            merged[idx] = card;
+                                        else
+                                            merged.push(card);
+                                    }
+                                    return merged;
+                                });
+                            }
+                            else {
+                                setCards(parsed);
+                            }
+                        }
+                        setStatus('complete');
+                        break;
+                    }
+                    case 'mission_failed': {
+                        const e = event;
+                        setError(e.error);
+                        setStatus('failed');
+                        break;
+                    }
+                }
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            setError(msg);
+            setStatus('failed');
+        }
+    }
+    const run = useCallback(async (intent, model) => {
+        reset();
+        refinedKeysRef.current = new Set();
+        const stream = client.execute(intent, model ?? defaultModel);
+        await drainStream(stream, false, new Set());
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, defaultModel]);
+    const refine = useCallback(async (id, intent, model) => {
+        if (status === 'running')
+            return;
+        const previousKeys = new Set(Object.keys(missionState?.data_payload ?? {}));
+        const stream = client.missions.refine(id, intent, model ?? defaultModel);
+        await drainStream(stream, true, previousKeys);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, defaultModel, status, missionState]);
+    return { run, refine, status, cards, activeAgent, error, missionId, missionState, reset };
+}

package/dist/types.d.ts

@@ -112,14 +112,14 @@ export interface BentoCard {
     /** True if this card was added/updated by a refinement round */
     isRefined?: boolean;
 }
-export interface UseMissionOptions {
+export interface UseOpalZeroOptions {
     client: OpalZeroClient;
     /** Default model to use. Can be overridden per-call in run(). */
     model?: string;
     /** Called for every SSE event before the hook updates its own state. Use this for side effects (trace logs, banners, etc.) that the hook doesn't need to manage. */
     onEvent?: (event: MissionEvent) => void;
 }
-export interface UseMissionReturn {
+export interface UseOpalZeroReturn {
     /** Execute a new mission. Clears previous state before starting. */
     run: (intent: string, model?: string) => Promise<void>;
     /** Refine an existing mission without clearing the card grid. */

package/logo.svg

@@ -0,0 +1,8 @@
+<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+  <path fill="#0DD4C6" d="M 59.96,50.87 L 85.86,53.14 A 36,36,0,0,1,70.65,79.49 L 55.74,58.19 A 10,10,0,0,0,59.96,50.87 Z"/>
+  <path fill="#5B8FEE" d="M 54.23,59.06 L 65.21,82.63 A 36,36,0,0,1,34.79,82.63 L 45.77,59.06 A 10,10,0,0,0,54.23,59.06 Z"/>
+  <path fill="#9B68F0" d="M 44.26,58.19 L 29.35,79.49 A 36,36,0,0,1,14.14,53.14 L 40.04,50.87 A 10,10,0,0,0,44.26,58.19 Z"/>
+  <path fill="#0DD4C6" d="M 40.04,49.13 L 14.14,46.86 A 36,36,0,0,1,29.35,20.51 L 44.26,41.81 A 10,10,0,0,0,40.04,49.13 Z"/>
+  <path fill="#5B8FEE" d="M 45.77,40.94 L 34.79,17.37 A 36,36,0,0,1,65.21,17.37 L 54.23,40.94 A 10,10,0,0,0,45.77,40.94 Z"/>
+  <path fill="#9B68F0" d="M 55.74,41.81 L 70.65,20.51 A 36,36,0,0,1,85.86,46.86 L 59.96,49.13 A 10,10,0,0,0,55.74,41.81 Z"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opal-zero",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "TypeScript client SDK for the OpalZero Intelligence Kernel",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -20,7 +20,7 @@ export type {
   UploadResult,
   ConfigStatus,
   BentoCard,
-  UseMissionOptions,
-  UseMissionReturn,
+  UseOpalZeroOptions,
+  UseOpalZeroReturn,
 } from "./types";
 // Note: useMission is NOT exported from the main entry — import from 'opal-zero/react'

package/src/react/index.ts

@@ -1 +1 @@
-export { useMission } from './useMission';
+export { useOpalZero } from './useOpalZero';

package/src/react/{useMission.ts → useOpalZero.ts}

@@ -3,8 +3,8 @@ import type {
   MissionStatus,
   MissionState,
   BentoCard,
-  UseMissionOptions,
-  UseMissionReturn,
+  UseOpalZeroOptions,
+  UseOpalZeroReturn,
   MissionEvent,
   TaskStartedEvent,
   MissionCompleteEvent,
@@ -12,7 +12,7 @@ import type {
 } from '../types';
 import { parseBentoCards } from '../parseBentoCards';
 
-export function useMission({ client, model: defaultModel, onEvent }: UseMissionOptions): UseMissionReturn {
+export function useOpalZero({ client, model: defaultModel, onEvent }: UseOpalZeroOptions): UseOpalZeroReturn {
   const [status,       setStatus]       = useState<MissionStatus>('idle');
   const [cards,        setCards]        = useState<BentoCard[]>([]);
   const [activeAgent,  setActiveAgent]  = useState<{ role: string; intent: string } | null>(null);

package/src/types.ts

@@ -156,7 +156,7 @@ export interface BentoCard {
 
 // ── useMission ────────────────────────────────────────────────────────────────
 
-export interface UseMissionOptions {
+export interface UseOpalZeroOptions {
   client: OpalZeroClient;
   /** Default model to use. Can be overridden per-call in run(). */
   model?: string;
@@ -164,7 +164,7 @@ export interface UseMissionOptions {
   onEvent?: (event: MissionEvent) => void;
 }
 
-export interface UseMissionReturn {
+export interface UseOpalZeroReturn {
   /** Execute a new mission. Clears previous state before starting. */
   run: (intent: string, model?: string) => Promise<void>;
   /** Refine an existing mission without clearing the card grid. */