@pinixai/core 0.7.1 → 0.8.0

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@pinixai/core",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Clip framework for Pinix \u2014 define once, run as CLI / MCP / Pinix bridge",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./web": "./src/web.ts"
+  },
   "files": [
     "src"
   ],

package/src/http.ts

@@ -1,5 +1,6 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { getClipName, type Clip } from "./clip";
+import type { Stream } from "./handler";
 import { zodToManifestType } from "./manifest";
 
 const CORS_HEADERS = {
@@ -135,6 +136,14 @@ function listCommands(clip: Clip): Response {
   return jsonResponse({ commands });
 }
 
+function wantsSSE(request: Request): boolean {
+  return (request.headers.get("accept") ?? "").includes("text/event-stream");
+}
+
+function sseEvent(data: unknown): string {
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
 async function handleCommandRequest(clip: Clip, commandName: string, request: Request): Promise<Response> {
   const commandHandler = clip.getCommands().get(commandName);
 
@@ -158,20 +167,59 @@ async function handleCommandRequest(clip: Clip, commandName: string, request: Re
     return errorResponse(toErrorMessage(error), 400);
   }
 
-  let output: unknown;
+  if (!wantsSSE(request)) {
+    let output: unknown;
 
-  try {
-    output = await commandHandler.fn(parsedInput as never);
-  } catch (error) {
-    return errorResponse(toErrorMessage(error), 500);
-  }
+    try {
+      output = await commandHandler.fn(parsedInput as never);
+    } catch (error) {
+      return errorResponse(toErrorMessage(error), 500);
+    }
 
-  try {
-    const parsedOutput = await commandHandler.output.parseAsync(output);
-    return jsonResponse(parsedOutput);
-  } catch (error) {
-    return errorResponse(toErrorMessage(error), 500);
+    try {
+      const parsedOutput = await commandHandler.output.parseAsync(output);
+      return jsonResponse(parsedOutput);
+    } catch (error) {
+      return errorResponse(toErrorMessage(error), 500);
+    }
   }
+
+  // SSE streaming: pass a Stream to the handler, emit chunks as SSE events
+  const { readable, writable } = new TransformStream();
+  const writer = writable.getWriter();
+  const encoder = new TextEncoder();
+
+  const stream: Stream = {
+    chunk(data: unknown) {
+      const raw = typeof data === "string" ? data : JSON.stringify(data);
+      // Each JSONL line becomes a separate SSE event (matches pinixd behavior)
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed) {
+          writer.write(encoder.encode(`data: ${trimmed}\n\n`)).catch(() => {});
+        }
+      }
+    },
+  };
+
+  commandHandler.fn(parsedInput as never, stream).then(
+    () => {
+      writer.write(encoder.encode("event: done\ndata: {}\n\n")).catch(() => {});
+      writer.close().catch(() => {});
+    },
+    (error) => {
+      writer.write(encoder.encode(sseEvent({ error: toErrorMessage(error) }))).catch(() => {});
+      writer.close().catch(() => {});
+    },
+  );
+
+  return new Response(readable, {
+    headers: createHeaders({
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+    }),
+  });
 }
 
 async function handleStaticRequest(pathname: string): Promise<Response> {

package/src/web.ts

@@ -0,0 +1,339 @@
+/**
+ * @pinixai/core/web — Browser client for Clip Web UIs.
+ *
+ * Clip developers use invoke() and invokeStream() without caring
+ * about the underlying transport:
+ *
+ *   import { invoke, invokeStream } from "@pinixai/core/web"
+ *
+ *   const config = await invoke<Config>("config", { args: ["get"] })
+ *
+ *   const cancel = invokeStream("send", { args: ["-p", "hello"] },
+ *     (event) => console.log(event),
+ *     (exitCode) => console.log("done", exitCode),
+ *   )
+ *
+ * Transport is auto-detected:
+ *   - Standalone (--web): HTTP POST /api/<command> + SSE streaming
+ *   - Hub (pinixd / Cloud Hub): Connect-RPC Invoke RPC
+ */
+
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-web";
+import { HubService } from "./gen/hub_pb";
+
+// ── Public types ──
+
+export interface InvokeOptions {
+  args?: string[];
+  stdin?: string;
+}
+
+export type StreamEvent =
+  | { type: "info"; message: string }
+  | { type: "text"; content: string }
+  | { type: "thinking"; content: string }
+  | { type: "tool_call"; name: string; arguments: string }
+  | { type: "tool_result"; content: string }
+  | { type: "inject"; content: string }
+  | { type: "result"; data: unknown }
+  | { type: "done" };
+
+// ── Environment detection ──
+
+interface StandaloneEnv {
+  mode: "standalone";
+}
+
+interface HubEnv {
+  mode: "hub";
+  clipName: string;
+  hubUrl: string;
+}
+
+type Env = StandaloneEnv | HubEnv;
+
+const STREAM_EVENT_TYPES = new Set([
+  "info", "text", "thinking", "tool_call", "tool_result", "inject", "result", "done",
+]);
+
+function isStreamEvent(value: unknown): value is StreamEvent {
+  if (!value || typeof value !== "object") return false;
+  const type = (value as { type?: unknown }).type;
+  return typeof type === "string" && STREAM_EVENT_TYPES.has(type);
+}
+
+/**
+ * Detect whether we're running standalone (--web) or inside a Hub (pinixd / Cloud Hub).
+ *
+ * Hub mode: page URL matches /clips/<clipName>/...
+ * Standalone: everything else (typically root /)
+ */
+function detectEnv(): Env {
+  const pathname = globalThis.location?.pathname ?? "/";
+  const match = pathname.match(/^\/clips\/([^/]+)\//);
+  if (match) {
+    return {
+      mode: "hub",
+      clipName: match[1],
+      hubUrl: globalThis.location.origin,
+    };
+  }
+  return { mode: "standalone" };
+}
+
+// ── Standalone transport (HTTP + SSE) ──
+
+async function httpInvoke(command: string, opts: InvokeOptions): Promise<unknown> {
+  const response = await fetch(`api/${command}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(opts),
+  });
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    const parsed = text ? tryParse(text) : null;
+    const msg = extractError(parsed, `Command "${command}" failed (${response.status})`);
+    throw new Error(msg);
+  }
+
+  return text ? JSON.parse(text) : null;
+}
+
+function httpInvokeStream(
+  command: string,
+  opts: InvokeOptions,
+  onEvent: (event: StreamEvent) => void,
+  onDone: (exitCode: number) => void,
+): () => void {
+  const controller = new AbortController();
+  let cancelled = false;
+
+  (async () => {
+    let response: Response;
+    try {
+      response = await fetch(`api/${command}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "text/event-stream",
+        },
+        body: JSON.stringify(opts),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (!cancelled) onDone(-1);
+      return;
+    }
+
+    if (!response.ok || !response.body) {
+      if (!cancelled) onDone(1);
+      return;
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+
+        const parts = buffer.split("\n\n");
+        buffer = parts.pop() ?? "";
+
+        for (const part of parts) {
+          if (!part.trim()) continue;
+
+          if (part.includes("event: done")) {
+            onEvent({ type: "done" });
+            continue;
+          }
+
+          const dataMatch = part.match(/^data:\s*(.+)$/m);
+          if (!dataMatch) continue;
+
+          try {
+            const chunk = JSON.parse(dataMatch[1]);
+            if (isStreamEvent(chunk)) {
+              onEvent(chunk);
+            } else if (chunk?.error) {
+              onEvent({ type: "info", message: `Error: ${chunk.error}` });
+            }
+          } catch {
+            // skip unparseable
+          }
+        }
+      }
+
+      if (!cancelled) onDone(0);
+    } catch (error) {
+      if (!cancelled) onDone(-1);
+    }
+  })();
+
+  return () => {
+    cancelled = true;
+    controller.abort();
+  };
+}
+
+// ── Hub transport (Connect-RPC) ──
+
+function createHubClient(hubUrl: string) {
+  const transport = createConnectTransport({ baseUrl: hubUrl });
+  return createClient(HubService, transport);
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+async function rpcInvoke(env: HubEnv, command: string, opts: InvokeOptions): Promise<unknown> {
+  const client = createHubClient(env.hubUrl);
+  const input = encoder.encode(JSON.stringify(opts));
+
+  let outputBytes = new Uint8Array(0);
+
+  for await (const response of client.invoke({
+    clipName: env.clipName,
+    command,
+    input,
+    clipToken: "",
+  })) {
+    if (response.error) {
+      throw new Error(response.error.message || response.error.code || "Hub invoke error");
+    }
+    if (response.output.length > 0) {
+      const merged = new Uint8Array(outputBytes.length + response.output.length);
+      merged.set(outputBytes);
+      merged.set(response.output, outputBytes.length);
+      outputBytes = merged;
+    }
+  }
+
+  if (outputBytes.length === 0) return undefined;
+  return JSON.parse(decoder.decode(outputBytes));
+}
+
+function rpcInvokeStream(
+  env: HubEnv,
+  command: string,
+  opts: InvokeOptions,
+  onEvent: (event: StreamEvent) => void,
+  onDone: (exitCode: number) => void,
+): () => void {
+  const controller = new AbortController();
+  let cancelled = false;
+
+  (async () => {
+    const client = createHubClient(env.hubUrl);
+    const input = encoder.encode(JSON.stringify(opts));
+
+    try {
+      for await (const response of client.invoke(
+        { clipName: env.clipName, command, input, clipToken: "" },
+        { signal: controller.signal },
+      )) {
+        if (cancelled) return;
+
+        if (response.error) {
+          onEvent({ type: "info", message: `Error: ${response.error.message}` });
+          if (!cancelled) onDone(1);
+          return;
+        }
+
+        if (response.output.length > 0) {
+          const text = decoder.decode(response.output);
+          // Each output chunk may contain JSONL lines
+          for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            try {
+              const event = JSON.parse(trimmed);
+              if (isStreamEvent(event)) {
+                onEvent(event);
+              }
+            } catch {
+              // skip non-JSON lines
+            }
+          }
+        }
+      }
+
+      if (!cancelled) onDone(0);
+    } catch (error) {
+      if (!cancelled) onDone(-1);
+    }
+  })();
+
+  return () => {
+    cancelled = true;
+    controller.abort();
+  };
+}
+
+// ── Helpers ──
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function extractError(payload: unknown, fallback: string): string {
+  if (typeof payload === "string" && payload.trim()) return payload;
+  if (payload && typeof payload === "object") {
+    const msg = (payload as { message?: string }).message;
+    if (typeof msg === "string" && msg.trim()) return msg;
+    const err = (payload as { error?: unknown }).error;
+    if (typeof err === "string" && err.trim()) return err;
+    if (err && typeof err === "object") {
+      const nestedMsg = (err as { message?: string }).message;
+      if (typeof nestedMsg === "string" && nestedMsg.trim()) return nestedMsg;
+    }
+  }
+  return fallback;
+}
+
+// ── Public API ──
+
+/**
+ * Invoke a clip command and return the parsed result.
+ *
+ * Automatically uses HTTP (standalone --web) or Connect-RPC (Hub).
+ */
+export async function invoke<T = unknown>(
+  command: string,
+  opts: InvokeOptions = {},
+): Promise<T> {
+  const env = detectEnv();
+  if (env.mode === "standalone") {
+    return httpInvoke(command, opts) as Promise<T>;
+  }
+  return rpcInvoke(env, command, opts) as Promise<T>;
+}
+
+/**
+ * Invoke a clip command with streaming output.
+ * Returns a cancel function.
+ *
+ * Automatically uses SSE (standalone --web) or Connect-RPC streaming (Hub).
+ */
+export function invokeStream(
+  command: string,
+  opts: InvokeOptions,
+  onEvent: (event: StreamEvent) => void,
+  onDone: (exitCode: number) => void,
+): () => void {
+  const env = detectEnv();
+  if (env.mode === "standalone") {
+    return httpInvokeStream(command, opts, onEvent, onDone);
+  }
+  return rpcInvokeStream(env, command, opts, onEvent, onDone);
+}