@m8t-stack/platform-sdk 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# `@m8t-stack/platform-sdk`
+
+> 📦 The one import for integrating with an m8t-stack gateway: `npm i @m8t-stack/platform-sdk`
+
+A thin, typed client for the m8t gateway HTTP API. Acquires a service-principal token from a pluggable Azure credential (default `DefaultAzureCredential`, secretless via Managed Identity), invokes workers, streams replies, and **re-exports all of [`@m8t-stack/api-contract`](../api-contract)** so you import types from one place.
+
+## Quick start
+
+```ts
+import { PlatformClient } from "@m8t-stack/platform-sdk";
+
+const client = new PlatformClient({
+  gatewayUrl: "https://your-gateway.example.com",
+  audience: "api://<gateway-app-client-id>",
+});
+
+const { id } = await client.createConversation({ agentName: "stacey" });
+const stream = client.invoke({ agentName: "stacey", conversationId: id, message: "Hello!" });
+for await (const ev of stream) {
+  if (ev.type === "text") process.stdout.write(ev.delta);
+}
+```
+
+The default credential resolves a token for `${audience}/.default`. The token's app role must include `Agents.Invoke` (see the gateway operator setup). Pass any `@azure/core-auth` `TokenCredential` as `credential` to override.
+
+See [versioning & deprecation policy](../../docs/versioning-and-deprecation.md). Full runnable example: [`examples/stream-reply.ts`](./examples/stream-reply.ts).

