@kynver-app/openclaw-agent-os 0.1.14 → 0.1.16

package/README.md

@@ -7,7 +7,7 @@ identity, goals, projects, contacts, sessions, daily logs, and long-term memory.
 
 ## What It Provides
 
-- 25 explicit `agent_os_*` tools in the OpenClaw tool namespace.
+- Explicit `agent_os_*` tools in the OpenClaw tool namespace covering identity, goals, projects, contacts, sessions, memory, skills, the durable task board, and first-class plans with version history.
 - Direct Kynver HTTP transport for low-latency calls, with primary-slug auto-resolution via `GET /api/agent-os` so installs work without hardcoding a persona.
 - `mcporter` fallback for compatibility with existing MCP setups.
 - Optional OpenClaw session lifecycle hooks that automatically open/close AgentOS sessions.
@@ -136,6 +136,27 @@ native Codex dynamic-tool bridge issue.
 - `agent_os_get_contacts`
 - `agent_os_create_contact`
 - `agent_os_update_contact`
+- `agent_os_plan_create`
+- `agent_os_plan_list`
+- `agent_os_plan_get`
+- `agent_os_plan_update`
+- `agent_os_plan_add_version`
+- `agent_os_plan_mark_current`
+- `agent_os_plan_add_link`
+- `agent_os_plan_list_links`
+- `agent_os_plan_list_versions`
+
+Plan tools manage first-class AgentOS plans — versioned operational artifacts
+distinct from goals/projects/tasks. Each `AgentPlan` owns a chain of immutable
+`AgentPlanVersion` snapshots (one stamped current at a time) and typed
+`AgentPlanLink` rows pointing at goals, projects, tasks, memories, sessions,
+plans, or remote refs (repo/branch/commit/PR/URL/markdown). The plan body is
+immutable — to record a new snapshot call `agent_os_plan_add_version`, which
+appends a version and (by default) advances `currentVersionId` atomically. To
+attach a plan to its own stable slug within the workspace, pass `planSlug`
+(the workspace `slug` argument is reserved for the AgentOS slug). All
+workspace-owned link targets are validated against the same AgentOS workspace
+server-side; remote refs carry metadata only and are not resolved.
 
 `agent_os_write_memory` and `agent_os_update_memory` are the OpenClaw
 memory-writer surface. They accept `sourceRefs` plus `memoryType`, `confidence`,

package/dist/index.js

@@ -372,6 +372,12 @@ function directRequestForTool(toolName, params, resolvedSlug) {
   switch (toolName) {
     case "agent_os_get_context":
       return { slug, method: "GET", path: "/stats" };
+    case "agent_os_context_envelope":
+      return {
+        slug,
+        method: "GET",
+        path: "/context-envelope" + queryString(params, ["anchorType", "anchorId", "memoryQuery", "memoryLimit", "sessionLimit"])
+      };
     case "agent_os_open_session":
       return { slug, method: "POST", path: "/sessions", body: withoutSlug };
     case "agent_os_close_session": {
@@ -570,10 +576,83 @@ function directRequestForTool(toolName, params, resolvedSlug) {
       const taskId = requiredString(params.taskId, "taskId");
       return { slug, method: "POST", path: `/tasks/${encodeURIComponent(taskId)}/renew-lease`, body: stripKeys(params, ["slug", "taskId"]) };
     }
+    case "agent_os_plan_create": {
+      const body = renamePlanSlug(stripKeys(params, ["slug"]));
+      return { slug, method: "POST", path: "/plans", body };
+    }
+    case "agent_os_plan_list":
+      return {
+        slug,
+        method: "GET",
+        path: `/plans${queryString(params, ["status", "projectId", "goalId", "canonicalKey", "limit"])}`
+      };
+    case "agent_os_plan_get": {
+      const planId = requiredString(params.planId, "planId");
+      return { slug, method: "GET", path: `/plans/${encodeURIComponent(planId)}` };
+    }
+    case "agent_os_plan_update": {
+      const planId = requiredString(params.planId, "planId");
+      const body = renamePlanSlug(stripKeys(params, ["slug", "planId"]));
+      return {
+        slug,
+        method: "PATCH",
+        path: `/plans/${encodeURIComponent(planId)}`,
+        body
+      };
+    }
+    case "agent_os_plan_add_version": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "POST",
+        path: `/plans/${encodeURIComponent(planId)}/versions`,
+        body: stripKeys(params, ["slug", "planId"])
+      };
+    }
+    case "agent_os_plan_mark_current": {
+      const planId = requiredString(params.planId, "planId");
+      const versionId = requiredString(params.versionId, "versionId");
+      return {
+        slug,
+        method: "POST",
+        path: `/plans/${encodeURIComponent(planId)}/versions`,
+        body: { action: "mark_current", versionId }
+      };
+    }
+    case "agent_os_plan_list_versions": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "GET",
+        path: `/plans/${encodeURIComponent(planId)}/versions`
+      };
+    }
+    case "agent_os_plan_add_link": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "POST",
+        path: `/plans/${encodeURIComponent(planId)}/links`,
+        body: stripKeys(params, ["slug", "planId"])
+      };
+    }
+    case "agent_os_plan_list_links": {
+      const planId = requiredString(params.planId, "planId");
+      return {
+        slug,
+        method: "GET",
+        path: `/plans/${encodeURIComponent(planId)}/links`
+      };
+    }
     default:
       throw new Error(`Unsupported AgentOS direct tool: ${toolName}`);
   }
 }
