rainskills 0.1.45 → 0.1.46

package/SKILL.md

@@ -56,7 +56,7 @@ Hermes Agent 中必须使用 `terminal` 以 `background=true` 启动授权命令
 
 DeepSeek Harness 和 WorkBuddy 也必须保持原命令附着直到退出；如果宿主把长命令转成持久终端或后台任务，只能轮询该原始命令句柄，不得另起 `runtime status` 推测授权结果。WorkBuddy 安装后若当前任务的 Skill 清单尚未刷新，在下一条业务动作前先刷新 Skill 列表或新建任务，不得退回内置 Sites 代替 Rainbond 部署。
 
-Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.45`）：
+Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.46`）：
 
 - 状态：执行 `runtime status --json`。
 - 首次连接：执行 `runtime connect <target> --saas` 或 `runtime connect <target> --rainbond-url <Console origin>`。

package/bin/bridge-errors.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const EXIT = Object.freeze({ USAGE: 2, CONFIG: 3, TRANSPORT: 4, TOOL: 5 });
+class BridgeError extends Error {
+  constructor(message, exitCode, payload, code) {
+    super(message);
+    this.exitCode = exitCode;
+    this.payload = payload;
+    this.code = code;
+  }
+}
+function inputValidation(action) {
+  try { return action(); } catch (error) {
+    if (error instanceof BridgeError) throw error;
+    throw new BridgeError("input validation failed; check the command schema", EXIT.USAGE, undefined, "E_INPUT_INVALID");
+  }
+}
+function errorResult(error) {
+  const code = error.code || ({ 2: "E_INPUT_INVALID", 3: "E_CONFIGURATION", 4: "E_TRANSPORT", 5: "E_PLATFORM" })[error.exitCode] || "E_INTERNAL";
+  return {
+    ...(error.payload || { error: error.message }), code,
+    stage: code === "E_RUNTIME_INCOMPLETE" ? "local" : error.exitCode === EXIT.USAGE ? "input" : error.exitCode === EXIT.CONFIG ? "configuration" : "request",
+    next_action: code === "E_RUNTIME_INCOMPLETE" ? "repair_runtime" : error.exitCode === EXIT.USAGE ? "correct_input" : code === "E_WRITE_RESULT_UNKNOWN" ? "query_state" : "inspect_error",
+  };
+}
+module.exports = { BridgeError, EXIT, inputValidation, errorResult };

package/bin/component-recipe.js

