@foldrun/core 0.6.0 → 0.7.0

package/dist/src/install-helper.js

@@ -0,0 +1,134 @@
+// The root half of the `install` tool: a tiny server the run container's root
+// start-up leaves running before it drops to the agent user.
+//
+//   node install-helper.js <socket> <runtime cache dir>
+//
+// The agent never becomes root. It can only ask this process, over a unix
+// socket, to install Debian packages BY NAME — each name re-checked against
+// Debian's naming rule here, so nothing but a package name reaches apt, and
+// apt is driven by the same snippet the start-up uses (systemInstallSh): the
+// account's .deb cache and snapshots, so a package anyone installed before is
+// restored in about a second. Requests are served one at a time; the process
+// dies with the container.
+//
+// pip and npm need no root and are installed by the tool itself, as the agent.
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { DEB_PACKAGE, systemInstallSh, summarizeInstallFailure } from "./runtime.js";
+/** Validate one request; null when it may run. Exported for the tests. */
+export function refuse(req) {
+    const r = req;
+    if (!r || typeof r !== "object")
+        return "not a request";
+    if (r.manager !== "apt")
+        return "this helper installs Debian packages (manager: apt) only";
+    if (!Array.isArray(r.packages) || r.packages.length === 0)
+        return "no packages named";
+    if (r.packages.length > 50)
+        return "at most 50 packages per request";
+    const bad = r.packages.filter((p) => typeof p !== "string" || !DEB_PACKAGE.test(p));
+    if (bad.length)
+        return `not Debian package names: ${bad.map(String).join(", ")}`;
+    return null;
+}
+/** Install one validated request with the start-up's own snippet. */
+export function installApt(packages, cacheDir) {
+    const logDir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-install-"));
+    return new Promise((resolve) => {
+        const child = spawn("sh", ["-c", systemInstallSh(cacheDir, logDir)], {
+            env: { ...process.env, FOLDRUN_SYSTEM_PACKAGES: packages.join(" ") },
+            stdio: "ignore",
+        });
+        child.on("close", () => {
+            let status = {};
+            try {
+                status = JSON.parse(fs.readFileSync(path.join(logDir, "system-install.json"), "utf8"));
+            }
+            catch {
+                status = { ok: false };
+            }
+            let log = "";
+            try {
+                log = fs.readFileSync(path.join(logDir, "system-install.log"), "utf8");
+            }
+            catch {
+                log = "";
+            }
+            fs.rmSync(logDir, { recursive: true, force: true });
+            resolve(status.ok
+                ? { ok: true, mode: status.mode, seconds: status.seconds }
+                : { ok: false, error: summarizeInstallFailure("apt-get install", log || "no output") });
+        });
+        child.on("error", (err) => {
+            fs.rmSync(logDir, { recursive: true, force: true });
+            resolve({ ok: false, error: `could not run the installer: ${err.message}` });
+        });
+    });
+}
+export function serve(socket, cacheDir) {
+    try {
+        fs.rmSync(socket, { force: true });
+    }
+    catch {
+        /* nothing there */
+    }
+    let queue = Promise.resolve();
+    const server = net.createServer((conn) => {
+        let buf = "";
+        conn.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            if (buf.length > 64_000) {
+                conn.end(JSON.stringify({ ok: false, error: "request too large" }) + "\n");
+                return;
+            }
+            const nl = buf.indexOf("\n");
+            if (nl < 0)
+                return;
+            const line = buf.slice(0, nl);
+            buf = "";
+            let req;
+            try {
+                req = JSON.parse(line);
+            }
+            catch {
+                conn.end(JSON.stringify({ ok: false, error: "not JSON" }) + "\n");
+                return;
+            }
+            const why = refuse(req);
+            if (why) {
+                conn.end(JSON.stringify({ ok: false, error: why }) + "\n");
+                return;
+            }
+            // One install at a time: apt holds a lock, and two dpkg runs in one
+            // container would fight over it.
+            queue = queue.then(async () => {
+                const reply = await installApt(req.packages, cacheDir);
+                conn.end(JSON.stringify(reply) + "\n");
+            });
+        });
+        conn.on("error", () => {
+            /* the client went away */
+        });
+    });
+    server.listen(socket, () => {
+        // The agent user must be able to connect; nothing else runs in here.
+        try {
+            fs.chmodSync(socket, 0o666);
+        }
+        catch {
+            /* best effort */
+        }
+    });
+    return server;
+}
+if (process.argv[1] && /install-helper\.(js|ts|mjs)$/.test(process.argv[1])) {
+    const [socket, cacheDir] = process.argv.slice(2);
+    if (!socket || !cacheDir) {
+        console.error("usage: install-helper <socket> <runtime cache dir>");
+        process.exit(2);
+    }
+    serve(socket, cacheDir);
+}

