@openhex-ai/agent-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+LICENSE — PLACEHOLDER (to be finalized before the first public release)
+
+Copyright (c) 2026 Openhex.
+
+This is a scaffold. The final license terms for @openhex/agent-sdk have not
+yet been decided. Do not redistribute until this file is replaced with the
+chosen license (e.g. an OSS license such as MIT/Apache-2.0, or commercial
+terms). Tracking: replace this placeholder in the MR that makes the package
+publishable.

package/README.md

@@ -0,0 +1,207 @@
+# @openhex-ai/agent-sdk
+
+Build AI agents on the **Openhex** platform. The same agent loop, built-in
+tools, hooks, sessions, and MCP support that power Openhex agents — exposed as a
+programmable TypeScript library.
+
+> **Status.** The **chat API** and the **workspace API** are implemented —
+> both speak the exact protocol the platform exposes (the user-side apps'
+> conversations protocol and the published `/api/v2/workspaces/*` surface).
+> The local `query()` agent loop is still a scaffold (throws
+> `NotImplementedError`) and lands in a follow-up MR.
+
+## Install
+
+```bash
+npm install @openhex-ai/agent-sdk
+# or
+pnpm add @openhex-ai/agent-sdk
+```
+
+## Authentication
+
+Get an API key (`mysta_…`) from the Openhex console, then set it as an
+environment variable (or pass `{ apiKey }` to the client):
+
+```bash
+export OPENHEX_API_KEY=mysta_...
+```
+
+## Chat with an agent
+
+The chat API mirrors the user-side apps' conversations protocol: a message
+creates (or continues) a conversation and routes it to the agent
+(auto-provisioning the agent's pod on first contact); the reply streams
+back over SSE until the turn completes.
+
+```ts
+import { OpenhexClient } from '@openhex-ai/agent-sdk';
+
+const client = new OpenhexClient({ agentId: '…', /* apiKey from env */ });
+
+// Simplest: send and await the aggregated turn (creates a conversation).
+const turn = await client.sendMessage('Summarize the latest support tickets');
+console.log(turn.text);
+console.log(turn.toolCalls);     // tools the agent used
+console.log(turn.conversationId); // reuse to continue the chat
+```
+
+### Multi-turn conversations
+
+A `Conversation` remembers its id so follow-ups keep context:
+
+```ts
+const convo = client.conversation();
+await convo.send('Remember my project is called Orbit.');
+const turn = await convo.send('What is my project called?'); // → "Orbit"
+```
+
+### Streaming
+
+```ts
+import { extractText, isTurnComplete } from '@openhex-ai/agent-sdk';
+
+for await (const record of client.runTurn('Group them by theme')) {
+  if (record.sender === 'assistant') process.stdout.write(extractText(record));
+  if (isTurnComplete(record)) break;
+}
+```
+
+### Low-level protocol
+
+`client.chat` exposes the wire 1:1 when you need full control:
+
+```ts
+// POST /conversations/send — create (targetAgentIds) or continue (conversationId)
+const { conversationId, userEventId } = await client.chat.send({
+  message: 'hello',
+  targetAgentIds: [agentId],
+});
+
+// GET /conversations/:id/stream — resumable (auto-reconnects with backoff).
+// Resume from a record's `id`, or from `userEventId` to capture just the reply.
+for await (const record of client.chat.stream(conversationId, { lastEventId: userEventId })) {
+  console.log(record.sender, record.raw.type);
+  if (record.raw.type === 'result') break;
+}
+
+await client.chat.interrupt(conversationId);          // POST /conversations/:id/interrupt
+const { entries } = await client.chat.messages(conversationId); // full history
+```
+
+Each stream record is `{ id, seq, sender, event, timestamp, sessionId, raw }`
+where `raw` carries the agent-runtime event (`{ type: 'assistant', message: { content: […] } }`,
+`{ type: 'result' }`, etc.) — identical to what the app's chat UI consumes.
+
+## Workspaces
+
+A **workspace** is a billing + membership boundary you (a service provider /
+partner) own. `client.workspaces` wraps the published `/api/v2/workspaces/*`
+API 1:1 — provision members, mint member sessions, grant credits, and read
+reporting. It speaks the same contract documented at
+`/api/v2/workspaces/openapi.json`.
+
+Auth is the `Bearer` token the client is configured with:
+
+| Token | Unlocks |
+| --- | --- |
+| Workspace API key (`sk_ws_…`) | `whoami`, member provision/suspend, sessions, member list, credit grants |
+| Owner user JWT | the above **plus** reporting (`ledger`, `insights`, member ledger) and API-key management |
+| none | the public SMS-signup endpoints (`sendSmsCode` / `verifySmsCode`) |
+
+```ts
+import { OpenhexClient } from '@openhex-ai/agent-sdk';
+
+// A partner backend authenticates with its workspace API key.
+const client = new OpenhexClient({ apiKey: 'sk_ws_…' });
+
+// Confirm which workspace the key belongs to.
+const me = await client.workspaces.whoami();
+
+// A slug-bound handle drops the slug from every call.
+const ws = client.workspace(me.slug);
+
+// Provision a member (idempotent on your sp_user_ref), grant credits,
+// then mint a session JWT for the member's client.
+const member = await ws.provisionMember({ sp_user_ref: 'user-42', display_name: 'Ada' });
+await ws.grantCredits(member.member_id, { amount: 500, idempotency_key: `bonus:${member.member_id}` });
+const session = await ws.mintSession({ sp_user_ref: 'user-42', ttl_seconds: 3600 });
+```
+
+Public SMS signup (no auth — requires `public_sms_signup_enabled` on the workspace):
+
+```ts
+const pub = new OpenhexClient({ apiKey: 'unused' }); // token ignored on these routes
+await pub.workspaces.sendSmsCode('acme', { phone: '13800000000' });
+const session = await pub.workspaces.verifySmsCode('acme', { phone: '13800000000', code: '123456' });
+```
+
+> The admin-side routes (workspace ledger, insights, per-member ledger,
+> API-key management, and the 4 workspace-lifecycle CRUD endpoints) are
+> intentionally **not** part of this client. They power the SP admin
+> webapp and aren't in the published partner spec — they'd 401 with a
+> workspace API key anyway.
+
+## Local agent loop (scaffold)
+
+```ts
+import { query } from '@openhex-ai/agent-sdk';
+
+for await (const message of query({
+  prompt: 'Summarize the latest support tickets',
+  options: { allowedTools: ['Read', 'WebSearch'] },
+})) {
+  if (message.type === 'result') console.log(message.result);
+}
+```
+
+## Custom tools
+
+```ts
+import { query } from '@openhex-ai/agent-sdk';
+import { tool, createSdkMcpServer } from '@openhex-ai/agent-sdk/tools';
+import { z } from 'zod';
+
+const getWeather = tool(
+  'get_weather',
+  'Look up the weather for a city',
+  z.object({ city: z.string() }),
+  async ({ city }) => ({ content: [{ type: 'text', text: `Sunny in ${city}` }] })
+);
+
+const q = query({
+  prompt: "What's the weather in Tokyo?",
+  options: {
+    mcpServers: { local: createSdkMcpServer({ name: 'local', tools: [getWeather] }) },
+  },
+});
+```
+
+## Concepts
+
+| Concept                     | Where                                                    |
+| --------------------------- | -------------------------------------------------------- |
+| Chat with a published agent | `client.sendMessage()`, `client.runTurn()`, `client.chat.*` |
+| Resumable record stream     | `client.chat.stream({ lastEventId })`                    |
+| One-shot / streaming runs   | `query()` (scaffold)                                     |
+| Stateful client + sessions  | `OpenhexClient`                                          |
+| Built-in & custom tools     | `options.allowedTools`, `tool()`, `createSdkMcpServer()` |
+| Lifecycle hooks             | `options.hooks`, `hookMatcher()`                         |
+| Subagents                   | `options.agents`                                         |
+| External integrations (MCP) | `options.mcpServers`                                     |
+| Permissions                 | `options.permissionMode`, `options.canUseTool`           |
+
+The surface intentionally mirrors the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview)
+so the mental model transfers directly.
+
+## Development
+
+```bash
+pnpm --filter @openhex-ai/agent-sdk build      # bundle to dist/ via tsup
+pnpm --filter @openhex-ai/agent-sdk typecheck  # tsc --noEmit
+pnpm --filter @openhex-ai/agent-sdk test       # jest
+```
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/index-DOE19uln.d.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+
+/**
+ * Tool definitions for the Openhex Agent SDK.
+ *
+ * Two kinds of tools exist:
+ *   1. Built-in tools the platform executes (Read, Bash, WebSearch, ...).
+ *      Reference these by name in {@link AgentOptions.allowedTools}.
+ *   2. Custom in-process tools you define with {@link tool} and expose
+ *      through an in-process MCP server ({@link createSdkMcpServer}).
+ *
+ * NOTE: scaffold only — the executor that actually runs custom tools is
+ * implemented in a follow-up MR.
+ */
+
+/** Names of the tools the platform ships with, available out of the box. */
+type BuiltinToolName = 'Read' | 'Write' | 'Edit' | 'Bash' | 'Glob' | 'Grep' | 'WebSearch' | 'WebFetch' | 'Agent' | 'AskUserQuestion';
+/** Either a known built-in tool or any custom/MCP tool name. */
+type ToolName = BuiltinToolName | (string & {});
+/** Value returned from a custom tool handler. */
+interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * A custom tool: a name, a Zod-typed input schema, and an async handler.
+ * Construct via {@link tool} rather than building this by hand.
+ */
+interface SdkToolDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    name: string;
+    description: string;
+    inputSchema: TSchema;
+    handler: (input: z.infer<TSchema>, extra: {
+        signal?: AbortSignal;
+    }) => Promise<ToolResult> | ToolResult;
+}
+/**
+ * A schema-erased tool definition, used wherever tools are stored in a
+ * heterogeneous collection. `tool()` returns the precisely-typed
+ * {@link SdkToolDefinition}; collections widen to this so an array can
+ * mix tools with different input schemas (Zod generics are invariant in
+ * the handler's parameter position, so the precise type can't be kept).
+ */
+type AnySdkToolDefinition = SdkToolDefinition<any>;
+/** An in-process MCP server bundling one or more {@link SdkToolDefinition}s. */
+interface SdkMcpServer {
+    type: 'sdk';
+    name: string;
+    version: string;
+    tools: AnySdkToolDefinition[];
+}
+
+/**
+ * Helpers for defining custom in-process tools.
+ *
+ * Available as a sub-path import:
+ *   import { tool, createSdkMcpServer } from '@openhex-ai/agent-sdk/tools';
+ *
+ * NOTE: scaffold only — `tool` and `createSdkMcpServer` build the typed
+ * definitions today; the executor that runs them inside the agent loop
+ * lands in a follow-up MR.
+ */
+
+/**
+ * Define a custom tool with a Zod-typed input schema and an async
+ * handler. Bundle the result into a server with {@link createSdkMcpServer}
+ * and pass it via `options.mcpServers`.
+ *
+ * @example
+ * const getWeather = tool(
+ *   'get_weather',
+ *   'Look up the weather for a city',
+ *   z.object({ city: z.string() }),
+ *   async ({ city }) => ({ content: [{ type: 'text', text: `Sunny in ${city}` }] }),
+ * );
+ */
+declare function tool<TSchema extends z.ZodTypeAny>(name: string, description: string, inputSchema: TSchema, handler: (input: z.infer<TSchema>, extra: {
+    signal?: AbortSignal;
+}) => Promise<ToolResult> | ToolResult): SdkToolDefinition<TSchema>;
+/**
+ * Bundle one or more {@link tool} definitions into an in-process MCP
+ * server that the agent loop can call without spawning a subprocess.
+ */
+declare function createSdkMcpServer(config: {
+    name: string;
+    version?: string;
+    tools: AnySdkToolDefinition[];
+}): SdkMcpServer;
+
+export { type AnySdkToolDefinition as A, type BuiltinToolName as B, type SdkMcpServer as S, type ToolName as T, type SdkToolDefinition as a, type ToolResult as b, createSdkMcpServer as c, tool as t };