@claude-flow/cli 3.33.0 → 3.35.0

package/.claude/.proven-config-version

@@ -0,0 +1 @@
+sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.32.29
+3.35.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.33.0",
+    "version": "3.35.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "dae295fb9ae2626b89899c19a20cc911541af82b52d2eeb9b214d618b96e9a86",
@@ -8,6 +8,6 @@
       "statusline.cjs": "0457fe53f8cd2c56458ff178392536a5868efd1a573665fa43bc01d2d95ca677"
     }
   },
-  "signature": "J0E/yeJoSS9oIfHsfle9CjlnSLNeSO6dcXPkuhzDx/2lddDeddDXMDXF3XO0GnQbpZWTduBKx5+cN0ip89fJDw==",
+  "signature": "tnK2I0enYGI5ql364QJqnAUHMo+pIh0AZK4y/Rad9H+WuPo/KzzG4jqL8/083EbEKWLPEneN6n9s0pEQcGzVCw==",
   "algorithm": "ed25519"
 }

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1785208363552,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 4,
-  "generatedAt": "2026-07-30T19:39:04.992Z",
-  "gitSha": "6e6c7347",
+  "generatedAt": "2026-08-10T14:19:13.896Z",
+  "gitSha": "4af1cfdd",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/agent.js

@@ -6,6 +6,7 @@ import { output } from '../output.js';
 import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { wasmSubcommands } from './agent-wasm.js';
+import { agentPublishCommand } from './agntcy/publish.js';
 import * as fs from 'fs';
 import * as path from 'path';
 /**
@@ -906,7 +907,7 @@ function formatLogLevel(level) {
 export const agentCommand = {
     name: 'agent',
     description: 'Agent management commands',
-    subcommands: [spawnCommand, listCommand, statusCommand, stopCommand, metricsCommand, poolCommand, healthCommand, logsCommand, ...wasmSubcommands],
+    subcommands: [spawnCommand, listCommand, statusCommand, stopCommand, metricsCommand, poolCommand, healthCommand, logsCommand, ...wasmSubcommands, agentPublishCommand],
     options: [],
     examples: [
         { command: 'claude-flow agent spawn -t coder', description: 'Spawn a coder agent' },

package/dist/src/commands/agntcy/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * V3 CLI AGNTCY/Outshift Runtime Integration — ADR-380 §2.
+ *
+ * Scaffolds the three new `ruflo` CLI verbs ADR-380 §2 specifies:
+ *
+ *   ruflo transport use slim
+ *   ruflo agent publish
+ *   ruflo swarm join <namespace>
+ *
+ * ============================================================================
+ * INTEGRATION STATUS: NOT WIRED IN. This module is intentionally
+ * self-contained and is NOT imported by, or registered with, the CLI's
+ * central command registry/index. A later, separate pass must:
+ *
+ *   1. Add `transportCommand` as a new top-level command (alongside
+ *      `agent`, `swarm`, etc. in whatever file enumerates top-level
+ *      commands today).
+ *   2. Merge `agentPublishCommand` into the existing `agentCommand`'s
+ *      `subcommands` array in `../agent.ts`.
+ *   3. Merge `swarmJoinCommand` into the existing `swarmCommand`'s
+ *      `subcommands` array in `../swarm.ts`.
+ *   4. Decide (per ADR-380's own "Open Questions") whether `transport use`
+ *      is a per-swarm or global-session setting before wiring state
+ *      persistence for the selected transport.
+ *
+ * No file outside `v3/@claude-flow/cli/src/commands/agntcy/` is touched by
+ * this scaffold.
+ * ============================================================================
+ *
+ * ARCHITECTURAL CONSTRAINT (mirrors ADR-150 §"architectural constraint",
+ * which ADR-380 §1 explicitly follows):
+ *   - No `@claude-flow/agntcy` (or any other AGNTCY/SLIM/Outshift) package
+ *     exists on npm or crates.io yet — verified 404 on every plausible
+ *     name. Nothing in this directory statically imports one.
+ *   - Every runtime touchpoint goes through `detectAgntcyRuntime()` in
+ *     `runtime.ts`, which only ever does a guarded dynamic `import()`
+ *     wrapped in try/catch, and only after an explicit
+ *     `RUFLO_AGNTCY_SLIM_ENDPOINT` env var opt-in.
+ *   - Every command in this directory exits 0 (not an error) when AGNTCY/
+ *     SLIM is not configured — this is optional, removable augmentation,
+ *     not a required dependency. The CLI, and these commands' own local
+ *     fallback behavior, work identically whether or not this directory
+ *     exists at all.
+ *
+ * Created with care by ruv.io
+ */
+import type { Command } from '../../types.js';
+export { transportCommand, useCommand } from './transport.js';
+export { agentPublishCommand } from './publish.js';
+export { swarmJoinCommand } from './swarm-join.js';
+export { detectAgntcyRuntime, AGNTCY_ENDPOINT_ENV, AGNTCY_PACKAGE_NAME, AGNTCY_ADR_PATH, AGNTCY_NOT_CONFIGURED_MESSAGE, } from './runtime.js';
+export type { AgntcyRuntimeStatus } from './runtime.js';
+export { validateOasfRecordShape, } from './publish.js';
+export type { OasfAgentRecordShape, OasfValidationResult } from './publish.js';
+export { validateNamespace } from './swarm-join.js';
+/**
+ * Convenience bundle for the later integration pass — NOT a registered
+ * command tree itself (there is no top-level `agntcy` verb per ADR-380;
+ * each of these attaches to an existing or new top-level command per the
+ * mapping documented above).
+ */
+export declare const agntcyCommands: readonly Command[];
+export default agntcyCommands;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/commands/agntcy/index.js