package/dist/src/install-tool.d.ts

@@ -0,0 +1,128 @@
+type Emit = (type: "text" | "tool" | "info" | "error", text: string) => void;
+export declare const INSTALL_TOOL = "mcp__foldrun_install__install";
+/** Ask the root helper; resolves with its reply or an error. */
+export declare function askHelper(socket: string, packages: string[], timeoutMs?: number): Promise<{
+    ok: boolean;
+    mode?: string;
+    seconds?: number;
+    error?: string;
+}>;
+export declare function buildInstallTool(opts: {
+    /** The per-step directory pip and npm install into (stepInstallEnv's). */
+    dir: string;
+    /** The root helper's socket; null where there is none (a laptop). */
+    socket: string | null;
+    /** The account's runtime cache, for uv's and npm's download caches. */
+    cacheRoot: string;
+    /** The interpreter pip installs for: the declared venv's, else python3. */
+    python: string;
+    env: Record<string, string | undefined>;
+    emit: Emit;
+}): {
+    server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+    toolName: string;
+    /** What this step installed, `manager:name`, for the run record. */
+    installed: () => string[];
+    /** The handler, for tests. */
+    call: (args: {
+        manager: "apt" | "pip" | "npm";
+        packages: string[];
+    }) => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export {};

package/dist/src/install-tool.js

@@ -0,0 +1,133 @@
+// The `install` tool: an agent installs what it finds it needs, mid-step,
+// without anyone having declared it. Built in and granted to every agent
+// (take it away with `disallowedTools: [install]`).
+//
+//   install(manager: "apt",  packages: ["ffmpeg"])      — Debian programs and libraries
+//   install(manager: "pip",  packages: ["manim>=0.19"]) — Python packages
+//   install(manager: "npm",  packages: ["sharp"])       — Node packages
+//
+// apt needs root, which the agent never has: it asks the root start-up's
+// install helper over a unix socket (install-helper.ts), which installs only
+// validated names through the same cache and snapshots as `runtime: system:`.
+// pip and npm need no root and run here, as the agent, into a per-step
+// directory already on PATH / PYTHONPATH / NODE_PATH (stepInstallEnv), so the
+// next command finds what this one installed. Inside a run container all of
+// it goes when the container does. Every install is logged with the line to
+// add to the agent's `runtime:` to have it before the step starts next time.
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { DEB_PACKAGE, PIP_REQUIREMENT, NPM_REQUIREMENT, summarizeInstallFailure } from "./runtime.js";
+export const INSTALL_TOOL = "mcp__foldrun_install__install";
+const PATTERNS = { apt: DEB_PACKAGE, pip: PIP_REQUIREMENT, npm: NPM_REQUIREMENT };
+const RUNTIME_KEY = { apt: "system", pip: "packages", npm: "npm" };
+function findUv() {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (dir && fs.existsSync(path.join(dir, "uv")))
+            return path.join(dir, "uv");
+    }
+    return null;
+}
+/** Ask the root helper; resolves with its reply or an error. */
+export function askHelper(socket, packages, timeoutMs = 600_000) {
+    return new Promise((resolve) => {
+        const conn = net.createConnection(socket);
+        let buf = "";
+        const timer = setTimeout(() => {
+            conn.destroy();
+            resolve({ ok: false, error: `the install helper did not answer in ${Math.round(timeoutMs / 1000)}s` });
+        }, timeoutMs);
+        conn.on("connect", () => conn.write(JSON.stringify({ manager: "apt", packages }) + "\n"));
+        conn.on("data", (c) => (buf += c.toString("utf8")));
+        conn.on("end", () => {
+            clearTimeout(timer);
+            try {
+                resolve(JSON.parse(buf.trim()));
+            }
+            catch {
+                resolve({ ok: false, error: "the install helper sent no answer" });
+            }
+        });
+        conn.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, error: `the install helper is not reachable (${err.message})` });
+        });
+    });
+}
+export function buildInstallTool(opts) {
+    const installed = [];
+    const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
+    const install = tool("install", "Install a program or library this step needs and does not have: Debian packages with manager \"apt\" (ffmpeg, imagemagick, tesseract-ocr, libcairo2-dev, build-essential), Python packages with \"pip\", Node packages with \"npm\". Use this instead of apt-get, pip or npm in Bash — you are not root and those would fail. What you install is usable by your next command (on PATH, importable) and lasts for this step. Name real packages only; versions as the manager writes them (\"pandas>=2\", \"sharp@^0.34\").", {
+        manager: z.enum(["apt", "pip", "npm"]).describe("apt for Debian programs and system libraries, pip for Python, npm for Node"),
+        packages: z.array(z.string()).min(1).max(30).describe("Package names, e.g. [\"ffmpeg\"] or [\"manim\", \"numpy<2\"]"),
+    }, async ({ manager, packages }) => {
+        const names = packages.map((p) => String(p).trim()).filter(Boolean);
+        const bad = names.filter((p) => !PATTERNS[manager].test(p));
+        if (bad.length)
+            return text(`Not ${manager} package names: ${bad.join(", ")}. Nothing was installed.`, true);
+        const t0 = Date.now();
+        let how = "";
+        if (manager === "apt") {
+            if (!opts.socket || !fs.existsSync(opts.socket)) {
+                return text("Debian packages can only be installed inside a run container, and this step is not running in one. Nothing was installed.", true);
+            }
+            const r = await askHelper(opts.socket, names);
+            if (!r.ok) {
+                opts.emit("error", `install: apt ${names.join(" ")} — ${String(r.error).split("\n")[0]}`);
+                return text(r.error ?? "apt failed", true);
+            }
+            how = `${r.mode ?? "apt"}, ${r.seconds ?? Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        else if (manager === "pip") {
+            const target = path.join(opts.dir, "py");
+            fs.mkdirSync(target, { recursive: true });
+            const uv = findUv();
+            const res = uv
+                ? spawnSync(uv, ["pip", "install", "-q", "--python", opts.python, "--target", target, ...names], {
+                    env: { ...opts.env, UV_CACHE_DIR: path.join(opts.cacheRoot, ".uv-cache"), UV_LINK_MODE: "copy", UV_NO_PROGRESS: "1" },
+                    encoding: "utf8",
+                    timeout: 600_000,
+                })
+                : spawnSync(opts.python, ["-m", "pip", "install", "-q", "--disable-pip-version-check", "--target", target, ...names], {
+                    env: opts.env,
+                    encoding: "utf8",
+                    timeout: 600_000,
+                });
+            if (res.status !== 0) {
+                const msg = summarizeInstallFailure(uv ? "uv pip install" : "pip install", `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`);
+                opts.emit("error", `install: pip ${names.join(" ")} — ${msg.split("\n")[0]}`);
+                return text(msg, true);
+            }
+            how = `pip, ${Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        else {
+            const prefix = path.join(opts.dir, "npm");
+            fs.mkdirSync(prefix, { recursive: true });
+            const res = spawnSync("npm", ["install", "--no-fund", "--no-audit", "--no-progress", "--prefix", prefix, ...names], {
+                env: { ...opts.env, npm_config_cache: path.join(opts.cacheRoot, ".npm-cache") },
+                encoding: "utf8",
+                timeout: 600_000,
+            });
+            if (res.status !== 0) {
+                const msg = summarizeInstallFailure("npm install", `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`);
+                opts.emit("error", `install: npm ${names.join(" ")} — ${msg.split("\n")[0]}`);
+                return text(msg, true);
+            }
+            how = `npm, ${Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        installed.push(...names.map((n) => `${manager}:${n}`));
+        opts.emit("info", `install: ${manager} ${names.join(" ")} — ready (${how}). To have it before the step starts: runtime: ${RUNTIME_KEY[manager]}: [${names.join(", ")}]`);
+        return text(`Installed ${names.join(", ")} (${manager}). Usable now in this step — run it or import it directly.`);
+    });
+    return {
+        server: createSdkMcpServer({ name: "foldrun_install", version: "1.0.0", tools: [install] }),
+        toolName: INSTALL_TOOL,
+        /** What this step installed, `manager:name`, for the run record. */
+        installed: () => [...installed],
+        /** The handler, for tests. */
+        call: (args) => install.handler(args, {}),
+    };
+}

package/dist/src/model-credential.d.ts

@@ -12,3 +12,19 @@ export declare function credentialLine(c: ModelCredential): {
     type: "info" | "error";
     text: string;
 };
+/** The account vault names the account's own model key lives under. */
+export declare const ACCOUNT_MODEL_SECRETS: {
+    readonly provider: "FOLDRUN_MODEL_PROVIDER";
+    readonly key: "FOLDRUN_MODEL_API_KEY";
+    readonly baseUrl: "FOLDRUN_MODEL_BASE_URL";
+    readonly format: "FOLDRUN_MODEL_FORMAT";
+};
+/** A provider: block built from the account's own model secrets, or
+ *  undefined when it has set no key. `read` is the account-scope secret
+ *  reader (getSecret without a workspace). */
+export declare function accountModelBlock(read: (name: string) => string | null): Record<string, unknown> | undefined;
+/** A Claude login token (`claude setup-token`, sk-ant-oat…), not an API key.
+ *  Anthropic's terms do not let a third-party product run customers on
+ *  claude.ai logins, so on a hosted platform only the operator's own
+ *  accounts may; a customer's key must be an API key. */
+export declare function isClaudeLoginToken(value: string | null | undefined): boolean;

package/dist/src/model-credential.js

@@ -56,3 +56,43 @@ export function credentialLine(c) {
             "Set ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN from `claude setup-token`",
     };
 }
+// ---------------------------------------------------------------- the account's own key
+//
+// An account brings its own model key without writing a provider: block:
+// three secrets in the ACCOUNT vault (set from Settings → Model, the API's
+// /api/account/model, or `foldrun model set`). A provider: block at any
+// level still wins; this is what a step falls to when none names one, before
+// the platform's own credential.
+/** The account vault names the account's own model key lives under. */
+export const ACCOUNT_MODEL_SECRETS = {
+    provider: "FOLDRUN_MODEL_PROVIDER",
+    key: "FOLDRUN_MODEL_API_KEY",
+    baseUrl: "FOLDRUN_MODEL_BASE_URL",
+    format: "FOLDRUN_MODEL_FORMAT",
+};
+/** A provider: block built from the account's own model secrets, or
+ *  undefined when it has set no key. `read` is the account-scope secret
+ *  reader (getSecret without a workspace). */
+export function accountModelBlock(read) {
+    const key = read(ACCOUNT_MODEL_SECRETS.key);
+    if (!key)
+        return undefined;
+    const block = { token: `\${${ACCOUNT_MODEL_SECRETS.key}}` };
+    const name = read(ACCOUNT_MODEL_SECRETS.provider);
+    const baseUrl = read(ACCOUNT_MODEL_SECRETS.baseUrl);
+    const format = read(ACCOUNT_MODEL_SECRETS.format);
+    if (name)
+        block.name = name;
+    if (baseUrl)
+        block.base_url = baseUrl;
+    if (format)
+        block.format = format;
+    return block;
+}
+/** A Claude login token (`claude setup-token`, sk-ant-oat…), not an API key.
+ *  Anthropic's terms do not let a third-party product run customers on
+ *  claude.ai logins, so on a hosted platform only the operator's own
+ *  accounts may; a customer's key must be an API key. */
+export function isClaudeLoginToken(value) {
+    return typeof value === "string" && /^sk-ant-oat\d*-/.test(value.trim());
+}

package/dist/src/model-env.d.ts

@@ -0,0 +1,17 @@
+/** Refused for want of a usable key; `status` is what an HTTP layer answers. */
+export declare class ModelKeyError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare const NO_MODEL_KEY: string;
+/**
+ * `platform` is a function: the caller's own way to build the platform's env
+ * (a step's, or the SDK's host env), called only when this account may use
+ * it. `format` says what the endpoint speaks — a caller with no translator
+ * refuses anything but anthropic.
+ */
+export declare function accountModelEnv(tenant: string, workspace: string, platformEnv: () => Record<string, string | undefined>): {
+    env: Record<string, string | undefined>;
+    supply: "provider" | "platform";
+    format: string;
+};

package/dist/src/model-env.js

@@ -0,0 +1,57 @@
+// The model environment for work an ACCOUNT asks for outside a step: an eval's
+// judge, the dashboard's "draft a flow with AI". Resolved the way a step
+// resolves it — the workspace's provider: block, else the account's, else the
+// account's own key from Settings → Model — and only then the platform's own
+// credential, which a hosted platform keeps for its operator's accounts
+// (platform.platformKeyAllowed). Every other account brings an API key;
+// asking for the platform's here is refused, not quietly billed to it.
+import { accountDir, workspaceDir, parseProvider, providerEnvFor } from "./store.js";
+import { readAgentsMd } from "./runner.js";
+import { getSecret } from "./secrets.js";
+import { platform } from "./platform.js";
+import { accountModelBlock, isClaudeLoginToken } from "./model-credential.js";
+/** Refused for want of a usable key; `status` is what an HTTP layer answers. */
+export class ModelKeyError extends Error {
+    status;
+    constructor(message, status = 402) {
+        super(message);
+        this.status = status;
+    }
+}
+export const NO_MODEL_KEY = "no model key: this account runs on its own API key, and none is set — add one in Settings → Model " +
+    "(or `foldrun model set <provider> --key …`), or write a provider: block in AGENTS.md";
+/**
+ * `platform` is a function: the caller's own way to build the platform's env
+ * (a step's, or the SDK's host env), called only when this account may use
+ * it. `format` says what the endpoint speaks — a caller with no translator
+ * refuses anything but anthropic.
+ */
+export function accountModelEnv(tenant, workspace, platformEnv) {
+    const raw = readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider ??
+        readAgentsMd(accountDir(tenant))?.data?.provider ??
+        accountModelBlock((name) => getSecret(tenant, name)?.value ?? null);
+    const spec = parseProvider(raw);
+    if (!spec?.baseUrl) {
+        if (!platform.platformKeyAllowed(tenant))
+            throw new ModelKeyError(NO_MODEL_KEY);
+        return { env: platformEnv(), supply: "platform", format: "anthropic" };
+    }
+    const sub = (text) => text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => getSecret(tenant, name, workspace)?.value ?? whole);
+    const token = sub(spec.token);
+    if (token.includes("${"))
+        throw new ModelKeyError("the provider's token secret is not set — `foldrun secrets` sets it", 422);
+    if (!platform.platformKeyAllowed(tenant) && isClaudeLoginToken(token)) {
+        throw new ModelKeyError("model key: a Claude login token (sk-ant-oat…) cannot be used here — use an API key from your provider", 422);
+    }
+    return {
+        env: providerEnvFor({
+            baseUrl: spec.baseUrl,
+            token,
+            auth: spec.auth,
+            models: spec.models,
+            headers: Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)])),
+        }),
+        supply: "provider",
+        format: spec.format,
+    };
+}

package/dist/src/package.d.ts

@@ -0,0 +1,67 @@
+import { type DeployFile } from "./store.ts";
+export type PackageKind = "workspace" | "flow" | "agent";
+export interface PackageManifest {
+    format: "foldrun-package";
+    version: 1;
+    kind: PackageKind;
+    /** The workspace's, flow's or agent's name. */
+    name: string;
+    /** The workspace it was exported from. */
+    workspace: string;
+    exportedAt: string;
+    files: string[];
+}
+export interface Package {
+    manifest: PackageManifest;
+    files: DeployFile[];
+    /** Entries in the zip that are not authored source, left out (readPackage). */
+    skipped?: string[];
+}
+/** An error the API layer turns into a status rather than a 500. */
+export declare class PackageError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare const MANIFEST_FILE = "foldrun-package.json";
+export declare function isPackagedPath(rel: string): boolean;
+export declare function packageOf(tenant: string, workspace: string, kind: PackageKind, name?: string): Package;
+export declare function packageZip(pkg: Package): Buffer;
+/** What the download is called: `<workspace>.zip`, `<workspace>-flow-<name>.zip`. */
+export declare function packageFilename(m: PackageManifest): string;
+export declare function readPackage(buf: Buffer): Package;
+export interface ImportPlan {
+    kind: PackageKind;
+    name: string;
+    /** Where it came from, as the package says. */
+    from: string;
+    workspace: string;
+    /** True when the workspace does not exist yet and the import makes it. */
+    creates: boolean;
+    added: string[];
+    /** Files that exist with different text — written only with `overwrite`. */
+    overwritten: string[];
+    unchanged: string[];
+    /** In the zip, not written: memory, state, .gitignore, anything outside
+     *  the authored folders. */
+    skipped: string[];
+    /** What the imported files name that the target cannot provide. The import
+     *  still happens — a missing secret is set in a minute. */
+    needs: {
+        secrets: string[];
+        tools: string[];
+        skills: string[];
+        scripts: string[];
+        agents: string[];
+        flows: string[];
+    };
+}
+export interface ImportResult extends ImportPlan {
+    written: string[];
+    revision: string | null;
+}
+export declare function planImport(tenant: string, workspace: string, pkg: Package): ImportPlan;
+export declare function applyImport(tenant: string, workspace: string, pkg: Package, opts?: {
+    overwrite?: boolean;
+    by?: string;
+    expect?: "create" | "merge";
+}): ImportResult;