+function renamePlanSlug(body) {
+  if (!("planSlug" in body)) return body;
+  const { planSlug, ...rest } = body;
+  return planSlug === void 0 ? rest : { ...rest, slug: planSlug };
+}
 function requiredString(value, name) {
   const stringValue2 = stringParam(value);
   if (!stringValue2) throw new Error(`${name} is required`);
@@ -867,10 +946,10 @@ function formatRuntimeSkillManifestContext(cached, maxSkills) {
   for (const skill of skills) {
     const description = skill.description ? " - " + singleLine(skill.description) : "";
     const trigger = skill.triggerRules ? " Trigger: " + singleLine(skill.triggerRules) : "";
-    const category = skill.category ? " category=" + skill.category : "";
+    const category = skill.category ? " category=" + singleLine(skill.category) : "";
     const priority = typeof skill.priority === "number" ? " priority=" + skill.priority : "";
     const autoInvoke = skill.autoInvoke === true ? " autoInvoke=requested-by-binding" : "";
-    lines.push("- " + skill.slug + " (" + skill.source + ") " + skill.name + description + "." + category + priority + autoInvoke + trigger);
+    lines.push("- " + singleLine(skill.slug) + " (" + skill.source + ") " + singleLine(skill.name) + description + "." + category + priority + autoInvoke + trigger);
   }
   if (manifest.skills.length > skills.length) {
     lines.push("- " + (manifest.skills.length - skills.length) + " additional enabled skills omitted by runtimeSkillManifestMaxSkills.");
@@ -978,6 +1057,39 @@ var getContextSchema = {
   additionalProperties: false,
   $schema: "http://json-schema.org/draft-07/schema#"
 };
+var contextEnvelopeSchema = {
+  type: "object",
+  required: ["anchorType", "anchorId"],
+  properties: {
+    anchorType: {
+      type: "string",
+      enum: ["plan", "task", "goal", "project", "session"],
+      description: "Kind of anchor to load context around."
+    },
+    anchorId: {
+      type: "string",
+      description: "Id of the anchor row within this workspace."
+    },
+    memoryQuery: {
+      type: "string",
+      description: "Override the memory search query. Defaults to a query derived from the anchor's title/summary."
+    },
+    memoryLimit: {
+      type: "number",
+      description: "Max memory hits (default 5, max 20). Set 0 to skip memory recall."
+    },
+    sessionLimit: {
+      type: "number",
+      description: "Max recent sessions (default 1, max 5). Set 0 to skip."
+    },
+    slug: {
+      type: "string",
+      description: "AgentOS slug. Omit to use the account's primary AgentOS workspace."
+    }
+  },
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
 
 // src/tools/context.ts
 function createContextTools(config) {
@@ -998,6 +1110,23 @@ function createContextTools(config) {
         agentOsSlug: config.agentOsSlug,
         enableDirectHttp: config.enableDirectHttp
       })
+    },
+    {
+      name: "agent_os_context_envelope",
+      label: "AgentOS Context Envelope",
+      description: "Compact context envelope for one anchor (plan | task | goal | project | session): the resolved anchor, its goal + current plan version + most-relevant task + recent session + top related memories, with deduplicated source refs. Use instead of reading giant docs.",
+      parameters: contextEnvelopeSchema,
+      execute: (_toolCallId, params) => callAgentOsTool({
+        serverName: config.agentOsServer,
+        toolName: "agent_os_context_envelope",
+        params,
+        timeoutMs: config.timeoutMs,
+        mcporterConfigPath: config.mcporterConfigPath,
+        kynverApiUrl: config.kynverApiUrl,
+        kynverApiKey: config.kynverApiKey,
+        agentOsSlug: config.agentOsSlug,
+        enableDirectHttp: config.enableDirectHttp
+      })
     }
   ];
 }
@@ -1345,6 +1474,286 @@ function createMemoryTools(config) {
   ];
 }
 