@@ -0,0 +1,64 @@
+/**
+ * V3 CLI AGNTCY/Outshift Runtime Integration — ADR-380 §2.
+ *
+ * Scaffolds the three new `ruflo` CLI verbs ADR-380 §2 specifies:
+ *
+ *   ruflo transport use slim
+ *   ruflo agent publish
+ *   ruflo swarm join <namespace>
+ *
+ * ============================================================================
+ * INTEGRATION STATUS: NOT WIRED IN. This module is intentionally
+ * self-contained and is NOT imported by, or registered with, the CLI's
+ * central command registry/index. A later, separate pass must:
+ *
+ *   1. Add `transportCommand` as a new top-level command (alongside
+ *      `agent`, `swarm`, etc. in whatever file enumerates top-level
+ *      commands today).
+ *   2. Merge `agentPublishCommand` into the existing `agentCommand`'s
+ *      `subcommands` array in `../agent.ts`.
+ *   3. Merge `swarmJoinCommand` into the existing `swarmCommand`'s
+ *      `subcommands` array in `../swarm.ts`.
+ *   4. Decide (per ADR-380's own "Open Questions") whether `transport use`
+ *      is a per-swarm or global-session setting before wiring state
+ *      persistence for the selected transport.
+ *
+ * No file outside `v3/@claude-flow/cli/src/commands/agntcy/` is touched by
+ * this scaffold.
+ * ============================================================================
+ *
+ * ARCHITECTURAL CONSTRAINT (mirrors ADR-150 §"architectural constraint",
+ * which ADR-380 §1 explicitly follows):
+ *   - No `@claude-flow/agntcy` (or any other AGNTCY/SLIM/Outshift) package
+ *     exists on npm or crates.io yet — verified 404 on every plausible
+ *     name. Nothing in this directory statically imports one.
+ *   - Every runtime touchpoint goes through `detectAgntcyRuntime()` in
+ *     `runtime.ts`, which only ever does a guarded dynamic `import()`
+ *     wrapped in try/catch, and only after an explicit
+ *     `RUFLO_AGNTCY_SLIM_ENDPOINT` env var opt-in.
+ *   - Every command in this directory exits 0 (not an error) when AGNTCY/
+ *     SLIM is not configured — this is optional, removable augmentation,
+ *     not a required dependency. The CLI, and these commands' own local
+ *     fallback behavior, work identically whether or not this directory
+ *     exists at all.
+ *
+ * Created with care by ruv.io
+ */
+export { transportCommand, useCommand } from './transport.js';
+export { agentPublishCommand } from './publish.js';
+export { swarmJoinCommand } from './swarm-join.js';
+export { detectAgntcyRuntime, AGNTCY_ENDPOINT_ENV, AGNTCY_PACKAGE_NAME, AGNTCY_ADR_PATH, AGNTCY_NOT_CONFIGURED_MESSAGE, } from './runtime.js';
+export { validateOasfRecordShape, } from './publish.js';
+export { validateNamespace } from './swarm-join.js';
+import { transportCommand } from './transport.js';
+import { agentPublishCommand } from './publish.js';
+import { swarmJoinCommand } from './swarm-join.js';
+/**
+ * Convenience bundle for the later integration pass — NOT a registered
+ * command tree itself (there is no top-level `agntcy` verb per ADR-380;
+ * each of these attaches to an existing or new top-level command per the
+ * mapping documented above).
+ */
+export const agntcyCommands = [transportCommand, agentPublishCommand, swarmJoinCommand];
+export default agntcyCommands;
+//# sourceMappingURL=index.js.map

