@openvole/paw-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenVole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import { ZodSchema } from 'zod';
+export { z } from 'zod';
+
+/** Agent context passed to hooks and the Brain */
+interface AgentContext {
+    taskId: string;
+    messages: AgentMessage[];
+    availableTools: ToolSummary[];
+    activeSkills: ActiveSkill[];
+    metadata: Record<string, unknown>;
+    iteration: number;
+    maxIterations: number;
+}
+interface AgentMessage {
+    role: 'user' | 'brain' | 'tool_result' | 'error';
+    content: string;
+    toolCall?: {
+        name: string;
+        params: unknown;
+    };
+    timestamp: number;
+}
+interface ToolSummary {
+    name: string;
+    description: string;
+    pawName: string;
+}
+interface ActiveSkill {
+    name: string;
+    description: string;
+    satisfiedBy: string[];
+}
+/** Result of a tool execution */
+interface ActionResult {
+    toolName: string;
+    pawName: string;
+    success: boolean;
+    output?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    durationMs: number;
+}
+/** Plan returned by a Brain Paw */
+interface AgentPlan {
+    actions: PlannedAction[];
+    execution?: 'parallel' | 'sequential';
+    response?: string;
+    done?: boolean;
+}
+interface PlannedAction {
+    tool: string;
+    params: unknown;
+}
+/** Tool definition within a Paw */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+    execute: (params: unknown) => Promise<unknown>;
+}
+/** Bootstrap hook — called once when a task starts */
+type BootstrapHook = (context: AgentContext) => Promise<AgentContext>;
+/** Perceive hook — called before Think to enrich context */
+type PerceiveHook = (context: AgentContext) => Promise<AgentContext>;
+/** Observe hook — called after Act, fire-and-forget side effect */
+type ObserveHook = (result: ActionResult) => Promise<void>;
+/** Compact hook — called when context exceeds size threshold */
+type CompactHook = (context: AgentContext) => Promise<AgentContext>;
+/** Schedule hook */
+interface ScheduleHook {
+    cron: string;
+    handler: () => Promise<{
+        input: string;
+        source?: 'schedule' | 'paw';
+    }>;
+}
+/** VoleIO interface for Paws that want to provide I/O */
+interface VoleIO {
+    confirm(message: string): Promise<boolean>;
+    prompt(message: string): Promise<string>;
+    notify(message: string): void;
+}
+/** The full Paw definition */
+interface PawDefinition {
+    name: string;
+    version: string;
+    description: string;
+    brain?: boolean;
+    inProcess?: boolean;
+    config?: ZodSchema;
+    hooks?: {
+        onBootstrap?: BootstrapHook;
+        onPerceive?: PerceiveHook;
+        onObserve?: ObserveHook;
+        onCompact?: CompactHook;
+        onSchedule?: ScheduleHook[];
+    };
+    tools?: ToolDefinition[];
+    think?: (context: AgentContext) => Promise<AgentPlan>;
+    io?: VoleIO;
+    onLoad?: (config: unknown) => Promise<void>;
+    onUnload?: () => Promise<void>;
+}
+
+/**
+ * definePaw — the primary export for Paw developers.
+ *
+ * For in-process Paws, this simply returns the definition (loaded directly by core).
+ * For subprocess Paws, this sets up the IPC transport and registers handlers.
+ */
+declare function definePaw(definition: PawDefinition): PawDefinition;
+
+type RequestHandler = (params: unknown) => Promise<unknown>;
+/** Create an IPC transport for Node.js Paw subprocesses */
+declare function createIpcTransport(): {
+    /** Register a handler for a method called by the core */
+    onRequest(method: string, handler: RequestHandler): void;
+    /** Send a notification to the core (no response expected) */
+    send(method: string, params?: unknown): void;
+    /** Send a request to the core and wait for a response */
+    request(method: string, params?: unknown): Promise<unknown>;
+    /** Subscribe to bus events from the core */
+    subscribe(events: string[]): void;
+    /** Query core state (tools, paws, skills, tasks) */
+    query(type: "tools" | "paws" | "skills" | "tasks"): Promise<unknown>;
+    /** Register a handler for forwarded bus events */
+    onBusEvent(handler: (event: string, data: unknown) => void): void;
+    /** Create a task in the core's task queue (for channel Paws that receive inbound messages) */
+    createTask(input: string, metadata?: Record<string, unknown> & {
+        sessionId?: string;
+    }): Promise<{
+        taskId: string;
+    }>;
+};
+/** Create a stdio transport for non-Node Paw processes (LSP-style framing) */
+declare function createStdioTransport(): {
+    onRequest(method: string, handler: RequestHandler): void;
+    send(method: string, params?: unknown): void;
+};
+
+export { type ActionResult, type ActiveSkill, type AgentContext, type AgentMessage, type AgentPlan, type BootstrapHook, type CompactHook, type ObserveHook, type PawDefinition, type PerceiveHook, type PlannedAction, type ScheduleHook, type ToolDefinition, type ToolSummary, type VoleIO, createIpcTransport, createStdioTransport, definePaw };

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/transport.ts
+function createIpcTransport() {
+  const handlers = /* @__PURE__ */ new Map();
+  process.on("message", async (msg) => {
+    if (!msg.method) return;
+    const handler = handlers.get(msg.method);
+    if (handler) {
+      try {
+        const result = await handler(msg.params);
+        if (msg.id) {
+          process.send({ jsonrpc: "2.0", id: msg.id, result });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (msg.id) {
+          process.send({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: { code: -32603, message }
+          });
+        }
+      }
+    }
+  });
+  return {
+    /** Register a handler for a method called by the core */
+    onRequest(method, handler) {
+      handlers.set(method, handler);
+    },
+    /** Send a notification to the core (no response expected) */
+    send(method, params) {
+      process.send({ jsonrpc: "2.0", method, params });
+    },
+    /** Send a request to the core and wait for a response */
+    async request(method, params) {
+      const id = crypto.randomUUID();
+      const message = { jsonrpc: "2.0", id, method, params };
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error(`Request "${method}" timed out`));
+        }, 3e4);
+        const listener = (msg) => {
+          if (msg.id === id) {
+            clearTimeout(timeout);
+            process.off("message", listener);
+            if (msg.error) {
+              reject(new Error(msg.error.message));
+            } else {
+              resolve(msg.result);
+            }
+          }
+        };
+        process.on("message", listener);
+        process.send(message);
+      });
+    },
+    /** Subscribe to bus events from the core */
+    subscribe(events) {
+      process.send({ jsonrpc: "2.0", method: "subscribe", params: { events } });
+    },
+    /** Query core state (tools, paws, skills, tasks) */
+    async query(type) {
+      const id = crypto.randomUUID();
+      const message = { jsonrpc: "2.0", id, method: "query", params: { type } };
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error(`Query "${type}" timed out`));
+        }, 1e4);
+        const listener = (msg) => {
+          if (msg.id === id) {
+            clearTimeout(timeout);
+            process.off("message", listener);
+            if (msg.error) {
+              reject(new Error(msg.error.message));
+            } else {
+              resolve(msg.result);
+            }
+          }
+        };
+        process.on("message", listener);
+        process.send(message);
+      });
+    },
+    /** Register a handler for forwarded bus events */
+    onBusEvent(handler) {
+      handlers.set("bus_event", async (params) => {
+        const { event, data } = params;
+        handler(event, data);
+        return { ok: true };
+      });
+    },
+    /** Create a task in the core's task queue (for channel Paws that receive inbound messages) */
+    async createTask(input, metadata) {
+      const { sessionId, ...rest } = metadata ?? {};
+      const id = crypto.randomUUID();
+      const message = {
+        jsonrpc: "2.0",
+        id,
+        method: "create_task",
+        params: { input, source: "paw", sessionId, metadata: rest }
+      };
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("createTask timed out"));
+        }, 1e4);
+        const listener = (msg) => {
+          if (msg.id === id) {
+            clearTimeout(timeout);
+            process.off("message", listener);
+            if (msg.error) {
+              reject(new Error(msg.error.message));
+            } else {
+              resolve(msg.result);
+            }
+          }
+        };
+        process.on("message", listener);
+        process.send(message);
+      });
+    }
+  };
+}
+function createStdioTransport() {
+  const handlers = /* @__PURE__ */ new Map();
+  let buffer = "";
+  process.stdin.setEncoding("utf-8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    processBuffer();
+  });
+  async function processBuffer() {
+    while (buffer.length > 0) {
+      const headerEnd = buffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) break;
+      const header = buffer.substring(0, headerEnd);
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) {
+        buffer = buffer.substring(headerEnd + 4);
+        continue;
+      }
+      const contentLength = Number.parseInt(match[1], 10);
+      const bodyStart = headerEnd + 4;
+      if (buffer.length < bodyStart + contentLength) break;
+      const body = buffer.substring(bodyStart, bodyStart + contentLength);
+      buffer = buffer.substring(bodyStart + contentLength);
+      try {
+        const msg = JSON.parse(body);
+        await handleMessage(msg);
+      } catch {
+      }
+    }
+  }
+  async function handleMessage(msg) {
+    if (!msg.method) return;
+    const handler = handlers.get(msg.method);
+    if (handler) {
+      try {
+        const result = await handler(msg.params);
+        if (msg.id) {
+          send({ jsonrpc: "2.0", id: msg.id, result });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (msg.id) {
+          send({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: { code: -32603, message }
+          });
+        }
+      }
+    }
+  }
+  function send(message) {
+    const json = JSON.stringify(message);
+    const header = `Content-Length: ${Buffer.byteLength(json)}\r
+\r
+`;
+    process.stdout.write(header + json);
+  }
+  return {
+    onRequest(method, handler) {
+      handlers.set(method, handler);
+    },
+    send(method, params) {
+      send({ jsonrpc: "2.0", method, params });
+    }
+  };
+}
+
+// src/define.ts
+function definePaw(definition) {
+  if (definition.inProcess || !isSubprocess()) {
+    return definition;
+  }
+  setupSubprocessPaw(definition);
+  return definition;
+}
+function isSubprocess() {
+  return typeof process.send === "function";
+}
+function setupSubprocessPaw(definition) {
+  const transport = createIpcTransport();
+  transport.send("register", {
+    name: definition.name,
+    version: definition.version,
+    brain: definition.brain ?? false,
+    tools: (definition.tools ?? []).map((t) => ({
+      name: t.name,
+      description: t.description
+    })),
+    hooks: {
+      bootstrap: !!definition.hooks?.onBootstrap,
+      perceive: !!definition.hooks?.onPerceive,
+      observe: !!definition.hooks?.onObserve,
+      compact: !!definition.hooks?.onCompact,
+      schedule: (definition.hooks?.onSchedule ?? []).map((s) => s.cron)
+    }
+  });
+  if (definition.hooks?.onBootstrap) {
+    transport.onRequest("bootstrap", async (params) => {
+      return definition.hooks.onBootstrap(params);
+    });
+  }
+  if (definition.hooks?.onPerceive) {
+    transport.onRequest("perceive", async (params) => {
+      return definition.hooks.onPerceive(params);
+    });
+  }
+  if (definition.think) {
+    transport.onRequest("think", async (params) => {
+      return definition.think(params);
+    });
+  }
+  if (definition.tools && definition.tools.length > 0) {
+    const toolMap = new Map(definition.tools.map((t) => [t.name, t]));
+    transport.onRequest("execute_tool", async (params) => {
+      const { toolName, params: toolParams } = params;
+      const tool = toolMap.get(toolName);
+      if (!tool) {
+        throw new Error(`Tool "${toolName}" not found in this Paw`);
+      }
+      const validated = tool.parameters.parse(toolParams);
+      return tool.execute(validated);
+    });
+  }
+  if (definition.hooks?.onObserve) {
+    transport.onRequest("observe", async (params) => {
+      await definition.hooks.onObserve(params);
+      return { ok: true };
+    });
+  }
+  if (definition.hooks?.onCompact) {
+    transport.onRequest("compact", async (params) => {
+      return definition.hooks.onCompact(params);
+    });
+  }
+  transport.onRequest("shutdown", async () => {
+    if (definition.onUnload) {
+      await definition.onUnload();
+    }
+    process.exit(0);
+  });
+  if (definition.onLoad) {
+    definition.onLoad({}).catch((err) => {
+      console.error(`[${definition.name}] onLoad failed:`, err);
+      process.exit(1);
+    });
+  }
+}
+
+// src/index.ts
+import { z } from "zod";
+export {
+  createIpcTransport,
+  createStdioTransport,
+  definePaw,
+  z
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport.ts","../src/define.ts","../src/index.ts"],"sourcesContent":["/** JSON-RPC 2.0 message */\ninterface IpcMessage {\n\tjsonrpc: '2.0'\n\tid?: string\n\tmethod?: string\n\tparams?: unknown\n\tresult?: unknown\n\terror?: { code: number; message: string; data?: unknown }\n}\n\ntype RequestHandler = (params: unknown) => Promise<unknown>\n\n/** Create an IPC transport for Node.js Paw subprocesses */\nexport function createIpcTransport() {\n\tconst handlers = new Map<string, RequestHandler>()\n\n\t// Listen for incoming messages from the core\n\tprocess.on('message', async (msg: IpcMessage) => {\n\t\tif (!msg.method) return\n\n\t\tconst handler = handlers.get(msg.method)\n\t\tif (handler) {\n\t\t\ttry {\n\t\t\t\tconst result = await handler(msg.params)\n\t\t\t\tif (msg.id) {\n\t\t\t\t\tprocess.send!({ jsonrpc: '2.0', id: msg.id, result })\n\t\t\t\t}\n\t\t\t} catch (err) {\n\t\t\t\tconst message = err instanceof Error ? err.message : String(err)\n\t\t\t\tif (msg.id) {\n\t\t\t\t\tprocess.send!({\n\t\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\t\tid: msg.id,\n\t\t\t\t\t\terror: { code: -32603, message },\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t})\n\n\treturn {\n\t\t/** Register a handler for a method called by the core */\n\t\tonRequest(method: string, handler: RequestHandler): void {\n\t\t\thandlers.set(method, handler)\n\t\t},\n\n\t\t/** Send a notification to the core (no response expected) */\n\t\tsend(method: string, params?: unknown): void {\n\t\t\tprocess.send!({ jsonrpc: '2.0', method, params })\n\t\t},\n\n\t\t/** Send a request to the core and wait for a response */\n\t\tasync request(method: string, params?: unknown): Promise<unknown> {\n\t\t\tconst id = crypto.randomUUID()\n\t\t\tconst message: IpcMessage = { jsonrpc: '2.0', id, method, params }\n\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tconst timeout = setTimeout(() => {\n\t\t\t\t\treject(new Error(`Request \"${method}\" timed out`))\n\t\t\t\t}, 30_000)\n\n\t\t\t\tconst listener = (msg: IpcMessage) => {\n\t\t\t\t\tif (msg.id === id) {\n\t\t\t\t\t\tclearTimeout(timeout)\n\t\t\t\t\t\tprocess.off('message', listener)\n\t\t\t\t\t\tif (msg.error) {\n\t\t\t\t\t\t\treject(new Error(msg.error.message))\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tresolve(msg.result)\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tprocess.on('message', listener)\n\t\t\t\tprocess.send!(message)\n\t\t\t})\n\t\t},\n\n\t\t/** Subscribe to bus events from the core */\n\t\tsubscribe(events: string[]): void {\n\t\t\tprocess.send!({ jsonrpc: '2.0', method: 'subscribe', params: { events } })\n\t\t},\n\n\t\t/** Query core state (tools, paws, skills, tasks) */\n\t\tasync query(type: 'tools' | 'paws' | 'skills' | 'tasks'): Promise<unknown> {\n\t\t\tconst id = crypto.randomUUID()\n\t\t\tconst message: IpcMessage = { jsonrpc: '2.0', id, method: 'query', params: { type } }\n\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tconst timeout = setTimeout(() => {\n\t\t\t\t\treject(new Error(`Query \"${type}\" timed out`))\n\t\t\t\t}, 10_000)\n\n\t\t\t\tconst listener = (msg: IpcMessage) => {\n\t\t\t\t\tif (msg.id === id) {\n\t\t\t\t\t\tclearTimeout(timeout)\n\t\t\t\t\t\tprocess.off('message', listener)\n\t\t\t\t\t\tif (msg.error) {\n\t\t\t\t\t\t\treject(new Error(msg.error.message))\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tresolve(msg.result)\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tprocess.on('message', listener)\n\t\t\t\tprocess.send!(message)\n\t\t\t})\n\t\t},\n\n\t\t/** Register a handler for forwarded bus events */\n\t\tonBusEvent(handler: (event: string, data: unknown) => void): void {\n\t\t\thandlers.set('bus_event', async (params) => {\n\t\t\t\tconst { event, data } = params as { event: string; data: unknown }\n\t\t\t\thandler(event, data)\n\t\t\t\treturn { ok: true }\n\t\t\t})\n\t\t},\n\n\t\t/** Create a task in the core's task queue (for channel Paws that receive inbound messages) */\n\t\tasync createTask(input: string, metadata?: Record<string, unknown> & { sessionId?: string }): Promise<{ taskId: string }> {\n\t\t\tconst { sessionId, ...rest } = metadata ?? {}\n\t\t\tconst id = crypto.randomUUID()\n\t\t\tconst message: IpcMessage = {\n\t\t\t\tjsonrpc: '2.0',\n\t\t\t\tid,\n\t\t\t\tmethod: 'create_task',\n\t\t\t\tparams: { input, source: 'paw', sessionId, metadata: rest },\n\t\t\t}\n\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tconst timeout = setTimeout(() => {\n\t\t\t\t\treject(new Error('createTask timed out'))\n\t\t\t\t}, 10_000)\n\n\t\t\t\tconst listener = (msg: IpcMessage) => {\n\t\t\t\t\tif (msg.id === id) {\n\t\t\t\t\t\tclearTimeout(timeout)\n\t\t\t\t\t\tprocess.off('message', listener)\n\t\t\t\t\t\tif (msg.error) {\n\t\t\t\t\t\t\treject(new Error(msg.error.message))\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tresolve(msg.result as { taskId: string })\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tprocess.on('message', listener)\n\t\t\t\tprocess.send!(message)\n\t\t\t})\n\t\t},\n\t}\n}\n\n/** Create a stdio transport for non-Node Paw processes (LSP-style framing) */\nexport function createStdioTransport() {\n\tconst handlers = new Map<string, RequestHandler>()\n\tlet buffer = ''\n\n\tprocess.stdin.setEncoding('utf-8')\n\tprocess.stdin.on('data', (chunk: string) => {\n\t\tbuffer += chunk\n\t\tprocessBuffer()\n\t})\n\n\tasync function processBuffer(): Promise<void> {\n\t\twhile (buffer.length > 0) {\n\t\t\tconst headerEnd = buffer.indexOf('\\r\\n\\r\\n')\n\t\t\tif (headerEnd === -1) break\n\n\t\t\tconst header = buffer.substring(0, headerEnd)\n\t\t\tconst match = header.match(/Content-Length:\\s*(\\d+)/i)\n\t\t\tif (!match) {\n\t\t\t\tbuffer = buffer.substring(headerEnd + 4)\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tconst contentLength = Number.parseInt(match[1], 10)\n\t\t\tconst bodyStart = headerEnd + 4\n\t\t\tif (buffer.length < bodyStart + contentLength) break\n\n\t\t\tconst body = buffer.substring(bodyStart, bodyStart + contentLength)\n\t\t\tbuffer = buffer.substring(bodyStart + contentLength)\n\n\t\t\ttry {\n\t\t\t\tconst msg = JSON.parse(body) as IpcMessage\n\t\t\t\tawait handleMessage(msg)\n\t\t\t} catch {\n\t\t\t\t// Skip malformed messages\n\t\t\t}\n\t\t}\n\t}\n\n\tasync function handleMessage(msg: IpcMessage): Promise<void> {\n\t\tif (!msg.method) return\n\n\t\tconst handler = handlers.get(msg.method)\n\t\tif (handler) {\n\t\t\ttry {\n\t\t\t\tconst result = await handler(msg.params)\n\t\t\t\tif (msg.id) {\n\t\t\t\t\tsend({ jsonrpc: '2.0', id: msg.id, result })\n\t\t\t\t}\n\t\t\t} catch (err) {\n\t\t\t\tconst message = err instanceof Error ? err.message : String(err)\n\t\t\t\tif (msg.id) {\n\t\t\t\t\tsend({\n\t\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\t\tid: msg.id,\n\t\t\t\t\t\terror: { code: -32603, message },\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tfunction send(message: IpcMessage): void {\n\t\tconst json = JSON.stringify(message)\n\t\tconst header = `Content-Length: ${Buffer.byteLength(json)}\\r\\n\\r\\n`\n\t\tprocess.stdout.write(header + json)\n\t}\n\n\treturn {\n\t\tonRequest(method: string, handler: RequestHandler): void {\n\t\t\thandlers.set(method, handler)\n\t\t},\n\n\t\tsend(method: string, params?: unknown): void {\n\t\t\tsend({ jsonrpc: '2.0', method, params })\n\t\t},\n\t}\n}\n","import type { PawDefinition, AgentContext, ActionResult } from './types.js'\nimport { createIpcTransport } from './transport.js'\n\n/**\n * definePaw — the primary export for Paw developers.\n *\n * For in-process Paws, this simply returns the definition (loaded directly by core).\n * For subprocess Paws, this sets up the IPC transport and registers handlers.\n */\nexport function definePaw(definition: PawDefinition): PawDefinition {\n\t// If this module is being imported by the core (in-process), just return the definition\n\tif (definition.inProcess || !isSubprocess()) {\n\t\treturn definition\n\t}\n\n\t// Running as a subprocess — wire up IPC transport\n\tsetupSubprocessPaw(definition)\n\treturn definition\n}\n\n/** Check if we're running as a subprocess (have IPC channel) */\nfunction isSubprocess(): boolean {\n\treturn typeof process.send === 'function'\n}\n\n/** Set up IPC handlers for a subprocess Paw */\nfunction setupSubprocessPaw(definition: PawDefinition): void {\n\tconst transport = createIpcTransport()\n\n\t// Register with the core\n\ttransport.send('register', {\n\t\tname: definition.name,\n\t\tversion: definition.version,\n\t\tbrain: definition.brain ?? false,\n\t\ttools: (definition.tools ?? []).map((t) => ({\n\t\t\tname: t.name,\n\t\t\tdescription: t.description,\n\t\t})),\n\t\thooks: {\n\t\t\tbootstrap: !!definition.hooks?.onBootstrap,\n\t\t\tperceive: !!definition.hooks?.onPerceive,\n\t\t\tobserve: !!definition.hooks?.onObserve,\n\t\t\tcompact: !!definition.hooks?.onCompact,\n\t\t\tschedule: (definition.hooks?.onSchedule ?? []).map((s) => s.cron),\n\t\t},\n\t})\n\n\t// Handle bootstrap — called once at task start\n\tif (definition.hooks?.onBootstrap) {\n\t\ttransport.onRequest('bootstrap', async (params) => {\n\t\t\treturn definition.hooks!.onBootstrap!(params as AgentContext)\n\t\t})\n\t}\n\n\t// Handle perceive\n\tif (definition.hooks?.onPerceive) {\n\t\ttransport.onRequest('perceive', async (params) => {\n\t\t\treturn definition.hooks!.onPerceive!(params as AgentContext)\n\t\t})\n\t}\n\n\t// Handle think (Brain Paw)\n\tif (definition.think) {\n\t\ttransport.onRequest('think', async (params) => {\n\t\t\treturn definition.think!(params as AgentContext)\n\t\t})\n\t}\n\n\t// Handle tool execution\n\tif (definition.tools && definition.tools.length > 0) {\n\t\tconst toolMap = new Map(definition.tools.map((t) => [t.name, t]))\n\n\t\ttransport.onRequest('execute_tool', async (params) => {\n\t\t\tconst { toolName, params: toolParams } = params as {\n\t\t\t\ttoolName: string\n\t\t\t\tparams: unknown\n\t\t\t}\n\n\t\t\tconst tool = toolMap.get(toolName)\n\t\t\tif (!tool) {\n\t\t\t\tthrow new Error(`Tool \"${toolName}\" not found in this Paw`)\n\t\t\t}\n\n\t\t\t// Validate parameters\n\t\t\tconst validated = tool.parameters.parse(toolParams)\n\t\t\treturn tool.execute(validated)\n\t\t})\n\t}\n\n\t// Handle observe\n\tif (definition.hooks?.onObserve) {\n\t\ttransport.onRequest('observe', async (params) => {\n\t\t\tawait definition.hooks!.onObserve!(params as ActionResult)\n\t\t\treturn { ok: true }\n\t\t})\n\t}\n\n\t// Handle compact — called when context exceeds threshold\n\tif (definition.hooks?.onCompact) {\n\t\ttransport.onRequest('compact', async (params) => {\n\t\t\treturn definition.hooks!.onCompact!(params as AgentContext)\n\t\t})\n\t}\n\n\t// Handle shutdown\n\ttransport.onRequest('shutdown', async () => {\n\t\tif (definition.onUnload) {\n\t\t\tawait definition.onUnload()\n\t\t}\n\t\tprocess.exit(0)\n\t})\n\n\t// Run onLoad\n\tif (definition.onLoad) {\n\t\tdefinition.onLoad({}).catch((err) => {\n\t\t\tconsole.error(`[${definition.name}] onLoad failed:`, err)\n\t\t\tprocess.exit(1)\n\t\t})\n\t}\n}\n","export { definePaw } from './define.js'\nexport { createIpcTransport, createStdioTransport } from './transport.js'\nexport { z } from 'zod'\nexport type {\n\tPawDefinition,\n\tToolDefinition,\n\tAgentContext,\n\tAgentMessage,\n\tAgentPlan,\n\tPlannedAction,\n\tActionResult,\n\tActiveSkill,\n\tToolSummary,\n\tBootstrapHook,\n\tPerceiveHook,\n\tObserveHook,\n\tCompactHook,\n\tScheduleHook,\n\tVoleIO,\n} from './types.js'\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@openvole/paw-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building OpenVole Paws — tool providers for the agent loop",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openvole/openvole",
+    "directory": "src/paw-sdk"
+  },
+  "keywords": [
+    "openvole",
+    "paw",
+    "sdk",
+    "agent",
+    "tools"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}