@aramisfa/openclaw-a2a-outbound 0.2.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramisfa/openclaw-a2a-outbound",
-  "version": "0.2.2",
+  "version": "2.0.0",
   "description": "Outbound A2A delegation plugin for OpenClaw agents",
   "license": "MIT",
   "repository": {
@@ -41,14 +41,6 @@
       "./dist/index.js"
     ]
   },
-  "scripts": {
-    "build": "tsc -b",
-    "typecheck:src": "tsc -b --pretty false",
-    "typecheck:tests": "tsc -p tsconfig.tests.json --pretty false",
-    "typecheck": "corepack pnpm run typecheck:src && corepack pnpm run typecheck:tests",
-    "test": "corepack pnpm run build && node --import tsx --test tests/*.test.ts",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.10",
     "ajv": "^8.18.0",
@@ -67,5 +59,13 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck:src": "tsc -b --pretty false",
+    "typecheck:tests": "tsc -p tsconfig.tests.json --pretty false",
+    "typecheck": "corepack pnpm run typecheck:src && corepack pnpm run typecheck:tests",
+    "test": "corepack pnpm run build && node --import tsx --test tests/*.test.ts",
+    "clean": "rm -rf dist"
   }
-}
+}

package/skills/remote-agent/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: remote-agent
 description: Delegate work to external A2A agents using the remote_agent tool.
-metadata: {"openclaw": {"requires": {"config": ["plugins.entries.openclaw-a2a-outbound.enabled"]}}}
+metadata: {"openclaw": {"requires": {"config": ["plugins.entries.openclaw-a2a-outbound.enabled", "plugins.entries.openclaw-a2a-outbound.config.enabled"]}}}
 ---
 
 # Remote Agent Delegation
 
-Use the `remote_agent` tool to delegate work to external A2A-compatible agents and manage delegated tasks.
+If the plugin is not installed or configured yet, use the `a2a-delegation-setup` skill first.
+
+Use the `remote_agent` tool to delegate work to external A2A-compatible agents and manage delegated tasks. `send` is the only action to start a new remote turn or continue an existing one.
 
 ## When to delegate
 
@@ -38,21 +40,85 @@ Discover configured targets.
 
 ### send
 
-Send a request to a remote agent.
+Send a request to a remote agent. Use it for:
+
+- a brand-new remote task
+- a follow-up turn on an existing remote task
+- a related new task that references prior work
+- a new task inside an existing remote conversation
 
 ```json
 {
   "action": "send",
   "target_alias": "my-agent",
-  "input": "Summarize the latest quarterly report.",
+  "parts": [
+    {
+      "kind": "text",
+      "text": "Summarize the latest quarterly report."
+    }
+  ],
   "follow_updates": true
 }
 ```
 
-- `input` (required): the user text to send.
+- `parts` (required): non-empty array of `text`, `file`, or `data` parts.
 - `target_alias`: configured target name. Omit when a default target exists.
