@kynver-app/openclaw-agent-os 0.1.18 → 0.1.20

package/README.md

@@ -24,6 +24,19 @@ openclaw plugins install @kynver-app/openclaw-agent-os@latest --force
 If your OpenClaw install does not support package installs yet, install this package into the OpenClaw
 extensions directory and enable the plugin from there. The runtime entry point is `dist/index.js`.
 
+For a wiped machine or new-user setup, use the packaged bootstrap command:
+
+```bash
+export KYNVER_API_URL="https://www.kynver.com"
+export KYNVER_API_KEY="kynver_xxx"
+export KYNVER_HARNESS_REPO="/path/to/Kynver" # optional, enables kynver_harness_* tools
+
+npx -y -p @kynver-app/openclaw-agent-os@latest kynver-openclaw-agent-os-bootstrap
+```
+
+See `docs/runbooks/openclaw-agent-os-bootstrap.md` in the Kynver repo for the
+full recovery/onboarding runbook.
+
 ## Configure
 
 Recommended direct HTTP config:
@@ -31,14 +44,19 @@ Recommended direct HTTP config:
 ```json
 {
   "plugins": {
-    "config": {
+    "entries": {
       "kynver-agent-os-tools": {
-        "kynverApiUrl": "https://www.kynver.com",
-        "kynverApiKey": "kynver_xxx",
-        "enableDirectHttp": true,
-        "enableSessionLifecycle": true,
-        "enableRuntimeSkillManifest": true,
-        "enableContinuityGuidance": true
+        "enabled": true,
+        "config": {
+          "kynverApiUrl": "https://www.kynver.com",
+          "kynverApiKey": "kynver_xxx",
+          "enableDirectHttp": true,
+          "enableSessionLifecycle": true,
+          "enableRuntimeSkillManifest": true,
+          "enableContinuityGuidance": true,
+          "enableHarnessTools": true,
+          "harnessRepo": "/path/to/Kynver"
+        }
       }
     }
   }
@@ -57,10 +75,13 @@ Compatibility config through an existing `mcporter.json` still works:
 ```json
 {
   "plugins": {
-    "config": {
+    "entries": {
       "kynver-agent-os-tools": {
-        "agentOsServer": "kynver-agent-os",
-        "mcporterConfigPath": "<home>/.openclaw/workspace/config/mcporter.json"
+        "enabled": true,
+        "config": {
+          "agentOsServer": "kynver-agent-os",
+          "mcporterConfigPath": "<home>/.openclaw/workspace/config/mcporter.json"
+        }
       }
     }
   }
@@ -145,6 +166,22 @@ native Codex dynamic-tool bridge issue.
 - `agent_os_plan_add_link`
 - `agent_os_plan_list_links`
 - `agent_os_plan_list_versions`
+- `agent_os_command_center_get`
+- `agent_os_task_next_action`
+- `agent_os_plan_progress_rows_list`
+- `agent_os_plan_progress_rows_upsert`
+- `agent_os_plan_progress_event_append`
+
+`agent_os_command_center_get` returns the same unified Command Center rollup the
+browser operator console uses (plan rollups, project hierarchy, action-required,
+DQ inbox, goals, review lanes, harness summaries). It calls the by-id HTTP
+surface and resolves `agentOsId` from the workspace slug when omitted.
+
+`agent_os_task_next_action` posts harness completion signals to the deterministic
+next-action router (review/fix/landing dispatch, close, or await-human).
+
+Plan progress tools mirror the AgentOS MCP plan-progress surface for structured
+checklist rows and role-lane events.
 
 Plan tools manage first-class AgentOS plans — versioned operational artifacts
 distinct from goals/projects/tasks. Each `AgentPlan` owns a chain of immutable

package/dist/index.js

@@ -75,7 +75,8 @@ var pluginConfigSchema = {
     }
   }
 };
