@clawscarf/cli 0.1.0-alpha.1

package/generated/http/core/types.gen.d.ts

@@ -0,0 +1,83 @@
+import type { Auth, AuthToken } from './auth.gen.js';
+import type { BodySerializer, QuerySerializer, QuerySerializerOptions } from './bodySerializer.gen.js';
+export type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+export type Client<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
+    };
+});
+export interface Config {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g., converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
+}
+/**
+ * Arbitrary metadata passed through the `meta` request option.
+ */
+export interface ClientMeta {
+}
+type IsExactlyNeverOrNeverUndefined<T> = [T] extends [never] ? true : [T] extends [never | undefined] ? [undefined] extends [T] ? false : true : false;
+export type OmitNever<T extends Record<string, unknown>> = {
+    [K in keyof T as IsExactlyNeverOrNeverUndefined<T[K]> extends true ? never : K]: T[K];
+};
+export {};

package/generated/http/core/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/generated/http/core/utils.gen.d.ts

@@ -0,0 +1,19 @@
+import type { BodySerializer, QuerySerializer } from './bodySerializer.gen.js';
+export interface PathSerializer {
+    path: Record<string, unknown>;
+    url: string;
+}
+export declare const PATH_PARAM_RE: RegExp;
+export declare const defaultPathSerializer: ({ path, url: _url }: PathSerializer) => string;
+export declare const getUrl: ({ baseUrl, path, query, querySerializer, url: _url, }: {
+    baseUrl?: string;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    querySerializer: QuerySerializer;
+    url: string;
+}) => string;
+export declare function getValidRequestBody(options: {
+    body?: unknown;
+    bodySerializer?: BodySerializer | null;
+    serializedBody?: unknown;
+}): unknown;

package/generated/http/core/utils.gen.js

