@clawscarf/cli 0.1.0-alpha.1

package/scripts/models/credentials.js

@@ -0,0 +1,132 @@
+import { OperatorError } from "../errors.js";
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { open, readFile, unlink } from "node:fs/promises";
+import { z } from "zod";
+import { Agent, fetch } from "undici";
+export async function issueRuntimeCredential(input) {
+    if (input.configuration.mode !== "litellm")
+        throw new OperatorError("Key provisioning requires bundled LiteLLM mode.");
+    const client = await managementClient(input);
+    const output = await open(input.output, "wx", 0o600).catch(async (error) => {
+        await client.close();
+        throw error;
+    });
+    let stored = false;
+    let cleanup;
+    try {
+        const response = await client.request("/key/generate", {
+            method: "POST",
+            redirect: "error",
+            signal: AbortSignal.timeout(30000),
+            headers: {
+                Authorization: `Bearer ${client.masterKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                models: input.configuration.models
+                    .filter((model) => model.enabled)
+                    .map((model) => model.id),
+                key_type: "llm_api",
+            }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new OperatorError("LiteLLM credential provisioning was rejected.");
+        }
+        const body = await response.json();
+        const result = z.object({ key: z.string().startsWith("sk-") }).parse(body);
+        await output.writeFile(`${result.key}\n`);
+        await output.sync();
+        stored = true;
+    }
+    finally {
+        cleanup = await Promise.allSettled([
+            output.close(),
+            client.close(),
+            ...(!stored ? [unlink(input.output)] : []),
+        ]);
+    }
+    if (cleanup.some((result) => result.status === "rejected"))
+        throw new OperatorError("Runtime key was stored, but local credential cleanup failed.");
+}
+async function managementClient(input) {
+    const origin = new URL(input.origin);
+    if (origin.origin !== input.origin ||
+        origin.username ||
+        origin.password ||
+        !["http:", "https:"].includes(origin.protocol))
+        throw new OperatorError("Use the private LiteLLM management origin.");
+    const masterKey = (await readFile(input.masterKeyFile, "utf8")).trim();
+    if (!masterKey.startsWith("sk-"))
+        throw new OperatorError("Invalid LiteLLM management credential.");
+    const dispatcher = input.caFile
+        ? new Agent({ connect: { ca: await readFile(input.caFile, "utf8") } })
+        : undefined;
+    return {
+        masterKey,
+        request: (path, options) => fetch(new URL(path, origin), {
+            ...options,
+            ...(dispatcher ? { dispatcher } : {}),
+        }),
+        close: async () => {
+            await dispatcher?.close();
+        },
+    };
+}
+/** Change only this existing key's model permissions; never create, renew or unblock it. */
+export async function setRuntimeCredentialModels(input) {
+    const key = (await readFile(input.keyFile, "utf8")).trim();
+    const models = z.array(z.string().min(1)).min(1).parse(input.models).sort();
+    const client = await managementClient(input);
+    try {
+        if (!key.startsWith("sk-") || key === client.masterKey)
+            throw new OperatorError("Supply distinct administrator and runtime credentials.");
+        const headers = {
+            Authorization: `Bearer ${client.masterKey}`,
+            "Content-Type": "application/json",
+        };
+        const observe = async () => {
+            const response = await client.request(`/key/info?key=${createHash("sha256").update(key).digest("hex")}`, {
+                headers,
+                redirect: "error",
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new OperatorError("The retained model credential could not be verified. It will not be replaced.");
+            }
+            const value = z
+                .object({
+                info: z.object({
+                    models: z.array(z.string()),
+                    blocked: z.boolean().nullable(),
+                    expires: z.iso.datetime({ offset: true }).nullable(),
+                }),
+            })
+                .parse(await response.json());
+            return { ...value.info, models: value.info.models.sort() };
+        };
+        const previous = await observe();
+        if (isDeepStrictEqual(previous.models, models))
+            return;
+        const response = await client.request("/key/update", {
+            method: "POST",
+            headers,
+            redirect: "error",
+            signal: AbortSignal.timeout(30_000),
+            body: JSON.stringify({ key, models }),
+        });
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new OperatorError("LiteLLM rejected the model permission change.");
+        const after = await observe();
+        if (!isDeepStrictEqual(after.models, models) ||
+            after.blocked !== previous.blocked ||
+            after.expires !== previous.expires)
+            throw new OperatorError("The model permission change was not confirmed. Observe the key before another explicit apply.");
+    }
+    finally {
+        await client.close();
+    }
+}

package/scripts/models/runtime.js

@@ -0,0 +1,87 @@
+import { modelResultSchema, ModelConfigurationError, } from "../../runtime/model-contract.js";
+import { spawn } from "node:child_process";
+import { nativeAssignments } from "./configuration.js";
+/** Use the same packaged native helper while its owned home volume is stopped. */
+export async function configureStoppedRuntimeModels(options) {
+    return runModelHelper("docker", [
+        "run",
+        "--rm",
+        "-i",
+        "--pull",
+        "never",
+        "--network",
+        "none",
+        "--read-only",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges:true",
+        "--user",
+        "1000:1000",
+        "--tmpfs",
+        "/tmp:rw,nosuid,nodev,size=64m",
+        "--mount",
+        `type=volume,source=${options.volume},target=/home/node,volume-nocopy`,
+        "--entrypoint",
+        "node",
+        options.image,
+        "/app/clawscarf/models-main.js",
+    ], {
+        assignments: nativeAssignments(options.configuration),
+        ...options.credential,
+        ca: options.credential.ca ?? null,
+        apply: options.apply,
+    });
+}
+/** Preserve structured helper failures and never replay an uncertain apply. */
+function runModelHelper(executable, args, input) {
+    return new Promise((resolve, reject) => {
+        let output = "";
+        const child = spawn(executable, args, {
+            stdio: ["pipe", "pipe", "ignore"],
+            signal: AbortSignal.timeout(60_000),
+        });
+        let spawned = false;
+        const transportFailure = () => new ModelConfigurationError(input.apply && spawned ? "outcome_unknown" : "unavailable");
+        child.once("spawn", () => {
+            spawned = true;
+        });
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            output += chunk;
+            if (output.length > 4096) {
+                child.kill();
+                reject(transportFailure());
+            }
+        });
+        child.once("error", () => {
+            reject(transportFailure());
+        });
+        child.stdin.on("error", () => {
+            reject(transportFailure());
+        });
+        child.once("close", (code) => {
+            try {
+                const value = JSON.parse(output);
+                const result = modelResultSchema.safeParse(value);
+                if (!result.success) {
+                    reject(transportFailure());
+                    return;
+                }
+                if (!result.data.ok) {
+                    reject(new ModelConfigurationError(result.data.error));
+                    return;
+                }
+                if (code !== 0) {
+                    reject(transportFailure());
+                    return;
+                }
+                resolve(result.data.state);
+            }
+            catch {
+                reject(transportFailure());
+            }
+        });
+        child.stdin.end(JSON.stringify(input));
+    });
+}

package/scripts/output.js

@@ -0,0 +1,34 @@
+/** Human output is deliberately not a scripting contract; use --json for that. */
+export function writeResult(command, value, human) {
+    const json = command.optsWithGlobals().json;
+    process.stdout.write((json ? JSON.stringify(value, null, 2) : (human ?? describe(value))) + "\n");
+}
+function describe(value, indent = "") {
+    if (value === null || value === undefined)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "Yes" : "No";
+    if (Array.isArray(value))
+        return value.length
+            ? value
+                .map((item) => `${indent}- ${describe(item, indent + "  ").trimStart()}`)
+                .join("\n")
+            : "None";
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "bigint")
+        return String(value);
+    if (typeof value !== "object")
+        return "Unavailable";
+    return Object.entries(value)
+        .map(([key, item]) => {
+        const label = key
+            .replace(/([a-z])([A-Z])/g, "$1 $2")
+            .replaceAll("_", " ");
+        const nested = item !== null &&
+            typeof item === "object" &&
+            (!Array.isArray(item) || item.length > 0);
+        return `${indent}${label.charAt(0).toUpperCase()}${label.slice(1)}:${nested ? "\n" : " "}${describe(item, nested ? indent + "  " : "")}`;
+    })
+        .join("\n");
+}

package/scripts/packs/connections.js

@@ -0,0 +1,95 @@
+import { OperatorError } from "../errors.js";
+import { readFile, realpath } from "node:fs/promises";
+import { sep } from "node:path";
+import { z } from "zod";
+import { createClient } from "../../generated/http/client/index.js";
+import { getConnection } from "../../services/connections/cloud/generated/sdk.gen.js";
+const bindingsSchema = z.strictObject({
+    origin: z.url(),
+    brokerUrl: z.url(),
+    sessionFile: z.string(),
+    connections: z.record(z.string(), z.uuid()),
+});
+export async function verifyConnections(member, native, sourceRoot, bindingsFile) {
+    const connections = [];
+    if (member.requirements.connections.length) {
+        if (!member.connectionFile)
+            throw new OperatorError("A connection-dependent member must declare its native-owned connectionFile.");
+        if (!native.supportsConnectionBindings)
+            throw new OperatorError("Connection-dependent packs require operator-side verification; do not copy administrator sessions into this runtime.");
+        if (!bindingsFile)
+            throw new OperatorError("This pack requires explicit connection bindings.");
+        const bindings = bindingsSchema.parse(JSON.parse(await readFile(bindingsFile, "utf8")));
+        const origin = new URL(bindings.origin);
+        if (origin.username ||
+            origin.password ||
+            origin.search ||
+            origin.hash ||
+            origin.pathname !== "/")
+            throw new OperatorError("Management origin must not contain credentials, path, query or fragment.");
+        if (origin.protocol !== "https:" &&
+            !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname))
+            throw new OperatorError("Connection bindings require HTTPS or a loopback origin.");
+        const broker = await native.brokerUrl();
+        if (broker !== bindings.brokerUrl.replace(/\/$/, ""))
+            throw new OperatorError("Connection bindings do not match the target runtime broker.");
+        for (const privatePath of [bindingsFile, bindings.sessionFile]) {
+            const path = await realpath(privatePath);
+            if (path === sourceRoot || path.startsWith(sourceRoot + sep))
+                throw new OperatorError("Keep connection bindings and administrator sessions outside the pack source.");
+        }
+        const cookie = (await readFile(bindings.sessionFile, "utf8")).trim();
+        if (!/^[A-Za-z0-9_-]+$/.test(cookie))
+            throw new OperatorError("Invalid session file.");
+        const client = createClient({
+            baseUrl: origin.origin,
+            redirect: "error",
+            headers: { Cookie: `clawscarf_session=${cookie}` },
+        });
+        for (const required of member.requirements.connections) {
+            const id = bindings.connections[required.slot];
+            if (!id)
+                throw new OperatorError(`Missing connection binding: ${required.slot}`);
+            const { data } = await getConnection({
+                client,
+                path: { connectionId: id },
+                throwOnError: true,
+                signal: AbortSignal.timeout(10_000),
+            });
+            const account = z
+                .object({
+                id: z.uuid(),
+                serverId: z.uuid(),
+                connectorId: z.string(),
+                name: z.string(),
+                state: z.string(),
+                revision: z.number().int(),
+                grant: z.discriminatedUnion("mode", [
+                    z.object({ mode: z.literal("all") }),
+                    z.object({
+                        mode: z.literal("selected"),
+                        agentIds: z.array(z.string()),
+                    }),
+                ]),
+            })
+                .parse(data);
+            if (account.id !== id ||
+                account.connectorId !== required.connectorId ||
+                account.state !== "connected" ||
+                (account.grant.mode === "selected" &&
+                    !account.grant.agentIds.includes(member.id)))
+                throw new OperatorError(`Connection binding is unavailable for ${member.id}: ${required.slot}`);
+            if (connections.some((connection) => connection.serverId !== account.serverId))
+                throw new OperatorError("Pack account bindings must belong to one server.");
+            connections.push({
+                slot: required.slot,
+                serverId: account.serverId,
+                connectionId: id,
+                revision: account.revision,
+                name: account.name,
+                connectorId: account.connectorId,
+            });
+        }
+    }
+    return connections;
+}

package/scripts/packs/lifecycle.js

@@ -0,0 +1,125 @@
+import { OperatorError } from "../errors.js";
+import { join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { openPack, prepareSource } from "./source.js";
+import { requirements } from "./requirements.js";
+import { planSchema } from "./model.js";
+function argumentsFor(operation, root, member, workspace) {
+    return operation === "add"
+        ? [
+            "claws",
+            "add",
+            join(root, member.source),
+            "--agent-id",
+            member.id,
+            "--workspace",
+            workspace,
+        ]
+        : operation === "update"
+            ? ["claws", "update", member.id, "--from", join(root, member.source)]
+            : ["claws", "remove", member.id];
+}
+export async function inspectPack(directory, native) {
+    await native.version();
+    const source = await openPack(directory);
+    const targetRoot = await native.source(source.root, source.digest);
+    const members = [];
+    for (const member of source.manifest.members)
+        members.push({
+            id: member.id,
+            native: await native.run([
+                "claws",
+                "inspect",
+                join(targetRoot, member.source),
+                "--json",
+            ]),
+        });
+    return { pack: source.manifest, digest: source.digest, members };
+}
+export async function planPack(input, native) {
+    await native.version();
+    const source = await openPack(input.directory);
+    const member = source.manifest.members.find((item) => item.id === input.member);
+    if (!member)
+        throw new OperatorError("Unknown pack member.");
+    const verified = input.operation === "remove"
+        ? { model: null, connections: [], network: null }
+        : await requirements(source.manifest, member, native, input.bindingsFile, source.root);
+    const target = await native.target();
+    const targetRoot = input.operation === "remove"
+        ? (input.targetPack ?? source.root)
+        : await prepareSource(source, member, verified.connections, native, input.targetPack);
+    const workspace = resolve(input.workspace);
+    const nativePlan = await native.run([
+        ...argumentsFor(input.operation, targetRoot, member, workspace),
+        "--dry-run",
+        "--json",
+    ]);
+    const validated = z
+        .object({
+        schemaVersion: z.literal({
+            add: "openclaw.clawAddPlan.v1",
+            update: "openclaw.clawUpdatePlan.v1",
+            remove: "openclaw.clawRemovePlan.v1",
+        }[input.operation]),
+        stability: z.literal("experimental"),
+        planIntegrity: z.string(),
+        diagnostics: z.array(z.object({ level: z.string() })).optional(),
+        summary: z
+            .object({
+            blockedActions: z.number().optional(),
+            blocked: z.number().optional(),
+        })
+            .optional(),
+    })
+        .parse(nativePlan);
+    if (validated.summary?.blockedActions ||
+        validated.summary?.blocked ||
+        validated.diagnostics?.some((item) => item.level === "error"))
+        throw new OperatorError("Native Claw plan is blocked; inspect it with openclaw claws before applying.");
+    return planSchema.parse({
+        schemaVersion: 1,
+        pack: source.root,
+        packDigest: source.digest,
+        target,
+        targetPack: targetRoot,
+        member: member.id,
+        operation: input.operation,
+        workspace,
+        nativePlan,
+        planIntegrity: validated.planIntegrity,
+        requirements: verified,
+    });
+}
+export async function applyPack(value, native, bindingsFile) {
+    const plan = planSchema.parse(value);
+    if (!isDeepStrictEqual(await native.target(), plan.target))
+        throw new OperatorError("Pack target changed; review a new plan.");
+    const source = await openPack(plan.pack);
+    if (source.digest !== plan.packDigest)
+        throw new OperatorError("Pack sources changed; review a new plan.");
+    const fresh = await planPack({
+        directory: source.root,
+        member: plan.member,
+        operation: plan.operation,
+        workspace: plan.workspace,
+        targetPack: plan.targetPack,
+        ...(bindingsFile ? { bindingsFile } : {}),
+    }, native);
+    if (fresh.targetPack !== plan.targetPack ||
+        !isDeepStrictEqual(fresh.target, plan.target) ||
+        fresh.planIntegrity !== plan.planIntegrity ||
+        !isDeepStrictEqual(fresh.requirements, plan.requirements))
+        throw new OperatorError("Native state or requirements changed; review a new plan.");
+    const member = source.manifest.members.find((item) => item.id === plan.member);
+    if (!member)
+        throw new OperatorError("Pack member disappeared.");
+    return native.run([
+        ...argumentsFor(plan.operation, plan.targetPack, member, plan.workspace),
+        "--yes",
+        "--plan-integrity",
+        plan.planIntegrity,
+        "--json",
+    ]);
+}

package/scripts/packs/model.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { networkRequirementSchema, policyProofSchema } from "./policy.js";
+const id = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+export const packSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    id,
+    version: z.string().regex(/^\d+\.\d+\.\d+$/),
+    openclaw: z.literal("2026.9.4"),
+    description: z.string().min(1),
+    members: z
+        .array(z.strictObject({
+        id,
+        source: z.string().regex(/^[a-z][a-z0-9/-]*$/),
+        connectionFile: z
+            .string()
+            .regex(/^[a-z][a-z0-9_-]*\.json$/)
+            .optional(),
+        requirements: z.strictObject({
+            model: z.enum(["configured-default", "none"]),
+            connections: z.array(z.strictObject({
+                slot: id,
+                connectorId: z.string().regex(/^[a-z][a-z0-9_]{0,99}$/),
+            })),
+        }),
+    }))
+        .min(1)
+        .max(32),
+    execution: z.strictObject({
+        location: z.literal("native-tools"),
+        binaries: z.array(z.string().regex(/^[a-zA-Z0-9._+-]+$/)),
+        network: z.array(networkRequirementSchema),
+    }),
+});
+export const targetSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("local") }),
+    z.strictObject({
+        kind: z.literal("openshell"),
+        gateway: z.string().min(1),
+        sandbox: z.string().min(1),
+        sandboxId: z.uuid(),
+    }),
+]);
+export const planSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    pack: z.string(),
+    packDigest: z.string(),
+    target: targetSchema,
+    targetPack: z.string(),
+    member: id,
+    operation: z.enum(["add", "update", "remove"]),
+    workspace: z.string(),
+    nativePlan: z.unknown(),
+    planIntegrity: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    requirements: z.object({
+        model: z.string().nullable(),
+        network: policyProofSchema.nullable(),
+        connections: z.array(z.object({
+            slot: z.string(),
+            connectionId: z.string(),
+            serverId: z.uuid(),
+            revision: z.number().int(),
+            name: z.string(),
+            connectorId: z.string(),
+        })),
+    }),
+});

package/scripts/packs/native.js

@@ -0,0 +1,69 @@
+import { OperatorError } from "../errors.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execute = promisify(execFile);
+export class NativeClaws {
+    executable;
+    supportsConnectionBindings;
+    constructor(executable, supportsConnectionBindings = true) {
+        this.executable = executable;
+        this.supportsConnectionBindings = supportsConnectionBindings;
+    }
+    target() {
+        return Promise.resolve({ kind: "local" });
+    }
+    source(root, _digest, _existing) {
+        return Promise.resolve(root);
+    }
+    binary(name) {
+        return Promise.reject(new Error(`Required binary ${name} needs operator-side verification on the team runtime.`));
+    }
+    async run(args) {
+        if (process.env.OPENCLAW_EXPERIMENTAL_CLAWS !== "1")
+            throw new OperatorError("Set OPENCLAW_EXPERIMENTAL_CLAWS=1 to acknowledge the experimental native Claws contract.");
+        const { stdout } = await execute(this.executable, [...args], {
+            maxBuffer: 4 * 1024 * 1024,
+            timeout: 120000,
+        });
+        const value = JSON.parse(stdout);
+        return value;
+    }
+    async version() {
+        const { stdout } = await execute(this.executable, ["--version"], {
+            maxBuffer: 8192,
+            timeout: 10000,
+        });
+        if (!/\b2026\.9\.4\b/.test(stdout))
+            throw new OperatorError("Packs require the pinned OpenClaw 2026.9.4 release.");
+    }
+    network(requirements) {
+        if (requirements.length)
+            throw new OperatorError("Network-dependent packs require a verified OpenShell target policy.");
+        return Promise.resolve(null);
+    }
+    async brokerUrl() {
+        const enabled = await this.run([
+            "config",
+            "get",
+            "plugins.entries.clawscarf-connections.enabled",
+            "--json",
+        ]);
+        if (enabled !== true)
+            throw new OperatorError("The target Connections plugin is not enabled.");
+        return z
+            .url()
+            .parse(await this.run([
+            "config",
+            "get",
+            "plugins.entries.clawscarf-connections.config.brokerUrl",
+            "--json",
+        ]))
+            .replace(/\/$/, "");
+    }
+    async defaultModel() {
+        const status = await this.run(["models", "status", "--json", "--check"]);
+        return z.object({ resolvedDefault: z.string().min(1) }).parse(status)
+            .resolvedDefault;
+    }
+}