@easynet-run/node 0.27.14

package/src/errors.js

@@ -0,0 +1,146 @@
+// sdk/node/src/errors.ts — Canonical error taxonomy for the Axon SDK.
+//
+// Terminology:
+//   Ability  — network-addressable governed execution contract
+//   Skill    — packaged implementation artifact (SKILL.md + invoke.sh)
+//   Tool     — export projection for LLM ecosystems (OpenAI / Anthropic)
+//
+// Each error class exposes a `code` property for cross-SDK mapping.
+// See the Rust reference: sdk/rust/src/error.rs
+//
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+/** Base error for all Axon SDK errors. */
+export class AxonError extends Error {
+    /** Canonical error code for cross-SDK mapping. */
+    code = "UNKNOWN";
+    constructor(message) {
+        super(message);
+        this.name = "AxonError";
+    }
+}
+// -- Input / config errors ---------------------------------------------------
+/** Input validation or configuration error (before any network call). */
+export class AxonConfigError extends AxonError {
+    code = "VALIDATION";
+    constructor(message) {
+        super(message);
+        this.name = "AxonConfigError";
+    }
+}
+// -- Bridge errors -----------------------------------------------------------
+/** Native bridge initialization or connection to the Axon runtime failed. */
+export class AxonBridgeError extends AxonError {
+    code = "BRIDGE";
+    constructor(message) {
+        super(message);
+        this.name = "AxonBridgeError";
+    }
+}
+// -- Lifecycle state errors --------------------------------------------------
+/** The requested ability is not installed on the target node. */
+export class AxonNotInstalledError extends AxonError {
+    code = "NOT_INSTALLED";
+    constructor(message) {
+        super(message);
+        this.name = "AxonNotInstalledError";
+    }
+}
+/** The ability is installed but not yet activated. */
+export class AxonNotActivatedError extends AxonError {
+    code = "NOT_ACTIVATED";
+    constructor(message) {
+        super(message);
+        this.name = "AxonNotActivatedError";
+    }
+}
+// -- Execution errors --------------------------------------------------------
+/**
+ * Remote invocation or deploy operation failed.
+ *
+ * When thrown from a deploy pipeline the optional `trace` field carries the
+ * {@link DeployTrace} collected before the failure, so callers can inspect
+ * per-phase timing even on error:
+ *
+ * ```ts
+ * try { await deployToNode(bridge, tenant, nodeId, desc, sig); }
+ * catch (e) { if (e instanceof AxonInvocationError && e.trace) console.log(e.trace); }
+ * ```
+ */
+export class AxonInvocationError extends AxonError {
+    code = "INVOCATION";
+    remotePayload;
+    /** Deploy trace collected before the failure (if available). */
+    trace;
+    constructor(message, remotePayload, trace) {
+        super(message);
+        this.name = "AxonInvocationError";
+        this.remotePayload = remotePayload;
+        this.trace = trace;
+    }
+}
+/** Streaming transport was interrupted before completion. */
+export class AxonStreamError extends AxonError {
+    code = "STREAM";
+    constructor(message) {
+        super(message);
+        this.name = "AxonStreamError";
+    }
+}
+/** A governance policy rejected the operation. */
+export class AxonPolicyDeniedError extends AxonError {
+    code = "POLICY_DENIED";
+    constructor(message) {
+        super(message);
+        this.name = "AxonPolicyDeniedError";
+    }
+}
+// -- MCP transport errors -----------------------------------------------------
+/** MCP transport or protocol error. */
+export class AxonMcpError extends AxonError {
+    code = "MCP";
+    constructor(message) {
+        super(message);
+        this.name = "AxonMcpError";
+    }
+}
+// -- Batch / partial errors --------------------------------------------------
+/** Operation completed with partial failures (e.g. `forgetAll`). */
+export class AxonPartialSuccessError extends AxonError {
+    code = "PARTIAL_SUCCESS";
+    succeeded;
+    failed;
+    details;
+    constructor(message, succeeded, failed, details) {
+        super(message);
+        this.name = "AxonPartialSuccessError";
+        this.succeeded = succeeded;
+        this.failed = failed;
+        this.details = details;
+    }
+}
+// -- Serialization / IO errors -----------------------------------------------
+/** JSON serialization or deserialization error. */
+export class AxonJsonError extends AxonError {
+    code = "JSON";
+    constructor(message) {
+        super(message);
+        this.name = "AxonJsonError";
+    }
+}
+/** Filesystem or general I/O error. */
+export class AxonIoError extends AxonError {
+    code = "IO";
+    constructor(message) {
+        super(message);
+        this.name = "AxonIoError";
+    }
+}
+// -- FFI symbol errors --------------------------------------------------------
+/** A required FFI symbol was not found in the native library. */
+export class AxonSymbolNotFoundError extends AxonError {
+    code = "SYMBOL_NOT_FOUND";
+    constructor(message) {
+        super(message);
+        this.name = "AxonSymbolNotFoundError";
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,55 @@
+export { validateUninstallCapabilityRequest, buildUninstallCapabilityPayload, } from "./capability_request.js";
+export type { McpToolProvider, McpToolResult, } from "./mcp/server.js";
+export { StdioMcpServer } from "./mcp/server.js";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+export interface ClientCallOptions {
+    principalId?: string;
+}
+export interface Transport {
+    call(tenantId: string, resourceUri: string, payload: JsonValue, options?: ClientCallOptions): Promise<JsonValue>;
+    callRaw?(tenantId: string, resourceUri: string, payload: JsonValue, options?: ClientCallOptions): Promise<Record<string, unknown>>;
+}
+export declare class SidecarTransport implements Transport {
+    endpoint: string;
+    private readonly timeoutMs;
+    private bridge;
+    private readonly connectTimeoutMs;
+    private readonly libraryPath?;
+    constructor(endpoint?: string, connectTimeoutMs?: number, timeoutMs?: number, libraryPath?: string);
+    private ensureBridge;
+    /**
+     * Invoke an ability via the sidecar FFI bridge.
+     *
+     * WARNING: The underlying FFI call is synchronous and blocks the event loop.
+     * Returns a resolved Promise for Transport interface compatibility.
+     */
+    call(tenantId: string, resourceUri: string, payload: JsonValue, options?: ClientCallOptions): Promise<JsonValue>;
+    /**
+     * Invoke an ability and return the raw envelope via FFI.
+     *
+     * WARNING: The underlying FFI call is synchronous and blocks the event loop.
+     * Returns a resolved Promise for Transport interface compatibility.
+     */
+    callRaw(tenantId: string, resourceUri: string, payload: JsonValue, options?: ClientCallOptions): Promise<Record<string, unknown>>;
+    close(): void;
+}
+export declare class Client {
+    private readonly transport;
+    private readonly tenantId;
+    private readonly resourceUri;
+    private readonly principalId;
+    constructor(transport?: Transport, tenantId?: string, resourceUri?: string, principalId?: string);
+    tenant(tenantId: string): Client;
+    ability(resourceUri: string): Client;
+    principal(principalId: string): Client;
+    call(payload: JsonValue): Promise<JsonValue>;
+    callRaw(payload: JsonValue): Promise<Record<string, unknown>>;
+}
+export declare function client(transport?: Transport): Client;
+export { createAbility, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, type AbilityDescriptor, type AbilityTarget, type AbilityExportResult, type ServerHandle, type BridgeInterface, type ForgetAllResult, type ForgetAllFailure, type DeployResult, } from "./ability_lifecycle.js";
+export { AxonError, AxonConfigError, AxonBridgeError, AxonNotInstalledError, AxonNotActivatedError, AxonInvocationError, AxonStreamError, AxonPolicyDeniedError, AxonMcpError, AxonPartialSuccessError, AxonJsonError, AxonIoError, AxonSymbolNotFoundError, } from "./errors.js";
+export { beginPhase, skippedReceipt, buildDeployTrace, phaseFromTrace, PhaseReceiptBuilder, type Phase, type PhaseStatus, type PhaseReceipt, type DeployTrace, } from "./receipt.js";
+export { AbilityToolAdapter, type ToolSpec as AdapterToolSpec, type OpenAITool, type OpenAIChatTool, type AnthropicTool, type ToolParameters, type LocalHandler, type RegisterOptions, type AbilityToolAdapterOptions, } from "./tool_adapter.js";
+export { DendriteBridge, DendriteServerStream, DendriteBidiStream, type DendriteBridgeOptions, DendriteError, type DendriteUnaryCallOptions, type DendriteAbilityCallOptions, type DendriteStreamCallOptions, type DendriteClientStreamCallOptions, type DendriteBidiStreamCallOptions, type DendriteListNodesOptions, type DendriteRegisterNodeOptions, type DendritePublishCapabilityOptions, type DendriteInstallCapabilityOptions, type DendriteListA2aAgentsOptions, type DendriteSendA2aTaskOptions, type DendriteDeployMcpListDirOptions, type DendriteListMcpToolsOptions, type DendriteCallMcpToolOptions, type DendriteUninstallCapabilityOptions, type DendriteUpdateMcpListDirOptions, type DendriteVoiceCodecProfileOptions, type DendriteVoiceMetricsOptions, type DendriteVoiceDescriptionOptions, type DendriteVoiceCandidateOptions, type DendriteVoiceCreateCallOptions, type DendriteVoiceJoinCallOptions, type DendriteVoiceUpdateMediaPathOptions, type DendriteVoiceEndCallOptions, type DendriteVoiceWatchOptions, type DendriteVoiceCreateTransportSessionOptions, type DendriteVoiceEndTransportSessionOptions, type DendriteProtocolInvokeOptions, } from "./dendrite_bridge.js";

package/src/index.js

@@ -0,0 +1,164 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/index.ts
+// Description: Source file for Node SDK facade and Dendrite integration; keeps behavior explicit and interoperable across language/runtime boundaries with tenant/principal fluent context.
+//
+// Protocol Responsibility:
+// - Implements Node SDK facade and Dendrite integration contracts required by current Axon service and SDK surfaces.
+// - Preserves stable request/response semantics and error mapping for index.ts call paths.
+//
+// Implementation Approach:
+// - Uses small typed helpers and explicit control flow to avoid hidden side effects.
+// - Keeps protocol translation and transport details close to this module boundary.
+//
+// Usage Contract:
+// - Callers should provide valid tenant/resource/runtime context before invoking exported APIs; principal context is optional and, when provided, is mapped to EasyNet subject context.
+// - Errors should be treated as typed protocol/runtime outcomes rather than silently ignored.
+//
+// Architectural Position:
+// - Part of the Node SDK facade and Dendrite integration layer.
+// - Should not embed unrelated orchestration logic outside this file's responsibility.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { DendriteBridge } from "./dendrite_bridge.js";
+import { AxonConfigError, AxonInvocationError } from "./errors.js";
+export { validateUninstallCapabilityRequest, buildUninstallCapabilityPayload, } from "./capability_request.js";
+export { StdioMcpServer } from "./mcp/server.js";
+function visibilityFromResourceUri(resourceUri) {
+    const normalized = resourceUri.trim().toLowerCase();
+    if (normalized.startsWith("easynet:///r/pub/")) {
+        return "pub";
+    }
+    if (normalized.startsWith("easynet:///r/prv/")) {
+        return "prv";
+    }
+    return "org";
+}
+function principalToSubjectId(principalId, resourceUri) {
+    const normalized = principalId.trim();
+    if (!normalized) {
+        throw new AxonConfigError("principal(...) cannot be blank");
+    }
+    if (normalized.startsWith("easynet:")) {
+        return normalized;
+    }
+    const visibility = visibilityFromResourceUri(resourceUri);
+    return `easynet:${visibility}:reg:agent.${normalized}`;
+}
+function extractResultJson(raw) {
+    if (!raw || typeof raw !== "object" || !Object.prototype.hasOwnProperty.call(raw, "result_json")) {
+        throw new AxonInvocationError("invoke response missing result_json");
+    }
+    return raw.result_json;
+}
+export class SidecarTransport {
+    endpoint;
+    timeoutMs;
+    bridge = null;
+    connectTimeoutMs;
+    libraryPath;
+    constructor(endpoint = process.env.EASYNET_AXON_ENDPOINT ?? "http://127.0.0.1:50051", connectTimeoutMs = 5000, timeoutMs = 30000, libraryPath) {
+        this.endpoint = endpoint;
+        this.timeoutMs = timeoutMs;
+        this.connectTimeoutMs = connectTimeoutMs;
+        this.libraryPath = libraryPath;
+    }
+    ensureBridge() {
+        if (!this.bridge) {
+            this.bridge = new DendriteBridge({
+                endpoint: this.endpoint,
+                connectTimeoutMs: this.connectTimeoutMs,
+                libraryPath: this.libraryPath,
+            });
+        }
+        return this.bridge;
+    }
+    /**
+     * Invoke an ability via the sidecar FFI bridge.
+     *
+     * WARNING: The underlying FFI call is synchronous and blocks the event loop.
+     * Returns a resolved Promise for Transport interface compatibility.
+     */
+    call(tenantId, resourceUri, payload, options = {}) {
+        const subjectId = options.principalId
+            ? principalToSubjectId(options.principalId, resourceUri)
+            : undefined;
+        const raw = this.ensureBridge().abilityCallRaw(tenantId, resourceUri, payload, {
+            timeoutMs: this.timeoutMs,
+            subjectId,
+        });
+        return Promise.resolve(extractResultJson(raw));
+    }
+    /**
+     * Invoke an ability and return the raw envelope via FFI.
+     *
+     * WARNING: The underlying FFI call is synchronous and blocks the event loop.
+     * Returns a resolved Promise for Transport interface compatibility.
+     */
+    callRaw(tenantId, resourceUri, payload, options = {}) {
+        const subjectId = options.principalId
+            ? principalToSubjectId(options.principalId, resourceUri)
+            : undefined;
+        return Promise.resolve(this.ensureBridge().abilityCallRaw(tenantId, resourceUri, payload, {
+            timeoutMs: this.timeoutMs,
+            subjectId,
+        }));
+    }
+    close() {
+        this.bridge?.close();
+        this.bridge = null;
+    }
+}
+export class Client {
+    transport;
+    tenantId;
+    resourceUri;
+    principalId;
+    constructor(transport = new SidecarTransport(), tenantId = "", resourceUri = "", principalId = "") {
+        this.transport = transport;
+        this.tenantId = tenantId;
+        this.resourceUri = resourceUri;
+        this.principalId = principalId;
+    }
+    tenant(tenantId) {
+        return new Client(this.transport, tenantId, this.resourceUri, this.principalId);
+    }
+    ability(resourceUri) {
+        return new Client(this.transport, this.tenantId, resourceUri, this.principalId);
+    }
+    principal(principalId) {
+        return new Client(this.transport, this.tenantId, this.resourceUri, principalId);
+    }
+    async call(payload) {
+        if (!this.tenantId)
+            throw new AxonConfigError("tenant(...) is required before call(...)");
+        if (!this.resourceUri)
+            throw new AxonConfigError("ability(...) is required before call(...)");
+        return this.transport.call(this.tenantId, this.resourceUri, payload, {
+            principalId: this.principalId || undefined,
+        });
+    }
+    async callRaw(payload) {
+        if (!this.tenantId)
+            throw new AxonConfigError("tenant(...) is required before callRaw(...)");
+        if (!this.resourceUri)
+            throw new AxonConfigError("ability(...) is required before callRaw(...)");
+        if (!this.transport.callRaw) {
+            throw new AxonConfigError("configured transport does not support callRaw(...)");
+        }
+        return this.transport.callRaw(this.tenantId, this.resourceUri, payload, {
+            principalId: this.principalId || undefined,
+        });
+    }
+}
+export function client(transport) {
+    return new Client(transport);
+}
+export { createAbility, exportAbility, deployToNode, listAbilities, invokeAbility, uninstallAbility, discoverNodes, executeCommand, forgetAll, disconnectDevice, drainDevice, listRemoteTools, buildDeployPackage, deployPackage, startServer, toToolSpec, } from "./ability_lifecycle.js";
+export { AxonError, AxonConfigError, AxonBridgeError, AxonNotInstalledError, AxonNotActivatedError, AxonInvocationError, AxonStreamError, AxonPolicyDeniedError, AxonMcpError, AxonPartialSuccessError, AxonJsonError, AxonIoError, AxonSymbolNotFoundError, } from "./errors.js";
+export { beginPhase, skippedReceipt, buildDeployTrace, phaseFromTrace, PhaseReceiptBuilder, } from "./receipt.js";
+export { AbilityToolAdapter, } from "./tool_adapter.js";
+export { DendriteBridge, DendriteServerStream, DendriteBidiStream, DendriteError, } from "./dendrite_bridge.js";

package/src/koffi.d.ts

@@ -0,0 +1,34 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/koffi.d.ts
+// Description: Ambient type declaration for the koffi native FFI module; provides minimal type surface consumed by the DendriteBridge FFI layer to load and call native library symbols.
+//
+// Protocol Responsibility:
+// - Declares TypeScript types for the koffi module's load, func, and disposable APIs used across the dendrite_bridge FFI binding.
+// - Enables type-safe FFI symbol resolution without bundling koffi's full type definitions.
+//
+// Implementation Approach:
+// - Uses a `declare module` ambient declaration so TypeScript resolves koffi imports without requiring @types/koffi.
+// - Keeps the surface minimal — only APIs actually consumed by this SDK are declared.
+//
+// Usage Contract:
+// - This file is consumed by the TypeScript compiler only; it has no runtime effect.
+// - If koffi publishes official type definitions in the future, this file can be removed.
+//
+// Architectural Position:
+// - Part of the Node SDK type layer; supports the dendrite_bridge FFI binding.
+// - Should not declare types unrelated to koffi FFI interop.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+
+declare module "koffi" {
+  export interface KoffiLibrary {
+    func(...args: unknown[]): unknown;
+  }
+
+  export function load(path: string): KoffiLibrary;
+  export function disposable(typeName: string, disposer: (ptr: unknown) => void): unknown;
+}

package/src/mcp/server.d.ts

@@ -0,0 +1,29 @@
+export interface McpToolResult {
+    payload: Record<string, unknown>;
+    isError: boolean;
+}
+export interface McpToolProvider {
+    toolSpecs(): Array<Record<string, unknown>>;
+    handleToolCall(name: string, args: Record<string, unknown>): McpToolResult | Promise<McpToolResult>;
+}
+interface McpTransportOptions {
+    protocolVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+}
+interface JsonMessage {
+    [key: string]: unknown;
+}
+export declare class StdioMcpServer {
+    private readonly provider;
+    private readonly protocolVersion;
+    private readonly serverName;
+    private readonly serverVersion;
+    private _closed;
+    constructor(provider: McpToolProvider, options?: McpTransportOptions);
+    close(): void;
+    run(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): void;
+    handleRawLine(raw: string): JsonMessage | Promise<JsonMessage> | null;
+    handleRequest(request: JsonMessage): JsonMessage | Promise<JsonMessage> | null;
+}
+export {};

package/src/mcp/server.js

@@ -0,0 +1,190 @@
+const DEFAULT_PROTOCOL_VERSION = "2026-02-26";
+const DEFAULT_SERVER_NAME = "easynet-axon-remote-node";
+const DEFAULT_SERVER_VERSION = "0.2.0";
+const MAX_LINE_LENGTH = 4 * 1024 * 1024; // 4 MiB per JSON-RPC message
+export class StdioMcpServer {
+    provider;
+    protocolVersion;
+    serverName;
+    serverVersion;
+    _closed = false;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.protocolVersion = options.protocolVersion?.trim() || DEFAULT_PROTOCOL_VERSION;
+        this.serverName = options.serverName?.trim() || DEFAULT_SERVER_NAME;
+        this.serverVersion = options.serverVersion?.trim() || DEFAULT_SERVER_VERSION;
+    }
+    close() {
+        this._closed = true;
+    }
+    run(input, output) {
+        let cache = "";
+        input.setEncoding("utf8");
+        input.on("error", (error) => {
+            if (this._closed)
+                return;
+            const payload = jsonrpcError(null, -32000, `stream error: ${String(error)}`);
+            write(output, payload);
+        });
+        input.on("close", () => {
+            // no-op: caller controls lifecycle
+        });
+        input.on("data", (chunk) => {
+            if (this._closed)
+                return;
+            cache += chunk.toString();
+            if (cache.length > MAX_LINE_LENGTH && !cache.includes("\n")) {
+                write(output, jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
+                cache = "";
+                return;
+            }
+            const lines = cache.split("\n");
+            cache = lines.pop() ?? "";
+            for (const raw of lines) {
+                if (!raw.trim()) {
+                    continue;
+                }
+                if (this._closed)
+                    break;
+                if (raw.length > MAX_LINE_LENGTH) {
+                    write(output, jsonrpcError(null, -32000, `input line exceeds maximum length (${MAX_LINE_LENGTH} bytes)`));
+                    continue;
+                }
+                const requestId = parseJson(raw)?.id ?? null;
+                const response = this.handleRawLine(raw);
+                if (response !== null) {
+                    if (typeof response.then === "function") {
+                        response.then((resolved) => { if (resolved !== null)
+                            write(output, resolved); }, (error) => { write(output, jsonrpcError(requestId, -32000, String(error))); });
+                    }
+                    else {
+                        write(output, response);
+                    }
+                }
+            }
+        });
+    }
+    handleRawLine(raw) {
+        const request = parseJson(raw);
+        if (request === null) {
+            return jsonrpcError(null, -32700, "parse error");
+        }
+        return this.handleRequest(request);
+    }
+    handleRequest(request) {
+        const id = request.id;
+        const method = typeof request.method === "string" ? request.method : "";
+        const params = asMap(request.params);
+        // JSON-RPC 2.0 requires "jsonrpc": "2.0" on every request.
+        if (request.jsonrpc !== "2.0" && id !== undefined) {
+            return jsonrpcError(id, -32600, "invalid request: missing jsonrpc version");
+        }
+        if (method === "notifications/initialized") {
+            return null;
+        }
+        if (method === "initialize") {
+            if (id === undefined) {
+                return null;
+            }
+            return jsonrpcSuccess(id, {
+                protocolVersion: this.protocolVersion,
+                capabilities: { tools: {} },
+                serverInfo: {
+                    name: this.serverName,
+                    version: this.serverVersion,
+                },
+            });
+        }
+        if (method === "tools/list") {
+            if (id === undefined) {
+                return null;
+            }
+            return jsonrpcSuccess(id, { tools: this.provider.toolSpecs() });
+        }
+        if (method === "tools/call") {
+            if (id === undefined) {
+                return null;
+            }
+            const name = asString(params.name);
+            if (!name) {
+                return jsonrpcError(id, -32602, "tool name is required");
+            }
+            let args = params.arguments;
+            if (typeof args !== "object" || args === null || Array.isArray(args)) {
+                args = {};
+            }
+            const typedArgs = args;
+            let maybeResult;
+            try {
+                maybeResult = this.provider.handleToolCall(name, typedArgs);
+            }
+            catch (error) {
+                return jsonrpcSuccess(id, toolResponse({
+                    payload: { ok: false, error: String(error) },
+                    isError: true,
+                }));
+            }
+            if (maybeResult && typeof maybeResult.then === "function") {
+                return maybeResult.then((result) => jsonrpcSuccess(id, toolResponse(result)), (error) => jsonrpcSuccess(id, toolResponse({
+                    payload: { ok: false, error: String(error) },
+                    isError: true,
+                })));
+            }
+            return jsonrpcSuccess(id, toolResponse(maybeResult));
+        }
+        if (method === "ping" && id !== undefined) {
+            return jsonrpcSuccess(id, {});
+        }
+        if (id === undefined) {
+            return null;
+        }
+        return jsonrpcError(id, -32601, `method not found: ${method}`);
+    }
+}
+function parseJson(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (value === null || typeof value !== "object") {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function asMap(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function asString(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    return value.trim();
+}
+function write(stream, payload) {
+    stream.write(`${JSON.stringify(payload)}\n`);
+}
+function toolResponse(result) {
+    const payload = {
+        content: [{ type: "text", text: JSON.stringify(result.payload, null, 2) }],
+    };
+    return result.isError ? { ...payload, isError: true } : payload;
+}
+function jsonrpcSuccess(id, result) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+}
+function jsonrpcError(id, code, message) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code, message },
+    };
+}

package/src/presets/ability_dispatch/args.d.ts

@@ -0,0 +1,5 @@
+type ArgMap = Record<string, string | boolean>;
+export declare const BOOL_FLAGS: Set<string>;
+export declare function parseArgs(argv: string[]): ArgMap;
+export declare function parsePositiveInt(raw: string | undefined, fallback: number, field: string): number;
+export {};

package/src/presets/ability_dispatch/args.js

@@ -0,0 +1,36 @@
+// EasyNet Axon for AgentNet -- argument parsing helpers for ability-dispatch workflow.
+export const BOOL_FLAGS = new Set([
+    "auto-request-permission",
+    "no-write-media-files",
+    "keep-installed",
+    "require-real",
+    "allow-mock-fallback",
+]);
+export function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token.startsWith("--")) {
+            continue;
+        }
+        const key = token.slice(2);
+        if (BOOL_FLAGS.has(key)) {
+            out[key] = true;
+            continue;
+        }
+        const value = argv[i + 1];
+        if (!value || value.startsWith("--")) {
+            throw new Error(`missing value for --${key}`);
+        }
+        out[key] = value;
+        i += 1;
+    }
+    return out;
+}
+export function parsePositiveInt(raw, fallback, field) {
+    const parsed = Number.parseInt(raw ?? `${fallback}`, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`--${field} must be > 0`);
+    }
+    return parsed;
+}

package/src/presets/ability_dispatch/bundle.d.ts

@@ -0,0 +1,7 @@
+export declare function sha256Prefixed(payload: Uint8Array): string;
+export declare function parseTarSize(raw: Buffer): number;
+export declare function isZeroBlock(block: Buffer): boolean;
+export declare function readBundleVersion(bundleBytes: Buffer): string;
+export declare function resolveBundlePath(raw: string, cfg: {
+    bundleFilePrefixes: string[];
+}): string;