@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/agents/api/agents.d.ts

@@ -0,0 +1,27 @@
+import type { AgentsSession } from "../session/types";
+import type { Agent, AgentConfig } from "./schema";
+/** List every agent (predefined + custom) visible to the session. */
+export declare const listAgents: (session: AgentsSession) => Promise<Agent[]>;
+/** Find one agent by `id` or `slug`. Returns `undefined` if not found. */
+export declare const getAgent: (session: AgentsSession, idOrSlug: string) => Promise<Agent | undefined>;
+export interface CreateAgentInput {
+    name: string;
+    description?: string;
+    prompt?: string;
+    tags?: string[];
+    config: AgentConfig;
+}
+/** Create a custom agent. Requires the caller's account to hold the Builder role. */
+export declare const createAgent: (session: AgentsSession, input: CreateAgentInput) => Promise<Agent>;
+export interface UpdateAgentInput {
+    id: string;
+    name: string;
+    description?: string;
+    config: AgentConfig;
+}
+/** Update an agent in place (`PUT /api/agents`, full-replacement of config). */
+export declare const updateAgent: (session: AgentsSession, input: UpdateAgentInput) => Promise<void>;
+/** Duplicate an agent under a new name (`POST /api/agents/{id}`). */
+export declare const duplicateAgent: (session: AgentsSession, id: string, name: string) => Promise<Agent>;
+/** Delete an agent (`DELETE /api/agents/{id}`). */
+export declare const deleteAgent: (session: AgentsSession, id: string) => Promise<void>;

package/dist/agents/api/agents.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteAgent = exports.duplicateAgent = exports.updateAgent = exports.createAgent = exports.getAgent = exports.listAgents = void 0;
+/**
+ * Agent CRUD against the Agentic Studio BFF (`/api/agents`).
+ *
+ * `POST /api/agents` returns a single-element array `[{agent}]` — every
+ * create/duplicate unwraps it. There is no confirmed `GET /api/agents/{id}`,
+ * so `getAgent` filters the list instead.
+ */
+const request_1 = require("./request");
+const unwrapAgent = (value) => {
+    const agent = Array.isArray(value) ? value[0] : value;
+    return agent;
+};
+/** List every agent (predefined + custom) visible to the session. */
+const listAgents = async (session) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/agents");
+    return Array.isArray(data) ? data : [];
+};
+exports.listAgents = listAgents;
+/** Find one agent by `id` or `slug`. Returns `undefined` if not found. */
+const getAgent = async (session, idOrSlug) => {
+    const agents = await (0, exports.listAgents)(session);
+    return agents.find((agent) => agent.id === idOrSlug || agent.slug === idOrSlug);
+};
+exports.getAgent = getAgent;
+/** Create a custom agent. Requires the caller's account to hold the Builder role. */
+const createAgent = async (session, input) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/agents", {
+        method: "POST",
+        body: {
+            name: input.name,
+            description: input.description ?? "",
+            prompt: input.prompt ?? "",
+            tags: input.tags ?? [],
+            config: input.config,
+            isPredefined: false,
+        },
+    });
+    return unwrapAgent(data);
+};
+exports.createAgent = createAgent;
+/** Update an agent in place (`PUT /api/agents`, full-replacement of config). */
+const updateAgent = async (session, input) => {
+    await (0, request_1.agentsRequest)(session, "/api/agents", {
+        method: "PUT",
+        body: {
+            id: input.id,
+            name: input.name,
+            description: input.description ?? "",
+            config: input.config,
+        },
+    });
+};
+exports.updateAgent = updateAgent;
+/** Duplicate an agent under a new name (`POST /api/agents/{id}`). */
+const duplicateAgent = async (session, id, name) => {
+    const data = await (0, request_1.agentsRequest)(session, `/api/agents/${encodeURIComponent(id)}`, {
+        method: "POST",
+        body: { name },
+    });
+    return unwrapAgent(data);
+};
+exports.duplicateAgent = duplicateAgent;
+/** Delete an agent (`DELETE /api/agents/{id}`). */
+const deleteAgent = async (session, id) => {
+    await (0, request_1.agentsRequest)(session, `/api/agents/${encodeURIComponent(id)}`, { method: "DELETE" });
+};
+exports.deleteAgent = deleteAgent;

package/dist/agents/api/catalog.d.ts