-function resolvePluginConfig(raw) {
+function resolvePluginConfig(rawEntry) {
+  const raw = rawEntry?.config && typeof rawEntry.config === "object" && !Array.isArray(rawEntry.config) ? rawEntry.config : rawEntry;
   const rawServer = typeof raw?.agentOsServer === "string" && raw.agentOsServer.trim() ? raw.agentOsServer.trim() : "kynver-agent-os";
   if (!/^[a-zA-Z0-9_-]+$/.test(rawServer)) {
     throw new Error("Invalid agentOsServer: use letters, numbers, hyphens, and underscores only.");
@@ -301,6 +302,36 @@ function directConfigFromEnv(agentOsSlug, kynverApiKey) {
   };
 }
 var primarySlugCache = /* @__PURE__ */ new Map();
+var agentOsIdCache = /* @__PURE__ */ new Map();
+async function resolveAgentOsId(config, slug, timeoutMs) {
+  const cacheKey = `${config.apiUrl}|${config.apiKey || ""}|${slug}`;
+  const cached = agentOsIdCache.get(cacheKey);
+  if (cached) return cached;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1e3, Math.min(timeoutMs, 1e4)));
+  try {
+    const res = await fetch(`${config.apiUrl}/api/agent-os/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+      },
+      signal: controller.signal
+    });
+    if (!res.ok) return void 0;
+    const text = await res.text();
+    const payload = text ? safeJson(text) : null;
+    if (!payload || typeof payload !== "object") return void 0;
+    const id = typeof payload.id === "string" ? payload.id.trim() : "";
+    if (!id) return void 0;
+    agentOsIdCache.set(cacheKey, id);
+    return id;
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 async function resolvePrimarySlug(config, timeoutMs) {
   const cacheKey = `${config.apiUrl}|${config.apiKey || ""}`;
   const cached = primarySlugCache.get(cacheKey);
@@ -350,14 +381,25 @@ async function callAgentOsApiDirect(toolName2, params, timeoutMs, config) {
       "AgentOS slug could not be resolved. Set agentOsSlug in plugin config, or ensure the account has a primary AgentOS workspace at GET /api/agent-os."
     );
   }
-  const { slug, path: path3, method, body } = directRequestForTool(toolName2, params, resolvedSlug);
+  const request = directRequestForTool(toolName2, params, resolvedSlug);
+  const { slug, path: path3, method, body } = request;
   if (!slug) {
     throw new Error("AgentOS slug could not be resolved.");
   }
+  let url = `${config.apiUrl}/api/agent-os/${encodeURIComponent(slug)}${path3}`;
+  if (request.route === "by-id") {
+    const agentOsId = request.agentOsId || stringParam(params.agentOsId) || await resolveAgentOsId(config, slug, timeoutMs);
+    if (!agentOsId) {
+      throw new Error(
+        "AgentOS id could not be resolved for by-id Command Center routes. Pass agentOsId or ensure GET /api/agent-os/{slug} returns id."
+      );
+    }
+    url = `${config.apiUrl}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}${path3}`;
+  }
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${config.apiUrl}/api/agent-os/${encodeURIComponent(slug)}${path3}`, {
+    const res = await fetch(url, {
       method,
       headers: {
         "Content-Type": "application/json",
@@ -379,7 +421,7 @@ async function callAgentOsApiDirect(toolName2, params, timeoutMs, config) {
 }
 function directRequestForTool(toolName2, params, resolvedSlug) {
   const slug = stringParam(params.slug) || resolvedSlug;
-  const withoutSlug = stripKeys(params, ["slug"]);
+  const withoutSlug = stripKeys(params, ["slug", "agentOsId"]);
   switch (toolName2) {
     case "agent_os_get_context":
       return { slug, method: "GET", path: "/stats" };
@@ -655,6 +697,51 @@ function directRequestForTool(toolName2, params, resolvedSlug) {
         path: `/plans/${encodeURIComponent(planId)}/links`
       };
     }
+    case "agent_os_command_center_get":
+      return {
+        route: "by-id",
+        agentOsId: stringParam(params.agentOsId),
+        slug,
+        method: "GET",
+        path: `/command-center${queryString(params, ["since", "limit", "harnessLimit"])}`
+      };
+    case "agent_os_task_next_action": {
+      const taskId = requiredString(params.taskId, "taskId");
+      return {
+        slug,
+        method: "POST",
+        path: `/tasks/${encodeURIComponent(taskId)}/next-action`,
+        body: stripKeys(params, ["slug", "taskId"])
+      };
+    }
+    case "agent_os_plan_progress_rows_list": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "GET",
+        path: `/plans/${encodeURIComponent(planId)}/progress-rows`
+      };
+    }
+    case "agent_os_plan_progress_rows_upsert": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "POST",
+        path: `/plans/${encodeURIComponent(planId)}/progress-rows`,
+        body: { rows: params.rows }
+      };
+    }
+    case "agent_os_plan_progress_event_append": {
+      const planId = requiredString(params.planId, "planId");
+      const body = stripKeys(params, ["slug", "planId", "remainingWork"]);
+      const remainingWork = stringParam(params.remainingWork);
+      return {
+        slug,
+        method: "POST",
+        path: `/plans/${encodeURIComponent(planId)}/progress-events`,
+        body: remainingWork === void 0 ? body : { ...body, remaining: remainingWork }
+      };
+    }
     default:
       throw new Error(`Unsupported AgentOS direct tool: ${toolName2}`);
   }
@@ -806,7 +893,17 @@ function buildAgentOsContinuityGuidanceContext(config) {
     "",
     "Local markdown memory (CLAUDE.md, AGENTS.md, /memory, scratch notes) is a fallback and a cache. Use it when AgentOS is unreachable or for in-conversation scratch; do not treat it as authoritative when AgentOS is available.",
     "Privacy: AgentOS context is personal to the signed-in account. Do not expose AgentOS identity, goals, projects, contacts, or memory excerpts in shared, broadcast, group, or multi-tenant contexts unless the user explicitly asks for it. If you cannot determine the channel scope, withhold AgentOS specifics by default.",
-    "If an AgentOS call fails or returns unavailable, say so explicitly, fall back to local markdown or conversation memory for that turn, and ask the user before persisting anything that would normally go to AgentOS."
+    "If an AgentOS call fails or returns unavailable, say so explicitly, fall back to local markdown or conversation memory for that turn, and ask the user before persisting anything that would normally go to AgentOS.",
+    "",
+    "Command Center (operational control plane):",
+    "- For the same unified rollup the browser Command Center uses (projects, plans, action-required, DQ inbox, harness summaries), call agent_os_command_center_get. Omit slug to resolve the account primary workspace; pass agentOsId when you already have it from a prior identity fetch.",
+    "",
+    "Plan execution progress (Agentic OS operational flow):",
+    "- Workers (`kynver plan progress`, harness/by-id route): emit checkpoints only \u2014 `running`, `partial`, or `blocked` as implementer with evidence and `executorRef`. The harness route rejects `status: done` and confirm events; never propose or confirm row closure from the worker CLI.",
+    "- Chat agents / orchestrators (MCP `agent_os_plan_progress_event_append` on the slug route): propose row done (`proposed: true`, `status: done`, evidence) and confirm (`proposed: false`, reviewer lanes). Split implementer vs reviewer across models when possible.",
+    "- Discovery that needs the operator, runtime, or another reviewer: create a linked review/decision AgentTask via `agent_os_plan_review_task_create` (or `agent_os_ask_human` for human decisions), link it on the progress row, and mark the row blocked until resolved.",
+    "- Respect review ordering: completion-report review before deep implementation review; deep review before follow-up-for-completion closure.",
+    "- Runtime verification (`kynver plan verify` or operator Verify plan in Command Center) is required before plan closure \u2014 worker completion alone is not sufficient."
   ];
   return lines.join("\n");
 }
@@ -2430,6 +2527,186 @@ function createHarnessTools(config) {
   }));
 }
 