-- `follow_updates`: when `true`, streams updates and returns the full event log.
-- `attachments`: optional array of file or data attachments.
+- `task_handle`: preferred continuation key for `send`, `watch`, `status`, and `cancel`.
+- `task_id`: optional continuation id for `send`; for follow-up actions it identifies the remote task when no `task_handle` is available. `task_id` continues an existing task.
+- `context_id`: optional conversation continuation id for `send`. Use it with `task_id`, or by itself to start a new task in the same conversation.
+- `reference_task_ids`: optional related task ids for `send`. `reference_task_ids` references prior tasks without continuing them.
+- `task_requirement`: optional durability contract. `task_requirement="required"` forces explicit task creation or fails fast.
+- `follow_updates`: when `true`, streams updates and returns the full event log. `follow_updates=true` means “stream the initial send”; it does not guarantee task creation unless `task_requirement="required"`.
+- `blocking`: only for non-stream `send`; do not combine it with `follow_updates=true`.
+
+Preferred continuation forms:
+
+```json
+{ "action": "send", "task_handle": "rah_abc123", "parts": [{ "kind": "text", "text": "Approved. Continue." }] }
+```
+
+```json
+{ "action": "send", "target_alias": "my-agent", "task_id": "task-123", "parts": [{ "kind": "text", "text": "Continue the task." }] }
+```
+
+```json
+{ "action": "send", "target_alias": "my-agent", "context_id": "ctx-123", "parts": [{ "kind": "text", "text": "Start a new task in the same conversation." }] }
+```
+
+```json
+{ "action": "send", "target_alias": "my-agent", "context_id": "ctx-123", "reference_task_ids": ["task-1", "task-2"], "parts": [{ "kind": "text", "text": "Start related work without continuing those tasks." }] }
+```
+
+## Continuation safety
+
+Interpret follow-up capability from `result.summary.continuation`, not from prompt text, message text, or other inferred context.
+
+- `response_kind` is descriptive only. Keep follow-up logic anchored to `summary.continuation`.
+- `summary.continuation.task`: trackable task continuity. Use it for follow-up `send`, `watch`, `status`, and `cancel`.
+- `summary.continuation.conversation`: conversation continuity only. Use it only with `send` to start a new task in the same conversation.
+- Branch on `summary.continuation.task` vs `summary.continuation.conversation` before choosing the next action.
+- Never infer or synthesize `summary.continuation.task` from `summary.continuation.conversation`, session ids, run ids, prior prompts, or summary text.
+- Do not call `watch`, `status`, or `cancel` from a result that has only `summary.continuation.conversation`.
+- If lifecycle tracking is required, fail fast when the peer returns only `summary.continuation.conversation`.
+
+```ts
+const task = result.summary.continuation?.task
+const conversation = result.summary.continuation?.conversation
+
+if (task) {
+  // Trackable task lifecycle.
+} else if (conversation) {
+  // Send-only conversation continuity.
+}
+```
+
+Invalid follow-up example:
+
+```json
+{ "action": "status", "context_id": "ctx-123" }
+```
+
+That is invalid because `status`, `watch`, and `cancel` require task continuity, not just conversation continuity.
 
 ### status
 
@@ -80,7 +146,7 @@ Cancel a running task.
 
 ## Task handles
 
-After a successful `send`, the result includes a `task_handle` (prefixed `rah_`). Always prefer `task_handle` over `target_alias + task_id` for follow-up actions — the handle encodes the target and task identity in one opaque token. Handles are process-local and expire after restart or TTL. If a handle expires, fall back to `target_alias` + `task_id`.
+After a successful `send`, the result usually includes `summary.continuation.task.task_handle` (prefixed `rah_`) when the remote peer exposes task continuity. `task_handle` is returned only when the peer actually created a task. Always prefer `summary.continuation.task.task_handle` over `target_alias + summary.continuation.task.task_id` for follow-up `send`/`watch`/`status`/`cancel` actions. Handles are process-local and expire after restart or TTL. If a handle expires, fall back to `target_alias` + `summary.continuation.task.task_id`. Treat `send.task_id` as a continuation id for the remote peer, not as a replacement for `summary.continuation.task.task_handle`. If the result includes only `summary.continuation.conversation`, there is no task lifecycle to poll, watch, or cancel.
 
 ## watch vs status
 

package/dist/plugin-config.d.ts

@@ -1,5 +0,0 @@
-import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
-import { type A2AOutboundPluginConfig } from "./constants.js";
-export declare function parseA2AOutboundPluginConfig(input: unknown): A2AOutboundPluginConfig;
-export declare const A2AOutboundPluginConfigSchema: OpenClawPluginConfigSchema;
-//# sourceMappingURL=plugin-config.d.ts.map

package/dist/plugin-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plugin-config.d.ts","sourceRoot":"","sources":["../src/plugin-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAGL,KAAK,uBAAuB,EAE7B,MAAM,gBAAgB,CAAC;AAuFxB,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,uBAAuB,CA4CzB;AAED,eAAO,MAAM,6BAA6B,EAAE,0BAI3C,CAAC"}

