@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/agents/session/index.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logoutAgents = exports.loginAgents = exports.acquireAgentsSession = exports.agentsSessionFromCookie = exports.createAgentsSession = exports.DEFAULT_AGENTS_REGION = exports.agentsBaseUrl = void 0;
+/**
+ * Agentic Studio session factory + credential lifecycle.
+ *
+ * `createAgentsSession` turns a stored `AgentsCredential` into the
+ * `AgentsSession` the transport consumes. `loginAgents` /
+ * `acquireAgentsSession` / `logoutAgents` manage the keychain-backed
+ * credential. The Playwright dependency is reached only via
+ * `loginAgents` → `./playwright-login`.
+ */
+const keychain_1 = require("../../shared/keychain");
+const errors_1 = require("../../shared/errors");
+const types_1 = require("./types");
+const playwright_login_1 = require("./playwright-login");
+var types_2 = require("./types");
+Object.defineProperty(exports, "agentsBaseUrl", { enumerable: true, get: function () { return types_2.agentsBaseUrl; } });
+Object.defineProperty(exports, "DEFAULT_AGENTS_REGION", { enumerable: true, get: function () { return types_2.DEFAULT_AGENTS_REGION; } });
+/**
+ * A current Chrome User-Agent, used when a stored credential predates
+ * `userAgent` capture. Sitecore Cloud's edge WAF 406s non-browser callers.
+ */
+const FALLBACK_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36";
+const platformBrand = () => {
+    if (process.platform === "darwin")
+        return '"macOS"';
+    if (process.platform === "win32")
+        return '"Windows"';
+    return '"Linux"';
+};
+/**
+ * Browser-fingerprint headers paired with the captured `User-Agent`.
+ * Part of the temporary cookie strategy — a future bearer session sends
+ * none of this.
+ */
+const browserHeaders = (userAgent) => ({
+    "User-Agent": userAgent || FALLBACK_USER_AGENT,
+    "Accept-Language": "en-US,en;q=0.9",
+    "sec-ch-ua": '"Chromium";v="148", "Microsoft Edge";v="148", "Not/A)Brand";v="99"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": platformBrand(),
+    "sec-fetch-dest": "empty",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-site": "same-origin",
+});
+const parseCredential = (raw) => {
+    try {
+        const value = JSON.parse(raw);
+        if (value.kind === "cookie" && typeof value.cookieHeader === "string" && value.cookieHeader) {
+            return {
+                kind: "cookie",
+                region: value.region ?? types_1.DEFAULT_AGENTS_REGION,
+                cookieHeader: value.cookieHeader,
+                userAgent: value.userAgent ?? FALLBACK_USER_AGENT,
+                actionHashes: value.actionHashes,
+                capturedAt: value.capturedAt ?? new Date(0).toISOString(),
+            };
+        }
+    }
+    catch {
+        /* not a credential — fall through */
+    }
+    return undefined;
+};
+/**
+ * Build the transport-facing session handle from a stored credential.
+ * Today every credential is a cookie; when a `kind: "bearer"` variant is
+ * added, branch here to emit an `Authorization` header instead.
+ */
+const createAgentsSession = (credential) => ({
+    baseUrl: (0, types_1.agentsBaseUrl)(credential.region),
+    authHeaders: () => ({
+        Cookie: credential.cookieHeader,
+        ...browserHeaders(credential.userAgent),
+    }),
+    actionHashes: credential.actionHashes,
+});
+exports.createAgentsSession = createAgentsSession;
+/**
+ * Build a session straight from a browser session cookie — no Playwright,
+ * no keychain. The entry point for embedding contexts that already hold
+ * the cookie: a Sitecore Marketplace app runs inside the authenticated
+ * portal, so the BFF session is present in its browser context and can be
+ * handed straight in.
+ *
+ * One of three ways to reach an `AgentsSession`, all equivalent downstream:
+ * Playwright login (`loginAgents`, CLI), this cookie injection (embedded
+ * UI), and — once Sitecore ships it — a bearer token. See `./types`.
+ */
+const agentsSessionFromCookie = (input) => (0, exports.createAgentsSession)({
+    kind: "cookie",
+    region: input.region ?? types_1.DEFAULT_AGENTS_REGION,
+    cookieHeader: input.cookieHeader,
+    userAgent: input.userAgent ?? FALLBACK_USER_AGENT,
+    capturedAt: new Date().toISOString(),
+});
+exports.agentsSessionFromCookie = agentsSessionFromCookie;
+/**
+ * Load the stored session for an environment. Throws `AUTH_REQUIRED`
+ * (pointing at `scai agents login`) when none is present. Staleness is
+ * detected later — by the transport, on the first 401.
+ */
+const acquireAgentsSession = async (envName) => {
+    const raw = await (0, keychain_1.getAgentsCredential)(envName);
+    const credential = raw ? parseCredential(raw) : undefined;
+    if (!credential) {
+        throw (0, errors_1.createScaiError)(`No Agentic Studio session stored for environment "${envName}".`, "AUTH_REQUIRED", { hint: `Run \`scai agents login -n ${envName}\` to capture a browser session.` });
+    }
+    return (0, exports.createAgentsSession)(credential);
+};
+exports.acquireAgentsSession = acquireAgentsSession;
+/**
+ * Run the (temporary) interactive browser login and persist the captured
+ * session to the keychain. Returns the stored credential's metadata.
+ */
+const loginAgents = async (options) => {
+    const region = options.region ?? types_1.DEFAULT_AGENTS_REGION;
+    const credential = await (0, playwright_login_1.runPlaywrightLogin)({ region, timeoutMs: options.timeoutMs });
+    await (0, keychain_1.setAgentsCredential)(options.envName, JSON.stringify(credential));
+    return { region: credential.region, capturedAt: credential.capturedAt };
+};
+exports.loginAgents = loginAgents;
+/** Forget the stored Agentic Studio session for an environment. */
+const logoutAgents = async (envName) => (0, keychain_1.clearAgentsCredential)(envName);
+exports.logoutAgents = logoutAgents;