@@ -0,0 +1,87 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from './pathSerializer.gen.js';
+export const PATH_PARAM_RE = /\{[^{}]+\}/g;
+export const defaultPathSerializer = ({ path, url: _url }) => {
+    let url = _url;
+    const matches = _url.match(PATH_PARAM_RE);
+    if (matches) {
+        for (const match of matches) {
+            let explode = false;
+            let name = match.substring(1, match.length - 1);
+            let style = 'simple';
+            if (name.endsWith('*')) {
+                explode = true;
+                name = name.substring(0, name.length - 1);
+            }
+            if (name.startsWith('.')) {
+                name = name.substring(1);
+                style = 'label';
+            }
+            else if (name.startsWith(';')) {
+                name = name.substring(1);
+                style = 'matrix';
+            }
+            const value = path[name];
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                url = url.replace(match, serializeArrayParam({ explode, name, style, value }));
+                continue;
+            }
+            if (typeof value === 'object') {
+                url = url.replace(match, serializeObjectParam({
+                    explode,
+                    name,
+                    style,
+                    value: value,
+                    valueOnly: true,
+                }));
+                continue;
+            }
+            if (style === 'matrix') {
+                url = url.replace(match, `;${serializePrimitiveParam({
+                    name,
+                    value: value,
+                })}`);
+                continue;
+            }
+            const replaceValue = encodeURIComponent(style === 'label' ? `.${value}` : value);
+            url = url.replace(match, replaceValue);
+        }
+    }
+    return url;
+};
+export const getUrl = ({ baseUrl, path, query, querySerializer, url: _url, }) => {
+    const pathUrl = _url.startsWith('/') ? _url : `/${_url}`;
+    let url = (baseUrl ?? '') + pathUrl;
+    if (path) {
+        url = defaultPathSerializer({ path, url });
+    }
+    let search = query ? querySerializer(query) : '';
+    if (search.startsWith('?')) {
+        search = search.substring(1);
+    }
+    if (search) {
+        url += `?${search}`;
+    }
+    return url;
+};
+export function getValidRequestBody(options) {
+    const hasBody = options.body !== undefined;
+    const isSerializedBody = hasBody && options.bodySerializer;
+    if (isSerializedBody) {
+        if ('serializedBody' in options) {
+            const hasSerializedBody = options.serializedBody !== undefined && options.serializedBody !== '';
+            return hasSerializedBody ? options.serializedBody : null;
+        }
+        // not all clients implement a serializedBody property (i.e., client-axios)
+        return options.body !== '' ? options.body : null;
+    }
+    // plain/text body
+    if (hasBody) {
+        return options.body;
+    }
+    // no body was provided
+    return undefined;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "version": "0.1.0-alpha.1",
+  "engines": {
+    "node": ">=24.16.0 <25 || >=26.1.0"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "commander": "^15.0.0",
+    "ipaddr.js": "2.5.0",
+    "node-pg-migrate": "9.0.0",
+    "openid-client": "6.8.8",
+    "pg": "8.23.0",
+    "proper-lockfile": "4.1.2",
+    "undici": "8.10.2",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
+  },
+  "name": "@clawscarf/cli",
+  "private": false,
+  "bin": {
+    "clawscarf": "scripts/clawscarf.js"
+  },
+  "scripts": {
+    "clawscarf": "node scripts/clawscarf.js",
+    "controller": "node scripts/controller.js"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawscarf/clawscarf.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packs/README.md

@@ -0,0 +1,130 @@
+# Optional packs
+
+A ClawScarf pack groups native OpenClaw Claws. Each member is a normal
+[CLAW.md](research-team/researcher/CLAW.md) package with an optional [OpenClaw profile](research-team/researcher/profiles/openclaw.yml). OpenClaw owns its agents,
+workspace files, skills, plugins, MCP definitions, workflows and ownership records.
+ClawScarf's small group manifest adds compatibility and prerequisite bindings; it
+has no pack database or alternate installer for native resources.
+Recipes can select pack IDs and members from the [CLI package](../release/README.md).
+The CLI package carries the native files. Preparation records their content digests
+and collects required operator/account inputs. No separate pack registry is involved.
+
+The [research-team pack](research-team/pack.json) contains a researcher and reviewer
+with workspace-only file tools. It requires the configured default model; it does
+not install network tools, accounts or a provider. Its agents remain independent;
+a person supplies material and transfers a draft for review.
+
+## Select and change packs
+
+Use `clawscarf configure --directory /path/to/team` to select bundled packs and
+members. Noninteractive callers use `--pack <id:member,member>` and optional
+`--pack-bindings <id=file>`. `--no-packs` removes all selected members. Changes
+are reviewed before the server stops; native application finishes at startup.
+
+The installation operator calls OpenClaw's native Claws preview/apply operations.
+It preserves edited and unmanaged files, checks plan integrity and does not replay
+uncertain mutations. Removing an agent remains destructive. Native monitor cleanup
+uses OpenClaw's direct-local password authentication supplied by the
+[runtime launcher](../runtime/README.md); trusted-proxy login remains in place for
+people. Retained installations need the updated runtime image and a Gateway restart.
+
+The private runtime helper only inspects packaged source. Individual portable Claws
+can be built with native `openclaw claws build <member-directory> --out <artifact.tgz>`.
+
+## Requirements and bindings
+
+The manifest records model readiness, connection slots, binaries, execution location
+and network requirements. `configured-default` checks native model configuration
+and credential readiness, not a successful inference. It never sets a provider or
+copies keys. Required binaries, network policy, native Claws commands, model readiness and
+owned files are checked on the same protected team runtime.
+The operator uses the official OpenShell SDK through its [transport](../scripts/packs/transport.py),
+with the controller's existing TLS credentials. Supply its Python environment using
+`--pack-python`; dependencies are pinned in [requirements.txt](../scripts/packs/requirements.txt).
+Operations target the recorded runtime UUID, so replacing a sandbox under the same
+name cannot redirect a mutation. Browser/controller credentials remain outside it.
+
+A binding file contains:
+
+```json
+{
+  "origin": "https://team.example.com",
+  "brokerUrl": "https://team.example.com/_clawscarf/connections",
+  "sessionFile": "/private/current-session",
+  "connections": { "documents": "00000000-0000-4000-8000-000000000001" }
+}
+```
+
+Keep both files outside the pack. The generated REST client verifies the exact
+account ID/type, current account state and grant for the target agent using the
+administrator's current session. Missing selected-agent grants block preview;
+never widen access automatically. Initial installation can use an existing account
+already available to all agents. Once the pack exists, restrict that account to its
+agent and reconfigure the pack. An account restricted to a not-yet-created agent needs
+an explicit two-stage setup; this command does not invent pre-admission grants. The target plugin's configured broker must match the explicit `brokerUrl`. `origin`
+is the administrator-facing management origin; these may differ in a local
+composition (for example, localhost versus a private runtime hostname). This is
+operator-owned deployment mapping, not discovery or cryptographic server identity.
+All selected accounts must belong to the same server and their server IDs are
+recorded in the reviewed plan. Public URL
+matching does not prove runtime-credential validity: the broker still checks that
+credential and current grants on each tool call.
+
+A connection-dependent member declares `connectionFile`, for example accounts.json.
+Its native [CLAW.md](research-team/researcher/CLAW.md) must explicitly include that file in `workspace.files`; the
+pack's instructions must tell its agent to read it. ClawScarf renders only that
+JSON file with schema version 1 and a `connections` array of slot, connectionId,
+name and connectorId. It performs no prompt templating and copies no credential.
+Native Claws previews and owns the file, including update/removal and preservation
+of user edits. An account slot is therefore concrete agent-readable configuration,
+not merely a successful prerequisite check.
+
+Preview uploads a fresh private source directory; it does not overwrite earlier
+staging directories or agent workspaces. Apply rechecks local/target digests, native
+plan integrity, account revisions/grants and policy before mutation. A changed
+account or source needs a new preview. No mutation is replayed automatically after
+an uncertain result. Staged source directories remain available for native ownership
+records and reviewed plans; deleting them invalidates those plans.
+
+Network requirements are explicit objects with `binary` (canonical absolute target
+path), `host` (exact DNS name), `port` and `protocol: "tcp"`. The operator checks the
+runtime sandbox's effective policy against its acknowledged loaded revision, records exact
+hash/version/config revision and rechecks for changes. Only unconditional exact
+executable/TCP grants are supported. Global/provider-composed mismatches, wildcard,
+audit and conditional/L7 policies fail closed. Omitted native protocol means proxy
+passthrough, not transparent TCP, and does not satisfy a TCP requirement. This checks
+loaded policy coverage, not DNS/reachability, successful account operations or
+per-agent isolation when agents share an executable. It never changes policy.
+
+## Verification
+
+[Lifecycle checks](../tests/packs/lifecycle.test.ts) cover source changes, model
+readiness changes and source-link rejection. The [native test](../tests/packs/native.test.ts)
+uses vanilla OpenClaw with trusted-proxy auth and its local CLI password. It covers
+both an ordinary pack member and one with an owned automation, including removal
+after a Gateway restart, preservation of edited files and rejection of forwarded
+password authentication. The copied fixture omits the model prerequisite; no model
+inference is purchased. Set `CLAWSCARF_TEST_NATIVE_PACKS=1` to run it, optionally
+with `CLAWSCARF_TEST_OPENCLAW` pointing at the packaged runtime launcher. The same
+fixture has passed inside a disposable OpenShell runtime using the pinned upstream
+image plus the updated launcher.
+[Operator binding checks](../tests/packs/connections.test.ts) cover current session,
+exact grants and revision drift. [Transport checks](../tests/packs/transport.test.ts)
+cover UUID dispatch and uncertain failure without replay. The optional
+[OpenShell binding test](../tests/packs/openshell.test.ts) uses controlled account HTTP
+with real SDK/native package ownership on one runtime. It requires
+`CLAWSCARF_TEST_PACK_SANDBOX`, the controller/SDK settings and an already-running
+Gateway with native CLI authentication. Its token-authenticated fixture does not
+qualify trusted-proxy removal, external OAuth or connector execution.
+[Policy checks](../tests/packs/policy.test.ts) cover loaded acknowledgment and drift.
+[Execution-target checks](../tests/packs/execution-target.test.ts) use controlled operator
+processes to verify unified runtime dispatch, missing binaries, denied policy
+and runtime replacement. They do not replace live OpenShell qualification.
+A disposable runtime with the image's nftables 1.1.3/libnftnl 1.2.9 dependencies
+loaded an explicit TCP policy: verification accepted its exact process/host/port
+and rejected a different port. This qualifies policy observation and matching;
+it does not establish a successful connector request or application execution.
+
+Run `CLAWSCARF_TEST_NATIVE_PACKS=1 pnpm exec tsx --test tests/packs/native.test.ts`
+for the disposable native test. It writes isolated temporary state and uses the
+pinned OpenClaw dependency installed for the Connections plugin.

package/packs/research-team/pack.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "id": "research-team",
+  "version": "0.1.0",
+  "openclaw": "2026.9.4",
+  "description": "A researcher and a reviewer for evidence-based team briefs.",
+  "members": [
+    {
+      "id": "researcher",
+      "source": "researcher",
+      "requirements": { "model": "configured-default", "connections": [] }
+    },
+    {
+      "id": "reviewer",
+      "source": "reviewer",
+      "requirements": { "model": "configured-default", "connections": [] }
+    }
+  ],
+  "execution": { "location": "native-tools", "binaries": [], "network": [] }
+}

package/packs/research-team/researcher/CLAW.md

@@ -0,0 +1,19 @@
+---
+schemaVersion: 1
+agent:
+  id: researcher
+  name: Researcher
+workspace:
+  bootstrapFiles: {}
+packages: []
+mcpServers: {}
+cronJobs: []
+---
+
+# Researcher
+
+Prepare concise briefs from the material the team supplies. Separate evidence,
+inference and unanswered questions. Cite the supplied source for every material
+claim. Ask for missing source material instead of inventing it. Write drafts only
+inside your workspace. Hand the draft to a human for review; never publish or send
+messages on the team's behalf without explicit authorization.

package/packs/research-team/researcher/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@clawscarf/researcher-claw",
+  "version": "0.1.0",
+  "type": "module",
+  "openclaw": {
+    "claw": "CLAW.md"
+  }
+}

package/packs/research-team/researcher/profiles/openclaw.yml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+agent:
+  tools:
+    allow: [read, write, edit]
+    fs:
+      workspaceOnly: true

package/packs/research-team/reviewer/CLAW.md

@@ -0,0 +1,19 @@
+---
+schemaVersion: 1
+agent:
+  id: reviewer
+  name: Reviewer
+workspace:
+  bootstrapFiles: {}
+packages: []
+mcpServers: {}
+cronJobs: []
+---
+
+# Reviewer
+
+Review briefs supplied by the team. Identify unsupported claims, missing context,
+contradictions and decisions that need a human. Distinguish blocking findings from
+optional wording improvements. Preserve source quotations and provide concise,
+actionable review notes. Write only inside your workspace. Do not access another
+agent's files or publish material unless a human explicitly supplies and authorizes it.

package/packs/research-team/reviewer/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@clawscarf/reviewer-claw",
+  "version": "0.1.0",
+  "type": "module",
+  "openclaw": {
+    "claw": "CLAW.md"
+  }
+}

package/packs/research-team/reviewer/profiles/openclaw.yml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+agent:
+  tools:
+    allow: [read, write, edit]
+    fs:
+      workspaceOnly: true