@@ -0,0 +1,66 @@
+"use strict";
+const { BridgeError, EXIT } = require("./bridge-errors.js");
+const { validateBatch, executeBatch, projectResult } = require("./confirmed-batch.js");
+const CREATE_TOOLS = Object.freeze({ image: "rainbond_create_component_from_image", source: "rainbond_create_component_from_source", package: "rainbond_create_component_from_package" });
+const PLACEHOLDER = "0".repeat(32);
+function invalid(message = "invalid component recipe; use the component-recipe schema") { throw new BridgeError(message, EXIT.USAGE); }
+function prepareRecipe(input) {
+  if (!input || input.schema !== "rainskills.component-recipe.v1.request" || Buffer.byteLength(JSON.stringify(input)) > 128 * 1024) invalid();
+  if (Object.keys(input).some((key) => !["schema", "scope", "enterprise_id", "kind", "create", "configure", "stateful", "storage"].includes(key))) invalid();
+  if (!Object.hasOwn(CREATE_TOOLS, input.kind) || typeof input.enterprise_id !== "string" || !input.enterprise_id) invalid();
+  if (!input.create || Array.isArray(input.create) || typeof input.create.service_cname !== "string" || !input.create.service_cname) invalid();
+  if (input.create.is_deploy !== undefined && input.create.is_deploy !== false) invalid("creation recipes configure before deployment");
+  if (input.stateful !== undefined && typeof input.stateful !== "boolean") invalid();
+  if (input.stateful && (!input.storage || !input.storage.volume_path || !input.storage.volume_name || !input.storage.volume_type)) invalid("stateful providers require explicit persistent storage before deployment");
+  if (input.kind === "image" && !input.create.image) invalid();
+  if (input.kind === "source" && (!input.create.git_url || !input.create.code_from)) invalid();
+  if (input.kind === "package" && !input.create.event_id) invalid();
+  const configuration = input.configure || [];
+  if (!Array.isArray(configuration) || configuration.length > 32 || configuration.some((s) => !s || typeof s !== "object" || Array.isArray(s) || !s.arguments || typeof s.arguments !== "object" || Array.isArray(s.arguments) || Object.hasOwn(s.arguments, "service_id"))) invalid();
+  const steps = configuration.map((step) => ({ ...step, arguments: { ...step.arguments, service_id: PLACEHOLDER } }));
+  // Reuse the same scope and configuration policy even for an empty recipe.
+  validateBatch({ schema: "rainskills.confirmed-batch.v1.request", scope: input.scope, steps: steps.length ? steps : [{ key: "scope-validation", tool: "rainbond_manage_component_ports", arguments: { service_id: PLACEHOLDER, operation: "add", port: 80, protocol: "http" } }] });
+  for (const [key, value] of Object.entries(input.scope)) if (Object.hasOwn(input.create, key) && input.create[key] !== value) invalid();
+  if (input.storage && Object.keys(input.storage).some((key) => ["service_id", "team_name", "region_name", "app_id", "operation"].includes(key))) invalid();
+  return { tool: CREATE_TOOLS[input.kind], arguments: { ...input.create, ...input.scope, is_deploy: false }, steps };
+}
+async function preflightRecipe(input, { validate, read }) {
+  const plan = prepareRecipe(input);
+  await validate(plan.tool, plan.arguments);
+  for (const step of plan.steps) await validate(step.tool, { ...step.arguments, ...input.scope });
+  if (input.storage) await validate("rainbond_manage_component_storage", { ...input.storage, ...input.scope, service_id: PLACEHOLDER, operation: "create_volume" });
+  const query = { enterprise_id: input.enterprise_id, app_id: input.scope.app_id, query: input.create.service_cname, page: 1, page_size: 20 };
+  await validate("rainbond_query_components", query);
+  const observed = await read("rainbond_query_components", query);
+  const items = observed?.list || observed?.items;
+  if (!Array.isArray(items) || (typeof observed.total === "number" && observed.total > items.length)) invalid("component lookup is incomplete; resolve the exact existing topology first");
+  if (items.some((item) => item.service_cname === input.create.service_cname || item.service_alias === input.create.service_cname)) invalid("component already exists; adopt its verified service_id instead of creating again");
+  if (input.kind === "package") {
+    const args = { team_name: input.scope.team_name, region_name: input.scope.region_name, event_id: input.create.event_id };
+    await validate("rainbond_get_package_upload_status", args);
+    const status = await read("rainbond_get_package_upload_status", args);
+    if (!Array.isArray(status?.uploaded_packages) || !status.uploaded_packages.length) invalid("package upload is empty; complete the protected upload and local cleanup before creation");
+  }
+  return plan;
+}
+async function executeRecipe(input, adapters) {
+  const plan = await preflightRecipe(input, adapters);
+  if (adapters.signal?.aborted) throw new BridgeError("recipe cancelled", EXIT.USAGE, undefined, "E_CANCELLED");
+  const created = await adapters.call(plan.tool, plan.arguments);
+  const serviceId = created?.service_id || created?.component?.service_id || created?.service?.service_id;
+  if (typeof serviceId !== "string" || !serviceId || serviceId.length > 128) throw new BridgeError("creation result lacks a verified service_id; query the exact target before continuing", EXIT.TRANSPORT, undefined, "E_WRITE_RESULT_UNKNOWN");
+  const identity = { service_id: serviceId, ...projectResult(created) };
+  delete identity.status;
+  if (adapters.onCreated) await adapters.onCreated(identity);
+  if (adapters.signal?.aborted) return { schema: "rainskills.component-recipe.v1.result", ...identity, status: "partial", blocker: { code: "E_CANCELLED" }, next_action: "query_state" };
+  if (input.storage) {
+    try { await adapters.call("rainbond_manage_component_storage", { ...input.storage, ...input.scope, service_id: serviceId, operation: "create_volume" }); }
+    catch (error) {
+      return { schema: "rainskills.component-recipe.v1.result", status: error.exitCode === EXIT.TRANSPORT ? "unknown" : "partial", ...identity, blocker: { code: error.exitCode === EXIT.TRANSPORT ? "E_WRITE_RESULT_UNKNOWN" : "E_PLATFORM" }, next_action: "query_state" };
+    }
+  }
+  let configured = { status: "succeeded", completed: 0, steps: [], blocker: null };
+  if (plan.steps.length) configured = await executeBatch({ schema: "rainskills.confirmed-batch.v1.request", scope: input.scope, steps: plan.steps.map((step) => ({ ...step, arguments: { ...step.arguments, service_id: serviceId } })) }, adapters);
+  return { schema: "rainskills.component-recipe.v1.result", ...identity, status: configured.status === "failed" ? "partial" : configured.status, configured: configured.completed, steps: configured.steps, blocker: configured.blocker, next_action: configured.status === "succeeded" ? "deploy_and_verify" : "query_state" };
+}
+module.exports = { prepareRecipe, preflightRecipe, executeRecipe };