+// src/schemas/plans.ts
+var planStatusValues = [
+  "draft",
+  "active",
+  "blocked",
+  "complete",
+  "archived",
+  "superseded"
+];
+var planPriorityValues = ["low", "normal", "high", "critical"];
+var planLinkTargetValues = [
+  "goal",
+  "project",
+  "task",
+  "memory",
+  "session",
+  "repo",
+  "branch",
+  "commit",
+  "pr",
+  "url",
+  "markdown",
+  "plan"
+];
+var planStatus = { type: "string", enum: planStatusValues };
+var planPriority = { type: "string", enum: planPriorityValues };
+var planLinkTarget = { type: "string", enum: planLinkTargetValues };
+var initialVersion = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    body: { type: "string", description: "Full plan body (markdown)." },
+    summary: { type: "string" },
+    changeSummary: { type: "string" },
+    author: { type: "string" },
+    sourceRefs: {},
+    metadata: looseObject
+  },
+  required: ["body"],
+  additionalProperties: false
+};
+var planCreateSchema = {
+  type: "object",
+  properties: {
+    title: { type: "string", description: "Human-readable plan title." },
+    summary: { type: "string" },
+    planSlug: {
+      type: "string",
+      description: "Optional stable slug for the plan within the AgentOS workspace."
+    },
+    status: planStatus,
+    priority: planPriority,
+    owner: { type: "string" },
+    projectId: {
+      type: "string",
+      description: "AgentOS project id this plan belongs to."
+    },
+    goalId: {
+      type: "string",
+      description: "AgentOS goal id this plan supports."
+    },
+    canonicalKey: {
+      type: "string",
+      description: "Optional canonical key for deduping plans that describe the same artifact."
+    },
+    metadata: looseObject,
+    sourceRefs: {},
+    initialVersion: {
+      ...initialVersion,
+      description: "First version snapshot (required). Becomes the plan's current version."
+    },
+    slug: {
+      type: "string",
+      description: "AgentOS workspace slug. Omit to use the primary workspace."
+    }
+  },
+  required: ["title", "initialVersion"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planListSchema = {
+  type: "object",
+  properties: {
+    status: planStatus,
+    projectId: { type: "string" },
+    goalId: { type: "string" },
+    canonicalKey: { type: "string" },
+    limit: { type: "number", description: "Max rows (default 50, max 200)." },
+    slug: { type: "string" }
+  },
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planGetSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    slug: { type: "string" }
+  },
+  required: ["planId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planUpdateSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    title: { type: "string" },
+    summary: { type: "string" },
+    planSlug: {
+      type: "string",
+      description: "Optional stable slug for the plan within the AgentOS workspace."
+    },
+    status: planStatus,
+    priority: planPriority,
+    owner: { type: "string" },
+    projectId: { type: "string" },
+    goalId: { type: "string" },
+    canonicalKey: { type: "string" },
+    metadata: looseObject,
+    sourceRefs: {},
+    slug: { type: "string" }
+  },
+  required: ["planId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planAddVersionSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    title: { type: "string" },
+    body: { type: "string", description: "Full new version body (markdown)." },
+    summary: { type: "string" },
+    changeSummary: { type: "string" },
+    author: { type: "string" },
+    sourceRefs: {},
+    metadata: looseObject,
+    markCurrent: {
+      type: "boolean",
+      description: "When true (default), the new version becomes the plan's current version."
+    },
+    slug: { type: "string" }
+  },
+  required: ["planId", "body"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planMarkCurrentSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    versionId: {
+      type: "string",
+      description: "Existing version id to promote to current."
+    },
+    slug: { type: "string" }
+  },
+  required: ["planId", "versionId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planAddLinkSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    planVersionId: {
+      type: "string",
+      description: "Optional version id when the link applies to a specific snapshot."
+    },
+    targetType: planLinkTarget,
+    targetId: {
+      type: "string",
+      description: "AgentOS-owned target id (goal/project/task/memory/session/plan). Required for workspace-owned link types."
+    },
+    targetUrl: {
+      type: "string",
+      description: "URL for remote refs (repo/branch/commit/pr/url/markdown). Either targetId or targetUrl is required."
+    },
+    label: { type: "string" },
+    relation: {
+      type: "string",
+      description: "Optional free-form relation label (e.g. 'derived_from', 'supersedes')."
+    },
+    metadata: looseObject,
+    slug: { type: "string" }
+  },
+  required: ["planId", "targetType"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planListLinksSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    slug: { type: "string" }
+  },
+  required: ["planId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+var planListVersionsSchema = {
+  type: "object",
+  properties: {
+    planId: { type: "string" },
+    slug: { type: "string" }
+  },
+  required: ["planId"],
+  additionalProperties: false,
+  $schema: "http://json-schema.org/draft-07/schema#"
+};
+
+// src/tools/plans.ts
+function createPlanTools(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_plan_create",
+      "Create a first-class AgentOS plan with an initial version. Plans are versioned operational artifacts (separate from goals/projects/tasks) \u2014 the initial version body is required and becomes the plan's current version.",
+      planCreateSchema
+    ),
+    mk(
+      "agent_os_plan_list",
+      "List AgentOS plans, optionally filtered by status, projectId, goalId, or canonicalKey.",
+      planListSchema
+    ),
+    mk(
+      "agent_os_plan_get",
+      "Fetch one AgentOS plan with its full version history, current version pointer, and typed links.",
+      planGetSchema
+    ),
+    mk(
+      "agent_os_plan_update",
+      "Patch an AgentOS plan's metadata (title, summary, status, priority, owner, project/goal links, canonicalKey). The plan body itself is immutable \u2014 use agent_os_plan_add_version to record a new snapshot.",
+      planUpdateSchema
+    ),
+    mk(
+      "agent_os_plan_add_version",
+      "Append an immutable version snapshot to a plan. The new version's versionNumber is one greater than the latest, and (when markCurrent is true, the default) the plan's currentVersionId pointer advances atomically.",
+      planAddVersionSchema
+    ),
+    mk(
+      "agent_os_plan_mark_current",
+      "Promote an existing version of a plan to be the current version. The version must already belong to the plan.",
+      planMarkCurrentSchema
+    ),
+    mk(
+      "agent_os_plan_add_link",
+      "Add a typed link from a plan (and optionally a specific version) to a related goal, project, task, memory, session, repo, branch, commit, PR, URL, markdown file, or other plan. Workspace-owned targets are validated against the same AgentOS workspace server-side; remote refs (url/repo/branch/commit/pr/markdown) carry metadata only.",
+      planAddLinkSchema
+    ),
+    mk(
+      "agent_os_plan_list_links",
+      "List the typed links attached to a plan.",
+      planListLinksSchema
+    ),
+    mk(
+      "agent_os_plan_list_versions",
+      "List the version history of a plan in ascending order by versionNumber. agent_os_plan_get already returns versions; use this when you only need the version list.",
+      planListVersionsSchema
+    )
+  ];
+}
+
 // src/schemas/projects.ts
 var getProjectsSchema = {
   type: "object",
@@ -1922,7 +2331,8 @@ function createAllTools(config) {
     ...createMemoryTools(config),
     ...createSkillTools(config),
     ...createContactTools(config),
-    ...createTaskTools(config)
+    ...createTaskTools(config),
+    ...createPlanTools(config)
   ];
 }