package/dist/plugin-config.js

@@ -1,89 +0,0 @@
-import { ALL_TRANSPORTS, DEFAULTS, } from "./constants.js";
-function cloneConfig(config) {
-    return {
-        enabled: config.enabled,
-        defaults: {
-            timeoutMs: config.defaults.timeoutMs,
-            cardPath: config.defaults.cardPath,
-            preferredTransports: [...config.defaults.preferredTransports],
-            serviceParameters: { ...config.defaults.serviceParameters },
-        },
-        policy: {
-            acceptedOutputModes: [...config.policy.acceptedOutputModes],
-            normalizeBaseUrl: config.policy.normalizeBaseUrl,
-            enforceSupportedTransports: config.policy.enforceSupportedTransports,
-        },
-    };
-}
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizeStringArray(value, fallback = []) {
-    if (!Array.isArray(value)) {
-        return [...fallback];
-    }
-    const normalized = [];
-    for (const entry of value) {
-        if (typeof entry !== "string" || entry.trim() === "") {
-            continue;
-        }
-        if (!normalized.includes(entry)) {
-            normalized.push(entry);
-        }
-    }
-    return normalized;
-}
-function normalizeTransports(value, fallback) {
-    const normalized = normalizeStringArray(value).filter((entry) => ALL_TRANSPORTS.includes(entry));
-    return normalized.length > 0 ? normalized : [...fallback];
-}
-function normalizeStringMap(value, fallback = {}) {
-    if (!isPlainObject(value)) {
-        return { ...fallback };
-    }
-    const normalized = {};
-    for (const [key, entry] of Object.entries(value)) {
-        if (typeof entry === "string") {
-            normalized[key] = entry;
-        }
-    }
-    return normalized;
-}
-function readBoolean(value, fallback) {
-    return typeof value === "boolean" ? value : fallback;
-}
-function readPositiveInteger(value, fallback) {
-    return Number.isInteger(value) && value > 0
-        ? value
-        : fallback;
-}
-export function parseA2AOutboundPluginConfig(input) {
-    if (!isPlainObject(input)) {
-        return cloneConfig(DEFAULTS);
-    }
-    const rawDefaults = isPlainObject(input.defaults) ? input.defaults : {};
-    const rawPolicy = isPlainObject(input.policy) ? input.policy : {};
-    return {
-        enabled: readBoolean(input.enabled, DEFAULTS.enabled),
-        defaults: {
-            timeoutMs: readPositiveInteger(rawDefaults.timeoutMs, DEFAULTS.defaults.timeoutMs),
-            cardPath: typeof rawDefaults.cardPath === "string" &&
-                rawDefaults.cardPath.trim() !== ""
-                ? rawDefaults.cardPath
-                : DEFAULTS.defaults.cardPath,
-            preferredTransports: normalizeTransports(rawDefaults.preferredTransports, DEFAULTS.defaults.preferredTransports),
-            serviceParameters: normalizeStringMap(rawDefaults.serviceParameters, DEFAULTS.defaults.serviceParameters),
-        },
-        policy: {
-            acceptedOutputModes: normalizeStringArray(rawPolicy.acceptedOutputModes, DEFAULTS.policy.acceptedOutputModes),
-            normalizeBaseUrl: readBoolean(rawPolicy.normalizeBaseUrl, DEFAULTS.policy.normalizeBaseUrl),
-            enforceSupportedTransports: readBoolean(rawPolicy.enforceSupportedTransports, DEFAULTS.policy.enforceSupportedTransports),
-        },
-    };
-}
-export const A2AOutboundPluginConfigSchema = {
-    parse(value) {
-        return parseA2AOutboundPluginConfig(value);
-    },
-};
-//# sourceMappingURL=plugin-config.js.map

package/dist/plugin-config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"plugin-config.js","sourceRoot":"","sources":["../src/plugin-config.ts"],"names":[],"mappings":"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"}