package/dist/cjs/client.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformClient = void 0;
+const identity_1 = require("@azure/identity");
+const api_contract_1 = require("@m8t-stack/api-contract");
+const credential_js_1 = require("./credential.js");
+const errors_js_1 = require("./errors.js");
+const stream_js_1 = require("./stream.js");
+/**
+ * Typed client for an m8t-stack gateway. Authenticates as a service principal
+ * (or any TokenCredential) and calls the gateway HTTP API — never Foundry directly.
+ */
+class PlatformClient {
+    #base;
+    #audience;
+    #credential;
+    #fetch;
+    constructor(options) {
+        this.#base = options.gatewayUrl.replace(/\/+$/, "");
+        this.#audience = options.audience;
+        this.#credential = options.credential ?? new identity_1.DefaultAzureCredential();
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async #token() {
+        return (0, credential_js_1.acquireGatewayToken)(this.#credential, this.#audience);
+    }
+    async #authHeaders(extra) {
+        return { authorization: `Bearer ${await this.#token()}`, ...extra };
+    }
+    /** Build a PlatformApiError from a gateway error envelope + the HTTP status. */
+    #envelopeError(error, status) {
+        return new errors_js_1.PlatformApiError(error.code, error.message, error.details, status);
+    }
+    /** Call a JSON gateway route and unwrap its ApiResponse envelope, throwing on error. */
+    async #json(path, init) {
+        const res = await this.#fetch(`${this.#base}${path}`, init);
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            throw new errors_js_1.PlatformApiError("invalid_response", `Gateway returned a non-JSON ${String(res.status)} response for ${path}.`, undefined, res.status);
+        }
+        if (!(0, api_contract_1.isApiResponse)(parsed)) {
+            throw new errors_js_1.PlatformApiError("invalid_response", `Gateway returned an unrecognised body for ${path}.`, undefined, res.status);
+        }
+        if (!parsed.ok)
+            throw this.#envelopeError(parsed.error, res.status);
+        if (!res.ok) {
+            throw new errors_js_1.PlatformApiError("http_error", `HTTP ${String(res.status)} for ${path}.`, undefined, res.status);
+        }
+        return parsed.data;
+    }
+    /** GET /api/me — the validated caller identity (incl. the F1 `principalId`). */
+    async me() {
+        return this.#json("/api/me", { method: "GET", headers: await this.#authHeaders() });
+    }
+    /** GET /api/agents — the worker roster. */
+    async listAgents() {
+        return this.#json("/api/agents", { method: "GET", headers: await this.#authHeaders() });
+    }
+    /** POST /api/conversations — create a conversation for an agent. */
+    async createConversation(opts) {
+        return this.#json("/api/conversations", {
+            method: "POST",
+            headers: await this.#authHeaders({ "content-type": "application/json" }),
+            body: JSON.stringify({ agentName: opts.agentName }),
+        });
+    }
+    /**
+     * POST /api/chat — invoke a worker and stream its reply. Returns an
+     * InvokeStream (async-iterable of text/artifacts events, with `.text()`).
+     * The request is sent lazily on first iteration.
+     */
+    invoke(opts) {
+        return (0, stream_js_1.makeInvokeStream)(async () => {
+            const res = await this.#fetch(`${this.#base}/api/chat`, {
+                method: "POST",
+                headers: await this.#authHeaders({ "content-type": "application/json" }),
+                body: JSON.stringify({
+                    agentName: opts.agentName,
+                    conversationId: opts.conversationId,
+                    messages: [{ role: "user", content: opts.message }],
+                }),
+            });
+            if (!res.ok) {
+                let parsed;
+                try {
+                    parsed = await res.json();
+                }
+                catch {
+                    throw new errors_js_1.PlatformApiError("invalid_response", `Chat failed with a non-JSON HTTP ${String(res.status)} response.`, undefined, res.status);
+                }
+                if ((0, api_contract_1.isApiResponse)(parsed) && !parsed.ok) {
+                    throw this.#envelopeError(parsed.error, res.status);
+                }
+                throw new errors_js_1.PlatformApiError("invalid_response", `Chat failed with HTTP ${String(res.status)} and an unrecognised body.`, undefined, res.status);
+            }
+            if (!res.body) {
+                throw new errors_js_1.PlatformApiError("no_stream_body", "Chat response had no body to stream.", undefined, res.status);
+            }
+            return res.body;
+        });
+    }
+}
+exports.PlatformClient = PlatformClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/credential.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireGatewayToken = acquireGatewayToken;
+const errors_js_1 = require("./errors.js");
+/**
+ * Acquire a bearer token for the gateway's API audience. Scope is
+ * `${audience}/.default` (the Entra app-only convention). The token must carry
+ * the `Agents.Invoke` app role — granted to the caller's service identity by the
+ * gateway operator. Any `@azure/core-auth` TokenCredential works
+ * (DefaultAzureCredential / ManagedIdentityCredential / ClientSecretCredential …).
+ */
+async function acquireGatewayToken(credential, audience) {
+    const scope = `${audience}/.default`;
+    const accessToken = await credential.getToken(scope);
+    if (!accessToken?.token) {
+        throw new errors_js_1.PlatformApiError("token_unavailable", `Could not acquire a gateway token for scope ${scope}.`);
+    }
+    return accessToken.token;
+}
+//# sourceMappingURL=credential.js.map

package/dist/cjs/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../../src/credential.ts"],"names":[],"mappings":";;AAUA,kDAUC;AAnBD,2CAA+C;AAE/C;;;;;;GAMG;AACI,KAAK,UAAU,mBAAmB,CAAC,UAA2B,EAAE,QAAgB;IACrF,MAAM,KAAK,GAAG,GAAG,QAAQ,WAAW,CAAC;IACrC,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,4BAAgB,CACxB,mBAAmB,EACnB,+CAA+C,KAAK,GAAG,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC;AAC3B,CAAC"}

