@orkestrate/sdk 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# `@orkestrate/sdk`
+
+Publisher HTTP handler for [Orkestrate](https://orkestrate.space).
+
+**What you get:** secret check, session id, caller model (BYOM), JSON wire.  
+**What you own:** chat history — same as any AI SDK app. Use `sessionId` as your chat key.
+
+## Install
+
+```bash
+npm install @orkestrate/sdk ai
+```
+
+## Primitives (any framework)
+
+```ts
+import { verifyRequest, parseRequest, buildModel, respond } from "@orkestrate/sdk";
+
+async function handler(request: Request) {
+  verifyRequest(request, process.env.ORKESTRATE_SECRET!);
+  const { action, sessionId, message, modelConfig, messages } =
+    await parseRequest(request);
+
+  switch (action) {
+    case "ping":
+      return respond.ok();
+    case "end_session":
+      return respond.ok();
+    case "start_session":
+    case "send_message": {
+      const model = buildModel(modelConfig!);
+      const reply = await runAgent({
+        message: message!,
+        model,
+        sessionId: sessionId!,
+        messages: messages!,
+      });
+      return respond.reply(reply);
+    }
+  }
+}
+```
+
+## Usage with AI SDK (convenience)
+
+Same primitives, but `createOrkestrateHandler` wires them for you:
+
+```ts
+// app/api/orkestrate/route.ts
+import { createOrkestrateHandler } from "@orkestrate/sdk";
+import { generateText } from "ai";
+
+export const { GET, POST } = createOrkestrateHandler({
+  secret: process.env.ORKESTRATE_SECRET!,
+
+  async onTurn({ message, model, messages, callerId }) {
+    // messages is the full conversation — gateway handles storage
+    const result = await generateText({ model, messages });
+    return { reply: result.text };
+  },
+});
+```
+
+## Wire (gateway → you)
+
+| Header | When |
+|--------|------|
+| `Authorization: Bearer <secret>` | always on POST |
+| `X-Orkestrate-Action` | `start_session` \| `send_message` \| `end_session` \| `ping` |
+| `X-Orkestrate-Session-Id` | open / send / close |
+| `X-Orkestrate-Model` | open / send — base64url JSON `{ provider, model, apiKey, baseURL? }` |
+| `X-Orkestrate-Caller-Id` | optional |
+
+Body open/send: `{ "message": "...", "messages": [{ role, content }, ...] }`  
+Success: `{ "reply": "..." }` or `{ "ok": true }`
+
+Session ids are **minted by Orkestrate**. You never invent them for this path.
+
+## Error codes
+
+| Code | HTTP | Meaning |
+|------|------|---------|
+| `UNAUTHORIZED` | 401 | Bad or missing `Authorization` header |
+| `BAD_REQUEST` | 400 | Missing header, invalid body, bad model config |
+| `MODEL_ERROR` | 400 | `buildModel` rejected the config (e.g. unknown provider) |
+| `SESSION_NOT_FOUND` | 500 | Session id does not exist |
+| `SESSION_EXPIRED` | 500 | Session has expired (idle or hard TTL) |
+| `SESSION_STALE` | 500 | Session data is stale |
+| `CONFLICT` | 500 | Concurrent operation on the same session |
+| `LIMIT_EXCEEDED` | 500 | Turn limit or rate limit hit |
+| `INTERNAL` | 500 | `onTurn` threw or returned an empty reply |
+
+## Notes
+
+- **`ai` peer dependency:** `npm install @orkestrate/sdk ai` if you use `createOrkestrateHandler` or call `generateText`. If you only use the primitives, you can ignore the peer dep warning — `ai` is not required at runtime.
+- **Streaming:** V1 is text-turn only. `respond.reply` sends one string. Streaming (`streamText`, SSE) is not yet supported.
+- **`custom` provider:** Assumes an OpenAI-compatible API (OpenAI SDK shape). For Ollama, vLLM, etc. that serve an OpenAI-compatible `/chat/completions`.
+- **Package size:** `@orkestrate/sdk` depends on `@ai-sdk/openai`, `@ai-sdk/anthropic`, and `@ai-sdk/google` regardless of which provider you use.
+
+## Not included (on purpose)
+
+- Built-in chat store  
+- MCP server  
+- OAuth / dashboard  
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Verify that `request` carries a valid `Authorization: Bearer <secret>`.
+ * Throws `OrkestrateError("UNAUTHORIZED")` on failure.
+ */
+export declare function verifyRequest(request: Request, secret: string): void;

package/dist/auth.js

@@ -0,0 +1,41 @@
+import { timingSafeEqual } from "node:crypto";
+import { OrkestrateError } from "./errors";
+/**
+ * Verify that `request` carries a valid `Authorization: Bearer <secret>`.
+ * Throws `OrkestrateError("UNAUTHORIZED")` on failure.
+ */
+export function verifyRequest(request, secret) {
+    if (!secret) {
+        throw new OrkestrateError("INTERNAL", "Publisher secret is not configured", 500);
+    }
+    const header = request.headers.get("authorization");
+    if (!header) {
+        throw new OrkestrateError("UNAUTHORIZED", "Missing Authorization header");
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    if (!match?.[1]) {
+        throw new OrkestrateError("UNAUTHORIZED", "Authorization must be Bearer <secret>");
+    }
+    const token = match[1].trim();
+    if (!secretsEqual(token, secret)) {
+        throw new OrkestrateError("UNAUTHORIZED", "Invalid secret");
+    }
+}
+/**
+ * Constant-time comparison of two strings.
+ *
+ * On length mismatch we compare `a` against itself so that callers cannot
+ * distinguish "wrong length" from "wrong content" by timing alone. The
+ * branch (return false vs. continue) still leaks ~1 bit — acceptable for a
+ * shared-secret check against remote timing noise but not for password
+ * hashing.
+ */
+function secretsEqual(a, b) {
+    const aBuf = Buffer.from(a, "utf8");
+    const bBuf = Buffer.from(b, "utf8");
+    if (aBuf.length !== bBuf.length) {
+        timingSafeEqual(aBuf, aBuf);
+        return false;
+    }
+    return timingSafeEqual(aBuf, bBuf);
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/** Wire error codes returned to the gateway. */
+export type OrkestrateErrorCode = "UNAUTHORIZED" | "BAD_REQUEST" | "MODEL_ERROR" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "SESSION_STALE" | "CONFLICT" | "LIMIT_EXCEEDED" | "INTERNAL";
+export declare class OrkestrateError extends Error {
+    readonly code: OrkestrateErrorCode;
+    readonly status: number;
+    constructor(code: OrkestrateErrorCode, message: string, status?: number);
+}
+/** Wire-format response builders. */
+export declare const respond: {
+    ok: (extra?: Record<string, unknown>) => Response;
+    reply: (text: string) => Response;
+    error: (code: OrkestrateErrorCode, message: string, status?: number) => Response;
+};
+/**
+ * Convert any thrown error to a wire-format Response.
+ * @internal used by createOrkestrateHandler
+ */
+export declare function toErrorResponse(error: unknown): Response;

package/dist/errors.js

@@ -0,0 +1,34 @@
+function defaultStatus(code) {
+    return code === "UNAUTHORIZED"
+        ? 401
+        : code === "BAD_REQUEST" || code === "MODEL_ERROR"
+            ? 400
+            : 500;
+}
+export class OrkestrateError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = "OrkestrateError";
+        this.code = code;
+        this.status = status ?? defaultStatus(code);
+    }
+}
+/** Wire-format response builders. */
+export const respond = {
+    ok: (extra) => Response.json({ ok: true, ...extra }),
+    reply: (text) => Response.json({ reply: text }),
+    error: (code, message, status) => Response.json({ error: { code, message } }, { status: status ?? defaultStatus(code) }),
+};
+/**
+ * Convert any thrown error to a wire-format Response.
+ * @internal used by createOrkestrateHandler
+ */
+export function toErrorResponse(error) {
+    if (error instanceof OrkestrateError) {
+        return respond.error(error.code, error.message, error.status);
+    }
+    const message = error instanceof Error ? error.message : "Internal error";
+    return respond.error("INTERNAL", message);
+}

package/dist/handler.d.ts

@@ -0,0 +1,10 @@
+import type { CreateOrkestrateHandlerOptions, OrkestrateHandlers } from "./types";
+/**
+ * Create GET + POST handlers for a Next.js (or any) route.
+ *
+ * Thin convenience over the SDK primitives:
+ *   verifyRequest → parseRequest → buildModel → onTurn → respond
+ *
+ * For full control, import the primitives directly.
+ */
+export declare function createOrkestrateHandler(options: CreateOrkestrateHandlerOptions): OrkestrateHandlers;

package/dist/handler.js

@@ -0,0 +1,92 @@
+import { verifyRequest } from "./auth";
+import { OrkestrateError, toErrorResponse } from "./errors";
+import { buildModel } from "./model";
+import { parseRequest } from "./protocol";
+import { respond } from "./errors";
+const PROTOCOL_VERSION = 1;
+/**
+ * Create GET + POST handlers for a Next.js (or any) route.
+ *
+ * Thin convenience over the SDK primitives:
+ *   verifyRequest → parseRequest → buildModel → onTurn → respond
+ *
+ * For full control, import the primitives directly.
+ */
+export function createOrkestrateHandler(options) {
+    if (!options?.secret || typeof options.secret !== "string") {
+        throw new Error("createOrkestrateHandler: `secret` is required");
+    }
+    if (typeof options.onTurn !== "function") {
+        throw new Error("createOrkestrateHandler: `onTurn` is required");
+    }
+    const { secret, onTurn, onClose } = options;
+    async function GET(_request) {
+        return respond.ok({ protocol: PROTOCOL_VERSION });
+    }
+    async function POST(request) {
+        try {
+            verifyRequest(request, secret);
+            const parsed = await parseRequest(request);
+            switch (parsed.action) {
+                case "ping":
+                    return respond.ok();
+                case "end_session": {
+                    if (onClose) {
+                        await onClose({
+                            sessionId: parsed.sessionId,
+                            callerId: parsed.callerId,
+                        });
+                    }
+                    return respond.ok();
+                }
+                case "start_session":
+                case "send_message": {
+                    if (!parsed.sessionId) {
+                        return respond.error("BAD_REQUEST", "Missing session id");
+                    }
+                    if (!parsed.message) {
+                        return respond.error("BAD_REQUEST", "Missing message");
+                    }
+                    if (!parsed.modelConfig) {
+                        return respond.error("BAD_REQUEST", "Missing caller model config");
+                    }
+                    if (!parsed.messages || parsed.messages.length === 0) {
+                        return respond.error("BAD_REQUEST", "Missing or empty messages");
+                    }
+                    const model = buildModel(parsed.modelConfig);
+                    let result;
+                    try {
+                        result = await onTurn({
+                            sessionId: parsed.sessionId,
+                            message: parsed.message,
+                            messages: parsed.messages,
+                            model,
+                            action: parsed.action,
+                            callerId: parsed.callerId,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof OrkestrateError)
+                            throw error;
+                        const msg = error instanceof Error ? error.message : "Turn failed";
+                        throw new OrkestrateError("INTERNAL", msg);
+                    }
+                    if (!result ||
+                        typeof result.reply !== "string" ||
+                        result.reply.length === 0) {
+                        throw new OrkestrateError("INTERNAL", "onTurn must return { reply: non-empty string }");
+                    }
+                    return respond.reply(result.reply);
+                }
+                default: {
+                    const _never = parsed.action;
+                    throw new OrkestrateError("BAD_REQUEST", `Unknown action: ${String(_never)}`);
+                }
+            }
+        }
+        catch (error) {
+            return toErrorResponse(error);
+        }
+    }
+    return { GET, POST };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @orkestrate/sdk
+ *
+ * Publisher SDK for the Orkestrate agent gateway.
+ *
+ * Primitives (any framework):
+ *   verifyRequest   — authenticate incoming gateway requests
+ *   parseRequest    — decode gateway headers + body
+ *   buildModel      — build an AI SDK LanguageModel from caller's BYOM config
+ *   respond         — wire-format response builders (.ok / .reply / .error)
+ *
+ * Convenience (AI SDK):
+ *   createOrkestrateHandler  — calls the above in order for generateText users
+ *
+ * Types:
+ *   CallerModelConfig, ParsedRequest, SessionMessage, TurnContext, CloseContext,
+ *   TurnResult, CreateOrkestrateHandlerOptions, OrkestrateHandlers, OrkestrateAction
+ */
+export { verifyRequest } from "./auth";
+export { parseRequest, encodeModelConfig } from "./protocol";
+export { buildModel } from "./model";
+export { respond, OrkestrateError } from "./errors";
+export type { OrkestrateErrorCode } from "./errors";
+export { createOrkestrateHandler } from "./handler";
+export type { CallerModelConfig, CloseContext, CreateOrkestrateHandlerOptions, OrkestrateAction, OrkestrateHandlers, ParsedRequest, SessionMessage, TurnContext, TurnResult, } from "./types";

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @orkestrate/sdk
+ *
+ * Publisher SDK for the Orkestrate agent gateway.
+ *
+ * Primitives (any framework):
+ *   verifyRequest   — authenticate incoming gateway requests
+ *   parseRequest    — decode gateway headers + body
+ *   buildModel      — build an AI SDK LanguageModel from caller's BYOM config
+ *   respond         — wire-format response builders (.ok / .reply / .error)
+ *
+ * Convenience (AI SDK):
+ *   createOrkestrateHandler  — calls the above in order for generateText users
+ *
+ * Types:
+ *   CallerModelConfig, ParsedRequest, SessionMessage, TurnContext, CloseContext,
+ *   TurnResult, CreateOrkestrateHandlerOptions, OrkestrateHandlers, OrkestrateAction
+ */
+/* Primitives */
+export { verifyRequest } from "./auth";
+export { parseRequest, encodeModelConfig } from "./protocol";
+export { buildModel } from "./model";
+export { respond, OrkestrateError } from "./errors";
+/* Convenience */
+export { createOrkestrateHandler } from "./handler";

package/dist/model.d.ts

@@ -0,0 +1,7 @@
+import type { LanguageModel } from "ai";
+import type { CallerModelConfig } from "./types";
+/**
+ * Build an AI SDK language model from the caller's BYOM config.
+ * Eng never pastes provider keys for Orkestrate traffic.
+ */
+export declare function buildModel(config: CallerModelConfig): LanguageModel;

package/dist/model.js

@@ -0,0 +1,52 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAI } from "@ai-sdk/openai";
+import { OrkestrateError } from "./errors";
+/**
+ * Build an AI SDK language model from the caller's BYOM config.
+ * Eng never pastes provider keys for Orkestrate traffic.
+ */
+export function buildModel(config) {
+    try {
+        switch (config.provider) {
+            case "openai": {
+                const openai = createOpenAI({
+                    apiKey: config.apiKey,
+                    ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+                });
+                return openai.chat(config.model);
+            }
+            case "anthropic": {
+                const anthropic = createAnthropic({
+                    apiKey: config.apiKey,
+                    ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+                });
+                return anthropic(config.model);
+            }
+            case "google": {
+                const google = createGoogleGenerativeAI({
+                    apiKey: config.apiKey,
+                    ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+                });
+                return google(config.model);
+            }
+            case "custom": {
+                const openai = createOpenAI({
+                    apiKey: config.apiKey,
+                    baseURL: config.baseURL,
+                });
+                return openai.chat(config.model);
+            }
+            default: {
+                const _exhaustive = config.provider;
+                throw new OrkestrateError("MODEL_ERROR", `Unsupported provider: ${String(_exhaustive)}`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof OrkestrateError)
+            throw error;
+        const message = error instanceof Error ? error.message : "Failed to build model";
+        throw new OrkestrateError("MODEL_ERROR", message);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,14 @@
+import type { CallerModelConfig, ParsedRequest, SessionMessage } from "./types";
+export declare const HEADER_SESSION_ID = "x-orkestrate-session-id";
+export declare const HEADER_ACTION = "x-orkestrate-action";
+export declare const HEADER_CALLER_ID = "x-orkestrate-caller-id";
+export declare const HEADER_MODEL = "x-orkestrate-model";
+/**
+ * Parse the gateway's HTTP request into typed fields.
+ * Throws `OrkestrateError("BAD_REQUEST")` on invalid input.
+ */
+export declare function parseRequest(request: Request): Promise<ParsedRequest>;
+/** Validate and parse messages from the body. */
+export declare function parseMessages(raw: unknown, message?: string): SessionMessage[];
+/** Encode model config for tests / gateway. Never log the result. */
+export declare function encodeModelConfig(config: CallerModelConfig): string;

package/dist/protocol.js

@@ -0,0 +1,132 @@
+import { OrkestrateError } from "./errors";
+export const HEADER_SESSION_ID = "x-orkestrate-session-id";
+export const HEADER_ACTION = "x-orkestrate-action";
+export const HEADER_CALLER_ID = "x-orkestrate-caller-id";
+export const HEADER_MODEL = "x-orkestrate-model";
+const ACTIONS = new Set([
+    "start_session",
+    "send_message",
+    "end_session",
+    "ping",
+]);
+/**
+ * Parse the gateway's HTTP request into typed fields.
+ * Throws `OrkestrateError("BAD_REQUEST")` on invalid input.
+ */
+export async function parseRequest(request) {
+    const actionRaw = request.headers.get(HEADER_ACTION)?.trim();
+    if (!actionRaw || !ACTIONS.has(actionRaw)) {
+        throw new OrkestrateError("BAD_REQUEST", `Missing or invalid ${HEADER_ACTION}. Expected start_session | send_message | end_session | ping`);
+    }
+    const action = actionRaw;
+    const sessionId = request.headers.get(HEADER_SESSION_ID)?.trim() || undefined;
+    const callerId = request.headers.get(HEADER_CALLER_ID)?.trim() || undefined;
+    let body = {};
+    const text = await request.text();
+    if (text.trim()) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new OrkestrateError("BAD_REQUEST", "Body must be JSON");
+        }
+    }
+    if (body !== null && typeof body !== "object") {
+        throw new OrkestrateError("BAD_REQUEST", "Body must be a JSON object");
+    }
+    const record = (body ?? {});
+    const message = typeof record.message === "string" ? record.message : undefined;
+    let modelConfig;
+    const modelHeader = request.headers.get(HEADER_MODEL)?.trim();
+    if (modelHeader) {
+        modelConfig = decodeModelConfig(modelHeader);
+    }
+    let messages;
+    if (action === "start_session" || action === "send_message") {
+        messages = parseMessages(record.messages, message);
+    }
+    return { action, sessionId, callerId, message, modelConfig, messages };
+}
+function decodeModelConfig(header) {
+    let json;
+    try {
+        json = Buffer.from(header, "base64url").toString("utf8");
+    }
+    catch {
+        throw new OrkestrateError("BAD_REQUEST", `${HEADER_MODEL} must be base64url-encoded JSON`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new OrkestrateError("BAD_REQUEST", `${HEADER_MODEL} must be base64url-encoded JSON`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new OrkestrateError("BAD_REQUEST", "Invalid model config");
+    }
+    const o = parsed;
+    const provider = o.provider;
+    const model = o.model;
+    const apiKey = o.apiKey;
+    const baseURL = o.baseURL;
+    if (provider !== "openai" &&
+        provider !== "anthropic" &&
+        provider !== "google" &&
+        provider !== "custom") {
+        throw new OrkestrateError("BAD_REQUEST", 'model.provider must be "openai" | "anthropic" | "google" | "custom"');
+    }
+    if (typeof model !== "string" || !model) {
+        throw new OrkestrateError("BAD_REQUEST", "model.model must be a non-empty string");
+    }
+    if (typeof apiKey !== "string" || !apiKey) {
+        throw new OrkestrateError("BAD_REQUEST", "model.apiKey must be a non-empty string");
+    }
+    if (baseURL !== undefined && typeof baseURL !== "string") {
+        throw new OrkestrateError("BAD_REQUEST", "model.baseURL must be a string when set");
+    }
+    if (provider === "custom" && !baseURL) {
+        throw new OrkestrateError("BAD_REQUEST", 'model.baseURL is required when provider is "custom"');
+    }
+    return {
+        provider,
+        model,
+        apiKey,
+        ...(typeof baseURL === "string" ? { baseURL } : {}),
+    };
+}
+/** Validate and parse messages from the body. */
+export function parseMessages(raw, message) {
+    if (!Array.isArray(raw)) {
+        throw new OrkestrateError("BAD_REQUEST", "Body.messages must be a non-empty array of { role, content }");
+    }
+    if (raw.length === 0) {
+        throw new OrkestrateError("BAD_REQUEST", "Body.messages must be a non-empty array of { role, content }");
+    }
+    for (const m of raw) {
+        if (!m || typeof m !== "object") {
+            throw new OrkestrateError("BAD_REQUEST", "Each messages entry must be { role: 'user' | 'assistant', content: string }");
+        }
+        const o = m;
+        if (o.role !== "user" && o.role !== "assistant") {
+            throw new OrkestrateError("BAD_REQUEST", "Each messages entry must have role 'user' or 'assistant'");
+        }
+        if (typeof o.content !== "string" || !o.content) {
+            throw new OrkestrateError("BAD_REQUEST", "Each messages entry must have non-empty content string");
+        }
+    }
+    const msgs = raw;
+    // Consistency: last message must match the `message` field
+    const last = msgs[msgs.length - 1];
+    if (last.role !== "user") {
+        throw new OrkestrateError("BAD_REQUEST", "Last message in messages must be from user");
+    }
+    if (message !== undefined && last.content !== message) {
+        throw new OrkestrateError("BAD_REQUEST", "Body.message must match the last user message in messages");
+    }
+    return msgs;
+}
+/** Encode model config for tests / gateway. Never log the result. */
+export function encodeModelConfig(config) {
+    return Buffer.from(JSON.stringify(config), "utf8").toString("base64url");
+}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+import type { LanguageModel } from "ai";
+/** Actions the gateway may send on POST. */
+export type OrkestrateAction = "start_session" | "send_message" | "end_session" | "ping";
+/**
+ * Caller model config (BYOM). Sent by the gateway as
+ * `X-Orkestrate-Model` (base64url JSON). Built into an AI SDK model for you.
+ */
+export type CallerModelConfig = {
+    provider: "openai" | "anthropic" | "google" | "custom";
+    model: string;
+    apiKey: string;
+    /** Required for `custom`; optional override for openai-compatible hosts. */
+    baseURL?: string;
+};
+/** A single turn in the session conversation history. */
+export type SessionMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+/** Result of parsing a gateway request. */
+export type ParsedRequest = {
+    action: OrkestrateAction;
+    sessionId?: string;
+    callerId?: string;
+    message?: string;
+    modelConfig?: CallerModelConfig;
+    /** Full conversation history, including the latest user message. */
+    messages?: SessionMessage[];
+};
+export type TurnContext = {
+    /** Gateway-minted session id. Use this as your chat id. */
+    sessionId: string;
+    /** The new user text for this turn (also last element of `messages`). */
+    message: string;
+    /** Full conversation history including the latest user turn. */
+    messages: SessionMessage[];
+    /** Ready for `generateText` / `streamText` / agents. */
+    model: LanguageModel;
+    action: "start_session" | "send_message";
+    /** Opaque Clerk user id when the gateway sends it. */
+    callerId?: string;
+};
+export type CloseContext = {
+    sessionId: string;
+    callerId?: string;
+};
+export type TurnResult = {
+    reply: string;
+};
+export type CreateOrkestrateHandlerOptions = {
+    /** Shared secret from the Orkestrate dashboard (registration). */
+    secret: string;
+    /**
+     * Run one agent turn.
+     * The gateway forwards `messages` (full conversation history) on every turn.
+     * Eng can feed `ctx.messages` directly into `generateText` — no DB needed.
+     */
+    onTurn: (ctx: TurnContext) => Promise<TurnResult>;
+    /**
+     * Optional cleanup when the gateway closes a session.
+     * Safe to omit; response is still `{ ok: true }`.
+     */
+    onClose?: (ctx: CloseContext) => Promise<void>;
+};
+export type OrkestrateHandlers = {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@orkestrate/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Publisher HTTP handler for Orkestrate — auth, session id, BYOM model, your turn.",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.15",
+    "@ai-sdk/google": "^4.0.17",
+    "@ai-sdk/openai": "^4.0.15"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "ai": "^7.0.29",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/system1970/orkestrate.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://orkestrate.space"
+}