package/dist/agents/session/playwright-login.d.ts

@@ -0,0 +1,11 @@
+import { type AgentsCredential } from "./types";
+export interface PlaywrightLoginOptions {
+    region: string;
+    /** Max time to wait for the operator to finish signing in (ms). */
+    timeoutMs?: number;
+}
+/**
+ * Launch a headed browser, let the operator sign in, and capture the
+ * resulting BFF session cookie as an `AgentsCredential`.
+ */
+export declare const runPlaywrightLogin: (options: PlaywrightLoginOptions) => Promise<AgentsCredential>;

package/dist/agents/session/playwright-login.js

@@ -0,0 +1,169 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlaywrightLogin = void 0;
+const errors_1 = require("../../shared/errors");
+const types_1 = require("./types");
+/** System browser channels to try, in order. */
+const CHANNELS = ["chrome", "msedge"];
+const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60000;
+const loadPlaywright = async () => {
+    try {
+        return await Promise.resolve().then(() => __importStar(require("playwright-core")));
+    }
+    catch {
+        throw (0, errors_1.createScaiError)("Agentic Studio login needs Playwright, which is not installed.", "AUTH_REQUIRED", {
+            hint: "Run `pnpm add -O playwright-core` (a temporary dependency — see src/agents/session/types.ts).",
+        });
+    }
+};
+/**
+ * Discover a Next.js server-action hash from a create page's JS chunks.
+ *
+ * schema / html-template writes replay a server action whose hash rotates
+ * on every Agentic Studio deploy. Capturing it fresh at login (rather
+ * than hard-coding it) keeps those writes self-healing. Best-effort:
+ * returns `undefined` if the page or pattern can't be read, and the
+ * writes then fall back to their env override / constant.
+ */
+const discoverActionHash = async (page, url, actionNameHint) => {
+    const chunkBodies = [];
+    const collect = (response) => {
+        const responseUrl = response.url();
+        if (responseUrl.includes("/_next/static/chunks/") && responseUrl.endsWith(".js")) {
+            chunkBodies.push(response.text().catch(() => ""));
+        }
+    };
+    page.on("response", collect);
+    await page.goto(url, { waitUntil: "networkidle" }).catch(() => undefined);
+    page.off("response", collect);
+    // Minified call site: `(0,x.createServerReference)("<hash>",x.callServer,
+    // void 0,x.findSourceMapURL,"<actionName>")`. The `\)?` matches that
+    // comma-expression form (and skips the runtime *definition*, which has
+    // no `(` after the name) — verified by `scripts/scan-agentic-actions.ts`.
+    const pattern = /createServerReference\)?\(\s*"([0-9a-f]{30,})"[^)]*?"([^"]*)"/g;
+    for (const chunk of await Promise.all(chunkBodies)) {
+        let match;
+        while ((match = pattern.exec(chunk)) !== null) {
+            if (match[2].toLowerCase().includes(actionNameHint))
+                return match[1];
+        }
+    }
+    return undefined;
+};
+/**
+ * Launch a headed browser, let the operator sign in, and capture the
+ * resulting BFF session cookie as an `AgentsCredential`.
+ */
+const runPlaywrightLogin = async (options) => {
+    const baseUrl = (0, types_1.agentsBaseUrl)(options.region);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
+    const { chromium } = await loadPlaywright();
+    let browser;
+    let lastError;
+    for (const channel of CHANNELS) {
+        try {
+            browser = await chromium.launch({ headless: false, channel });
+            break;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    if (!browser) {
+        throw (0, errors_1.createScaiError)("Could not launch a browser for Agentic Studio login.", "AUTH_REQUIRED", {
+            hint: "Install Google Chrome or Microsoft Edge. Underlying error: " +
+                (lastError instanceof Error ? lastError.message : String(lastError)),
+        });
+    }
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        // Capture the real browser User-Agent now, on the stable `about:blank`
+        // page — it is replayed on every API call so the edge WAF accepts
+        // requests made from Node. Done *after* sign-in this raced the Auth0
+        // redirect chain and destroyed the evaluate context ("Execution
+        // context was destroyed"); the blank page has the same UA and never
+        // navigates, so capturing it here is race-free.
+        const userAgent = String(await page.evaluate("navigator.userAgent"));
+        await page.goto(`${baseUrl}/agents`, { waitUntil: "domcontentloaded" });
+        // The operator completes Auth0 (+ MFA) in the window. Detect completion
+        // by polling an authenticated endpoint: /api/agents answers 200 ONLY
+        // once the BFF session cookie is set. (token-refresh answers 2xx even
+        // for an anonymous context, which would close the window before login.)
+        const deadline = Date.now() + timeoutMs;
+        let authenticated = false;
+        while (Date.now() < deadline) {
+            const probe = await context.request
+                .get(`${baseUrl}/api/agents`, { failOnStatusCode: false, maxRedirects: 0 })
+                .catch(() => undefined);
+            if (probe && probe.status() === 200) {
+                authenticated = true;
+                break;
+            }
+            await page.waitForTimeout(2000);
+        }
+        if (!authenticated) {
+            throw (0, errors_1.createScaiError)("Timed out waiting for Agentic Studio login to complete.", "AUTH_REQUIRED", { hint: "Re-run `scai agents login` and finish signing in within the browser window." });
+        }
+        const cookies = await context.cookies(baseUrl);
+        const cookieHeader = cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
+        if (!cookieHeader) {
+            throw (0, errors_1.createScaiError)("Agentic Studio login completed but no session cookie was captured.", "AUTH_REQUIRED");
+        }
+        // Capture the server-action hashes for the create pages — they rotate
+        // per Agentic Studio deploy, so discovering them here keeps the
+        // schema / html-template writes self-healing across logins.
+        const actionHashes = {};
+        const schemaHash = await discoverActionHash(page, `${baseUrl}/schemas/create`, "schema");
+        if (schemaHash)
+            actionHashes["/schemas/create"] = schemaHash;
+        const templateHash = await discoverActionHash(page, `${baseUrl}/html-templates/create`, "template");
+        if (templateHash)
+            actionHashes["/html-templates/create"] = templateHash;
+        return {
+            kind: "cookie",
+            region: options.region,
+            cookieHeader,
+            userAgent,
+            capturedAt: new Date().toISOString(),
+            ...(Object.keys(actionHashes).length > 0 ? { actionHashes } : {}),
+        };
+    }
+    finally {
+        await browser.close();
+    }
+};
+exports.runPlaywrightLogin = runPlaywrightLogin;

package/dist/agents/session/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Auth seam for the Sitecore Agentic Studio BFF.
+ *
+ * Agentic Studio's `/api/*` routes are gated by a first-party browser
+ * **session cookie**, not a bearer token — so this area does NOT use the
+ * client-credentials OAuth the rest of scai relies on. An `AgentsSession`
+ * is just "an origin plus the headers that authenticate a request": a
+ * `Cookie` header today, an `Authorization` header once Sitecore exposes
+ * the product to ordinary user credentials.
+ *
+ * TEMPORARY — the cookie path exists only until that happens. Everything
+ * Playwright-specific is confined to `playwright-login.ts`; nothing else
+ * in `src/agents/` imports it. To retire the browser path:
+ *   1. add a `kind: "bearer"` variant to `AgentsCredential`,
+ *   2. handle it in `createAgentsSession` (`authHeaders` → `Authorization`),
+ *   3. delete `playwright-login.ts` and drop the `playwright-core` dep.
+ * The transport in `api/request.ts` does not change.
+ */
+/** Default Agentic Studio region (EU West). */
+export declare const DEFAULT_AGENTS_REGION = "euw";
+/** Origin of a regional Agentic Studio deployment. */
+export declare const agentsBaseUrl: (region?: string) => string;
+/**
+ * A persisted Agentic Studio credential (OS keychain). The `kind`
+ * discriminator is the seam — only `"cookie"` exists today.
+ */
+export interface AgentsCredential {
+    kind: "cookie";
+    /** Region the credential is bound to — selects the BFF origin. */
+    region: string;
+    /** `Cookie:` header value carrying the BFF session. */
+    cookieHeader: string;
+    /**
+     * Browser User-Agent captured at login. Replayed on every request —
+     * Sitecore Cloud's edge WAF answers HTTP 406 to non-browser callers.
+     */
+    userAgent: string;
+    /**
+     * Server-action hashes discovered at login, keyed by route (e.g.
+     * `/schemas/create`). They rotate per Agentic Studio deploy —
+     * capturing them fresh each login keeps the schema / html-template
+     * writes working with no manual upkeep. Absent if discovery failed.
+     */
+    actionHashes?: Record<string, string>;
+    /** ISO-8601 timestamp the session was captured. */
+    capturedAt: string;
+}
+/** Per-request options understood by the Agentic Studio transport. */
+export interface AgentsRequestInit {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | undefined>;
+    signal?: AbortSignal;
+}
+/**
+ * An authenticated handle to one Agentic Studio tenant. The transport
+ * (`api/request.ts`) talks only to this interface — it never learns
+ * whether auth is a cookie (today) or a bearer token (future).
+ */
+export interface AgentsSession {
+    /** BFF origin, e.g. `https://agentic-studio-euw.sitecorecloud.io`. */
+    readonly baseUrl: string;
+    /** Headers that authenticate a request — `Cookie` today. */
+    authHeaders(): Record<string, string>;
+    /**
+     * Server-action hashes captured at login (see `AgentsCredential`),
+     * keyed by route. Consumed by the server-action writes (schema,
+     * html-template); absent for sessions built without Playwright.
+     */
+    readonly actionHashes?: Record<string, string>;
+}

package/dist/agents/session/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Auth seam for the Sitecore Agentic Studio BFF.
+ *
+ * Agentic Studio's `/api/*` routes are gated by a first-party browser
+ * **session cookie**, not a bearer token — so this area does NOT use the
+ * client-credentials OAuth the rest of scai relies on. An `AgentsSession`
+ * is just "an origin plus the headers that authenticate a request": a
+ * `Cookie` header today, an `Authorization` header once Sitecore exposes
+ * the product to ordinary user credentials.
+ *
+ * TEMPORARY — the cookie path exists only until that happens. Everything
+ * Playwright-specific is confined to `playwright-login.ts`; nothing else
+ * in `src/agents/` imports it. To retire the browser path:
+ *   1. add a `kind: "bearer"` variant to `AgentsCredential`,
+ *   2. handle it in `createAgentsSession` (`authHeaders` → `Authorization`),
+ *   3. delete `playwright-login.ts` and drop the `playwright-core` dep.
+ * The transport in `api/request.ts` does not change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsBaseUrl = exports.DEFAULT_AGENTS_REGION = void 0;
+/** Default Agentic Studio region (EU West). */
+exports.DEFAULT_AGENTS_REGION = "euw";
+/** Origin of a regional Agentic Studio deployment. */
+const agentsBaseUrl = (region = exports.DEFAULT_AGENTS_REGION) => `https://agentic-studio-${region}.sitecorecloud.io`;
+exports.agentsBaseUrl = agentsBaseUrl;

package/dist/agents/tasks/agent.d.ts

@@ -0,0 +1,27 @@
+import { type RunAgentsBaseOptions } from "./shared";
+export declare const runAgentList: (options: RunAgentsBaseOptions) => Promise<void>;
+export declare const runAgentGet: (options: RunAgentsBaseOptions & {
+    idOrSlug: string;
+}) => Promise<void>;
+export declare const runAgentCreate: (options: RunAgentsBaseOptions & {
+    file: string;
+    whatIf?: boolean;
+}) => Promise<void>;
+export declare const runAgentUpdate: (options: RunAgentsBaseOptions & {
+    idOrSlug: string;
+    file: string;
+    whatIf?: boolean;
+}) => Promise<void>;
+export declare const runAgentDuplicate: (options: RunAgentsBaseOptions & {
+    idOrSlug: string;
+    name: string;
+    whatIf?: boolean;
+}) => Promise<void>;
+export declare const runAgentDelete: (options: RunAgentsBaseOptions & {
+    idOrSlug: string;
+    whatIf?: boolean;
+}) => Promise<void>;
+export declare const runAgentRun: (options: RunAgentsBaseOptions & {
+    agentSlug: string;
+    message: string;
+}) => Promise<void>;

package/dist/agents/tasks/agent.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentRun = exports.runAgentDelete = exports.runAgentDuplicate = exports.runAgentUpdate = exports.runAgentCreate = exports.runAgentGet = exports.runAgentList = void 0;
+/**
+ * `scai agents agent …` — CRUD + run for Agentic Studio agents.
+ *
+ * Agents are the one Agentic Studio resource with a fully verified write
+ * API (`/api/agents` create / update / delete / duplicate), so this is
+ * straight imperative CRUD. `create` / `update` take a recipe file
+ * (`AgentRecipeSchema`) — the same format `scai agents sync` uses, so a
+ * file works with either path.
+ */
+const sync_1 = require("../../sync");
+const errors_1 = require("../../shared/errors");
+const agents_1 = require("../api/agents");
+const runs_1 = require("../api/runs");
+const spaces_1 = require("../api/spaces");
+const agent_schema_1 = require("../recipe/agent.schema");
+const agent_kind_1 = require("../recipe/agent.kind");
+const shared_1 = require("./shared");
+/** Match an agent by display name, falling back to slug. */
+const findByName = (agents, name) => agents.find((agent) => agent.name === name || agent.slug === name);
+const runAgentList = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    (0, shared_1.renderList)(logger, "agent(s)", await (0, agents_1.listAgents)(session), (agent) => `${agent.slug.padEnd(30)} ${agent.name ?? ""}`);
+};
+exports.runAgentList = runAgentList;
+const runAgentGet = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const agent = await (0, agents_1.getAgent)(session, options.idOrSlug);
+    if (!agent) {
+        throw (0, errors_1.createScaiError)(`Agent "${options.idOrSlug}" not found.`, "INPUT_INVALID", {
+            hint: "List agents with `scai agents agent list`.",
+        });
+    }
+    (0, shared_1.renderItem)(logger, `agent "${agent.slug}"`, agent);
+};
+exports.runAgentGet = runAgentGet;
+const runAgentCreate = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const recipe = (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
+    if (findByName(await (0, agents_1.listAgents)(session), recipe.name)) {
+        throw (0, errors_1.createScaiError)(`Agent "${recipe.name}" already exists.`, "INPUT_INVALID", {
+            hint: "Use `scai agents agent update` to change it, or pick a different name.",
+        });
+    }
+    if (options.whatIf) {
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ plan: { create: recipe.name } });
+        else
+            logger.info(`Would create agent "${recipe.name}".`, "yellow");
+        return;
+    }
+    const config = await (0, agent_kind_1.buildAgentConfig)(session, recipe);
+    const created = await (0, agents_1.createAgent)(session, {
+        name: recipe.name,
+        description: recipe.description,
+        prompt: recipe.prompt,
+        tags: recipe.tags,
+        config,
+    });
+    if (logger.isJson())
+        (0, shared_1.writeJson)({ ok: true, created });
+    else
+        logger.info(`Created agent "${recipe.name}".`, "green");
+};
+exports.runAgentCreate = runAgentCreate;
+const runAgentUpdate = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const recipe = (0, sync_1.loadRecipe)(options.file, agent_schema_1.AgentRecipeSchema);
+    const existing = await (0, agents_1.getAgent)(session, options.idOrSlug);
+    if (!existing) {
+        throw (0, errors_1.createScaiError)(`Agent "${options.idOrSlug}" not found.`, "INPUT_INVALID", {
+            hint: "List agents with `scai agents agent list`.",
+        });
+    }
+    if (options.whatIf) {
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ plan: { update: existing.id } });
+        else
+            logger.info(`Would update agent "${existing.slug}" (${existing.id}).`, "yellow");
+        return;
+    }
+    const config = await (0, agent_kind_1.buildAgentConfig)(session, recipe);
+    await (0, agents_1.updateAgent)(session, {
+        id: existing.id,
+        name: recipe.name,
+        description: recipe.description,
+        config,
+    });
+    if (logger.isJson())
+        (0, shared_1.writeJson)({ ok: true, updated: existing.id });
+    else
+        logger.info(`Updated agent "${recipe.name}".`, "green");
+};
+exports.runAgentUpdate = runAgentUpdate;
+const runAgentDuplicate = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const existing = await (0, agents_1.getAgent)(session, options.idOrSlug);
+    if (!existing) {
+        throw (0, errors_1.createScaiError)(`Agent "${options.idOrSlug}" not found.`, "INPUT_INVALID", {
+            hint: "List agents with `scai agents agent list`.",
+        });
+    }
+    if (options.whatIf) {
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ plan: { duplicate: existing.id, as: options.name } });
+        else
+            logger.info(`Would duplicate agent "${existing.slug}" as "${options.name}".`, "yellow");
+        return;
+    }
+    const created = await (0, agents_1.duplicateAgent)(session, existing.id, options.name);
+    if (logger.isJson())
+        (0, shared_1.writeJson)({ ok: true, created });
+    else
+        logger.info(`Duplicated agent "${existing.slug}" as "${options.name}".`, "green");
+};
+exports.runAgentDuplicate = runAgentDuplicate;
+const runAgentDelete = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const agent = await (0, agents_1.getAgent)(session, options.idOrSlug);
+    if (!agent) {
+        throw (0, errors_1.createScaiError)(`Agent "${options.idOrSlug}" not found.`, "INPUT_INVALID");
+    }
+    if (options.whatIf) {
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ plan: { delete: agent.id } });
+        else
+            logger.info(`Would delete agent "${agent.slug}" (${agent.id}).`, "yellow");
+        return;
+    }
+    await (0, agents_1.deleteAgent)(session, agent.id);
+    if (logger.isJson())
+        (0, shared_1.writeJson)({ ok: true, deleted: agent.id });
+    else
+        logger.info(`Deleted agent "${agent.slug}".`, "green");
+};
+exports.runAgentDelete = runAgentDelete;
+/**
+ * Best-effort fetch of a finished run's artifacts (`{ ok, data }` on the
+ * run's space). Never throws — a run that streamed fine should not fail
+ * just because the artifacts read did.
+ */
+const collectArtifacts = async (session, spaceId) => {
+    try {
+        return (await (0, spaces_1.getSpaceArtifacts)(session, spaceId)).data;
+    }
+    catch {
+        return undefined;
+    }
+};
+const runAgentRun = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const { spaceId, events } = await (0, runs_1.runAgent)(session, {
+        agentSlug: options.agentSlug,
+        message: options.message,
+    });
+    if (logger.isJson()) {
+        const collected = [];
+        for await (const event of events)
+            collected.push(event);
+        (0, shared_1.writeJson)({ spaceId, events: collected, artifacts: await collectArtifacts(session, spaceId) });
+        return;
+    }
+    logger.info(`Running "${options.agentSlug}" (space ${spaceId})…`, "cyan");
+    for await (const event of events) {
+        if (event.type === "text-delta" && typeof event.delta === "string") {
+            process.stdout.write(event.delta);
+        }
+        else if (event.type === "data-artifactDelta") {
+            const data = event.data;
+            if (typeof data?.content === "string")
+                process.stdout.write(data.content);
+        }
+    }
+    process.stdout.write("\n");
+    const artifacts = await collectArtifacts(session, spaceId);
+    if (artifacts !== undefined && artifacts !== null) {
+        logger.info("Run artifacts:", "cyan");
+        logger.info(JSON.stringify(artifacts, null, 2));
+    }
+};
+exports.runAgentRun = runAgentRun;

package/dist/agents/tasks/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `scai agents …` task runners — barrel.
+ *
+ * Runners are split by area: `shared` (env + session + rendering
+ * plumbing), `session` (login / logout / status), `agent` (agent CRUD +
+ * run), and `resources` (the shared skill / widget / schema / mcp /
+ * html-template / tool tasks). `@/agents/tasks` re-exports them all so
+ * command modules import from a single path.
+ */
+export * from "./shared";
+export * from "./session";
+export * from "./agent";
+export * from "./resources";
+export * from "./space";

package/dist/agents/tasks/index.js

@@ -0,0 +1,30 @@
+"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 });
+/**
+ * `scai agents …` task runners — barrel.
+ *
+ * Runners are split by area: `shared` (env + session + rendering
+ * plumbing), `session` (login / logout / status), `agent` (agent CRUD +
+ * run), and `resources` (the shared skill / widget / schema / mcp /
+ * html-template / tool tasks). `@/agents/tasks` re-exports them all so
+ * command modules import from a single path.
+ */
+__exportStar(require("./shared"), exports);
+__exportStar(require("./session"), exports);
+__exportStar(require("./agent"), exports);
+__exportStar(require("./resources"), exports);
+__exportStar(require("./space"), exports);