@@ -0,0 +1,8 @@
+import type { AgentsSession } from "../session/types";
+import type { ScheduledRun } from "./schema";
+/** Scheduled runs. Accepts a bare array or a `{ schedules }` envelope. */
+export declare const listScheduledRuns: (session: AgentsSession) => Promise<ScheduledRun[]>;
+/** Jobs. Accepts a bare array or a `{ jobs }` envelope. Shape untyped. */
+export declare const listJobs: (session: AgentsSession) => Promise<unknown[]>;
+/** Brand kits visible to the session. Shape unconfirmed — returned untyped. */
+export declare const listBrandKits: (session: AgentsSession) => Promise<unknown[]>;

package/dist/agents/api/catalog.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listBrandKits = exports.listJobs = exports.listScheduledRuns = void 0;
+/**
+ * Ancillary read endpoints — run history and supporting data that aren't
+ * a first-class authored resource of their own.
+ *
+ * Per-resource catalogs (tools, skills, schemas, widgets, custom-mcps)
+ * live in their own modules; this file holds the cross-cutting reads.
+ */
+const request_1 = require("./request");
+const asArray = (value) => (Array.isArray(value) ? value : []);
+/** Scheduled runs. Accepts a bare array or a `{ schedules }` envelope. */
+const listScheduledRuns = async (session) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/scheduled-runs");
+    if (Array.isArray(data))
+        return data;
+    const envelope = data;
+    return asArray(envelope?.schedules);
+};
+exports.listScheduledRuns = listScheduledRuns;
+/** Jobs. Accepts a bare array or a `{ jobs }` envelope. Shape untyped. */
+const listJobs = async (session) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/jobs");
+    if (Array.isArray(data))
+        return data;
+    const envelope = data;
+    return asArray(envelope?.jobs);
+};
+exports.listJobs = listJobs;
+/** Brand kits visible to the session. Shape unconfirmed — returned untyped. */
+const listBrandKits = async (session) => asArray(await (0, request_1.agentsRequest)(session, "/api/brand-kits"));
+exports.listBrandKits = listBrandKits;

package/dist/agents/api/custom-mcps.d.ts

@@ -0,0 +1,26 @@
+import type { AgentsSession } from "../session/types";
+import type { CustomMcp } from "./schema";
+/** List every registered custom MCP server. */
+export declare const listCustomMcps: (session: AgentsSession) => Promise<CustomMcp[]>;
+/** Find one custom MCP by `id` or `name`. Returns `undefined` if not found. */
+export declare const getCustomMcp: (session: AgentsSession, idOrName: string) => Promise<CustomMcp | undefined>;
+export interface CreateCustomMcpInput {
+    name: string;
+    /** The MCP server endpoint URL. */
+    url: string;
+}
+/** Register a custom MCP server (`POST /api/custom-mcps`). */
+export declare const createCustomMcp: (session: AgentsSession, input: CreateCustomMcpInput) => Promise<CustomMcp>;
+export interface UpdateCustomMcpInput extends CreateCustomMcpInput {
+    /** Id of the custom MCP to replace. */
+    id: string;
+}
+/**
+ * Update a custom MCP (`PUT /api/custom-mcps/{id}`).
+ * **UNVERIFIED — returned 405 on 2026-05-17; see the file header.**
+ */
+export declare const updateCustomMcp: (session: AgentsSession, input: UpdateCustomMcpInput) => Promise<void>;
+/** Delete a custom MCP (`DELETE /api/custom-mcps/{id}`). */
+export declare const deleteCustomMcp: (session: AgentsSession, id: string) => Promise<void>;
+/** Read the auth status for a registered MCP (`GET /api/custom-mcps/{id}/auth`). */
+export declare const getCustomMcpAuth: (session: AgentsSession, id: string) => Promise<unknown>;

