@openheinerss/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @openheinerss/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK oficial em **TypeScript / JavaScript** para integração com o **Openheinerss** (crom-org).
+
+## Instalação
+
+```bash
+npm install @openheinerss/sdk
+```
+
+## Uso no Backend / Node / Bun
+
+```typescript
+import { Openheinerss } from "@openheinerss/sdk";
+
+const agent = new Openheinerss({
+  options: {
+    harness: "claude-code", // ou "opencode", "mock"
+    provider: "openrouter",
+    model: "anthropic/claude-3.7-sonnet"
+  }
+});
+
+agent.on("thinking", (delta) => console.log("Pensando:", delta));
+agent.on("text", (delta) => process.stdout.write(delta));
+agent.on("permission", async (req) => {
+  console.log("Permissão solicitada para:", req.command);
+  await req.allow();
+});
+
+await agent.prompt("Refatore a autenticação");
+```
+
+## Uso no Frontend / React
+
+```tsx
+import { useOpenheinerss } from "@openheinerss/sdk";
+
+export function Chat() {
+  const { messages, isThinking, prompt } = useOpenheinerss();
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}><b>{m.role}:</b> {m.text}</div>
+      ))}
+      {isThinking && <p>Pensando...</p>}
+      <button onClick={() => prompt("Olá Openheinerss!")}>Enviar</button>
+    </div>
+  );
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { EventEmitter } from "node:events";
+import type { SessionOptions } from "./types.js";
+export * from "./types.js";
+export * from "./react.js";
+export interface ClientConfig {
+    transport?: "stdio" | "websocket";
+    wsEndpoint?: string;
+    binPath?: string;
+    options?: SessionOptions;
+}
+export declare class Openheinerss extends EventEmitter {
+    private proc?;
+    private ws?;
+    private sessionId?;
+    private reqId;
+    private pendingCallbacks;
+    private config;
+    constructor(config?: ClientConfig);
+    /**
+     * Conecta e inicializa a sessão com o harness desejado
+     */
+    start(options?: SessionOptions): Promise<string>;
+    /**
+     * Envia uma instrução textual e anexos para o agente
+     */
+    prompt(text: string, images?: Array<{
+        mediaType: string;
+        data: string;
+    }>): Promise<void>;
+    /**
+     * Responde uma autorização de ferramenta
+     */
+    respondPermission(requestId: string, allow: boolean, message?: string): Promise<void>;
+    /**
+     * Interrompe o processamento da sessão
+     */
+    abort(): Promise<void>;
+    /**
+     * Fecha os processos ou conexões
+     */
+    close(): void;
+    private initStdio;
+    private initWebSocket;
+    private handleIncoming;
+    private sendRPC;
+}

package/dist/index.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Openheinerss = void 0;
+const node_events_1 = require("node:events");
+const node_child_process_1 = require("node:child_process");
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./react.js"), exports);
+class Openheinerss extends node_events_1.EventEmitter {
+    proc;
+    ws;
+    sessionId;
+    reqId = 1;
+    pendingCallbacks = new Map();
+    config;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            transport: config.transport || (typeof window !== "undefined" ? "websocket" : "stdio"),
+            wsEndpoint: config.wsEndpoint || "ws://127.0.0.1:4799",
+            binPath: config.binPath || "openheinerss",
+            options: config.options || {},
+            ...config,
+        };
+    }
+    /**
+     * Conecta e inicializa a sessão com o harness desejado
+     */
+    async start(options) {
+        const opts = { ...this.config.options, ...options };
+        if (this.config.transport === "stdio") {
+            this.initStdio();
+        }
+        else {
+            await this.initWebSocket();
+        }
+        const res = await this.sendRPC("session.create", {
+            harness: opts.harness || "mock",
+            mode: opts.mode,
+            cwd: opts.cwd || (typeof process !== "undefined" ? process.cwd() : "/"),
+            provider: opts.provider,
+            model: opts.model,
+            options: {
+                permissionMode: opts.permissionMode || "ask",
+                systemPrompt: opts.systemPrompt,
+            },
+        });
+        this.sessionId = res.sessionId;
+        return this.sessionId;
+    }
+    /**
+     * Envia uma instrução textual e anexos para o agente
+     */
+    async prompt(text, images = []) {
+        if (!this.sessionId) {
+            await this.start();
+        }
+        await this.sendRPC("session.prompt", {
+            sessionId: this.sessionId,
+            text,
+            images,
+        });
+    }
+    /**
+     * Responde uma autorização de ferramenta
+     */
+    async respondPermission(requestId, allow, message) {
+        if (!this.sessionId)
+            return;
+        await this.sendRPC("session.permission_respond", {
+            sessionId: this.sessionId,
+            requestId,
+            decision: allow ? "allow" : "deny",
+            message,
+        });
+    }
+    /**
+     * Interrompe o processamento da sessão
+     */
+    async abort() {
+        if (!this.sessionId)
+            return;
+        await this.sendRPC("session.abort", {
+            sessionId: this.sessionId,
+        });
+    }
+    /**
+     * Fecha os processos ou conexões
+     */
+    close() {
+        if (this.proc) {
+            this.proc.kill();
+            this.proc = undefined;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = undefined;
+        }
+    }
+    initStdio() {
+        this.proc = (0, node_child_process_1.spawn)(this.config.binPath, ["serve", "--stdio"]);
+        let buffer = "";
+        this.proc.stdout?.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const msg = JSON.parse(line);
+                    this.handleIncoming(msg);
+                }
+                catch (_) { }
+            }
+        });
+        this.proc.on("error", (err) => {
+            this.emit("error", { message: `Falha ao iniciar binário openheinerss: ${err.message}` });
+        });
+    }
+    async initWebSocket() {
+        return new Promise((resolve, reject) => {
+            const WebSocketImpl = typeof WebSocket !== "undefined" ? WebSocket : globalThis.WebSocket;
+            if (!WebSocketImpl) {
+                return reject(new Error("Ambiente WebSocket não encontrado"));
+            }
+            this.ws = new WebSocketImpl(this.config.wsEndpoint);
+            this.ws.onopen = () => resolve();
+            this.ws.onerror = (err) => reject(new Error(`Falha ao conectar no WebSocket: ${err}`));
+            this.ws.onmessage = (event) => {
+                try {
+                    const data = typeof event.data === "string" ? event.data : event.data.toString();
+                    const msg = JSON.parse(data);
+                    this.handleIncoming(msg);
+                }
+                catch (_) { }
+            };
+        });
+    }
+    handleIncoming(msg) {
+        // Resposta a requisição enviada
+        if (msg.id !== undefined && this.pendingCallbacks.has(msg.id)) {
+            const cb = this.pendingCallbacks.get(msg.id);
+            this.pendingCallbacks.delete(msg.id);
+            if (msg.error) {
+                const err = new Error(msg.error.message);
+                err.code = msg.error.code;
+                err.data = msg.error.data;
+                throw err;
+            }
+            cb(msg.result);
+            return;
+        }
+        // Notificação de evento
+        if (msg.method) {
+            const p = msg.params || {};
+            switch (msg.method) {
+                case "agent.thinking":
+                    this.emit("thinking", p.delta);
+                    break;
+                case "agent.text":
+                    this.emit("text", p.delta);
+                    break;
+                case "agent.tool_call":
+                    this.emit("tool_call", p);
+                    break;
+                case "agent.tool_result":
+                    this.emit("tool_result", p);
+                    break;
+                case "agent.permission_request": {
+                    const permReq = {
+                        ...p,
+                        allow: async () => this.respondPermission(p.requestId, true),
+                        deny: async (reason) => this.respondPermission(p.requestId, false, reason),
+                    };
+                    this.emit("permission", permReq);
+                    break;
+                }
+                case "agent.complete":
+                    this.emit("complete", p.reason);
+                    break;
+                case "agent.error":
+                    this.emit("error", p);
+                    break;
+            }
+        }
+    }
+    sendRPC(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = this.reqId++;
+            this.pendingCallbacks.set(id, resolve);
+            const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+            if (this.config.transport === "stdio" && this.proc?.stdin) {
+                this.proc.stdin.write(payload);
+            }
+            else if (this.ws) {
+                this.ws.send(payload);
+            }
+            else {
+                this.pendingCallbacks.delete(id);
+                reject(new Error("Nenhum transporte ativo configurado"));
+            }
+        });
+    }
+}
+exports.Openheinerss = Openheinerss;

package/dist/react.d.ts

@@ -0,0 +1,22 @@
+import { Openheinerss, type ClientConfig } from "./index.js";
+import type { PermissionRequest } from "./types.js";
+export interface ChatMessage {
+    id: string;
+    role: "user" | "assistant" | "system";
+    text: string;
+    timestamp: string;
+}
+export interface UseOpenheinerssOptions extends ClientConfig {
+    autoConnect?: boolean;
+}
+export declare function useOpenheinerss(options?: UseOpenheinerssOptions): {
+    messages: ChatMessage[];
+    isThinking: boolean;
+    thinkingText: string;
+    permissionRequest: PermissionRequest | null;
+    status: "idle" | "running" | "waiting_permission";
+    prompt: (text: string) => Promise<void>;
+    respondPermission: (requestId: string, allow: boolean) => Promise<void>;
+    abort: () => Promise<void>;
+    client: Openheinerss | null;
+};

package/dist/react.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOpenheinerss = useOpenheinerss;
+const react_1 = require("react");
+const index_js_1 = require("./index.js");
+function useOpenheinerss(options = {}) {
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [isThinking, setIsThinking] = (0, react_1.useState)(false);
+    const [thinkingText, setThinkingText] = (0, react_1.useState)("");
+    const [permissionRequest, setPermissionRequest] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)("idle");
+    const clientRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        const client = new index_js_1.Openheinerss({
+            transport: "websocket",
+            wsEndpoint: options.wsEndpoint || "ws://127.0.0.1:4799",
+            options: options.options,
+            ...options,
+        });
+        clientRef.current = client;
+        client.on("thinking", (delta) => {
+            setIsThinking(true);
+            setThinkingText((prev) => prev + delta);
+        });
+        client.on("text", (delta) => {
+            setIsThinking(false);
+            setMessages((prev) => {
+                const last = prev[prev.length - 1];
+                if (last && last.role === "assistant") {
+                    return [
+                        ...prev.slice(0, -1),
+                        { ...last, text: last.text + delta },
+                    ];
+                }
+                return [
+                    ...prev,
+                    {
+                        id: Math.random().toString(36).substring(2, 9),
+                        role: "assistant",
+                        text: delta,
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            });
+        });
+        client.on("permission", (req) => {
+            setStatus("waiting_permission");
+            setPermissionRequest(req);
+        });
+        client.on("complete", () => {
+            setIsThinking(false);
+            setThinkingText("");
+            setStatus("idle");
+        });
+        client.on("error", (err) => {
+            setIsThinking(false);
+            setStatus("idle");
+            setMessages((prev) => [
+                ...prev,
+                {
+                    id: Math.random().toString(36).substring(2, 9),
+                    role: "system",
+                    text: `Erro: ${err.message}`,
+                    timestamp: new Date().toISOString(),
+                },
+            ]);
+        });
+        return () => {
+            client.close();
+        };
+    }, [options.wsEndpoint]);
+    const prompt = (0, react_1.useCallback)(async (text) => {
+        if (!clientRef.current)
+            return;
+        setStatus("running");
+        setMessages((prev) => [
+            ...prev,
+            {
+                id: Math.random().toString(36).substring(2, 9),
+                role: "user",
+                text,
+                timestamp: new Date().toISOString(),
+            },
+        ]);
+        await clientRef.current.prompt(text);
+    }, []);
+    const respondPermission = (0, react_1.useCallback)(async (requestId, allow) => {
+        if (!clientRef.current)
+            return;
+        await clientRef.current.respondPermission(requestId, allow);
+        setPermissionRequest(null);
+        setStatus("running");
+    }, []);
+    const abort = (0, react_1.useCallback)(async () => {
+        if (!clientRef.current)
+            return;
+        await clientRef.current.abort();
+        setIsThinking(false);
+        setStatus("idle");
+    }, []);
+    return {
+        messages,
+        isThinking,
+        thinkingText,
+        permissionRequest,
+        status,
+        prompt,
+        respondPermission,
+        abort,
+        client: clientRef.current,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export type HarnessType = "mock" | "claude-code" | "opencode" | string;
+export type HarnessMode = "sdk" | "cli" | "api" | "mock";
+export interface SessionOptions {
+    harness?: HarnessType;
+    mode?: HarnessMode;
+    cwd?: string;
+    provider?: string;
+    model?: string;
+    permissionMode?: "ask" | "always_allow" | "plan";
+    systemPrompt?: string;
+}
+export interface PermissionRequest {
+    sessionId: string;
+    requestId: string;
+    tool: string;
+    command?: string;
+    risk?: string;
+    allow: () => Promise<void>;
+    deny: (reason?: string) => Promise<void>;
+}
+export interface ToolCall {
+    sessionId: string;
+    callId: string;
+    tool: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResult {
+    sessionId: string;
+    callId: string;
+    status: "success" | "error";
+    output: string;
+}
+export interface OpenheinerssEvents {
+    thinking: (delta: string) => void;
+    text: (delta: string) => void;
+    tool_call: (call: ToolCall) => void;
+    tool_result: (result: ToolResult) => void;
+    permission: (req: PermissionRequest) => void;
+    complete: (reason: string) => void;
+    error: (err: {
+        message: string;
+        code?: number;
+    }) => void;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@openheinerss/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SDK oficial em TypeScript/JavaScript para o maestro Openheinerss",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crom-org/openheinerss.git",
+    "directory": "sdk/typescript"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude-code",
+    "opencode",
+    "orchestration",
+    "json-rpc",
+    "openheinerss"
+  ],
+  "author": "crom-org",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "typescript": "^5.4.5"
+  }
+}