@zoowork-ai/sdk 0.4.0

package/dist/events.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Session event normalization.
+ *
+ * The wire presents the SAME event in different shapes depending on where you read it:
+ *
+ *   unified lane (default)     → { id, seq, event_type, run_id, turn, payload, processed_at, created_at }
+ *                                on BOTH transports; the SSE `id:` line carries a `pse1:` resume token
+ *   deprecated `after` lane    → REST { seq, run_id, ... } stays snake_case, SSE frames arrive
+ *                                camelCase { seq, runId, eventType, createdAt, ... }
+ *
+ * No shape carries a top-level `type`. `normalizeEvent` absorbs all of them once, so callers
+ * switch on a single field. Legacy shapes verified against staging 2026-08-05; unified lane
+ * (input echo, pse1 cursors, idempotent postEvents) verified 2026-08-19.
+ *
+ * The vocabulary is SESSION_EVENT_TYPES plus PUBLIC_INPUT_EVENT_TYPES, mirrored from the API.
+ * Unknown types pass through unchanged rather than throwing — the API is Developer Preview
+ * and may add types within a version.
+ */
+/** SESSION_EVENT_TYPES, mirrored from the API. */
+export declare const SESSION_EVENT_TYPES: readonly ["run.started", "run.finished", "chat.delta", "chat.final", "chat.aborted", "chat.error", "agent.lifecycle", "agent.assistant", "agent.thinking", "agent.tool", "agent.item", "agent.plan", "agent.approval", "agent.command_output", "agent.patch", "agent.compaction", "agent.error", "attachment.created", "message.outbound"];
+export type SessionEventType = (typeof SESSION_EVENT_TYPES)[number];
+/** Your own inputs, echoed back in the unified event history. */
+export declare const PUBLIC_INPUT_EVENT_TYPES: readonly ["user.message", "user.interrupt", "user.tool_confirmation", "system.message"];
+export type PublicInputEventType = (typeof PUBLIC_INPUT_EVENT_TYPES)[number];
+/** A durable session event, normalized across the REST and SSE shapes. */
+export interface SessionEvent {
+    /** Durable per-session sequence: strictly increasing, not necessarily contiguous. */
+    seq: number;
+    eventType: SessionEventType | PublicInputEventType | string;
+    payload: Record<string, unknown>;
+    runId?: string;
+    turn?: number;
+    createdAt?: string;
+    /** Event id, when the server sends one. */
+    id?: string;
+    /** Input events only: `null` while queued, set once the agent has consumed it. */
+    processedAt?: string | null;
+    /** Resume token for `streamEvents({ cursor })`, present on streamed events. */
+    cursor?: string;
+}
+/** Accepts either wire shape (and an SSE `id:` line as the seq fallback). */
+export declare function normalizeEvent(raw: unknown, sseId?: string): SessionEvent;
+/**
+ * A run ends with `run.finished`. Its `payload.status` is `succeeded` | `failed` | `aborted`.
+ *
+ * Note that a run can finish `succeeded` even when individual tool calls errored — an
+ * `agent.tool` event with `payload.isError === true` does not fail the run. Do not infer
+ * turn success from the absence of tool errors.
+ */
+export declare function isRunFinished(e: SessionEvent): boolean;
+export declare function runOutcome(e: SessionEvent): 'succeeded' | 'failed' | 'aborted' | undefined;
+/**
+ * Text of one chat message — the `{ role, content }` shape that appears both as an
+ * `agent.assistant` event's `payload.message` and as a transcript row's `entry.message`.
+ *
+ * `content` is normally an array of blocks; only `{ type: 'text', text }` blocks carry
+ * text (tool-call blocks don't), and one message may hold several. A plain string is
+ * accepted too — that is how write-side `user.message` content comes back.
+ */
+export declare function messageText(message: unknown): string;
+/**
+ * Assistant text for an `agent.assistant` event; '' for every other event type.
+ *
+ * The text lives at `payload.message.content[]` — see `messageText`.
+ */
+export declare function assistantText(e: SessionEvent): string;
+/** Reasoning text for an `agent.thinking` event; '' for every other type. */
+export declare function thinkingText(e: SessionEvent): string;
+export interface ToolCall {
+    phase: 'start' | 'end' | 'blocked';
+    toolName: string;
+    toolCallId: string;
+    args?: Record<string, unknown>;
+    isError?: boolean;
+    resultPreview?: string;
+}
+/**
+ * Tool activity for an `agent.tool` event; undefined for every other type.
+ *
+ * One tool call produces TWO events sharing a `toolCallId`: `phase: 'start'` carries `args`,
+ * `phase: 'end'` carries `isError` and `resultPreview`. Pair them by `toolCallId` — they are
+ * NOT adjacent in the stream when calls run concurrently.
+ *
+ * `phase: 'blocked'` is a third state (see the Events reference): the call is waiting on an
+ * approval and has NOT run. Treat it as pending, not as an end — the matching `agent.approval`
+ * event carries the request, and an `end` still follows once it resolves.
+ */
+export declare function toolCall(e: SessionEvent): ToolCall | undefined;

