@kweaver-ai/kweaver-sdk 0.6.9 → 0.6.10

package/dist/api/agent-list.js

@@ -12,11 +12,24 @@ export async function listAgents(options) {
         custom_space_id,
         is_to_square,
     });
-    const response = await fetchWithRetry(url, {
+    // Some deployments (observed on dip-poc.aishu.cn) return an empty entries
+    // array when this endpoint is called with `application/json`; the same
+    // payload sent as `text/plain` works. Other deployments only accept
+    // `application/json` (and reject text/plain with 4xx). Try text/plain first
+    // and fall back to application/json on 4xx so both platform variants work
+    // out of the box.
+    const tryPost = async (contentType) => fetchWithRetry(url, {
         method: "POST",
-        headers: buildHeaders(accessToken, businessDomain),
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": contentType,
+        },
         body,
     });
+    let response = await tryPost("text/plain;charset=UTF-8");
+    if (!response.ok && response.status >= 400 && response.status < 500) {
+        response = await tryPost("application/json");
+    }
     const responseBody = await response.text();
     if (!response.ok) {
         throw new HttpError(response.status, response.statusText, responseBody);

package/dist/api/ontology-query.d.ts

@@ -44,11 +44,40 @@ export declare function actionTypeQuery(options: ActionTypeQueryOptions): Promis
 /**
  * Action-type execute: POST (has side effects).
  *
- * The request body must include `_instance_identities` — an array of objects
- * identifying which instances the action operates on:
+ * The request body must use the envelope shape below — top-level scalar fields
+ * (other than `trigger_type` and `_instance_identities`) are silently dropped
+ * by the backend, which causes downstream tools to receive `null` parameters
+ * (and typically respond with 401 token expired or 500 type errors).
+ *
  * ```json
- * {"_instance_identities": [{"<primary_key>": "<value>"}], ...otherParams}
+ * {
+ *   "trigger_type": "manual",
+ *   "_instance_identities": [{"<primary_key>": "<value>"}],
+ *   "dynamic_params": {
+ *     "<param_name>": "<value>",
+ *     "Authorization": "Bearer <token>"
+ *   }
+ * }
  * ```
+ *
+ * - `_instance_identities` may be `[]` for "create"-style actions.
+ * - Each ActionType parameter has a `value_from` discriminator:
+ *     • `input`    — caller MUST supply via `dynamic_params`. Includes
+ *                    `source: header` params (e.g. `Authorization`/`token`),
+ *                    which are usually credentials for the DOWNSTREAM system
+ *                    the action calls — NOT the platform session token. The
+ *                    SDK never auto-forwards its session token.
+ *     • `const`    — frozen in the ActionType snapshot; values in body are
+ *                    silently ignored. Edit the ActionType definition to
+ *                    `input` first if you need caller override.
+ *     • `property` — auto-populated from the resolved instance's property;
+ *                    do not (and cannot) supply via body.
+ *
+ * Practical recipe: query the ActionType, filter parameters where
+ * `value_from == "input"`, put exactly those names into `dynamic_params`.
+ *
+ * See `skills/kweaver-core/references/bkn.md` ("action-type execute 请求体契约")
+ * for the full contract and troubleshooting table.
  */
 export interface ActionTypeExecuteOptions extends OntologyQueryBaseOptions {
     atId: string;

package/dist/api/toolboxes.d.ts

@@ -44,4 +44,20 @@ export interface ListToolsOptions extends BaseOpts {
     boxId: string;
 }
 export declare function listTools(opts: ListToolsOptions): Promise<string>;
+export interface InvokeToolOptions extends BaseOpts {
+    boxId: string;
+    toolId: string;
+    /** Optional headers to forward to the downstream tool (e.g. Authorization). */
+    header?: Record<string, unknown>;
+    /** Optional query params to forward. */
+    query?: Record<string, unknown>;
+    /** JSON body forwarded to the downstream tool. */
+    body?: unknown;
+    /** Per-call timeout in seconds; backend default applies when omitted. */
+    timeout?: number;
+}
+/** Execute a published+enabled tool through the toolbox proxy. */
+export declare function executeTool(opts: InvokeToolOptions): Promise<string>;
+/** Debug a tool through the toolbox proxy (works on draft/disabled tools too). */
+export declare function debugTool(opts: InvokeToolOptions): Promise<string>;
 export {};

package/dist/api/toolboxes.js

@@ -5,15 +5,24 @@ import { buildHeaders } from "./headers.js";
 // Backend endpoints under /api/agent-operator-integration/v1/tool-box.
 //
 // Verified against kweaver/examples/03-action-lifecycle/run.sh (lines 78–197):
-//   POST   /tool-box                   create
-//   DELETE /tool-box/{id}              delete
-//   POST   /tool-box/{id}/status       publish/draft
-//   POST   /tool-box/{id}/tool         upload tool (multipart)
-//   POST   /tool-box/{id}/tools/status enable/disable (batch)
+//   POST   /tool-box                       create
+//   DELETE /tool-box/{id}                  delete
+//   POST   /tool-box/{id}/status           publish/draft
+//   POST   /tool-box/{id}/tool             upload tool (multipart)
+//   POST   /tool-box/{id}/tools/status     enable/disable (batch)
 //
 // Verified during Task 8 e2e against the live backend (2026-04-18):
 //   GET    /tool-box/list?keyword=&limit=&offset=  list toolboxes
 //   GET    /tool-box/{id}/tools/list               list tools
+//
+// Verified live on 2026-04-23 against dip-poc.aishu.cn:
+//   POST   /tool-box/{box}/proxy/{tool}            execute tool (envelope JSON)
+//   POST   /tool-box/{box}/tool/{tool}/debug       debug tool (envelope JSON)
+//
+// Envelope shape required by /proxy and /debug:
+//   { "timeout": <s>, "header": {...}, "query": {...}, "body": {...} }
+// Flat-shape requests cause the forwarder to drop downstream Authorization
+// headers, which manifests as 401 "token expired" from the underlying tool.
 const PATH = "/api/agent-operator-integration/v1/tool-box";
 function url(base, suffix = "") {
     return `${base.replace(/\/+$/, "")}${PATH}${suffix}`;
@@ -88,3 +97,28 @@ export async function listTools(opts) {
     });
     return body;
 }
+function buildEnvelope(opts) {
+    const envelope = {};
+    if (opts.timeout !== undefined)
+        envelope.timeout = opts.timeout;
+    envelope.header = opts.header ?? {};
+    envelope.query = opts.query ?? {};
+    envelope.body = opts.body ?? {};
+    return JSON.stringify(envelope);
+}
+async function invokeTool(opts, suffix) {
+    const { body } = await fetchTextOrThrow(url(opts.baseUrl, suffix), {
+        method: "POST",
+        headers: { ...buildHeaders(opts.accessToken, opts.businessDomain ?? "bd_public"), "content-type": "application/json" },
+        body: buildEnvelope(opts),
+    });
+    return body;
+}
+/** Execute a published+enabled tool through the toolbox proxy. */
+export async function executeTool(opts) {
+    return invokeTool(opts, `/${encodeURIComponent(opts.boxId)}/proxy/${encodeURIComponent(opts.toolId)}`);
+}
+/** Debug a tool through the toolbox proxy (works on draft/disabled tools too). */
+export async function debugTool(opts) {
+    return invokeTool(opts, `/${encodeURIComponent(opts.boxId)}/tool/${encodeURIComponent(opts.toolId)}/debug`);
+}

package/dist/cli.js

@@ -88,7 +88,8 @@ Usage:
   kweaver bkn object-type list|get|create|update|delete|query|properties <kn-id> ...
   kweaver bkn relation-type list|get|create|update|delete <kn-id> ...
   kweaver bkn subgraph <kn-id> <body-json>
-  kweaver bkn action-type list|query|execute <kn-id> ... [--wait] [--no-wait] [--timeout N]
+  kweaver bkn action-type list|query|inputs|execute <kn-id> ... [--wait] [--no-wait] [--timeout N]
+  kweaver bkn action-type execute <kn-id> <at-id> [<envelope-json>|--dynamic-params '<json>' --instance '<json>' --trigger-type <v>]
   kweaver bkn action-execution get <kn-id> <execution-id>
   kweaver bkn action-log list|get|cancel <kn-id> ...
 
@@ -110,6 +111,9 @@ Usage:
   kweaver tool upload --toolbox <box-id> <openapi-spec-path> [--metadata-type openapi]
   kweaver tool list --toolbox <box-id> [-bd value]
   kweaver tool enable|disable --toolbox <box-id> <tool-id>... [-bd value]
+  kweaver tool execute|debug --toolbox <box-id> <tool-id>
+                             [--body '<json>'|--body-file <path>]
+                             [--header '<json>'] [--query '<json>'] [--timeout <s>]
 
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]

package/dist/client.d.ts

@@ -7,6 +7,7 @@ import { DataViewsResource } from "./resources/dataviews.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
+import { ToolboxesResource } from "./resources/toolboxes.js";
 import { VegaResource } from "./resources/vega.js";
 /**
  * Shared credentials passed to every resource method.
@@ -102,6 +103,8 @@ export declare class KWeaverClient implements ClientContext {
     readonly vega: VegaResource;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
     readonly skills: SkillsResource;
+    /** Toolbox / tool management plus execute & debug invocation. */
+    readonly toolboxes: ToolboxesResource;
     constructor(opts?: KWeaverClientOptions);
     /**
      * Async factory that auto-refreshes expired or revoked tokens.

package/dist/client.js

@@ -12,6 +12,7 @@ import { DataViewsResource } from "./resources/dataviews.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
+import { ToolboxesResource } from "./resources/toolboxes.js";
 import { VegaResource } from "./resources/vega.js";
 // ── KWeaverClient ─────────────────────────────────────────────────────────────
 /**
@@ -64,6 +65,8 @@ export class KWeaverClient {
     vega;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
     skills;
+    /** Toolbox / tool management plus execute & debug invocation. */
+    toolboxes;
     constructor(opts = {}) {
         const envDomain = process.env.KWEAVER_BUSINESS_DOMAIN;
         if (opts.auth === false && opts.config) {
@@ -97,6 +100,7 @@ export class KWeaverClient {
             this.dataviews = new DataViewsResource(this);
             this.vega = new VegaResource(this);
             this.skills = new SkillsResource(this);
+            this.toolboxes = new ToolboxesResource(this);
             return;
         }
         if (opts.config) {
@@ -151,6 +155,7 @@ export class KWeaverClient {
         this.dataviews = new DataViewsResource(this);
         this.vega = new VegaResource(this);
         this.skills = new SkillsResource(this);
+        this.toolboxes = new ToolboxesResource(this);
     }
     /**
      * Async factory that auto-refreshes expired or revoked tokens.

package/dist/commands/bkn-schema.d.ts

@@ -95,6 +95,33 @@ export interface KnActionTypeExecuteOptions {
     timeout: number;
 }
 export declare function parseKnActionTypeExecuteArgs(args: string[]): KnActionTypeExecuteOptions;
+/**
+ * Assemble the action-type execute envelope from CLI flags. Each flag is
+ * parsed as JSON; instance entries must be JSON objects; dynamic_params must
+ * be a JSON object. The shape produced is the contract documented in
+ * skills/kweaver-core/references/bkn.md.
+ */
+export declare function buildExecuteEnvelope(opts: {
+    triggerType: string;
+    dynamicParamsJson?: string;
+    instanceJsons: string[];
+}): string;
+export interface InputParameterSummary {
+    name: string;
+    type?: string;
+    source?: string;
+    required?: boolean;
+    description?: string;
+}
+/**
+ * Walk a getActionType response and collect parameters where
+ * `value_from === "input"`. The exact response shape varies (sometimes the
+ * action-type is at the root, sometimes nested under data/result/...), so we
+ * search a few likely locations.
+ */
+export declare function extractInputParameters(rawJson: string): InputParameterSummary[];
+export declare function buildDynamicParamsTemplate(inputs: InputParameterSummary[]): Record<string, unknown>;
+export declare function renderInputsTable(atId: string, inputs: InputParameterSummary[]): string;
 /** Parse relation-type create args: --name --source --target [--mapping src:tgt ...] */
 export declare function parseRelationTypeCreateArgs(args: string[]): {
     knId: string;

package/dist/commands/bkn-schema.js

@@ -562,6 +562,9 @@ export function parseKnActionTypeExecuteArgs(args) {
     let businessDomain = "";
     let wait = true;
     let timeout = 300;
+    let dynamicParamsJson;
+    let triggerType;
+    const instanceJsons = [];
     const positional = [];
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -592,11 +595,41 @@ export function parseKnActionTypeExecuteArgs(args) {
             i += 1;
             continue;
         }
+        if (arg === "--dynamic-params" && args[i + 1]) {
+            dynamicParamsJson = args[++i];
+            continue;
+        }
+        if (arg === "--instance" && args[i + 1]) {
+            instanceJsons.push(args[++i]);
+            continue;
+        }
+        if (arg === "--trigger-type" && args[i + 1]) {
+            triggerType = args[++i];
+            continue;
+        }
         positional.push(arg);
     }
-    const [knId, atId, body] = positional;
-    if (!knId || !atId || !body) {
-        throw new Error("Missing kn-id, at-id, or body. Usage: kweaver bkn action-type execute <kn-id> <at-id> '<json>' [options]");
+    const usingFlags = dynamicParamsJson !== undefined || instanceJsons.length > 0 || triggerType !== undefined;
+    const [knId, atId, positionalBody] = positional;
+    if (!knId || !atId) {
+        throw new Error("Missing kn-id or at-id. Usage: kweaver bkn action-type execute <kn-id> <at-id> [<json>|--dynamic-params '<json>' --instance '<json>'] [options]");
+    }
+    if (positionalBody && usingFlags) {
+        throw new Error("Positional body and --dynamic-params/--instance/--trigger-type are mutually exclusive. Use one form.");
+    }
+    if (!positionalBody && !usingFlags) {
+        throw new Error("Missing body. Provide a positional JSON envelope, or use --dynamic-params / --instance / --trigger-type.");
+    }
+    let body;
+    if (positionalBody) {
+        body = positionalBody;
+    }
+    else {
+        body = buildExecuteEnvelope({
+            triggerType: triggerType ?? "manual",
+            dynamicParamsJson,
+            instanceJsons,
+        });
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
@@ -610,6 +643,143 @@ export function parseKnActionTypeExecuteArgs(args) {
         timeout,
     };
 }
+/**
+ * Assemble the action-type execute envelope from CLI flags. Each flag is
+ * parsed as JSON; instance entries must be JSON objects; dynamic_params must
+ * be a JSON object. The shape produced is the contract documented in
+ * skills/kweaver-core/references/bkn.md.
+ */
+export function buildExecuteEnvelope(opts) {
+    const envelope = {
+        trigger_type: opts.triggerType,
+        _instance_identities: opts.instanceJsons.map((s, idx) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(s);
+            }
+            catch (e) {
+                throw new Error(`--instance #${idx + 1} is not valid JSON: ${e.message}`);
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`--instance #${idx + 1} must be a JSON object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+            }
+            return parsed;
+        }),
+    };
+    if (opts.dynamicParamsJson !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(opts.dynamicParamsJson);
+        }
+        catch (e) {
+            throw new Error(`--dynamic-params is not valid JSON: ${e.message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`--dynamic-params must be a JSON object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+        }
+        envelope.dynamic_params = parsed;
+    }
+    else {
+        envelope.dynamic_params = {};
+    }
+    return JSON.stringify(envelope);
+}
+/**
+ * Walk a getActionType response and collect parameters where
+ * `value_from === "input"`. The exact response shape varies (sometimes the
+ * action-type is at the root, sometimes nested under data/result/...), so we
+ * search a few likely locations.
+ */
+export function extractInputParameters(rawJson) {
+    let root;
+    try {
+        root = JSON.parse(rawJson);
+    }
+    catch {
+        return [];
+    }
+    const candidates = collectParameterArrays(root);
+    const seen = new Set();
+    const out = [];
+    for (const params of candidates) {
+        for (const p of params) {
+            if (!p || typeof p !== "object")
+                continue;
+            const obj = p;
+            if (obj.value_from !== "input")
+                continue;
+            const name = typeof obj.name === "string" ? obj.name : "";
+            if (!name || seen.has(name))
+                continue;
+            seen.add(name);
+            out.push({
+                name,
+                type: typeof obj.type === "string" ? obj.type : undefined,
+                source: typeof obj.source === "string" ? obj.source : undefined,
+                required: typeof obj.required === "boolean" ? obj.required : undefined,
+                description: typeof obj.description === "string" ? obj.description : undefined,
+            });
+        }
+    }
+    return out;
+}
+function collectParameterArrays(node, acc = []) {
+    if (!node)
+        return acc;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectParameterArrays(item, acc);
+        return acc;
+    }
+    if (typeof node !== "object")
+        return acc;
+    const obj = node;
+    if (Array.isArray(obj.parameters))
+        acc.push(obj.parameters);
+    for (const v of Object.values(obj))
+        collectParameterArrays(v, acc);
+    return acc;
+}
+export function buildDynamicParamsTemplate(inputs) {
+    const tpl = {};
+    for (const p of inputs) {
+        tpl[p.name] = placeholderForType(p);
+    }
+    return tpl;
+}
+function placeholderForType(p) {
+    const hint = p.description ? ` (${p.description})` : "";
+    const t = (p.type ?? "").toLowerCase();
+    if (t === "int" || t === "integer" || t === "long" || t === "number" || t === "float" || t === "double")
+        return 0;
+    if (t === "bool" || t === "boolean")
+        return false;
+    if (t === "array" || t === "list")
+        return [];
+    if (t === "object" || t === "dict" || t === "map")
+        return {};
+    return `<${p.type ?? "string"}${p.required === false ? "?" : ""}>${hint}`;
+}
+export function renderInputsTable(atId, inputs) {
+    if (inputs.length === 0) {
+        return `Action type ${atId} has no parameters with value_from=input. dynamic_params can be {}.`;
+    }
+    const rows = inputs.map(p => [
+        p.name,
+        p.type ?? "-",
+        p.source ?? "-",
+        p.required === undefined ? "-" : p.required ? "yes" : "no",
+        truncate(p.description ?? "", 60),
+    ]);
+    const header = ["NAME", "TYPE", "SOURCE", "REQUIRED", "DESCRIPTION"];
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => r[i].length)));
+    const fmt = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ");
+    const lines = [fmt(header), fmt(widths.map(w => "-".repeat(w))), ...rows.map(fmt)];
+    return `Action type ${atId} input parameters (value_from=input):\n${lines.join("\n")}`;
+}
+function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
 // ── Action-type execute helpers ────────────────────────────────────────────────
 const TERMINAL_STATUSES = ["SUCCESS", "FAILED", "CANCELLED"];
 function extractExecutionId(body) {
@@ -1123,17 +1293,30 @@ kweaver bkn action-type create <kn-id> '<json>' [--pretty] [-bd value]
 kweaver bkn action-type update <kn-id> <at-id> '<json>' [--pretty] [-bd value]
 kweaver bkn action-type delete <kn-id> <at-ids> [-y] [--pretty] [-bd value]
 kweaver bkn action-type query <kn-id> <at-id> '<json>' [--pretty] [-bd value]
-kweaver bkn action-type execute <kn-id> <at-id> '<json>' [--pretty] [-bd value] [--wait|--no-wait] [--timeout n]
+kweaver bkn action-type inputs <kn-id> <at-id> [--json|--template] [-bd value]
+kweaver bkn action-type execute <kn-id> <at-id> [<json>|--dynamic-params '<json>' --instance '<json>' --trigger-type <v>] [--pretty] [-bd value] [--wait|--no-wait] [--timeout n]
 
 list: List action types (schema) from ontology-manager.
 get: Get a single action type by ID.
 create: Create action type(s) (POST JSON body).
 update: Update an action type (PUT JSON body).
 delete: Delete action type(s) by ID(s).
-query/execute: Query or execute actions. execute has side effects - only use when explicitly requested.
+query: Query actions backing this action type.
+inputs: List parameters with value_from=input that the caller MUST supply.
+        Default prints a table + a starter dynamic_params template.
+        --json     dump filtered parameters as raw JSON
+        --template print only the dynamic_params template object
+execute: Run an action (has side effects - only use when explicitly requested).
+  Body forms (mutually exclusive):
+    1. Positional envelope JSON: '{"trigger_type":"manual","_instance_identities":[],"dynamic_params":{...}}'
+    2. Flag form (CLI assembles the envelope):
+         --dynamic-params '<json object>'   parameters with value_from=input
+         --instance '<json object>'         repeatable; one per identity
+         --trigger-type <value>             defaults to "manual"
   --wait (default)    Poll until execution completes
   --no-wait           Return immediately after starting execution
-  --timeout <seconds> Max wait time when --wait (default: 300)`);
+  --timeout <seconds> Max wait time when --wait (default: 300)
+See skills/kweaver-core/references/bkn.md for the full payload contract.`);
         return 0;
     }
     if (action === "list") {
@@ -1283,6 +1466,48 @@ query/execute: Query or execute actions. execute has side effects - only use whe
             return 1;
         }
     }
+    if (action === "inputs") {
+        const parsed = parseOntologyQueryFlags(rest);
+        const flags = new Set(parsed.filteredArgs.filter(a => a.startsWith("--")));
+        const positional = parsed.filteredArgs.filter(a => !a.startsWith("--"));
+        const [knId, atId] = positional;
+        if (!knId || !atId) {
+            console.error("Usage: kweaver bkn action-type inputs <kn-id> <at-id> [--json|--template]");
+            return 1;
+        }
+        if (flags.has("--json") && flags.has("--template")) {
+            console.error("--json and --template are mutually exclusive.");
+            return 1;
+        }
+        try {
+            const token = await ensureValidToken();
+            const raw = await getActionType({
+                baseUrl: token.baseUrl,
+                accessToken: token.accessToken,
+                knId,
+                atId,
+                businessDomain: parsed.businessDomain,
+            });
+            const inputs = extractInputParameters(raw);
+            if (flags.has("--json")) {
+                console.log(formatCallOutput(JSON.stringify(inputs), parsed.pretty));
+                return 0;
+            }
+            const template = buildDynamicParamsTemplate(inputs);
+            if (flags.has("--template")) {
+                console.log(JSON.stringify(template, null, 2));
+                return 0;
+            }
+            console.log(renderInputsTable(atId, inputs));
+            console.log("\n# Starter dynamic_params (fill in real values, then pass via --dynamic-params):");
+            console.log(JSON.stringify(template, null, 2));
+            return 0;
+        }
+        catch (error) {
+            console.error(formatHttpError(error));
+            return 1;
+        }
+    }
     if (action === "execute") {
         let options;
         try {
@@ -1349,7 +1574,7 @@ query/execute: Query or execute actions. execute has side effects - only use whe
             return 1;
         }
     }
-    console.error(`Unknown action-type action: ${action}. Use list, get, create, update, delete, query, or execute.`);
+    console.error(`Unknown action-type action: ${action}. Use list, get, create, update, delete, query, inputs, or execute.`);
     return 1;
 }
 export function parseConceptGroupArgs(args) {

package/dist/commands/bkn.js

@@ -393,7 +393,8 @@ Subcommands:
   action-type update <kn-id> <at-id> '<json>'   Update action type
   action-type delete <kn-id> <at-ids> [-y]   Delete action type(s)
   action-type query <kn-id> <at-id> '<json>'   Query action info
-  action-type execute <kn-id> <at-id> '<json>'   Execute action (has side effects)
+  action-type inputs <kn-id> <at-id>   List value_from=input params + dynamic_params template
+  action-type execute <kn-id> <at-id> '<envelope-json>' | --dynamic-params '<json>' [--instance '<json>']... [--trigger-type <v>]   Execute action (has side effects)
   action-execution get <kn-id> <execution-id>   Get execution status
   action-log list <kn-id> [options]   List action execution logs
   action-log get <kn-id> <log-id>   Get single execution log

package/dist/commands/tool.d.ts

@@ -14,3 +14,15 @@ export interface ToolStatusOptions {
     businessDomain: string;
 }
 export declare function parseToolStatusArgs(args: string[], status: "enabled" | "disabled"): ToolStatusOptions;
+export interface ToolInvokeOptions {
+    boxId: string;
+    toolId: string;
+    header?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    bodyFile?: string;
+    timeout?: number;
+    businessDomain: string;
+    pretty: boolean;
+}
+export declare function parseToolInvokeArgs(args: string[]): ToolInvokeOptions;

package/dist/commands/tool.js

@@ -1,18 +1,29 @@
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { listTools, setToolStatuses, uploadTool } from "../api/toolboxes.js";
+import { debugTool, executeTool, listTools, setToolStatuses, uploadTool } from "../api/toolboxes.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 const HELP = `kweaver tool
 
 Subcommands:
   upload --toolbox <box-id> <openapi-spec-path> [--metadata-type openapi]
-                                          Upload an OpenAPI spec file as a tool
-  list --toolbox <box-id>                  List tools in a toolbox
-  enable --toolbox <box-id> <tool-id>...   Enable one or more tools
-  disable --toolbox <box-id> <tool-id>...  Disable one or more tools
+                                              Upload an OpenAPI spec file as a tool
+  list --toolbox <box-id>                      List tools in a toolbox
+  enable --toolbox <box-id> <tool-id>...       Enable one or more tools
+  disable --toolbox <box-id> <tool-id>...      Disable one or more tools
+  execute --toolbox <box-id> <tool-id> [--body '<json>'|--body-file <path>]
+                                              Invoke a published+enabled tool
+  debug   --toolbox <box-id> <tool-id> [--body '<json>'|--body-file <path>]
+                                              Invoke a tool (works on draft/disabled too)
 
-Options:
+Options for execute/debug:
+  --header '<json>'       Headers map forwarded to the downstream tool
+                          (Authorization is auto-injected from current session
+                          when --header omits it; pass {} to send none)
+  --query  '<json>'       Query params map forwarded to the downstream tool
+  --timeout <seconds>     Per-call timeout (backend default applies when omitted)
+
+Common options:
   -bd, --biz-domain <s>   Business domain (default: bd_public)
   --pretty                Pretty-print JSON (default)
   --compact               Single-line JSON (pipeline-friendly)`;
@@ -31,6 +42,10 @@ export async function runToolCommand(args) {
             return runToolStatus(rest, "enabled");
         if (subcommand === "disable")
             return runToolStatus(rest, "disabled");
+        if (subcommand === "execute")
+            return runToolInvoke(rest, "execute");
+        if (subcommand === "debug")
+            return runToolInvoke(rest, "debug");
         return Promise.resolve(-1);
     };
     try {
@@ -206,3 +221,158 @@ async function runToolStatus(args, status) {
     console.error(`${status === "enabled" ? "Enabled" : "Disabled"} ${opts.toolIds.length} tool(s) in toolbox ${opts.boxId}`);
     return 0;
 }
+function parseJsonOption(name, raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${name} must be valid JSON: ${e.message}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${name} must be a JSON object`);
+    }
+    return value;
+}
+export function parseToolInvokeArgs(args) {
+    let boxId = "";
+    let toolId = "";
+    let businessDomain = "";
+    let pretty = true;
+    let header;
+    let query;
+    let body;
+    let bodyProvided = false;
+    let bodyFile;
+    let timeout;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--toolbox" && args[i + 1]) {
+            boxId = args[++i];
+            continue;
+        }
+        if (a === "--header" && args[i + 1]) {
+            header = parseJsonOption("--header", args[++i]);
+            continue;
+        }
+        if (a === "--query" && args[i + 1]) {
+            query = parseJsonOption("--query", args[++i]);
+            continue;
+        }
+        if (a === "--body" && args[i + 1]) {
+            const raw = args[++i];
+            try {
+                body = JSON.parse(raw);
+            }
+            catch (e) {
+                throw new Error(`--body must be valid JSON: ${e.message}`);
+            }
+            bodyProvided = true;
+            continue;
+        }
+        if (a === "--body-file" && args[i + 1]) {
+            bodyFile = args[++i];
+            bodyProvided = true;
+            continue;
+        }
+        if (a === "--timeout" && args[i + 1]) {
+            const t = Number(args[++i]);
+            if (!Number.isFinite(t) || t <= 0)
+                throw new Error("--timeout must be a positive number");
+            timeout = t;
+            continue;
+        }
+        if ((a === "-bd" || a === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[++i];
+            continue;
+        }
+        if (a === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (a === "--compact") {
+            pretty = false;
+            continue;
+        }
+        if (!a.startsWith("-") && !toolId) {
+            toolId = a;
+            continue;
+        }
+    }
+    if (!boxId)
+        throw new Error("Missing required flag: --toolbox");
+    if (!toolId)
+        throw new Error("Missing required positional argument: <tool-id>");
+    if (bodyFile && body !== undefined)
+        throw new Error("--body and --body-file are mutually exclusive");
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return {
+        boxId,
+        toolId,
+        header,
+        query,
+        body: bodyProvided ? body : undefined,
+        bodyFile,
+        timeout,
+        businessDomain,
+        pretty,
+    };
+}
+async function loadBodyFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (e) {
+        throw new Error(`Cannot read --body-file ${path}: ${e.message}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`--body-file ${path} is not valid JSON: ${e.message}`);
+    }
+}
+async function runToolInvoke(args, action) {
+    let opts;
+    try {
+        opts = parseToolInvokeArgs(args);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    let body = opts.body;
+    if (opts.bodyFile !== undefined) {
+        try {
+            body = await loadBodyFile(opts.bodyFile);
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            return 1;
+        }
+    }
+    const token = await ensureValidToken();
+    // Auto-inject Authorization unless caller already provided one — most tools
+    // declare an `Authorization` header parameter and would otherwise be called
+    // anonymously, which the downstream tool answers with 401 token expired.
+    const header = { ...(opts.header ?? {}) };
+    const hasAuth = Object.keys(header).some((k) => k.toLowerCase() === "authorization");
+    if (!hasAuth)
+        header.Authorization = `Bearer ${token.accessToken}`;
+    const fn = action === "execute" ? executeTool : debugTool;
+    const responseBody = await fn({
+        baseUrl: token.baseUrl,
+        accessToken: token.accessToken,
+        businessDomain: opts.businessDomain,
+        boxId: opts.boxId,
+        toolId: opts.toolId,
+        header,
+        query: opts.query,
+        body,
+        timeout: opts.timeout,
+    });
+    console.log(formatCallOutput(responseBody, opts.pretty));
+    return 0;
+}

package/dist/index.d.ts

@@ -50,6 +50,8 @@ export { BknResource } from "./resources/bkn.js";
 export { ConversationsResource } from "./resources/conversations.js";
 export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
+export { ToolboxesResource } from "./resources/toolboxes.js";
+export type { InvokeToolArgs } from "./resources/toolboxes.js";
 export type { SkillStatus, SkillSummary, SkillInfo, SkillFileSummary, SkillContentIndex, SkillFileReadResult, RegisterSkillResult, DeleteSkillResult, UpdateSkillStatusResult, SkillListResult, ListSkillsOptions, ListSkillMarketOptions, GetSkillOptions, RegisterSkillContentOptions, RegisterSkillZipOptions, UpdateSkillStatusOptions, ReadSkillFileOptions, DownloadSkillOptions, DownloadedSkillArchive, } from "./api/skills.js";
 export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
 export type { ViewField, DataView, CreateDataViewOptions, GetDataViewOptions, ListDataViewsOptions, DeleteDataViewOptions, FindDataViewOptions, QueryDataViewOptions, DataViewQueryResult, } from "./api/dataviews.js";
@@ -57,6 +59,8 @@ export { parseDataView, createDataView, getDataView, listDataViews, deleteDataVi
 export { DataViewsResource } from "./resources/dataviews.js";
 export type { BusinessDomain, ListBusinessDomainsOptions } from "./api/business-domains.js";
 export { listBusinessDomains } from "./api/business-domains.js";
+export type { CreateToolboxOptions, DeleteToolboxOptions, SetToolboxStatusOptions, UploadToolOptions, SetToolStatusesOptions, ListToolboxesOptions, ListToolsOptions, InvokeToolOptions, } from "./api/toolboxes.js";
+export { createToolbox, deleteToolbox, setToolboxStatus, uploadTool, setToolStatuses, listToolboxes, listTools, executeTool, debugTool, } from "./api/toolboxes.js";
 export { HttpError, NetworkRequestError, fetchTextOrThrow } from "./utils/http.js";
 export type { TokenConfig, ContextLoaderEntry, ContextLoaderConfig, } from "./config/store.js";
 export type { UserProfile } from "./config/store.js";

package/dist/index.js

@@ -40,10 +40,12 @@ export { BknResource } from "./resources/bkn.js";
 export { ConversationsResource } from "./resources/conversations.js";
 export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
+export { ToolboxesResource } from "./resources/toolboxes.js";
 export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
 export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
 export { DataViewsResource } from "./resources/dataviews.js";
 export { listBusinessDomains } from "./api/business-domains.js";
+export { createToolbox, deleteToolbox, setToolboxStatus, uploadTool, setToolStatuses, listToolboxes, listTools, executeTool, debugTool, } from "./api/toolboxes.js";
 // ── HTTP utilities ────────────────────────────────────────────────────────────
 export { HttpError, NetworkRequestError, fetchTextOrThrow } from "./utils/http.js";
 export { NO_AUTH_TOKEN, isNoAuth, saveNoAuthPlatform, autoSelectBusinessDomain, getConfigDir, getCurrentPlatform, getActiveUser, setActiveUser, listUsers, listUserProfiles, resolveUserId, extractUserId, } from "./config/store.js";

package/dist/resources/agents.js

@@ -11,11 +11,25 @@ export class AgentsResource {
         const { keyword, ...rest } = opts;
         const raw = await listAgents({ ...this.ctx.base(), name: keyword, ...rest });
         const parsed = JSON.parse(raw);
-        const items = parsed && typeof parsed === "object" && "data" in parsed
-            ? parsed.data?.records ?? []
-            : Array.isArray(parsed)
-                ? parsed
-                : [];
+        const items = (() => {
+            if (Array.isArray(parsed))
+                return parsed;
+            if (!parsed || typeof parsed !== "object")
+                return [];
+            const obj = parsed;
+            if (Array.isArray(obj.entries))
+                return obj.entries;
+            if (Array.isArray(obj.data))
+                return obj.data;
+            if (obj.data && typeof obj.data === "object") {
+                const dataObj = obj.data;
+                if (Array.isArray(dataObj.records))
+                    return dataObj.records;
+                if (Array.isArray(dataObj.entries))
+                    return dataObj.entries;
+            }
+            return [];
+        })();
         return items;
     }
     // ── Get by ID ────────────────────────────────────────────────────────────

package/dist/resources/toolboxes.d.ts

@@ -0,0 +1,39 @@
+import type { ClientContext } from "../client.js";
+export interface InvokeToolArgs {
+    /** Optional headers to forward to the downstream tool. Authorization is
+     *  auto-injected from the client's access token when omitted; pass `{}` to
+     *  send no headers. */
+    header?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** Per-call timeout in seconds (backend default applies when omitted). */
+    timeout?: number;
+}
+/** Toolbox / tool management on the agent-operator-integration service. */
+export declare class ToolboxesResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(opts?: {
+        keyword?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<string>;
+    listToolsIn(boxId: string): Promise<string>;
+    uploadTool(opts: {
+        boxId: string;
+        filePath: string;
+        metadataType?: "openapi";
+    }): Promise<string>;
+    setToolStatuses(opts: {
+        boxId: string;
+        updates: Array<{
+            toolId: string;
+            status: "enabled" | "disabled";
+        }>;
+    }): Promise<void>;
+    /** Execute a published+enabled tool through the toolbox proxy. */
+    execute(boxId: string, toolId: string, args?: InvokeToolArgs): Promise<string>;
+    /** Debug a tool through the toolbox proxy (works on draft/disabled tools too). */
+    debug(boxId: string, toolId: string, args?: InvokeToolArgs): Promise<string>;
+    private injectAuth;
+}

package/dist/resources/toolboxes.js

@@ -0,0 +1,54 @@
+import { debugTool, executeTool, listTools, listToolboxes, setToolStatuses, uploadTool, } from "../api/toolboxes.js";
+/** Toolbox / tool management on the agent-operator-integration service. */
+export class ToolboxesResource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async list(opts = {}) {
+        return listToolboxes({ ...this.ctx.base(), ...opts });
+    }
+    async listToolsIn(boxId) {
+        return listTools({ ...this.ctx.base(), boxId });
+    }
+    async uploadTool(opts) {
+        return uploadTool({
+            ...this.ctx.base(),
+            boxId: opts.boxId,
+            filePath: opts.filePath,
+            metadataType: opts.metadataType,
+        });
+    }
+    async setToolStatuses(opts) {
+        await setToolStatuses({ ...this.ctx.base(), ...opts });
+    }
+    /** Execute a published+enabled tool through the toolbox proxy. */
+    async execute(boxId, toolId, args = {}) {
+        return executeTool({
+            ...this.ctx.base(),
+            boxId,
+            toolId,
+            ...this.injectAuth(args),
+        });
+    }
+    /** Debug a tool through the toolbox proxy (works on draft/disabled tools too). */
+    async debug(boxId, toolId, args = {}) {
+        return debugTool({
+            ...this.ctx.base(),
+            boxId,
+            toolId,
+            ...this.injectAuth(args),
+        });
+    }
+    // The forwarder requires every header the downstream tool expects to be set
+    // explicitly under `header`; most published tools declare an Authorization
+    // parameter and would otherwise see no token. Auto-inject the active
+    // session token unless the caller already provided one.
+    injectAuth(args) {
+        const header = { ...(args.header ?? {}) };
+        const hasAuth = Object.keys(header).some((k) => k.toLowerCase() === "authorization");
+        if (!hasAuth)
+            header.Authorization = `Bearer ${this.ctx.base().accessToken}`;
+        return { ...args, header };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",