package/dist/cjs/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformApiError = void 0;
+/**
+ * Thrown for any non-success from the gateway — an `ApiResponse` error envelope
+ * (`{ ok: false, error: { code, message, details } }`), a mid-stream
+ * `{ type: "error", errorText }` SSE frame, or a transport-level failure.
+ */
+class PlatformApiError extends Error {
+    code;
+    details;
+    /** The HTTP status, when the error came from a response (undefined for stream/transport errors). */
+    httpStatus;
+    constructor(code, message, details, httpStatus) {
+        super(message);
+        this.name = "PlatformApiError";
+        this.code = code;
+        this.details = details;
+        this.httpStatus = httpStatus;
+    }
+}
+exports.PlatformApiError = PlatformApiError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IACb,OAAO,CAAW;IAC3B,oGAAoG;IAC3F,UAAU,CAAU;IAE7B,YAAY,IAAY,EAAE,OAAe,EAAE,OAAiB,EAAE,UAAmB;QAC/E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAbD,4CAaC"}

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"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.acquireGatewayToken = exports.makeInvokeStream = exports.PlatformApiError = exports.PlatformClient = void 0;
+// The one consumer-facing import: the typed gateway client + every api-contract type.
+__exportStar(require("@m8t-stack/api-contract"), exports);
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "PlatformClient", { enumerable: true, get: function () { return client_js_1.PlatformClient; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "PlatformApiError", { enumerable: true, get: function () { return errors_js_1.PlatformApiError; } });
+var stream_js_1 = require("./stream.js");
+Object.defineProperty(exports, "makeInvokeStream", { enumerable: true, get: function () { return stream_js_1.makeInvokeStream; } });
+var credential_js_1 = require("./credential.js");
+Object.defineProperty(exports, "acquireGatewayToken", { enumerable: true, get: function () { return credential_js_1.acquireGatewayToken; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,sFAAsF;AACtF,0DAAwC;AAExC,yCAA6C;AAApC,2GAAA,cAAc,OAAA;AAOvB,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA;AACzB,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA;AAEzB,iDAAsD;AAA7C,oHAAA,mBAAmB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/stream.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeInvokeStream = makeInvokeStream;
+const errors_js_1 = require("./errors.js");
+/**
+ * Parse a gateway `POST /api/chat` response body — the AI-SDK UI-message-stream
+ * v1 SSE protocol: `data: <json>\n\n` frames, terminated by `data: [DONE]`.
+ * Yields text/artifacts events; ignores control frames; throws on an `error` frame.
+ */
+async function* parseSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            // A clean stream ends via the `[DONE]` sentinel (an explicit `return`
+            // below). Reaching `done` here means the body closed without it — a
+            // truncated stream is treated as a silent end (any partial trailing
+            // frame in `buffer` is dropped), mirroring standard SSE clients.
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+                const frame = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                // `.trim()` (not just trimStart) so a normalized `\r\n` line ending
+                // can't leave a trailing `\r` that would break JSON.parse.
+                const data = frame.startsWith("data:") ? frame.slice(5).trim() : frame.trim();
+                if (data.length === 0)
+                    continue;
+                if (data === "[DONE]")
+                    return;
+                let part;
+                try {
+                    part = JSON.parse(data);
+                }
+                catch {
+                    continue; // tolerate a non-JSON keep-alive/comment line
+                }
+                if (part.type === "text-delta" && typeof part.delta === "string") {
+                    yield { type: "text", delta: part.delta };
+                }
+                else if (part.type === "data-artifacts" && Array.isArray(part.data)) {
+                    yield { type: "artifacts", artifacts: part.data };
+                }
+                else if (part.type === "error") {
+                    const text = typeof part.errorText === "string" ? part.errorText : "stream error";
+                    throw new errors_js_1.PlatformApiError("stream_error", text);
+                }
+                // else: control frame (start/start-step/text-start/text-end/finish-step/finish) — ignore
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+        // If the consumer broke out early (or an error frame threw), abandon the
+        // underlying HTTP body so the server stops pushing into a buffer no one
+        // reads. Best-effort: a no-op once the stream already ended.
+        void body.cancel().catch(() => { });
+    }
+}
+/**
+ * Build an `InvokeStream` from a lazy body provider. The body is fetched on first
+ * iteration (or first `.text()` call) so `invoke()` can return synchronously.
+ */
+function makeInvokeStream(getBody) {
+    let iterator;
+    const ensure = () => {
+        iterator ??= (async function* () {
+            const body = await getBody();
+            yield* parseSse(body);
+        })();
+        return iterator;
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            return ensure();
+        },
+        async text() {
+            let out = "";
+            for await (const ev of ensure()) {
+                if (ev.type === "text")
+                    out += ev.delta;
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/cjs/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"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"}

package/dist/esm/client.d.ts

@@ -0,0 +1,61 @@
+import type { TokenCredential } from "@azure/core-auth";
+import type { MeResponse } from "@m8t-stack/api-contract";
+import { type InvokeStream } from "./stream.js";
+/** One agent in the gateway's `GET /api/agents` roster (mirrors the gateway wire shape). */
+export interface AgentSummary {
+    name: string;
+    id?: string;
+    model: string;
+    description?: string;
+    /** "prompt" | "hosted" today; typed as string to tolerate new worker kinds. */
+    kind: string;
+    harness?: string;
+}
+export interface AgentsResponse {
+    projectName: string;
+    agents: AgentSummary[];
+}
+/** A gateway conversation (mirrors `ConversationSummary`). */
+export interface Conversation {
+    id: string;
+    agent: string;
+    title: string | null;
+    createdAt: string;
+}
+export interface PlatformClientOptions {
+    /** Gateway base URL, e.g. "https://gw.example.com" (no trailing /api). */
+    gatewayUrl: string;
+    /** Gateway app-reg audience, e.g. "api://<clientId>". Token scope is `${audience}/.default`. */
+    audience: string;
+    /** Any @azure/core-auth credential. Defaults to a secretless DefaultAzureCredential. */
+    credential?: TokenCredential;
+    /** Injectable fetch (tests / custom transport). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Typed client for an m8t-stack gateway. Authenticates as a service principal
+ * (or any TokenCredential) and calls the gateway HTTP API — never Foundry directly.
+ */
+export declare class PlatformClient {
+    #private;
+    constructor(options: PlatformClientOptions);
+    /** GET /api/me — the validated caller identity (incl. the F1 `principalId`). */
+    me(): Promise<MeResponse>;
+    /** GET /api/agents — the worker roster. */
+    listAgents(): Promise<AgentsResponse>;
+    /** POST /api/conversations — create a conversation for an agent. */
+    createConversation(opts: {
+        agentName: string;
+    }): Promise<Conversation>;
+    /**
+     * POST /api/chat — invoke a worker and stream its reply. Returns an
+     * InvokeStream (async-iterable of text/artifacts events, with `.text()`).
+     * The request is sent lazily on first iteration.
+     */
+    invoke(opts: {
+        agentName: string;
+        conversationId: string;
+        message: string;
+    }): InvokeStream;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAElE,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,cAAc;;gBAMb,OAAO,EAAE,qBAAqB;IAoD1C,gFAAgF;IAC1E,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC;IAI/B,2CAA2C;IACrC,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;IAI3C,oEAAoE;IAC9D,kBAAkB,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5E;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY;CAuC3F"}

package/dist/esm/client.js

@@ -0,0 +1,103 @@
+import { DefaultAzureCredential } from "@azure/identity";
+import { isApiResponse } from "@m8t-stack/api-contract";
+import { acquireGatewayToken } from "./credential.js";
+import { PlatformApiError } from "./errors.js";
+import { makeInvokeStream } from "./stream.js";
+/**
+ * Typed client for an m8t-stack gateway. Authenticates as a service principal
+ * (or any TokenCredential) and calls the gateway HTTP API — never Foundry directly.
+ */
+export class PlatformClient {
+    #base;
+    #audience;
+    #credential;
+    #fetch;
+    constructor(options) {
+        this.#base = options.gatewayUrl.replace(/\/+$/, "");
+        this.#audience = options.audience;
+        this.#credential = options.credential ?? new DefaultAzureCredential();
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async #token() {
+        return acquireGatewayToken(this.#credential, this.#audience);
+    }
+    async #authHeaders(extra) {
+        return { authorization: `Bearer ${await this.#token()}`, ...extra };
+    }
+    /** Build a PlatformApiError from a gateway error envelope + the HTTP status. */
+    #envelopeError(error, status) {
+        return new PlatformApiError(error.code, error.message, error.details, status);
+    }
+    /** Call a JSON gateway route and unwrap its ApiResponse envelope, throwing on error. */
+    async #json(path, init) {
+        const res = await this.#fetch(`${this.#base}${path}`, init);
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            throw new PlatformApiError("invalid_response", `Gateway returned a non-JSON ${String(res.status)} response for ${path}.`, undefined, res.status);
+        }
+        if (!isApiResponse(parsed)) {
+            throw new PlatformApiError("invalid_response", `Gateway returned an unrecognised body for ${path}.`, undefined, res.status);
+        }
+        if (!parsed.ok)
+            throw this.#envelopeError(parsed.error, res.status);
+        if (!res.ok) {
+            throw new PlatformApiError("http_error", `HTTP ${String(res.status)} for ${path}.`, undefined, res.status);
+        }
+        return parsed.data;
+    }
+    /** GET /api/me — the validated caller identity (incl. the F1 `principalId`). */
+    async me() {
+        return this.#json("/api/me", { method: "GET", headers: await this.#authHeaders() });
+    }
+    /** GET /api/agents — the worker roster. */
+    async listAgents() {
+        return this.#json("/api/agents", { method: "GET", headers: await this.#authHeaders() });
+    }
+    /** POST /api/conversations — create a conversation for an agent. */
+    async createConversation(opts) {
+        return this.#json("/api/conversations", {
+            method: "POST",
+            headers: await this.#authHeaders({ "content-type": "application/json" }),
+            body: JSON.stringify({ agentName: opts.agentName }),
+        });
+    }
+    /**
+     * POST /api/chat — invoke a worker and stream its reply. Returns an
+     * InvokeStream (async-iterable of text/artifacts events, with `.text()`).
+     * The request is sent lazily on first iteration.
+     */
+    invoke(opts) {
+        return makeInvokeStream(async () => {
+            const res = await this.#fetch(`${this.#base}/api/chat`, {
+                method: "POST",
+                headers: await this.#authHeaders({ "content-type": "application/json" }),
+                body: JSON.stringify({
+                    agentName: opts.agentName,
+                    conversationId: opts.conversationId,
+                    messages: [{ role: "user", content: opts.message }],
+                }),
+            });
+            if (!res.ok) {
+                let parsed;
+                try {
+                    parsed = await res.json();
+                }
+                catch {
+                    throw new PlatformApiError("invalid_response", `Chat failed with a non-JSON HTTP ${String(res.status)} response.`, undefined, res.status);
+                }
+                if (isApiResponse(parsed) && !parsed.ok) {
+                    throw this.#envelopeError(parsed.error, res.status);
+                }
+                throw new PlatformApiError("invalid_response", `Chat failed with HTTP ${String(res.status)} and an unrecognised body.`, undefined, res.status);
+            }
+            if (!res.body) {
+                throw new PlatformApiError("no_stream_body", "Chat response had no body to stream.", undefined, res.status);
+            }
+            return res.body;
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/credential.d.ts

@@ -0,0 +1,10 @@
+import type { TokenCredential } from "@azure/core-auth";
+/**
+ * Acquire a bearer token for the gateway's API audience. Scope is
+ * `${audience}/.default` (the Entra app-only convention). The token must carry
+ * the `Agents.Invoke` app role — granted to the caller's service identity by the
+ * gateway operator. Any `@azure/core-auth` TokenCredential works
+ * (DefaultAzureCredential / ManagedIdentityCredential / ClientSecretCredential …).
+ */
+export declare function acquireGatewayToken(credential: TokenCredential, audience: string): Promise<string>;
+//# sourceMappingURL=credential.d.ts.map

package/dist/esm/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../../src/credential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxG"}

package/dist/esm/credential.js

@@ -0,0 +1,17 @@
+import { PlatformApiError } from "./errors.js";
+/**
+ * Acquire a bearer token for the gateway's API audience. Scope is
+ * `${audience}/.default` (the Entra app-only convention). The token must carry
+ * the `Agents.Invoke` app role — granted to the caller's service identity by the
+ * gateway operator. Any `@azure/core-auth` TokenCredential works
+ * (DefaultAzureCredential / ManagedIdentityCredential / ClientSecretCredential …).
+ */
+export async function acquireGatewayToken(credential, audience) {
+    const scope = `${audience}/.default`;
+    const accessToken = await credential.getToken(scope);
+    if (!accessToken?.token) {
+        throw new PlatformApiError("token_unavailable", `Could not acquire a gateway token for scope ${scope}.`);
+    }
+    return accessToken.token;
+}
+//# sourceMappingURL=credential.js.map

package/dist/esm/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../../src/credential.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,UAA2B,EAAE,QAAgB;IACrF,MAAM,KAAK,GAAG,GAAG,QAAQ,WAAW,CAAC;IACrC,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,gBAAgB,CACxB,mBAAmB,EACnB,+CAA+C,KAAK,GAAG,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC;AAC3B,CAAC"}

package/dist/esm/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown for any non-success from the gateway — an `ApiResponse` error envelope
+ * (`{ ok: false, error: { code, message, details } }`), a mid-stream
+ * `{ type: "error", errorText }` SSE frame, or a transport-level failure.
+ */
+export declare class PlatformApiError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    /** The HTTP status, when the error came from a response (undefined for stream/transport errors). */
+    readonly httpStatus?: number;
+    constructor(code: string, message: string, details?: unknown, httpStatus?: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM;CAOlF"}

package/dist/esm/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Thrown for any non-success from the gateway — an `ApiResponse` error envelope
+ * (`{ ok: false, error: { code, message, details } }`), a mid-stream
+ * `{ type: "error", errorText }` SSE frame, or a transport-level failure.
+ */
+export class PlatformApiError extends Error {
+    code;
+    details;
+    /** The HTTP status, when the error came from a response (undefined for stream/transport errors). */
+    httpStatus;
+    constructor(code, message, details, httpStatus) {
+        super(message);
+        this.name = "PlatformApiError";
+        this.code = code;
+        this.details = details;
+        this.httpStatus = httpStatus;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IACb,OAAO,CAAW;IAC3B,oGAAoG;IAC3F,UAAU,CAAU;IAE7B,YAAY,IAAY,EAAE,OAAe,EAAE,OAAiB,EAAE,UAAmB;QAC/E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/esm/index.d.ts

@@ -0,0 +1,8 @@
+export * from "@m8t-stack/api-contract";
+export { PlatformClient } from "./client.js";
+export type { PlatformClientOptions, AgentSummary, AgentsResponse, Conversation, } from "./client.js";
+export { PlatformApiError } from "./errors.js";
+export { makeInvokeStream } from "./stream.js";
+export type { InvokeStream, InvokeEvent, InvokeTextEvent, InvokeArtifactsEvent } from "./stream.js";
+export { acquireGatewayToken } from "./credential.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// The one consumer-facing import: the typed gateway client + every api-contract type.
+export * from "@m8t-stack/api-contract";
+export { PlatformClient } from "./client.js";
+export { PlatformApiError } from "./errors.js";
+export { makeInvokeStream } from "./stream.js";
+export { acquireGatewayToken } from "./credential.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAO7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/esm/stream.d.ts

@@ -0,0 +1,29 @@
+/** A text token from the worker's reply. */
+export interface InvokeTextEvent {
+    type: "text";
+    delta: string;
+}
+/** Artifacts (e.g. files) emitted by a hosted worker, as a `data-artifacts` part. */
+export interface InvokeArtifactsEvent {
+    type: "artifacts";
+    artifacts: unknown[];
+}
+export type InvokeEvent = InvokeTextEvent | InvokeArtifactsEvent;
+/**
+ * An async-iterable reply stream with a `.text()` convenience that drains to a string.
+ *
+ * The async iterator and `.text()` share ONE underlying generator over the
+ * response body — consume the stream **one way**: either `for await (…)` OR
+ * `.text()`, not both, and not two concurrent iterations. A second consumer
+ * sees only what the first left unread.
+ */
+export interface InvokeStream extends AsyncIterable<InvokeEvent> {
+    /** Drain the stream and return the concatenated text deltas. */
+    text(): Promise<string>;
+}
+/**
+ * Build an `InvokeStream` from a lazy body provider. The body is fetched on first
+ * iteration (or first `.text()` call) so `invoke()` can return synchronously.
+ */
+export declare function makeInvokeStream(getBody: () => Promise<ReadableStream<Uint8Array>>): InvokeStream;
+//# sourceMappingURL=stream.d.ts.map

package/dist/esm/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAEA,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,YAAa,SAAQ,aAAa,CAAC,WAAW,CAAC;IAC9D,gEAAgE;IAChE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAuDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,GAAG,YAAY,CAqBjG"}

package/dist/esm/stream.js

@@ -0,0 +1,88 @@
+import { PlatformApiError } from "./errors.js";
+/**
+ * Parse a gateway `POST /api/chat` response body — the AI-SDK UI-message-stream
+ * v1 SSE protocol: `data: <json>\n\n` frames, terminated by `data: [DONE]`.
+ * Yields text/artifacts events; ignores control frames; throws on an `error` frame.
+ */
+async function* parseSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            // A clean stream ends via the `[DONE]` sentinel (an explicit `return`
+            // below). Reaching `done` here means the body closed without it — a
+            // truncated stream is treated as a silent end (any partial trailing
+            // frame in `buffer` is dropped), mirroring standard SSE clients.
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+                const frame = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                // `.trim()` (not just trimStart) so a normalized `\r\n` line ending
+                // can't leave a trailing `\r` that would break JSON.parse.
+                const data = frame.startsWith("data:") ? frame.slice(5).trim() : frame.trim();
+                if (data.length === 0)
+                    continue;
+                if (data === "[DONE]")
+                    return;
+                let part;
+                try {
+                    part = JSON.parse(data);
+                }
+                catch {
+                    continue; // tolerate a non-JSON keep-alive/comment line
+                }
+                if (part.type === "text-delta" && typeof part.delta === "string") {
+                    yield { type: "text", delta: part.delta };
+                }
+                else if (part.type === "data-artifacts" && Array.isArray(part.data)) {
+                    yield { type: "artifacts", artifacts: part.data };
+                }
+                else if (part.type === "error") {
+                    const text = typeof part.errorText === "string" ? part.errorText : "stream error";
+                    throw new PlatformApiError("stream_error", text);
+                }
+                // else: control frame (start/start-step/text-start/text-end/finish-step/finish) — ignore
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+        // If the consumer broke out early (or an error frame threw), abandon the
+        // underlying HTTP body so the server stops pushing into a buffer no one
+        // reads. Best-effort: a no-op once the stream already ended.
+        void body.cancel().catch(() => { });
+    }
+}
+/**
+ * Build an `InvokeStream` from a lazy body provider. The body is fetched on first
+ * iteration (or first `.text()` call) so `invoke()` can return synchronously.
+ */
+export function makeInvokeStream(getBody) {
+    let iterator;
+    const ensure = () => {
+        iterator ??= (async function* () {
+            const body = await getBody();
+            yield* parseSse(body);
+        })();
+        return iterator;
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            return ensure();
+        },
+        async text() {
+            let out = "";
+            for await (const ev of ensure()) {
+                if (ev.type === "text")
+                    out += ev.delta;
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/esm/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@m8t-stack/platform-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m8t-run/m8t.git",
+    "directory": "packages/platform-sdk"
+  },
+  "homepage": "https://github.com/m8t-run/m8t/tree/main/packages/platform-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/m8t-run/m8t/issues"
+  },
+  "description": "Typed client + service-principal auth for the m8t-stack gateway; re-exports @m8t-stack/api-contract.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "prepare": "pnpm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.eslint.json",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@azure/core-auth": "^1.10.1",
+    "@azure/identity": "^4.13.1",
+    "@m8t-stack/api-contract": "^0.1.0"
+  }
+}