package/dist/events.js

@@ -0,0 +1,151 @@
+/**
+ * Session event normalization.
+ *
+ * The wire presents the SAME event in different shapes depending on where you read it:
+ *
+ *   unified lane (default)     → { id, seq, event_type, run_id, turn, payload, processed_at, created_at }
+ *                                on BOTH transports; the SSE `id:` line carries a `pse1:` resume token
+ *   deprecated `after` lane    → REST { seq, run_id, ... } stays snake_case, SSE frames arrive
+ *                                camelCase { seq, runId, eventType, createdAt, ... }
+ *
+ * No shape carries a top-level `type`. `normalizeEvent` absorbs all of them once, so callers
+ * switch on a single field. Legacy shapes verified against staging 2026-08-05; unified lane
+ * (input echo, pse1 cursors, idempotent postEvents) verified 2026-08-19.
+ *
+ * The vocabulary is SESSION_EVENT_TYPES plus PUBLIC_INPUT_EVENT_TYPES, mirrored from the API.
+ * Unknown types pass through unchanged rather than throwing — the API is Developer Preview
+ * and may add types within a version.
+ */
+/** SESSION_EVENT_TYPES, mirrored from the API. */
+export const SESSION_EVENT_TYPES = [
+    'run.started',
+    'run.finished',
+    'chat.delta',
+    'chat.final',
+    'chat.aborted',
+    'chat.error',
+    'agent.lifecycle',
+    'agent.assistant',
+    'agent.thinking',
+    'agent.tool',
+    'agent.item',
+    'agent.plan',
+    'agent.approval',
+    'agent.command_output',
+    'agent.patch',
+    'agent.compaction',
+    'agent.error',
+    'attachment.created',
+    'message.outbound',
+];
+/** Your own inputs, echoed back in the unified event history. */
+export const PUBLIC_INPUT_EVENT_TYPES = [
+    'user.message',
+    'user.interrupt',
+    'user.tool_confirmation',
+    'system.message',
+];
+const isObj = (v) => !!v && typeof v === 'object';
+const str = (v) => (typeof v === 'string' ? v : undefined);
+/** Accepts either wire shape (and an SSE `id:` line as the seq fallback). */
+export function normalizeEvent(raw, sseId) {
+    const r = isObj(raw) ? raw : {};
+    let seq = typeof r.seq === 'number' ? r.seq : -1;
+    // A bare-integer id is the deprecated lane's seq; any other id is an opaque resume token,
+    // so a future token version keeps stamping `cursor` (only the seq fallback pins `pse1:`).
+    const numericId = sseId !== undefined ? Number(sseId) : Number.NaN;
+    const cursor = sseId !== undefined && !Number.isFinite(numericId) ? sseId : undefined;
+    if (seq < 0 && sseId !== undefined) {
+        const n = cursor === undefined ? numericId : Number(sseId.startsWith('pse1:') ? sseId.slice(5) : Number.NaN);
+        if (Number.isFinite(n))
+            seq = n;
+    }
+    const turn = typeof r.turn === 'number' ? r.turn : undefined;
+    const processedAt = 'processed_at' in r ? (str(r.processed_at) ?? null) : undefined;
+    return {
+        seq,
+        eventType: str(r.eventType) ?? str(r.event_type) ?? '',
+        payload: isObj(r.payload) ? r.payload : {},
+        ...(str(r.runId) ?? str(r.run_id) ? { runId: (str(r.runId) ?? str(r.run_id)) } : {}),
+        ...(turn !== undefined ? { turn } : {}),
+        ...(str(r.createdAt) ?? str(r.created_at) ? { createdAt: (str(r.createdAt) ?? str(r.created_at)) } : {}),
+        ...(str(r.id) ? { id: str(r.id) } : {}),
+        ...(processedAt !== undefined ? { processedAt } : {}),
+        ...(cursor !== undefined ? { cursor } : {}),
+    };
+}
+/**
+ * A run ends with `run.finished`. Its `payload.status` is `succeeded` | `failed` | `aborted`.
+ *
+ * Note that a run can finish `succeeded` even when individual tool calls errored — an
+ * `agent.tool` event with `payload.isError === true` does not fail the run. Do not infer
+ * turn success from the absence of tool errors.
+ */
+export function isRunFinished(e) {
+    return e.eventType === 'run.finished';
+}
+export function runOutcome(e) {
+    if (!isRunFinished(e))
+        return undefined;
+    const s = e.payload.status;
+    return s === 'succeeded' || s === 'failed' || s === 'aborted' ? s : undefined;
+}
+/**
+ * Text of one chat message — the `{ role, content }` shape that appears both as an
+ * `agent.assistant` event's `payload.message` and as a transcript row's `entry.message`.
+ *
+ * `content` is normally an array of blocks; only `{ type: 'text', text }` blocks carry
+ * text (tool-call blocks don't), and one message may hold several. A plain string is
+ * accepted too — that is how write-side `user.message` content comes back.
+ */
+export function messageText(message) {
+    if (!isObj(message))
+        return '';
+    const c = message.content;
+    if (typeof c === 'string')
+        return c;
+    if (!Array.isArray(c))
+        return '';
+    return c.map((b) => (isObj(b) && b.type === 'text' && typeof b.text === 'string' ? b.text : '')).join('');
+}
+/**
+ * Assistant text for an `agent.assistant` event; '' for every other event type.
+ *
+ * The text lives at `payload.message.content[]` — see `messageText`.
+ */
+export function assistantText(e) {
+    if (e.eventType !== 'agent.assistant')
+        return '';
+    return messageText(e.payload.message);
+}
+/** Reasoning text for an `agent.thinking` event; '' for every other type. */
+export function thinkingText(e) {
+    if (e.eventType !== 'agent.thinking')
+        return '';
+    return typeof e.payload.text === 'string' ? e.payload.text : '';
+}
+/**
+ * Tool activity for an `agent.tool` event; undefined for every other type.
+ *
+ * One tool call produces TWO events sharing a `toolCallId`: `phase: 'start'` carries `args`,
+ * `phase: 'end'` carries `isError` and `resultPreview`. Pair them by `toolCallId` — they are
+ * NOT adjacent in the stream when calls run concurrently.
+ *
+ * `phase: 'blocked'` is a third state (see the Events reference): the call is waiting on an
+ * approval and has NOT run. Treat it as pending, not as an end — the matching `agent.approval`
+ * event carries the request, and an `end` still follows once it resolves.
+ */
+export function toolCall(e) {
+    if (e.eventType !== 'agent.tool')
+        return undefined;
+    const p = e.payload;
+    const phase = p.phase === 'end' ? 'end' : p.phase === 'blocked' ? 'blocked' : 'start';
+    return {
+        phase,
+        toolName: typeof p.toolName === 'string' ? p.toolName : '',
+        toolCallId: typeof p.toolCallId === 'string' ? p.toolCallId : '',
+        ...(isObj(p.args) ? { args: p.args } : {}),
+        ...(typeof p.isError === 'boolean' ? { isError: p.isError } : {}),
+        ...(typeof p.resultPreview === 'string' ? { resultPreview: p.resultPreview } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient, type ZooworkConfig, type ZooworkAuth, type Ownership, type ModelInfo, type AgentResource, type AgentRecord, type AgentStatus, type AgentSkill, type AgentChannel, type ChannelPlatform, type AddChannelInput, type UpdateChannelInput, type FeishuSetupInput, type FeishuSetupSession, type FeishuPollResult, type McpServerDeclaration, type SkillRecord, type SessionRecord, type SessionHistoryEntry, type SessionEvent, type SessionEventPage, type OutboundEvent, type PostEventReceipt, type ApprovalDecision, type ApprovalRecord, type ArtifactPage, type ArtifactRecord, type ArtifactStatus, type OutcomeConfig, type OutcomeEvaluator, type SystemPromptDeclaration, type SystemPromptInfo, type SystemPromptPreview, type SystemPromptPreviewInput, type SystemPromptUpgrade, type ScheduleSpec, type SchedulePayload, type ScheduleInput, type ScheduleUpdate, type ScheduleRecord, type ScheduleRun, type WakeResult, type ExecResult, type EnvironmentConfig, type EnvironmentResource, type EnvironmentRecord, type EnvironmentVersionRecord, } from './client.js';
+export { SESSION_EVENT_TYPES, type SessionEventType, PUBLIC_INPUT_EVENT_TYPES, type PublicInputEventType, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, toolCall, type ToolCall, } from './events.js';
+export { parseSSE, type SSEMessage } from './sse.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, } from './client.js';
+export { SESSION_EVENT_TYPES, PUBLIC_INPUT_EVENT_TYPES, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, toolCall, } from './events.js';
+export { parseSSE } from './sse.js';

package/dist/sse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SSE line parser for the `/events/stream` endpoint endpoint.
+ *
+ * Ported from zoowork-app-kit server/zooclaw/sse.ts — that parser is correct against the
+ * live wire and needed no changes. The `id:` field matters: The server frames each durable
+ * event as `id: <seq>` + `data: <json>`, so dropping the id line would freeze the resume
+ * cursor. Web Streams + TextDecoder only, so this runs in workers and browsers as well as
+ * Node.
+ */
+export interface SSEMessage {
+    event: string;
+    /** The SSE `id:` field — the durable seq for the API event frames. */
+    id?: string;
+    data: unknown;
+}
+export declare const isObj: (v: unknown) => v is Record<string, unknown>;
+export declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEMessage>;

package/dist/sse.js

@@ -0,0 +1,69 @@
+/**
+ * SSE line parser for the `/events/stream` endpoint endpoint.
+ *
+ * Ported from zoowork-app-kit server/zooclaw/sse.ts — that parser is correct against the
+ * live wire and needed no changes. The `id:` field matters: The server frames each durable
+ * event as `id: <seq>` + `data: <json>`, so dropping the id line would freeze the resume
+ * cursor. Web Streams + TextDecoder only, so this runs in workers and browsers as well as
+ * Node.
+ */
+export const isObj = (v) => !!v && typeof v === 'object';
+export async function* parseSSE(body) {
+    const reader = body.getReader();
+    const dec = new TextDecoder('utf-8');
+    let buf = '';
+    let event = 'message';
+    let id;
+    let dataLines = [];
+    const flush = () => {
+        if (!dataLines.length && event === 'message' && id === undefined)
+            return null;
+        const s = dataLines.join('\n');
+        let data = s;
+        if (s) {
+            try {
+                data = JSON.parse(s);
+            }
+            catch {
+                /* not JSON — keep the raw string */
+            }
+        }
+        const msg = { event, data, ...(id !== undefined ? { id } : {}) };
+        event = 'message';
+        id = undefined;
+        dataLines = [];
+        return msg;
+    };
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buf += dec.decode(value, { stream: true });
+        let i;
+        while ((i = buf.indexOf('\n')) >= 0) {
+            const raw = buf.slice(0, i);
+            buf = buf.slice(i + 1);
+            const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+            if (line === '') {
+                const m = flush();
+                if (m)
+                    yield m;
+                continue;
+            }
+            if (line.startsWith(':'))
+                continue;
+            const c = line.indexOf(':');
+            const field = c === -1 ? line : line.slice(0, c);
+            const val = c === -1 ? '' : line.slice(c + 1).replace(/^ /, '');
+            if (field === 'event')
+                event = val;
+            else if (field === 'data')
+                dataLines.push(val);
+            else if (field === 'id')
+                id = val;
+        }
+    }
+    const m = flush();
+    if (m)
+        yield m;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zoowork-ai/sdk",
+  "version": "0.4.0",
+  "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
+  "keywords": [
+    "zoowork",
+    "agents",
+    "sdk",
+    "llm",
+    "sse",
+    "streaming"
+  ],
+  "homepage": "https://github.com/SerendipityOneInc/zoowork-sdk-typescript#readme",
+  "bugs": "https://github.com/SerendipityOneInc/zoowork-sdk-typescript/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SerendipityOneInc/zoowork-sdk-typescript.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit && vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.7",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}