package/dist/agents/api/custom-mcps.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCustomMcpAuth = exports.deleteCustomMcp = exports.updateCustomMcp = exports.createCustomMcp = exports.getCustomMcp = exports.listCustomMcps = void 0;
+/**
+ * Custom MCPs — external MCP servers registered with Agentic Studio by
+ * URL (`/api/custom-mcps`). Once registered and authorized, an agent can
+ * use the MCP's tools as additional context.
+ *
+ * `deleteCustomMcp` uses `DELETE /api/custom-mcps/{id}` — verified working
+ * 2026-05-17 against agentic-studio-euw. A custom MCP has **no update**:
+ * `PUT /api/custom-mcps/{id}` returns 405, and re-POSTing `/api/custom-mcps`
+ * with the same name creates a *duplicate* rather than upserting (both
+ * verified 2026-05-17). `updateCustomMcp` stays gated behind `--unverified`;
+ * the supported path is delete + recreate. See docs/agentic-studio-har-capture.md.
+ */
+const request_1 = require("./request");
+/** List every registered custom MCP server. */
+const listCustomMcps = async (session) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/custom-mcps");
+    return Array.isArray(data) ? data : [];
+};
+exports.listCustomMcps = listCustomMcps;
+/** Find one custom MCP by `id` or `name`. Returns `undefined` if not found. */
+const getCustomMcp = async (session, idOrName) => {
+    const mcps = await (0, exports.listCustomMcps)(session);
+    return mcps.find((mcp) => mcp.id === idOrName || mcp.name === idOrName);
+};
+exports.getCustomMcp = getCustomMcp;
+/** Register a custom MCP server (`POST /api/custom-mcps`). */
+const createCustomMcp = async (session, input) => (0, request_1.agentsRequest)(session, "/api/custom-mcps", {
+    method: "POST",
+    body: { name: input.name, url: input.url },
+});
+exports.createCustomMcp = createCustomMcp;
+/**
+ * Update a custom MCP (`PUT /api/custom-mcps/{id}`).
+ * **UNVERIFIED — returned 405 on 2026-05-17; see the file header.**
+ */
+const updateCustomMcp = async (session, input) => {
+    await (0, request_1.agentsRequest)(session, `/api/custom-mcps/${encodeURIComponent(input.id)}`, {
+        method: "PUT",
+        body: { name: input.name, url: input.url },
+    });
+};
+exports.updateCustomMcp = updateCustomMcp;
+/** Delete a custom MCP (`DELETE /api/custom-mcps/{id}`). */
+const deleteCustomMcp = async (session, id) => {
+    await (0, request_1.agentsRequest)(session, `/api/custom-mcps/${encodeURIComponent(id)}`, { method: "DELETE" });
+};
+exports.deleteCustomMcp = deleteCustomMcp;
+/** Read the auth status for a registered MCP (`GET /api/custom-mcps/{id}/auth`). */
+const getCustomMcpAuth = (session, id) => (0, request_1.agentsRequest)(session, `/api/custom-mcps/${encodeURIComponent(id)}/auth`);
+exports.getCustomMcpAuth = getCustomMcpAuth;

package/dist/agents/api/html-templates.d.ts

@@ -0,0 +1,35 @@
+import type { AgentsSession } from "../session/types";
+import type { HtmlTemplate } from "./schema";
+/** List every HTML template visible to the session. */
+export declare const listHtmlTemplates: (session: AgentsSession) => Promise<HtmlTemplate[]>;
+/** Find one HTML template by `id`, `templateId`, or `name`. `undefined` if not found. */
+export declare const getHtmlTemplate: (session: AgentsSession, idOrName: string) => Promise<HtmlTemplate | undefined>;
+export interface CreateHtmlTemplateInput {
+    /** Display name and identifier of the template. */
+    name: string;
+    /** The template's HTML body. */
+    code: string;
+    description?: string;
+    tags?: string[];
+}
+/**
+ * Create an HTML template. **UNSTABLE — see the file header.**
+ *
+ * Replays the `/html-templates/create` server action. Throws
+ * `AGENTS_API_FAILED` with a re-capture hint when the action hash has
+ * rotated (the most likely failure after an Agentic Studio deploy).
+ */
+export declare const createHtmlTemplate: (session: AgentsSession, input: CreateHtmlTemplateInput) => Promise<void>;
+export interface UpdateHtmlTemplateInput extends CreateHtmlTemplateInput {
+    /** Id of the HTML template to replace. */
+    id: string;
+}
+/**
+ * Update an HTML template — replays the `updateHtmlTemplateAction` server
+ * action `POST /html-templates/{id}`. The hash, route, router tree, and
+ * argument tuple (`[id, {templateId, name, description, code, tags}]`)
+ * were captured live 2026-05-17 — see the file header.
+ */
+export declare const updateHtmlTemplate: (session: AgentsSession, input: UpdateHtmlTemplateInput) => Promise<void>;
+/** Delete an HTML template (`DELETE /api/html-templates/{id}`). **UNVERIFIED — 404; see header.** */
+export declare const deleteHtmlTemplate: (session: AgentsSession, id: string) => Promise<void>;

