@easynet-run/node 0.27.14 → 0.39.29

package/src/presets/remote_control/descriptor.js

@@ -1,24 +1,44 @@
-import { DEFAULT_VERSION, asString } from "./config.js";
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/presets/remote_control/descriptor.ts
+// Description: Node remote-control ability package descriptor builders and parsers for deploy and package flows.
+//
+// Protocol Responsibility:
+// - Encodes and decodes portable ability package payloads used by remote-control deploy/package tool flows.
+// - Normalizes package, capability, tool, metadata, and signature fields before bridge/orchestrator calls.
+//
+// Implementation Approach:
+// - Keeps parsing, sanitization, and default generation close to descriptor construction helpers.
+// - Uses deterministic identifier/version/tag normalization so packaged abilities round-trip across SDKs.
+//
+// Usage Contract:
+// - Callers must pass descriptor inputs that can be losslessly represented as JSON-compatible values.
+// - Update descriptor rules here before changing remote-control packaging semantics elsewhere.
+//
+// Architectural Position:
+// - Shared descriptor translation layer for the remote-control preset and ability-lifecycle integrations.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+import { DEFAULT_VERSION, asBool, asString } from "./config.js";
 export function resolveTenant(raw, fallback) {
     const value = asString(raw);
     return !value || value === "<nil>" ? fallback : value;
 }
 export function parseBool(raw) {
-    if (typeof raw === "boolean") {
-        return raw;
-    }
-    if (typeof raw === "number") {
-        return raw !== 0;
-    }
-    const normalized = asString(raw).toLowerCase();
-    return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
+    return asBool(raw);
 }
 export function randomSuffix(length = 2) {
     return Math.floor(Math.random() * 1e18).toString(36).slice(0, length);
 }
 export function sanitizeId(raw) {
     const token = asString(raw).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
-    return token || "tool";
+    if (!token) {
+        throw new Error(`identifier contains no valid characters: ${JSON.stringify(raw)}`);
+    }
+    return token;
 }
 export function shellSingleQuote(raw) {
     return `'${raw.replace(/'/g, "'\"'\"'")}'`;
@@ -67,6 +87,21 @@ export function defaultOutputSchema() {
         required: ["entries"],
     };
 }