package/dist/src/commands/agntcy/publish.d.ts

@@ -0,0 +1,43 @@
+/**
+ * V3 CLI `ruflo agent publish` — ADR-380 §2.
+ *
+ * Emits the AGNTCY-identified, OASF-described agent record (produced
+ * build-time by the companion metaharness ADR-240 §2.1/2.2) to the
+ * configured AGNTCY Directory (https://github.com/agntcy/dir).
+ *
+ * This scaffold does NOT implement the Directory publish protocol — no
+ * SLIM/Directory SDK is installable yet (verified 404 on every plausible
+ * npm/crates.io name). It implements the one thing that IS real without
+ * an external SDK: reading a local OASF-shaped manifest off disk (the
+ * artifact metaharness ADR-240 is responsible for producing) and
+ * validating its shape before attempting a publish, so the eventual
+ * network call has a real payload to send rather than being invented at
+ * publish time.
+ *
+ * NOT WIRED INTO THE MAIN CLI ROUTER YET. This file is exported for a
+ * later integration pass to attach as a new subcommand of the existing
+ * `agent` command (`v3/@claude-flow/cli/src/commands/agent.ts`).
+ */
+import type { Command } from '../../types.js';
+/** Minimal shape check for the OASF agent record metaharness ADR-240 §2.1/2.2 produces. */
+export interface OasfAgentRecordShape {
+    name: unknown;
+    version: unknown;
+    identity?: unknown;
+    capabilities?: unknown;
+    [key: string]: unknown;
+}
+export interface OasfValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate that a parsed JSON value looks like an OASF agent record —
+ * deterministic shape check, no network, no LLM. Kept exported so the
+ * test file can exercise it directly without spawning the whole command.
+ */
+export declare function validateOasfRecordShape(record: unknown): OasfValidationResult;
+declare const publishCommand: Command;
+export { publishCommand as agentPublishCommand };
+export default publishCommand;
+//# sourceMappingURL=publish.d.ts.map

package/dist/src/commands/agntcy/publish.js