package/bin/confirmed-batch.js

@@ -0,0 +1,120 @@
+"use strict";
+
+const { BridgeError, EXIT } = require("./bridge-errors.js");
+const SCHEMA = "rainskills.confirmed-batch.v1.request";
+const CONFIG_OPERATIONS = Object.freeze({
+  rainbond_manage_component_envs: ["upsert"],
+  rainbond_manage_component_ports: ["add", "enable_inner", "enable_outer", "disable_outer", "update_protocol", "update_alias"],
+  rainbond_manage_component_connection_envs: ["create", "update"],
+  rainbond_manage_component_dependency: ["add"],
+});
+const plain = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const validString = (v) => typeof v === "string" && v.length > 0 && v.length <= 128 && !/[\u0000-\u001f\u007f]/u.test(v);
+function invalid() { throw new BridgeError("invalid batch; use the confirmed-batch schema and one verified app scope", EXIT.USAGE); }
+function keys(value, allowed) { if (!plain(value) || Object.keys(value).some((key) => !allowed.includes(key))) invalid(); }
+function validateBatch(input) {
+  if (Buffer.byteLength(JSON.stringify(input) || "") > 128 * 1024) invalid();
+  keys(input, ["schema", "scope", "steps"]);
+  if (input.schema !== SCHEMA) invalid();
+  keys(input.scope, ["team_name", "region_name", "app_id"]);
+  const scope = input.scope;
+  if (!validString(scope.team_name) || !validString(scope.region_name) || !Number.isInteger(scope.app_id) || scope.app_id < 1) invalid();
+  if (!Array.isArray(input.steps) || input.steps.length < 1 || input.steps.length > 32) invalid();
+  const names = new Set();
+  return input.steps.map((step) => {
+    keys(step, ["key", "tool", "arguments"]);
+    if (!validString(step.key) || Buffer.byteLength(step.key) > 64 || names.has(step.key) || !plain(step.arguments)) invalid();
+    names.add(step.key);
+    if (!Object.hasOwn(CONFIG_OPERATIONS, step.tool) || !CONFIG_OPERATIONS[step.tool].includes(step.arguments.operation)) invalid();
+    if (!validString(step.arguments.service_id)) invalid();
+    for (const [key, value] of Object.entries(scope)) {
+      if (Object.hasOwn(step.arguments, key) && step.arguments[key] !== value) invalid();
+    }
+    return { key: step.key, tool: step.tool, arguments: { ...step.arguments, ...scope } };
+  });
+}
+function projectResult(value) {
+  const output = {};
+  for (const key of ["service_id", "event_id", "app_id", "created", "updated", "status"]) {
+    if (["string", "boolean", "number"].includes(typeof value?.[key])) output[key] = typeof value[key] === "string" ? value[key].slice(0, 128) : value[key];
+  }
+  return output;
+}
+function boundedResult(output) {
+  if (Buffer.byteLength(JSON.stringify(output)) <= 8192) return output;
+  return { ...output, details_omitted: true, steps: output.steps.map(({ key, status }) => ({ key, status })) };
+}
+function configurationSatisfied(tool, args, snapshot) {
+  if (!snapshot || typeof snapshot !== "object") return false;
+  if (tool === "rainbond_manage_component_ports") {
+    const items = snapshot.ports?.items;
+    if (!Array.isArray(items)) return false;
+    const desired = args.ports || [{ port: args.port, protocol: args.protocol, port_alias: args.port_alias, is_inner_service: args.is_inner_service ?? args.enable_inner }];
+    return desired.length > 0 && desired.every((item) => {
+      const port = typeof item === "number" ? item : item.port;
+      const current = items.find((value) => (value.container_port ?? value.port) === port);
+      if (!current) return false;
+      if (args.operation === "add") {
+        const requested = typeof item === "number" ? {} : { ...item, is_inner_service: item.is_inner_service ?? item.enable_inner };
+        return ["protocol", "port_alias", "is_inner_service", "k8s_service_name"].every((key) => requested[key] === undefined || current[key] === requested[key]);
+      }
+      if (args.operation === "enable_inner") return current.is_inner_service === true;
+      if (args.operation === "enable_outer") return current.is_outer_service === true;
+      if (args.operation === "disable_outer") return current.is_outer_service === false;
+      return args.operation === "update_protocol" ? current.protocol === args.protocol : args.operation === "update_alias" && ["port_alias", "k8s_service_name"].some((key) => args[key] !== undefined) && ["port_alias", "k8s_service_name"].every((key) => args[key] === undefined || current[key] === args[key]);
+    });
+  }
+  if (tool === "rainbond_manage_component_dependency") {
+    if (!Array.isArray(snapshot.dependencies) || args.open_inner) return false;
+    const desired = args.dep_service_ids || [args.dep_service_id];
+    return desired.length > 0 && desired.every((id) => id && snapshot.dependencies.some((value) => (typeof value === "string" ? value : value.service_id) === id));
+  }
+  if (tool === "rainbond_manage_component_envs" && args.operation === "upsert") {
+    const items = snapshot.custom_envs?.items;
+    const desired = args.envs || [{ attr_name: args.attr_name || args.name, attr_value: args.attr_value, is_change: args.is_change }];
+    if (!Array.isArray(items) || !desired.length) return false;
+    return desired.every((env) => items.some((item) => item.attr_name === (env.attr_name || env.name)
+      && item.attr_value !== "[REDACTED]" && item.attr_value === env.attr_value
+      && (env.is_change === undefined || item.is_change === env.is_change)));
+  }
+  if (tool === "rainbond_manage_component_connection_envs") {
+    const items = snapshot.connection_envs?.items;
+    if (!Array.isArray(items) || args.operation !== "create") return false;
+    return items.some((item) => item.attr_name === (args.attr_name || args.name) && item.attr_value !== "[REDACTED]" && item.attr_value === args.attr_value);
+  }
+  return false;
+}
+async function executeBatch(input, { validate, call, signal, isSatisfied = async () => false, onProgress = async () => {} }) {
+  const steps = validateBatch(input);
+  for (const step of steps) await validate(step.tool, step.arguments);
+  const output = { schema: "rainskills.confirmed-batch.v1.result", status: "succeeded", completed: 0, skipped: 0, steps: steps.map(({ key }) => ({ key, status: "not_executed" })), blocker: null };
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index];
+    try {
+      if (signal?.aborted) throw Object.assign(new Error("cancelled"), { code: "E_CANCELLED" });
+      if (await isSatisfied(step)) {
+        output.skipped += 1;
+        output.steps[index] = { key: step.key, status: "skipped" };
+        await onProgress(output);
+        continue;
+      }
+      if (signal?.aborted) throw Object.assign(new Error("cancelled"), { code: "E_CANCELLED" });
+      const value = await call(step.tool, step.arguments);
+      output.steps[index] = { key: step.key, status: "succeeded", ...projectResult(value) };
+      // The batch status describes execution, not a platform-specific status field.
+      output.steps[index].status = "succeeded";
+      output.completed += 1;
+    } catch (error) {
+      const unknown = error.code === "E_WRITE_RESULT_UNKNOWN" || error.exitCode === EXIT.TRANSPORT;
+      output.steps[index] = { key: step.key, status: unknown ? "unknown" : "failed" };
+      output.status = unknown ? "unknown" : output.completed ? "partial" : "failed";
+      const code = unknown ? "E_WRITE_RESULT_UNKNOWN" : ["E_CANCELLED", "E_PLAN_STALE"].includes(error.code) ? error.code : "E_PLATFORM";
+      output.blocker = { key: step.key, code, next_action: unknown ? "query_state" : "inspect_error" };
+      await onProgress(output);
+      return boundedResult(output);
+    }
+    await onProgress(output);
+  }
+  return boundedResult(output);
+}
+module.exports = { validateBatch, executeBatch, projectResult, configurationSatisfied };