+function mergeAdditionalMetadata(base, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return base;
+    }
+    const merged = { ...base };
+    for (const [rawKey, rawValue] of Object.entries(raw)) {
+        const key = asString(rawKey);
+        const value = asString(rawValue);
+        if (!key || !value || Object.prototype.hasOwnProperty.call(merged, key)) {
+            continue;
+        }
+        merged[key] = value;
+    }
+    return merged;
+}
 export function serializeDescriptor(descriptor) {
     const payload = {
         "ability_name": descriptor.abilityName,
@@ -125,6 +160,16 @@ export function parseDescriptor(raw) {
         digest: asString(input.digest) || undefined,
     };
 }
+/**
+ * Build an `AbilityPackageDescriptor` from handler arguments.
+ *
+ * Normalises names, generates a package ID, encodes the command template
+ * into Base64 package bytes, and serialises agent extension properties
+ * (instructions, input_examples, prerequisites, context_bindings, category)
+ * into the metadata map under the `mcp.*` prefix.
+ *
+ * @throws {Error} If `ability_name`, `command_template`, or `signature_base64` is missing.
+ */
 export function buildDescriptor(args, defaultSignature) {
     const abilityName = requireString(args, "ability_name");
     const commandTemplate = requireString(args, "command_template");
@@ -145,7 +190,7 @@ export function buildDescriptor(args, defaultSignature) {
     const outputSchema = typeof args.output_schema === "object" && !Array.isArray(args.output_schema)
         ? args.output_schema
         : defaultOutputSchema();
-    const metadata = {
+    const baseMeta = {
         "mcp.tool_name": toolName,
         "mcp.description": description,
         "mcp.input_schema": JSON.stringify(inputSchema),
@@ -154,6 +199,25 @@ export function buildDescriptor(args, defaultSignature) {
         "ability.name": abilityName,
         "ability.version": version,
     };
+    const instructions = asString(args.instructions);
+    if (instructions)
+        baseMeta["mcp.instructions"] = instructions;
+    if (Array.isArray(args.input_examples) && args.input_examples.length > 0) {
+        baseMeta["mcp.input_examples"] = JSON.stringify(args.input_examples);
+    }
+    if (Array.isArray(args.prerequisites) && args.prerequisites.length > 0) {
+        const prerequisites = args.prerequisites.map((v) => asString(v)).filter(Boolean);
+        if (prerequisites.length > 0) {
+            baseMeta["mcp.prerequisites"] = JSON.stringify(prerequisites);
+        }
+    }
+    if (args.context_bindings && typeof args.context_bindings === "object" && !Array.isArray(args.context_bindings) && Object.keys(args.context_bindings).length > 0) {
+        baseMeta["mcp.context_bindings"] = JSON.stringify(args.context_bindings);
+    }
+    const category = asString(args.category);
+    if (category)
+        baseMeta["mcp.category"] = category;
+    const metadata = mergeAdditionalMetadata(baseMeta, args.metadata);
     const payload = {
         kind: "axon.ability.package.v1",
         ability_name: abilityName,
@@ -181,3 +245,195 @@ export function buildDescriptor(args, defaultSignature) {
         digest: asString(args.digest) || undefined,
     };
 }
+// ---------------------------------------------------------------------------
+// createAbilityDescriptor — build an AbilityDescriptorLite from MCP args
+// ---------------------------------------------------------------------------
+export function createAbilityDescriptor(args) {
+    const name = asString(args.name);
+    if (!name)
+        throw new Error("name is required");
+    const commandTemplate = asString(args.command_template);
+    if (!commandTemplate)
+        throw new Error("command_template is required");
+    const token = sanitizeId(name).replace(/-/g, "_");
+    const toolName = `ability_${token}`;
+    const inputExamples = Array.isArray(args.input_examples)
+        ? args.input_examples
+        : [];
+    const prerequisites = Array.isArray(args.prerequisites)
+        ? args.prerequisites.map((v) => asString(v)).filter(Boolean)
+        : [];
+    const contextBindings = args.context_bindings && typeof args.context_bindings === "object" && !Array.isArray(args.context_bindings)
+        ? Object.fromEntries(Object.entries(args.context_bindings).map(([k, v]) => [k, asString(v)]))
+        : {};
+    return {
+        name,
+        toolName,
+        description: asString(args.description) || `Ability ${name}`,
+        commandTemplate,
+        inputSchema: typeof args.input_schema === "object" && !Array.isArray(args.input_schema)
+            ? args.input_schema
+            : { type: "object", properties: {} },
+        outputSchema: typeof args.output_schema === "object" && !Array.isArray(args.output_schema)
+            ? args.output_schema
+            : { type: "object", properties: {} },
+        version: asString(args.version) || "1.0.0",
+        tags: asStringArray(args.tags),
+        resourceUri: asString(args.resource_uri) || `easynet:///r/org/${token}`,
+        instructions: asString(args.instructions),
+        inputExamples,
+        prerequisites,
+        contextBindings,
+        category: asString(args.category),
+    };
+}
+// ---------------------------------------------------------------------------
+// exportAbilitySkill — generate SKILL.md and invoke.sh from a descriptor
+// ---------------------------------------------------------------------------
+const DEFAULT_AXON_PORT = 50051;
+const SHELL_UNSAFE_RE = /[`$\\\"'\n\r;|&<>(){}!#\x00-\x1f]/;
+function sanitizeShellValue(value, label) {
+    if (SHELL_UNSAFE_RE.test(value)) {
+        throw new Error(`${label} contains disallowed shell characters: ${value}`);
+    }
+    return value;
+}
+function generateExportInvokeScript(resourceUri, endpoint) {
+    const safeEndpoint = sanitizeShellValue(endpoint, "endpoint");
+    const safeUri = sanitizeShellValue(resourceUri, "resource_uri");
+    return `#!/usr/bin/env bash
+set -euo pipefail
+AXON_ENDPOINT="\${AXON_ENDPOINT:-${safeEndpoint}}"
+TENANT="\${AXON_TENANT:-default}"
+RESOURCE_URI="${safeUri}"
+ARGS="\${1:-{}}"
+curl -sS -X POST "\${AXON_ENDPOINT}/v1/invoke" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"tenant_id\\":\\"\${TENANT}\\",\\"resource_uri\\":\\"\${RESOURCE_URI}\\",\\"payload\\":\${ARGS}}"
+`;
+}
+function pushSkillMetadata(lines, version, resourceUri) {
+    lines.push("metadata:");
+    lines.push("  author: easynet-axon");
+    lines.push(`  version: "${version}"`);
+    lines.push(`  axon-resource-uri: "${resourceUri}"`);
+}
+function generateExportAbilityMd(descriptor, target, token) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${token}`);
+    lines.push(`description: ${descriptor.description}`);
+    lines.push("compatibility: Requires network access to Axon runtime");
+    pushSkillMetadata(lines, descriptor.version, descriptor.resourceUri);
+    if (target === "claude") {
+        lines.push("allowed-tools: Bash(*)");
+    }
+    else if (target === "openclaw") {
+        lines.push("  openclaw:");
+        lines.push('    emoji: "⚡"');
+        lines.push("    requires:");
+        lines.push("      network: true");
+        lines.push("    command-dispatch: tool");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${descriptor.name}`);
+    lines.push("");
+    lines.push(descriptor.description);
+    lines.push("");
+    // Instructions
+    if (descriptor.instructions) {
+        lines.push(descriptor.instructions);
+        lines.push("");
+    }
+    // Prerequisites
+    if (descriptor.prerequisites.length > 0) {
+        lines.push("## Prerequisites");
+        lines.push("");
+        for (const prereq of descriptor.prerequisites) {
+            lines.push(`- ${prereq}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Parameters");
+    lines.push("");
+    lines.push("| Name | Type | Required | Description |");
+    lines.push("|------|------|----------|-------------|");
+    const props = (descriptor.inputSchema.properties ?? {});
+    const required = (descriptor.inputSchema.required ?? []);
+    for (const [propName, schema] of Object.entries(props)) {
+        const propType = schema.type ?? "string";
+        const propDesc = schema.description ?? "";
+        const isRequired = required.includes(propName) ? "Yes" : "No";
+        lines.push(`| ${propName} | ${propType} | ${isRequired} | ${propDesc} |`);
+    }
+    // Examples
+    if (descriptor.inputExamples.length > 0) {
+        lines.push("");
+        lines.push("## Examples");
+        lines.push("");
+        for (let i = 0; i < descriptor.inputExamples.length; i++) {
+            lines.push(`**Example ${i + 1}:**`);
+            lines.push("");
+            lines.push("```json");
+            const example = descriptor.inputExamples[i];
+            if (typeof example === "string") {
+                lines.push(example);
+            }
+            else {
+                lines.push(JSON.stringify(example, null, 2));
+            }
+            lines.push("```");
+            lines.push("");
+        }
+    }
+    // Context Bindings
+    const bindingEntries = Object.entries(descriptor.contextBindings);
+    if (bindingEntries.length > 0) {
+        lines.push("## Context Bindings");
+        lines.push("");
+        lines.push("| Key | Value |");
+        lines.push("|-----|-------|");
+        for (const [key, value] of bindingEntries) {
+            lines.push(`| \`${key}\` | ${value} |`);
+        }
+        lines.push("");
+    }
+    lines.push("");
+    lines.push("## Invoke");
+    lines.push("");
+    lines.push("Run the bundled script with a JSON argument:");
+    lines.push("");
+    const skillDirVar = target === "claude" ? "CLAUDE_SKILL_DIR"
+        : target === "codex" ? "CODEX_SKILL_DIR"
+            : "SKILL_DIR";
+    lines.push("```bash");
+    lines.push(`\${${skillDirVar}}/scripts/invoke.sh '{"param": "value"}'`);
+    lines.push("```");
+    lines.push("");
+    // Axon Resource footer
+    lines.push("## Axon Resource");
+    lines.push("");
+    lines.push(`- **URI**: \`${descriptor.resourceUri}\``);
+    lines.push(`- **Version**: ${descriptor.version}`);
+    if (descriptor.category) {
+        lines.push(`- **Category**: ${descriptor.category}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function parseAbilityTarget(raw) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "claude" || normalized === "codex" || normalized === "openclaw" || normalized === "agent_skills") {
+        return normalized;
+    }
+    return "agent_skills";
+}
+export function exportAbilitySkill(descriptor, target = "agent_skills", axonEndpoint) {
+    const token = descriptor.toolName;
+    const endpoint = axonEndpoint ?? `http://127.0.0.1:${DEFAULT_AXON_PORT}`;
+    const invokeScript = generateExportInvokeScript(descriptor.resourceUri, endpoint);
+    const abilityMd = generateExportAbilityMd(descriptor, target, token);
+    return { abilityMd, invokeScript, abilityName: token };
+}
+export { parseAbilityTarget };

package/src/presets/remote_control/handlers.d.ts

@@ -4,9 +4,17 @@ export declare function resolveDescriptor(args: JsonRecord, fallbackSignature: s
 export declare function handleDiscoverNodes(orch: RemoteOrchestrator, tenant: string): JsonRecord;
 export declare function handleListRemoteTools(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
 export declare function handleCallRemoteTool(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
+/** Open a streaming MCP tool call with validated tool_name and node_id. */
+export declare function handleCallRemoteToolStream(orch: RemoteOrchestrator, _tenant: string, args: JsonRecord): ReturnType<RemoteOrchestrator["callMcpToolStream"]>;
 export declare function handleDisconnectDevice(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
 export declare function handleUninstallAbility(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
 export declare function handlePackageAbility(tenant: string, args: JsonRecord, signature: string): JsonRecord;
 export declare function handleDeployAbilityPackage(orch: RemoteOrchestrator, tenant: string, args: JsonRecord, signature: string): JsonRecord;
 export declare function handleDeployAbility(orch: RemoteOrchestrator, tenant: string, args: JsonRecord, signature: string): JsonRecord;
 export declare function handleExecuteCommand(orch: RemoteOrchestrator, tenant: string, args: JsonRecord, signature: string): JsonRecord;
+export declare function handleDrainDevice(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
+export declare function handleCreateAbility(args: JsonRecord): JsonRecord;
+export declare function handleExportAbilitySkill(args: JsonRecord): JsonRecord;
+export declare function handleRedeployAbility(orch: RemoteOrchestrator, tenant: string, args: JsonRecord, signature: string): JsonRecord;
+export declare function handleListAbilities(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;
+export declare function handleForgetAll(orch: RemoteOrchestrator, tenant: string, args: JsonRecord): JsonRecord;

package/src/presets/remote_control/handlers.js

@@ -2,13 +2,29 @@
 // =========================
 //
 // File: sdk/node/src/presets/remote_control/handlers.ts
-// Description: MCP tool handlers for remote device control workflows.
+// Description: Node remote-control MCP tool handlers for discovery, deployment, execution, and lifecycle workflows.
+//
+// Protocol Responsibility:
+// - Publishes MCP-facing handlers for discovery, deployment, execution, and lifecycle control operations.
+// - Maps untyped tool arguments into stable tenant-scoped orchestrator requests and MCP result payloads.
+//
+// Implementation Approach:
+// - Performs validation and response shaping at the tool boundary while delegating side effects to orchestrator helpers.
+// - Reuses descriptor/config utilities so remote-control behavior stays aligned across language SDKs.
+//
+// Usage Contract:
+// - Intended to be called from MCP dispatch with untyped argument objects and preset runtime configuration.
+// - Handler error payloads are part of the remote-control tool contract and should stay explicit and machine-readable.
+//
+// Architectural Position:
+// - Preset execution layer between MCP server facades and bridge-backed orchestration helpers.
 //
 // Author: Silan.Hu
 // Email: silan.hu@u.nus.edu
 // Copyright (c) 2026-2027 easynet. All rights reserved.
-import { buildDescriptor, buildPythonSubprocessTemplate, parseBool, parseDescriptor, serializeDescriptor, } from "./descriptor.js";
-import { asString } from "./config.js";
+import { randomBytes } from "node:crypto";
+import { buildDescriptor, buildPythonSubprocessTemplate, createAbilityDescriptor, exportAbilitySkill, parseAbilityTarget, parseBool, parseDescriptor, serializeDescriptor, } from "./descriptor.js";
+import { asBool, asNumber, asString, DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS } from "./config.js";
 // ---------------------------------------------------------------------------
 // Architecture: ability_lifecycle vs presets/remote_control
 //
@@ -32,6 +48,18 @@ const INVOCATION_COMPLETED = 5;
 export function resolveDescriptor(args, fallbackSignature) {
     return args.package ? parseDescriptor(args.package) : buildDescriptor(args, fallbackSignature);
 }
+function abilityEntryFromTool(tool) {
+    const installId = String(tool.install_id ?? "").trim();
+    if (!installId) {
+        return null;
+    }
+    return {
+        tool_name: tool.tool_name ?? null,
+        description: tool.description ?? null,
+        capability_name: tool.capability_name ?? null,
+        install_id: installId,
+    };
+}
 export function handleDiscoverNodes(orch, tenant) {
     const nodes = orch.listNodes("");
     return {
@@ -55,13 +83,11 @@ export function handleListRemoteTools(orch, tenant, args) {
         count: tools.length,
         node_id: nodeId,
         name_pattern: pattern,
-        tools: tools.map((tool) => ({
-            tool_name: tool.tool_name,
-            description: tool.description,
-            capability_name: tool.capability_name,
-            available_nodes: tool.available_nodes,
-            node_ids: tool.node_ids,
-        })),
+        // Pass through the full tool entry from the runtime — including
+        // input_schema, output_schema, hints, instructions, examples,
+        // prerequisites, context_bindings, and category.  Stripping
+        // fields here would prevent AI agents from understanding tools.
+        tools: tools.map((tool) => ({ ...tool })),
     };
 }
 export function handleCallRemoteTool(orch, tenant, args) {
@@ -79,6 +105,21 @@ export function handleCallRemoteTool(orch, tenant, args) {
     const failed = asNumber(call.state) !== INVOCATION_COMPLETED || asBool(call.is_error);
     return { ok: !failed, tenant_id: tenant, tool_name: toolName, node_id: nodeId, call };
 }
+/** Open a streaming MCP tool call with validated tool_name and node_id. */
+export function handleCallRemoteToolStream(orch, _tenant, args) {
+    const toolName = String(args.tool_name || "").trim();
+    const nodeId = String(args.node_id || "").trim();
+    if (!toolName || !nodeId) {
+        throw new Error(!toolName ? "tool_name is required" : "node_id is required");
+    }
+    const callArgs = typeof args.arguments === "object" && !Array.isArray(args.arguments)
+        ? args.arguments
+        : {};
+    const timeoutMs = asNumber(args.timeout_ms);
+    return orch.callMcpToolStream(toolName, nodeId, callArgs, {
+        timeoutMs: timeoutMs > 0 ? timeoutMs : DEFAULT_MCP_TOOL_STREAM_TIMEOUT_MS,
+    });
+}
 export function handleDisconnectDevice(orch, tenant, args) {
     const nodeId = String(args.node_id || "").trim();
     if (!nodeId) {
@@ -149,7 +190,7 @@ export function handleDeployAbility(orch, tenant, args, signature) {
     if (!commandTemplate) {
         return { ok: false, tenant_id: tenant, node_id: nodeId, error: "command_template is required" };
     }
-    const toolName = String(args.tool_name || `tool_${Date.now()}`).trim();
+    const toolName = String(args.tool_name || `tool_${Date.now()}_${randomHex(4)}`).trim();
     const descriptor = buildDescriptor({
         ...args,
         ability_name: toolName,
@@ -177,7 +218,7 @@ export function handleExecuteCommand(orch, tenant, args, signature) {
     if (!command)
         return { ok: false, tenant_id: tenant, node_id: nodeId, error: "command is required" };
     const shouldCleanup = args.cleanup == null ? true : parseBool(args.cleanup);
-    const toolName = `cmd_${Date.now()}_${Math.floor(Math.random() * 1e4).toString(16)}`;
+    const toolName = `cmd_${Date.now()}_${randomHex(4)}`;
     const descriptor = buildDescriptor({
         ability_name: toolName,
         tool_name: toolName,
@@ -221,20 +262,6 @@ export function handleExecuteCommand(orch, tenant, args, signature) {
         };
     }
 }
-function asBool(raw) {
-    if (typeof raw === "boolean")
-        return raw;
-    if (typeof raw === "number")
-        return raw !== 0;
-    const normalized = String(raw ?? "").trim().toLowerCase();
-    return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
-}
-function asNumber(raw) {
-    if (typeof raw === "number")
-        return raw;
-    const value = Number.parseInt(String(raw ?? "0"), 10);
-    return Number.isFinite(value) ? value : 0;
-}
 function parseDeployFailure(error) {
     const message = error instanceof Error ? error.message : String(error ?? "");
     try {
@@ -277,3 +304,180 @@ function parseCleanupSummary(failure, orch, nodeId, shouldCleanup) {
         },
     ]);
 }
+// ---------------------------------------------------------------------------
+// DEVICE MANAGEMENT & ABILITY LIFECYCLE HANDLERS
+// Ported from Rust SDK for cross-SDK parity.
+// ---------------------------------------------------------------------------
+export function handleDrainDevice(orch, tenant, args) {
+    const nodeId = String(args.node_id || "").trim();
+    if (!nodeId) {
+        return { ok: false, tenant_id: tenant, error: "node_id is required" };
+    }
+    const reason = String(args.reason || "").trim() || "drain_device: requested by agent";
+    const response = orch.drainNode(nodeId, reason);
+    return {
+        ok: true,
+        tenant_id: tenant,
+        node_id: nodeId,
+        status: "draining",
+        response,
+    };
+}
+export function handleCreateAbility(args) {
+    try {
+        const descriptor = createAbilityDescriptor(args);
+        return { ok: true, descriptor };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function handleExportAbilitySkill(args) {
+    try {
+        const descriptor = createAbilityDescriptor(args);
+        const targetStr = String(args.target || "").trim();
+        const target = parseAbilityTarget(targetStr);
+        const axonEndpoint = String(args.axon_endpoint || "").trim() || undefined;
+        const result = exportAbilitySkill(descriptor, target, axonEndpoint);
+        return {
+            ok: true,
+            ability_name: result.abilityName,
+            ability_md: result.abilityMd,
+            invoke_script: result.invokeScript,
+        };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function handleRedeployAbility(orch, tenant, args, signature) {
+    const nodeId = String(args.node_id || "").trim();
+    if (!nodeId) {
+        return { ok: false, tenant_id: tenant, error: "node_id is required" };
+    }
+    const toolName = String(args.tool_name || "").trim();
+    if (!toolName) {
+        return { ok: false, tenant_id: tenant, node_id: nodeId, error: "tool_name is required" };
+    }
+    const commandTemplate = String(args.command_template || "").trim();
+    if (!commandTemplate) {
+        return { ok: false, tenant_id: tenant, node_id: nodeId, error: "command_template is required" };
+    }
+    const description = String(args.description || "").trim() || `Redeployed ability: ${toolName}`;
+    // Preserve all original args (including agent extension fields like
+    // instructions, input_examples, prerequisites, context_bindings, category)
+    // and override only the required fields.
+    const descriptor = buildDescriptor({
+        ...args,
+        ability_name: toolName,
+        tool_name: toolName,
+        description,
+        command_template: commandTemplate,
+    }, signature);
+    const deployed = orch.deployAbilityPackage(descriptor, nodeId, true);
+    return {
+        ok: true,
+        tenant_id: tenant,
+        node_id: nodeId,
+        tool_name: toolName,
+        description,
+        status: "redeployed",
+        install_id: asString(deployed.install_id),
+    };
+}
+export function handleListAbilities(orch, tenant, args) {
+    const nodeId = String(args.node_id || "").trim();
+    if (!nodeId) {
+        return { ok: false, tenant_id: tenant, error: "node_id is required" };
+    }
+    const tools = orch.listMcpTools("", [], nodeId);
+    const abilities = [];
+    for (const tool of Array.isArray(tools) ? tools : []) {
+        const ability = abilityEntryFromTool(tool);
+        if (ability) {
+            abilities.push(ability);
+        }
+    }
+    return {
+        ok: true,
+        tenant_id: tenant,
+        node_id: nodeId,
+        count: abilities.length,
+        abilities,
+    };
+}
+export function handleForgetAll(orch, tenant, args) {
+    const nodeId = String(args.node_id || "").trim();
+    if (!nodeId) {
+        return { ok: false, tenant_id: tenant, error: "node_id is required" };
+    }
+    const confirmed = parseBool(args.confirm ?? false);
+    const dryRun = parseBool(args.dry_run ?? false);
+    if (!confirmed && !dryRun) {
+        return {
+            ok: false,
+            tenant_id: tenant,
+            node_id: nodeId,
+            error: "forget_all requires confirm: true (destructive operation)",
+        };
+    }
+    // List all abilities on the device
+    const tools = orch.listMcpTools("", [], nodeId);
+    const abilities = (Array.isArray(tools) ? tools : []);
+    if (dryRun) {
+        const wouldRemove = [];
+        const wouldFail = [];
+        for (const tool of abilities) {
+            const t = tool;
+            const installId = String(t.install_id || "").trim();
+            const name = String(t.tool_name || "unknown");
+            if (!installId) {
+                wouldFail.push({ tool_name: name, error: "missing install_id" });
+            }
+            else {
+                wouldRemove.push(name);
+            }
+        }
+        return {
+            ok: true,
+            tenant_id: tenant,
+            node_id: nodeId,
+            dry_run: true,
+            removed: wouldRemove,
+            removed_count: wouldRemove.length,
+            failed: wouldFail,
+            failed_count: wouldFail.length,
+        };
+    }
+    const removed = [];
+    const failed = [];
+    for (const tool of abilities) {
+        const t = tool;
+        const installId = String(t.install_id || "").trim();
+        const name = String(t.tool_name || "unknown");
+        if (!installId) {
+            failed.push({ tool_name: name, error: "missing install_id" });
+            continue;
+        }
+        try {
+            orch.uninstallAbility(nodeId, installId, "forget_all: requested by agent");
+            removed.push(name);
+        }
+        catch (error) {
+            failed.push({ tool_name: name, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return {
+        ok: true,
+        tenant_id: tenant,
+        node_id: nodeId,
+        dry_run: false,
+        removed,
+        removed_count: removed.length,
+        failed,
+        failed_count: failed.length,
+    };
+}
+function randomHex(bytes) {
+    return randomBytes(bytes).toString("hex");
+}

package/src/presets/remote_control/kit.d.ts

@@ -1,4 +1,4 @@
-import type { McpToolProvider, McpToolResult } from "../../mcp/server.js";
+import { type McpToolProvider, type McpToolResult, type McpToolStreamHandle } from "../../mcp/server.js";
 import { type RemoteControlRuntimeConfig } from "./config.js";
 import { type JsonRecord } from "./descriptor.js";
 import { type OrchestratorFactory } from "./orchestrator.js";
@@ -14,7 +14,9 @@ export declare class RemoteControlCaseKit implements McpToolProvider {
     static ensureNativeLibEnv(): void;
     static ensureRemoteControlNativeLibEnv(): void;
     toolSpecs(): Array<JsonRecord>;
-    handleToolCall(name: string, args: JsonRecord): McpToolResult;
+    handleToolCall(name: string, args: JsonRecord): McpToolResult | Promise<McpToolResult>;
+    /** Handle streaming calls for `call_remote_tool_stream`. Returns null for unknown tools. */
+    handleToolCallStream(name: string, args: JsonRecord): McpToolStreamHandle | null;
     private dispatch;
     private withOrchestrator;
     private toolResult;