@@ -0,0 +1,121 @@
+/**
+ * V3 CLI `ruflo agent publish` — ADR-380 §2.
+ *
+ * Emits the AGNTCY-identified, OASF-described agent record (produced
+ * build-time by the companion metaharness ADR-240 §2.1/2.2) to the
+ * configured AGNTCY Directory (https://github.com/agntcy/dir).
+ *
+ * This scaffold does NOT implement the Directory publish protocol — no
+ * SLIM/Directory SDK is installable yet (verified 404 on every plausible
+ * npm/crates.io name). It implements the one thing that IS real without
+ * an external SDK: reading a local OASF-shaped manifest off disk (the
+ * artifact metaharness ADR-240 is responsible for producing) and
+ * validating its shape before attempting a publish, so the eventual
+ * network call has a real payload to send rather than being invented at
+ * publish time.
+ *
+ * NOT WIRED INTO THE MAIN CLI ROUTER YET. This file is exported for a
+ * later integration pass to attach as a new subcommand of the existing
+ * `agent` command (`v3/@claude-flow/cli/src/commands/agent.ts`).
+ */
+import { output } from '../../output.js';
+import { readFile } from 'fs/promises';
+import { AGNTCY_NOT_CONFIGURED_MESSAGE, AGNTCY_PACKAGE_NAME, detectAgntcyRuntime, } from './runtime.js';
+/**
+ * Validate that a parsed JSON value looks like an OASF agent record —
+ * deterministic shape check, no network, no LLM. Kept exported so the
+ * test file can exercise it directly without spawning the whole command.
+ */
+export function validateOasfRecordShape(record) {
+    const errors = [];
+    if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+        return { valid: false, errors: ['record is not a JSON object'] };
+    }
+    const rec = record;
+    if (typeof rec.name !== 'string' || rec.name.trim().length === 0) {
+        errors.push('missing or empty required field "name"');
+    }
+    if (typeof rec.version !== 'string' || rec.version.trim().length === 0) {
+        errors.push('missing or empty required field "version"');
+    }
+    return { valid: errors.length === 0, errors };
+}
+const DEFAULT_MANIFEST_PATH = '.agntcy/agent.oasf.json';
+const publishCommand = {
+    name: 'publish',
+    description: 'Publish the AGNTCY-identified, OASF-described agent record to the configured Directory (ADR-380 §2)',
+    options: [
+        {
+            name: 'manifest',
+            short: 'm',
+            description: 'Path to the OASF agent record produced by metaharness (ADR-240)',
+            type: 'string',
+            default: DEFAULT_MANIFEST_PATH,
+        },
+    ],
+    examples: [
+        { command: 'ruflo agent publish', description: 'Publish the local OASF agent record to the AGNTCY Directory' },
+        { command: 'ruflo agent publish --manifest ./out/agent.oasf.json', description: 'Publish a specific manifest' },
+    ],
+    action: async (ctx) => {
+        const manifestPath = ctx.flags.manifest || DEFAULT_MANIFEST_PATH;
+        // Step 1 (real, no SDK needed): locate + shape-validate the manifest.
+        let raw;
+        try {
+            raw = await readFile(manifestPath, 'utf-8');
+        }
+        catch {
+            output.printError(`No OASF agent record found at "${manifestPath}". Run the metaharness ADR-240 build step first, ` +
+                'or pass --manifest <path>.');
+            return { success: false, exitCode: 1 };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            output.printError(`"${manifestPath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            return { success: false, exitCode: 1 };
+        }
+        const validation = validateOasfRecordShape(parsed);
+        if (!validation.valid) {
+            output.printError(`"${manifestPath}" is not a valid OASF agent record:`);
+            for (const err of validation.errors) {
+                output.writeln(`  - ${err}`);
+            }
+            return { success: false, exitCode: 1 };
+        }
+        // Step 2 (stub, requires the not-yet-published runtime): the actual
+        // Directory publish call.
+        const status = await detectAgntcyRuntime();
+        if (!status.configured) {
+            output.printInfo(AGNTCY_NOT_CONFIGURED_MESSAGE);
+            output.printInfo(`Validated OASF record at "${manifestPath}" locally (name=${parsed.name}, ` +
+                `version=${parsed.version}); publish to the Directory was skipped.`);
+            return {
+                success: true,
+                data: { published: false, manifestPath, configured: false, reason: status.reason },
+            };
+        }
+        try {
+            const mod = (await import(AGNTCY_PACKAGE_NAME));
+            if (typeof mod.publishAgentRecord !== 'function') {
+                throw new Error(`"${AGNTCY_PACKAGE_NAME}" is installed but does not export publishAgentRecord()`);
+            }
+            const result = await mod.publishAgentRecord({
+                endpoint: status.endpoint,
+                record: parsed,
+            });
+            output.printSuccess(`Published agent record${result?.uri ? ` to ${result.uri}` : ''}.`);
+            return { success: true, data: { published: true, manifestPath, uri: result?.uri } };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            output.printError(`Directory publish failed: ${message}`);
+            return { success: true, data: { published: false, manifestPath, error: message } };
+        }
+    },
+};
+export { publishCommand as agentPublishCommand };
+export default publishCommand;
+//# sourceMappingURL=publish.js.map

package/dist/src/commands/agntcy/runtime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * V3 CLI AGNTCY/SLIM Runtime Presence Check — ADR-380 §1.
+ *
+ * ADR-380 introduces three new `ruflo` CLI verbs (`transport use slim`,
+ * `agent publish`, `swarm join <namespace>`) that talk to Cisco Outshift's
+ * AGNTCY ecosystem (SLIM transport, Directory publish, group membership).
+ *
+ * CORRECTED (2026-07-31): the original scaffold guessed at a package name
+ * (`@claude-flow/agntcy`) and concluded no real SLIM SDK existed anywhere.
+ * That check only tried guessed names — the real package is
+ * `@agntcy/slim-bindings` (npm, real, published, documented for plain
+ * Node.js use).
+ *
+ * `@agntcy/slim-bindings@1.4.1` (npm `latest`) fails to load in plain Node —
+ * a transitive dependency (`uniffi-bindgen-react-native`) ships raw,
+ * uncompiled TypeScript as its package.json `main`, which only works inside
+ * a bundler (Metro, for its React Native use case). Filed upstream:
+ * agntcy/slim#1916 and jhugman/uniffi-bindgen-react-native#422 (root cause).
+ *
+ * UPDATE (2026-07-31, later): the SLIM maintainers confirmed they've moved
+ * off `uniffi-bindgen-react-native` onto `@ubjs/core`/`@ubjs/node` (compiled
+ * output, not raw TS) in the `alpha` dist-tag (`2.0.0-alpha.4+`), not yet
+ * promoted to `latest`. Verified live: a real server-bring-up + client-
+ * connect + graceful-shutdown smoke test against `@agntcy/slim-bindings@
+ * 2.0.0-alpha.5` succeeds under plain Node with zero errors. `package.json`
+ * now pins that exact alpha version (not a caret range — this is a
+ * pre-release channel, pin deliberately rather than floating) until the fix
+ * is promoted to `latest`, tracked by the same issue.
+ *
+ * This module's existing graceful-degradation design already handled this
+ * correctly without any change to its logic: `detectAgntcyRuntime()`'s
+ * catch-all branch (anything other than MODULE_NOT_FOUND) reports the real
+ * underlying error and falls back to local transport when the import fails.
+ * Now that the pinned version actually loads, the happy path
+ * (`configured: true`) is real and verified, not aspirational — no change
+ * to this function was needed either way.
+ *
+ * Per ADR-150's precedent (which ADR-380 §1 explicitly follows, not
+ * ADR-321's hard-dependency exception):
+ *   - removable:            deleting this whole directory changes nothing
+ *                            about the rest of the CLI working.
+ *   - optional-only:        `@agntcy/slim-bindings` MUST live in
+ *                            optionalDependencies, never `dependencies`.
+ *   - graceful degradation: every caller of `detectAgntcyRuntime()` falls
+ *                            back to the local transport / existing
+ *                            authorization model on `configured: false`.
+ *   - CI-gated:              a "works without AGNTCY installed" smoke test
+ *                            is exercised by __tests__/agntcy-commands.test.ts.
+ */
+/** Env var an operator sets to point ruflo at a SLIM endpoint. */
+export declare const AGNTCY_ENDPOINT_ENV = "RUFLO_AGNTCY_SLIM_ENDPOINT";
+/**
+ * The real SLIM Node.js bindings package (npm, published, real). Kept as a
+ * named constant (not a string literal scattered through the module) so a
+ * single edit repoints every dynamic-import call site if that ever changes.
+ * Currently fails to load due to an upstream packaging bug — see this
+ * file's header comment — which `detectAgntcyRuntime()`'s catch-all branch
+ * already handles gracefully.
+ */
+export declare const AGNTCY_PACKAGE_NAME = "@agntcy/slim-bindings";
+/** Pointer to the ADR every "not configured" message should send users to. */
+export declare const AGNTCY_ADR_PATH = "v3/docs/adr/ADR-380-agntcy-outshift-runtime-integration.md";
+export declare const AGNTCY_NOT_CONFIGURED_MESSAGE: string;
+export interface AgntcyRuntimeStatus {
+    /** True only when an endpoint is set AND the optional runtime package resolves. */
+    configured: boolean;
+    /** Human-readable reason for the current status — always safe to print. */
+    reason: string;
+    /** The configured endpoint, if any (present even when configured is false, e.g. package missing). */
+    endpoint?: string;
+}
+/**
+ * Detect whether the optional AGNTCY/SLIM runtime is available.
+ *
+ * This function never throws and never makes a network call. It performs,
+ * in order:
+ *   1. An env var presence check for {@link AGNTCY_ENDPOINT_ENV}. Absent →
+ *      not configured, no further work.
+ *   2. A dynamic `import()` of {@link AGNTCY_PACKAGE_NAME} (or `packageName`
+ *      if overridden), wrapped in try/catch. Verified live: the pinned
+ *      `2.0.0-alpha.5` resolves cleanly — `configured: true` is a real,
+ *      exercised path today, not just a theoretical one.
+ *
+ * @param env Injectable for tests; defaults to `process.env`.
+ * @param packageName Injectable for tests (to simulate "package not
+ *   installed" without needing to actually uninstall the real optional
+ *   dependency); defaults to {@link AGNTCY_PACKAGE_NAME}.
+ */
+export declare function detectAgntcyRuntime(env?: NodeJS.ProcessEnv, packageName?: string): Promise<AgntcyRuntimeStatus>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/src/commands/agntcy/runtime.js

@@ -0,0 +1,115 @@
+/**
+ * V3 CLI AGNTCY/SLIM Runtime Presence Check — ADR-380 §1.
+ *
+ * ADR-380 introduces three new `ruflo` CLI verbs (`transport use slim`,
+ * `agent publish`, `swarm join <namespace>`) that talk to Cisco Outshift's
+ * AGNTCY ecosystem (SLIM transport, Directory publish, group membership).
+ *
+ * CORRECTED (2026-07-31): the original scaffold guessed at a package name
+ * (`@claude-flow/agntcy`) and concluded no real SLIM SDK existed anywhere.
+ * That check only tried guessed names — the real package is
+ * `@agntcy/slim-bindings` (npm, real, published, documented for plain
+ * Node.js use).
+ *
+ * `@agntcy/slim-bindings@1.4.1` (npm `latest`) fails to load in plain Node —
+ * a transitive dependency (`uniffi-bindgen-react-native`) ships raw,
+ * uncompiled TypeScript as its package.json `main`, which only works inside
+ * a bundler (Metro, for its React Native use case). Filed upstream:
+ * agntcy/slim#1916 and jhugman/uniffi-bindgen-react-native#422 (root cause).
+ *
+ * UPDATE (2026-07-31, later): the SLIM maintainers confirmed they've moved
+ * off `uniffi-bindgen-react-native` onto `@ubjs/core`/`@ubjs/node` (compiled
+ * output, not raw TS) in the `alpha` dist-tag (`2.0.0-alpha.4+`), not yet
+ * promoted to `latest`. Verified live: a real server-bring-up + client-
+ * connect + graceful-shutdown smoke test against `@agntcy/slim-bindings@
+ * 2.0.0-alpha.5` succeeds under plain Node with zero errors. `package.json`
+ * now pins that exact alpha version (not a caret range — this is a
+ * pre-release channel, pin deliberately rather than floating) until the fix
+ * is promoted to `latest`, tracked by the same issue.
+ *
+ * This module's existing graceful-degradation design already handled this
+ * correctly without any change to its logic: `detectAgntcyRuntime()`'s
+ * catch-all branch (anything other than MODULE_NOT_FOUND) reports the real
+ * underlying error and falls back to local transport when the import fails.
+ * Now that the pinned version actually loads, the happy path
+ * (`configured: true`) is real and verified, not aspirational — no change
+ * to this function was needed either way.
+ *
+ * Per ADR-150's precedent (which ADR-380 §1 explicitly follows, not
+ * ADR-321's hard-dependency exception):
+ *   - removable:            deleting this whole directory changes nothing
+ *                            about the rest of the CLI working.
+ *   - optional-only:        `@agntcy/slim-bindings` MUST live in
+ *                            optionalDependencies, never `dependencies`.
+ *   - graceful degradation: every caller of `detectAgntcyRuntime()` falls
+ *                            back to the local transport / existing
+ *                            authorization model on `configured: false`.
+ *   - CI-gated:              a "works without AGNTCY installed" smoke test
+ *                            is exercised by __tests__/agntcy-commands.test.ts.
+ */
+/** Env var an operator sets to point ruflo at a SLIM endpoint. */
+export const AGNTCY_ENDPOINT_ENV = 'RUFLO_AGNTCY_SLIM_ENDPOINT';
+/**
+ * The real SLIM Node.js bindings package (npm, published, real). Kept as a
+ * named constant (not a string literal scattered through the module) so a
+ * single edit repoints every dynamic-import call site if that ever changes.
+ * Currently fails to load due to an upstream packaging bug — see this
+ * file's header comment — which `detectAgntcyRuntime()`'s catch-all branch
+ * already handles gracefully.
+ */
+export const AGNTCY_PACKAGE_NAME = '@agntcy/slim-bindings';
+/** Pointer to the ADR every "not configured" message should send users to. */
+export const AGNTCY_ADR_PATH = 'v3/docs/adr/ADR-380-agntcy-outshift-runtime-integration.md';
+export const AGNTCY_NOT_CONFIGURED_MESSAGE = `AGNTCY/SLIM transport is not configured — see ADR-380 (${AGNTCY_ADR_PATH}) for setup. ` +
+    'Falling back to local transport.';
+/**
+ * Detect whether the optional AGNTCY/SLIM runtime is available.
+ *
+ * This function never throws and never makes a network call. It performs,
+ * in order:
+ *   1. An env var presence check for {@link AGNTCY_ENDPOINT_ENV}. Absent →
+ *      not configured, no further work.
+ *   2. A dynamic `import()` of {@link AGNTCY_PACKAGE_NAME} (or `packageName`
+ *      if overridden), wrapped in try/catch. Verified live: the pinned
+ *      `2.0.0-alpha.5` resolves cleanly — `configured: true` is a real,
+ *      exercised path today, not just a theoretical one.
+ *
+ * @param env Injectable for tests; defaults to `process.env`.
+ * @param packageName Injectable for tests (to simulate "package not
+ *   installed" without needing to actually uninstall the real optional
+ *   dependency); defaults to {@link AGNTCY_PACKAGE_NAME}.
+ */
+export async function detectAgntcyRuntime(env = process.env, packageName = AGNTCY_PACKAGE_NAME) {
+    const endpoint = env[AGNTCY_ENDPOINT_ENV];
+    if (!endpoint) {
+        return { configured: false, reason: `${AGNTCY_ENDPOINT_ENV} is not set` };
+    }
+    try {
+        // Dynamic import of an optional dependency, exactly the pattern this
+        // repo already uses for other optional runtimes (see status.ts's
+        // `await import('pg')`). Never a static `import` — a static import
+        // would make @claude-flow/cli fail to build/run when the package is
+        // absent, which is the one thing ADR-150/ADR-380 forbid.
+        await import(packageName);
+        return { configured: true, reason: `${packageName} resolved`, endpoint };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+            return {
+                configured: false,
+                reason: `${AGNTCY_ENDPOINT_ENV} is set but the optional "${packageName}" runtime package is not installed`,
+                endpoint,
+            };
+        }
+        // Any other error importing the module (syntax error in a real
+        // install, permission issue, etc.) — still degrade gracefully rather
+        // than propagate, but keep the real reason for diagnostics.
+        return {
+            configured: false,
+            reason: `error probing "${packageName}": ${error instanceof Error ? error.message : String(error)}`,
+            endpoint,
+        };
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/commands/agntcy/swarm-join.d.ts

@@ -0,0 +1,28 @@
+/**
+ * V3 CLI `ruflo swarm join <namespace>` — ADR-380 §2.
+ *
+ * Joins a SLIM group-membership channel scoped to a Cognitum tenant/project
+ * namespace (e.g. `cognitum/research/security`). This is an AGNTCY/SLIM
+ * concept layered on top of — never a replacement for — this repo's own
+ * `swarm_init`/`hive-mind_*` MCP-tool coordination, which remains the
+ * default for single-host swarms per ADR-380 §2.
+ *
+ * NOT WIRED INTO THE MAIN CLI ROUTER YET. This file is exported for a
+ * later integration pass to attach as a new subcommand of the existing
+ * `swarm` command (`v3/@claude-flow/cli/src/commands/swarm.ts`).
+ */
+import type { Command } from '../../types.js';
+/**
+ * SLIM group-membership namespaces are slash-delimited (e.g.
+ * `cognitum/research/security`), matching the ADR-380 §2 example. Validate
+ * the shape locally — deterministic, no SDK required — before ever
+ * attempting a network join.
+ */
+export declare function validateNamespace(namespace: string): {
+    valid: boolean;
+    error?: string;
+};
+declare const joinCommand: Command;
+export { joinCommand as swarmJoinCommand };
+export default joinCommand;
+//# sourceMappingURL=swarm-join.d.ts.map