package/bin/protected-poll.js

@@ -1,21 +1,12 @@
 "use strict";
 
-const READ_PREFIXES = [
-  "rainbond_query_", "rainbond_get_", "rainbond_list_", "rainbond_check_",
-  "rainbond_describe_", "rainbond_validate_", "rainbond_verify_", "rainbond_search_",
-];
-const DESTRUCTIVE = /(?:delete|remove|purge|destroy|update|create|set|manage|operate|restart|deploy)/i;
+const { classifyTool } = require("./tool-policy.js");
 const STATUS_PATH = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*){0,3}$/;
 
 function plain(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function readOnly(name) {
-  return typeof name === "string"
-    && READ_PREFIXES.some((prefix) => name.startsWith(prefix))
-    && !DESTRUCTIVE.test(name);
-}
 
 function stringArray(value, label) {
   if (!Array.isArray(value) || value.length < 1 || value.some((item) => typeof item !== "string" || !item)) {
@@ -24,7 +15,7 @@ function stringArray(value, label) {
 }
 
 function validatePollInput(toolName, input) {
-  if (!readOnly(toolName)) throw new Error("poll accepts only a read-only tool");
+  if (classifyTool(toolName, input?.arguments) !== "read") throw new Error("poll accepts only a read-only tool");
   if (!plain(input) || !plain(input.arguments)) throw new Error("poll input and arguments must be objects");
   if (!STATUS_PATH.test(input.status_path || "") || input.status_path.includes("__proto__")) throw new Error("status_path is invalid");
   stringArray(input.terminal_values, "terminal_values");
@@ -36,6 +27,25 @@ function validatePollInput(toolName, input) {
   return input;
 }
 
+async function withinBudget(action, milliseconds, signal) {
+  const controller = new AbortController();
+  let timer;
+  let abort;
+  const stopped = new Promise((_resolve, reject) => {
+    abort = () => { controller.abort(); reject(new Error("cancelled")); };
+    if (signal?.aborted) return abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    timer = setTimeout(() => { controller.abort(); reject(new Error("timeout")); }, Math.max(1, milliseconds));
+  });
+  try {
+    if (signal?.aborted) return await stopped;
+    return await Promise.race([stopped, action(controller.signal)]);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", abort);
+  }
+}
+
 function valueAtPath(value, path) {
   let current = value;
   for (const segment of path.split(".")) {
@@ -74,12 +84,14 @@ async function executeProtectedPoll(toolName, input, {
   let unchanged = 0;
   for (; attempts < input.max_attempts; attempts += 1) {
     if (signal?.aborted) return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "cancelled", retryable: false, start, end: now() });
-    if (now() - start > input.timeout_ms) return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "timeout", retryable: true, start, end: now() });
+    const remaining = input.timeout_ms - (now() - start);
+    if (remaining <= 0) return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "timeout", retryable: true, start, end: now() });
     let response;
     try {
-      response = await callTool(toolName, input.arguments);
-    } catch (_error) {
-      return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker: "read-failed", retryable: true, start, end: now() });
+      response = await withinBudget((requestSignal) => callTool(toolName, input.arguments, { timeoutMs: remaining, signal: requestSignal }), remaining, signal);
+    } catch (error) {
+      const blocker = signal?.aborted ? "cancelled" : ["timeout", "cancelled"].includes(error.message) ? error.message : "read-failed";
+      return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker, retryable: blocker !== "cancelled", start, end: now() });
     }
     const state = valueAtPath(response, input.status_path);
     if (typeof state !== "string" && typeof state !== "number" && typeof state !== "boolean") {
@@ -105,7 +117,12 @@ async function executeProtectedPoll(toolName, input, {
         end: now(),
       });
     }
-    if (attempts + 1 < input.max_attempts && input.interval_ms > 0) await sleep(input.interval_ms);
+    if (attempts + 1 < input.max_attempts && input.interval_ms > 0) {
+      const remainingSleep = input.timeout_ms - (now() - start);
+      if (remainingSleep <= 0) return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker: "timeout", retryable: true, start, end: now() });
+      try { await withinBudget(() => sleep(Math.min(input.interval_ms, remainingSleep)), remainingSleep, signal); }
+      catch { return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker: signal?.aborted ? "cancelled" : "timeout", retryable: !signal?.aborted, start, end: now() }); }
+    }
   }
   return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "attempt-budget-exhausted", retryable: true, start, end: now() });
 }