package/dist/agents/api/html-templates.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteHtmlTemplate = exports.updateHtmlTemplate = exports.createHtmlTemplate = exports.getHtmlTemplate = exports.listHtmlTemplates = void 0;
+/**
+ * HTML templates (`/api/html-templates`).
+ *
+ * `listHtmlTemplates` reads. `createHtmlTemplate` is **UNSTABLE**: there
+ * is no `/api/` html-template-write endpoint, so it replays the
+ * `/html-templates/create` Next.js server action via `agentsServerAction`
+ * — coupling scai to Agentic Studio's internal build (the action hash
+ * rotates on every deploy). To be deleted when a real
+ * `POST /api/html-templates` endpoint ships.
+ *
+ * `updateHtmlTemplate` replays the `updateHtmlTemplateAction` server
+ * action (`POST /html-templates/{id}`) — its hash, route, args, and
+ * router tree were captured live 2026-05-17 (agentic-studio-euw) with
+ * `scripts/record-agentic-actions.ts`.
+ *
+ * **Still UNVERIFIED:** `GET /api/html-templates` returns 404 on that
+ * tenant — no list/read path has been observed — so `listHtmlTemplates` /
+ * `getHtmlTemplate` fail and the CLI can only address a template by its
+ * id; and `deleteHtmlTemplate` has no captured endpoint. See
+ * docs/agentic-studio-har-capture.md.
+ */
+const request_1 = require("./request");
+/** List every HTML template visible to the session. */
+const listHtmlTemplates = async (session) => {
+    const data = await (0, request_1.agentsRequest)(session, "/api/html-templates");
+    return Array.isArray(data) ? data : [];
+};
+exports.listHtmlTemplates = listHtmlTemplates;
+/** Find one HTML template by `id`, `templateId`, or `name`. `undefined` if not found. */
+const getHtmlTemplate = async (session, idOrName) => {
+    const templates = await (0, exports.listHtmlTemplates)(session);
+    return templates.find((template) => template.id === idOrName || template.templateId === idOrName || template.name === idOrName);
+};
+exports.getHtmlTemplate = getHtmlTemplate;
+/**
+ * Last-resort `/html-templates/create` server-action hash. The hash
+ * ROTATES on every Agentic Studio deploy; `scai agents login` discovers
+ * the current one and stores it on the session (`session.actionHashes`),
+ * so this constant is only reached when discovery failed AND
+ * `SITECOREAI_HTML_TEMPLATE_ACTION` is unset.
+ */
+const HTML_TEMPLATE_CREATE_ACTION = "60702b611beeb3886f6a3d118e6332d1f6a3a29610";
+/** Router-state-tree the `/html-templates/create` action expects. */
+const HTML_TEMPLATE_CREATE_ROUTER_TREE = '["",{"children":["(settings)",{"children":["html-templates",{"children":' +
+    '["create",{"children":["__PAGE__",{},null,null,0]},null,null,0]},null,null,0]},null,null,0]},null,null,20]';
+/**
+ * Create an HTML template. **UNSTABLE — see the file header.**
+ *
+ * Replays the `/html-templates/create` server action. Throws
+ * `AGENTS_API_FAILED` with a re-capture hint when the action hash has
+ * rotated (the most likely failure after an Agentic Studio deploy).
+ */
+const createHtmlTemplate = async (session, input) => {
+    await (0, request_1.agentsServerAction)(session, "/html-templates/create", {
+        actionHash: session.actionHashes?.["/html-templates/create"] ??
+            process.env.SITECOREAI_HTML_TEMPLATE_ACTION ??
+            HTML_TEMPLATE_CREATE_ACTION,
+        routerStateTree: HTML_TEMPLATE_CREATE_ROUTER_TREE,
+        // Server-action args: [prevState, payload] — `$undefined` for absent optionals.
+        args: [
+            null,
+            {
+                templateId: input.name,
+                name: input.name,
+                code: input.code,
+                description: input.description ?? request_1.RSC_UNDEFINED,
+                tags: input.tags ?? request_1.RSC_UNDEFINED,
+            },
+        ],
+    });
+};
+exports.createHtmlTemplate = createHtmlTemplate;
+/**
+ * Last-resort `updateHtmlTemplateAction` server-action hash, captured
+ * 2026-05-17. Rotates per Agentic Studio deploy — override with
+ * `SITECOREAI_HTML_TEMPLATE_UPDATE_ACTION`.
+ */
+const HTML_TEMPLATE_UPDATE_ACTION = "6077abcec88bb09d86dd7229fce7031d84a96daa3c";
+/** Router-state-tree for the `/html-templates/{id}` edit page. */
+const htmlTemplateEditRouterTree = (id) => '["",{"children":["(settings)",{"children":["html-templates",{"children":' +
+    `[["id",${JSON.stringify(id)},"d",null],` +
+    '{"children":["__PAGE__",{},null,null,0]},null,null,0]},null,null,0]},null,null,0]},null,null,20]';
+/**
+ * Update an HTML template — replays the `updateHtmlTemplateAction` server
+ * action `POST /html-templates/{id}`. The hash, route, router tree, and
+ * argument tuple (`[id, {templateId, name, description, code, tags}]`)
+ * were captured live 2026-05-17 — see the file header.
+ */
+const updateHtmlTemplate = async (session, input) => {
+    await (0, request_1.agentsServerAction)(session, `/html-templates/${encodeURIComponent(input.id)}`, {
+        actionHash: process.env.SITECOREAI_HTML_TEMPLATE_UPDATE_ACTION ?? HTML_TEMPLATE_UPDATE_ACTION,
+        routerStateTree: htmlTemplateEditRouterTree(input.id),
+        // Captured arg tuple: [id, payload] — `$undefined` for absent optionals.
+        args: [
+            input.id,
+            {
+                templateId: input.name,
+                name: input.name,
+                description: input.description ?? request_1.RSC_UNDEFINED,
+                code: input.code,
+                tags: input.tags ?? request_1.RSC_UNDEFINED,
+            },
+        ],
+    });
+};
+exports.updateHtmlTemplate = updateHtmlTemplate;
+/** Delete an HTML template (`DELETE /api/html-templates/{id}`). **UNVERIFIED — 404; see header.** */
+const deleteHtmlTemplate = async (session, id) => {
+    await (0, request_1.agentsRequest)(session, `/api/html-templates/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+    });
+};
+exports.deleteHtmlTemplate = deleteHtmlTemplate;

package/dist/agents/api/request.d.ts

@@ -0,0 +1,28 @@
+import type { AgentsRequestInit, AgentsSession } from "../session/types";
+/** Issue a JSON request against a BFF `/api/*` path. */
+export declare const agentsRequest: <TResponse>(session: AgentsSession, path: string, init?: AgentsRequestInit) => Promise<TResponse>;
+/**
+ * Open a streaming request (the `chatv2` run endpoint emits
+ * `text/event-stream`) and yield decoded text chunks. SSE framing is
+ * left to the caller. Defaults to POST.
+ */
+export declare function agentsStream(session: AgentsSession, path: string, init: AgentsRequestInit): AsyncIterable<string>;
+/** Next.js RSC encoding for an absent (`undefined`) server-action argument. */
+export declare const RSC_UNDEFINED = "$undefined";
+export interface ServerActionInit {
+    /** The `Next-Action` hash. ROTATES on every Agentic Studio deploy. */
+    actionHash: string;
+    /** The `Next-Router-State-Tree` header value for the action's route. */
+    routerStateTree: string;
+    /** The server action's argument tuple — JSON-encoded as the request body. */
+    args: unknown;
+}
+/**
+ * Invoke a Next.js **server action** on the Agentic Studio app.
+ *
+ * Used by resources with no `/api/` write endpoint (schemas,
+ * html-templates). UNSTABLE by nature — `actionHash` rotates on every
+ * Agentic Studio deploy. Throws `AGENTS_API_FAILED` (with a re-capture
+ * hint) on a non-2xx; the response is an RSC stream and is not parsed.
+ */
+export declare const agentsServerAction: (session: AgentsSession, path: string, init: ServerActionInit) => Promise<void>;

package/dist/agents/api/request.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsServerAction = exports.RSC_UNDEFINED = exports.agentsRequest = void 0;
+exports.agentsStream = agentsStream;
+/**
+ * Agentic Studio BFF transport — `agentsRequest()` + `agentsStream()`.
+ *
+ * The BFF is the Next.js app at `agentic-studio-<region>.sitecorecloud.io`;
+ * its `/api/*` routes are reverse-engineered and unversioned (see the
+ * project memory `project_scai_agentic_studio_api`), so callers parse
+ * responses defensively.
+ *
+ * Errors map to `ScaiError`: `NETWORK` for transport failures,
+ * `AUTH_REQUIRED` for an expired/absent session (401), `AUTH_DENIED` for
+ * the Builder-role gate (403), `AGENTS_API_FAILED` otherwise.
+ */
+const errors_1 = require("../../shared/errors");
+const redact_1 = require("../../shared/redact");
+const toQueryString = (query) => {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined)
+            continue;
+        params.set(key, String(value));
+    }
+    const output = params.toString();
+    return output ? `?${output}` : "";
+};
+const requestTimeoutMs = () => Number(process.env.SITECOREAI_REQUEST_TIMEOUT_MS ?? 60000);
+const buildHeaders = (session, init, hasBody = false) => {
+    const headers = {
+        ...session.authHeaders(),
+        // `*/*` (not `application/json`) — the browser sends it and the edge
+        // WAF is picky. Same-origin Origin/Referer cover CSRF checks on writes.
+        Accept: "*/*",
+        Origin: session.baseUrl,
+        Referer: `${session.baseUrl}/`,
+        ...(init?.headers ?? {}),
+    };
+    if (hasBody)
+        headers["Content-Type"] = "application/json";
+    return headers;
+};
+const serializeBody = (body) => {
+    if (body === undefined)
+        return undefined;
+    return typeof body === "string" ? body : JSON.stringify(body);
+};
+/** Map a non-2xx Agentic Studio response (with its body text) to a `ScaiError`. */
+const mapHttpError = (status, body) => {
+    if (status === 401) {
+        return (0, errors_1.createScaiError)("Agentic Studio session is expired or missing.", "AUTH_REQUIRED", {
+            hint: "Run `scai agents login` to capture a fresh browser session.",
+        });
+    }
+    if (status === 403 && /builder/i.test(body)) {
+        return (0, errors_1.createScaiError)("Agentic Studio rejected the request: Builder role and license required.", "AUTH_DENIED", {
+            hint: "In Agentic Studio → User Management, set your account to Builder and confirm a Builder license seat, then retry.",
+        });
+    }
+    let message = `Agentic Studio request failed (${status}).`;
+    try {
+        const parsed = JSON.parse(body);
+        const detail = parsed.error ?? parsed.message;
+        if (typeof detail === "string" && detail)
+            message = detail;
+    }
+    catch {
+        /* non-JSON body — keep the generic message */
+    }
+    return (0, errors_1.createScaiError)((0, redact_1.redactSecrets)(message), "AGENTS_API_FAILED");
+};
+/** Node `fetch` reports the real failure on `error.cause` — surface it. */
+const describeCause = (error) => {
+    if (!(error instanceof Error))
+        return "";
+    const cause = error.cause;
+    if (cause === undefined)
+        return "";
+    const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+    const code = cause && typeof cause === "object" && "code" in cause
+        ? ` [${String(cause.code)}]`
+        : "";
+    return ` (cause: ${detail}${code})`;
+};
+const networkError = (error) => (0, errors_1.createScaiError)((0, redact_1.redactSecrets)(`Agentic Studio request failed: ${error instanceof Error ? error.message : String(error)}${describeCause(error)}`), "NETWORK", { hint: "Check network connectivity or try again later." });
+/** Issue a JSON request against a BFF `/api/*` path. */
+const agentsRequest = async (session, path, init) => {
+    const url = `${session.baseUrl}${path}${toQueryString(init?.query)}`;
+    const method = init?.method ? init.method.toUpperCase() : "GET";
+    const body = serializeBody(init?.body);
+    const headers = buildHeaders(session, init, body !== undefined);
+    const timeoutMs = requestTimeoutMs();
+    const controller = timeoutMs > 0 && !init?.signal ? new AbortController() : undefined;
+    const timeout = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+    let response;
+    try {
+        response = await fetch(url, {
+            method,
+            headers,
+            body,
+            signal: init?.signal ?? controller?.signal,
+        });
+    }
+    catch (error) {
+        throw networkError(error);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        throw mapHttpError(response.status, text);
+    }
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw (0, errors_1.createScaiError)("Agentic Studio returned a non-JSON response.", "AGENTS_API_FAILED");
+    }
+};
+exports.agentsRequest = agentsRequest;
+/**
+ * Open a streaming request (the `chatv2` run endpoint emits
+ * `text/event-stream`) and yield decoded text chunks. SSE framing is
+ * left to the caller. Defaults to POST.
+ */
+async function* agentsStream(session, path, init) {
+    const url = `${session.baseUrl}${path}${toQueryString(init.query)}`;
+    const body = serializeBody(init.body);
+    const headers = buildHeaders(session, init, body !== undefined);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: init.method ? init.method.toUpperCase() : "POST",
+            headers,
+            body,
+            signal: init.signal,
+        });
+    }
+    catch (error) {
+        throw networkError(error);
+    }
+    if (!response.ok) {
+        throw mapHttpError(response.status, await response.text());
+    }
+    if (!response.body)
+        return;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                yield decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Next.js RSC encoding for an absent (`undefined`) server-action argument. */
+exports.RSC_UNDEFINED = "$undefined";
+/**
+ * Invoke a Next.js **server action** on the Agentic Studio app.
+ *
+ * Used by resources with no `/api/` write endpoint (schemas,
+ * html-templates). UNSTABLE by nature — `actionHash` rotates on every
+ * Agentic Studio deploy. Throws `AGENTS_API_FAILED` (with a re-capture
+ * hint) on a non-2xx; the response is an RSC stream and is not parsed.
+ */
+const agentsServerAction = async (session, path, init) => {
+    let response;
+    try {
+        response = await fetch(`${session.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                ...session.authHeaders(),
+                "Content-Type": "text/plain;charset=UTF-8",
+                "Next-Action": init.actionHash,
+                "Next-Router-State-Tree": init.routerStateTree,
+                Accept: "text/x-component",
+                Origin: session.baseUrl,
+                Referer: `${session.baseUrl}${path}`,
+            },
+            body: JSON.stringify(init.args),
+        });
+    }
+    catch (error) {
+        throw networkError(error);
+    }
+    if (!response.ok) {
+        throw (0, errors_1.createScaiError)(`Agentic Studio rejected the ${path} server action (HTTP ${response.status}).`, "AGENTS_API_FAILED", {
+            hint: `${path} is a Next.js server action whose hash rotates on every Agentic ` +
+                "Studio deploy. Re-capture it from a HAR and update the action hash, or wait " +
+                "for a real /api/ write endpoint.",
+        });
+    }
+};
+exports.agentsServerAction = agentsServerAction;

package/dist/agents/api/runs.d.ts

@@ -0,0 +1,31 @@
+import type { AgentsSession } from "../session/types";
+import type { RunEvent } from "./schema";
+/** Parse a stream of raw SSE text chunks into typed run events. */
+export declare function parseRunEvents(chunks: AsyncIterable<string>): AsyncIterable<RunEvent>;
+export interface StreamRunInput {
+    spaceId: string;
+    /** chatv2 `graphType` — an agent slug (standard) or flow id (workflow). */
+    graphType: string;
+    message: string;
+    signal?: AbortSignal;
+}
+/** Trigger a run against an existing space and yield its events. */
+export declare const streamRun: (session: AgentsSession, input: StreamRunInput) => AsyncIterable<RunEvent>;
+export interface RunAgentInput {
+    /** Slug of the agent to run. */
+    agentSlug: string;
+    message: string;
+    /** Space title — defaults to a generated one. */
+    title?: string;
+    signal?: AbortSignal;
+}
+export interface RunHandle {
+    /** The space created for this run (spaces have no delete endpoint). */
+    spaceId: string;
+    events: AsyncIterable<RunEvent>;
+}
+/**
+ * Create a space for an agent and stream a run against it. Each call
+ * creates a new space — they accumulate, the BFF exposes no space delete.
+ */
+export declare const runAgent: (session: AgentsSession, input: RunAgentInput) => Promise<RunHandle>;