+// src/schemas/command-center.ts
+var slugField = {
+  type: "string",
+  description: "AgentOS workspace slug. Omit to use the account's primary AgentOS workspace."
+};
+var commandCenterGetSchema = {
+  type: "object",
+  properties: {
+    slug: slugField,
+    agentOsId: {
+      type: "string",
+      description: "Optional AgentOS row id. When omitted, resolved from slug via GET /api/agent-os/{slug}."
+    },
+    since: {
+      type: "string",
+      description: "ISO timestamp \u2014 only include tasks updated after this instant."
+    },
+    limit: {
+      type: "number",
+      description: "Max tasks to load (server cap 10000, default operator console uses 10000)."
+    },
+    harnessLimit: {
+      type: "number",
+      description: "Max harness runs in the rollup (server cap 200)."
+    }
+  },
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var taskNextActionSchema = {
+  type: "object",
+  properties: {
+    taskId: { type: "string", description: "Subject AgentTask id." },
+    lane: {
+      type: "string",
+      enum: ["worker", "reviewer", "landing"],
+      description: "Which harness lane just finished and is handing control to the router."
+    },
+    verdict: {
+      type: "string",
+      enum: ["pass", "changes_requested", "needs_input", "blocked", "in_progress"]
+    },
+    landingSucceeded: { type: "boolean" },
+    blockerText: { type: "string" },
+    sourceId: { type: "string" },
+    runId: { type: "string", description: "Required when lane is worker." },
+    workerName: { type: "string", description: "Required when lane is worker." },
+    startedAt: { type: "string" },
+    finishedAt: { type: "string" },
+    lastActivityAt: { type: "string" },
+    payload: { type: "object", additionalProperties: true },
+    slug: slugField
+  },
+  required: ["taskId", "lane"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var progressStatus = {
+  type: "string",
+  enum: ["todo", "running", "partial", "blocked", "done"]
+};
+var roleLane = {
+  type: "string",
+  enum: [
+    "plan_author",
+    "plan_reviewer",
+    "implementer",
+    "report_reviewer",
+    "deep_reviewer",
+    "repair_implementer",
+    "runtime_verifier",
+    "user",
+    "system"
+  ]
+};
+var progressRow = {
+  type: "object",
+  properties: {
+    rowKey: { type: "string" },
+    title: { type: "string" },
+    description: { type: "string" },
+    ordinal: { type: "number" },
+    stageId: { type: "string" },
+    ownerLane: roleLane,
+    taskId: { type: "string" }
+  },
+  required: ["rowKey", "title", "ordinal"],
+  additionalProperties: false
+};
+var planProgressRowsListSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    slug: slugField
+  },
+  required: ["planId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planProgressRowsUpsertSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    rows: { type: "array", items: progressRow },
+    slug: slugField
+  },
+  required: ["planId", "rows"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planProgressEventAppendSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    rowKey: { type: "string" },
+    rowId: { type: "string" },
+    taskId: { type: "string" },
+    reviewTaskId: { type: "string" },
+    roleLane,
+    status: progressStatus,
+    note: { type: "string" },
+    remainingWork: { type: "string" },
+    evidence: { type: "array", items: { type: "object", additionalProperties: true } },
+    proposed: { type: "boolean" },
+    executorRef: { type: "string" },
+    slug: slugField
+  },
+  required: ["planId", "roleLane", "status"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+
+// src/tools/command-center.ts
+function createCommandCenterTools(config) {
+  const mk = (name, description, parameters) => ({
+    name,
+    label: name,
+    description,
+    parameters,
+    execute: (_toolCallId, params) => callAgentOsTool({
+      serverName: config.agentOsServer,
+      toolName: name,
+      params,
+      timeoutMs: config.timeoutMs,
+      mcporterConfigPath: config.mcporterConfigPath,
+      kynverApiUrl: config.kynverApiUrl,
+      kynverApiKey: config.kynverApiKey,
+      agentOsSlug: config.agentOsSlug,
+      enableDirectHttp: config.enableDirectHttp
+    })
+  });
+  return [
+    mk(
+      "agent_os_command_center_get",
+      "Fetch the unified Command Center rollup for the AgentOS workspace: plan rollups, project hierarchy, action-required items, DQ inbox, goals, review lanes, and harness summaries \u2014 the same aggregate the browser Command Center uses.",
+      commandCenterGetSchema
+    ),
+    mk(
+      "agent_os_task_next_action",
+      "Route the deterministic next harness action after a worker, reviewer, or landing lane completes (dispatch review/fix/landing, close, or await human). Same POST surface as the production harness completion hook.",
+      taskNextActionSchema
+    ),
+    mk(
+      "agent_os_plan_progress_rows_list",
+      "List structured plan progress rows (canonical checklist state) for one plan.",
+      planProgressRowsListSchema
+    ),
+    mk(
+      "agent_os_plan_progress_rows_upsert",
+      "Seed or update structured plan progress rows for one plan.",
+      planProgressRowsUpsertSchema
+    ),
+    mk(
+      "agent_os_plan_progress_event_append",
+      "Append a role-lane progress event and apply allowed row transition rules for one plan.",
+      planProgressEventAppendSchema
+    )
+  ];
+}
+
 // src/tools/index.ts
 function createAllTools(config) {
   return [
@@ -2443,6 +2720,7 @@ function createAllTools(config) {
     ...createContactTools(config),
     ...createTaskTools(config),
     ...createPlanTools(config),
+    ...createCommandCenterTools(config),
     ...createHarnessTools(config)
   ];
 }
@@ -2454,7 +2732,7 @@ var plugin = {
   description: "First-class OpenClaw tools for Kynver AgentOS, using direct Kynver HTTP with mcporter fallback.",
   configSchema: pluginConfigSchema,
   register(api) {
-    const config = resolvePluginConfig(api?.config);
+    const config = resolvePluginConfig(api?.pluginConfig ?? api?.config);
     const tools = createAllTools(config);
     for (const tool of tools) {
       api.registerTool(tool);