openclaw-memory-atmem 2.2.6-beta.3 → 2.2.6-beta.4

package/dist/index.js

@@ -25,6 +25,7 @@ import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "nod
 import { spawnSync } from "node:child_process";
 import { AtmemClient } from "./src/rpc-client.js";
 import { runSetup } from "./src/setup.js";
+import { NOT_OWNER_MESSAGE, NO_IDENTITY_MESSAGE, describeDecision, isConversationOwner, ok, refusal, sessionIdentityForTool, } from "./src/task-tools.js";
 const TAG = "[memory-atmem]";
 const TAKEOVER_GUIDANCE = "<atmem_memory_provider>\n" +
     "AtMem is the active durable-memory provider. " +
@@ -352,6 +353,26 @@ function register(api) {
         }
         return cfg.subject;
     };
+    /**
+     * The identity AtMem resolves a governed task through.
+     *
+     * `sessionId` is the generation: OpenClaw changes it when a conversation is
+     * reset, which is what stops a recycled `sessionKey` from inheriting an
+     * earlier task binding. Both fields are optional upstream, so returning
+     * `undefined` is an ordinary outcome and callers must withhold rather than
+     * send a partial identity.
+     */
+    const sessionIdentityFor = (ctx) => {
+        const sessionKey = ctx.sessionKey ?? ctx.sessionId;
+        const sessionEpoch = ctx.sessionId;
+        if (!sessionKey || !sessionEpoch)
+            return undefined;
+        return {
+            host_type: "openclaw",
+            session_key: sessionKey,
+            session_epoch: sessionEpoch,
+        };
+    };
     const workspaceIdFor = (ctx) => {
         const workspace = cfg.agentWorkspaces[agentIdFor(ctx)];
         return workspace ? `ws_${digestText(workspace).slice(0, 16)}` : undefined;
@@ -747,9 +768,16 @@ function register(api) {
                     user_id: delegatedUserIdFor(ctx),
                     workspace_id: workspaceIdFor(ctx),
                 }, cfg.recall.timeoutMs));
-                const taskPrepared = ctx.taskId
+                // Task identity resolves through the manager, not from ctx.taskId
+                // alone: OpenClaw supplies no task identity of its own, so without a
+                // registered binding this branch could never run. Presenting the
+                // session identity on every lookup keeps binding and resolution from
+                // disagreeing about which conversation they mean.
+                const taskIdentity = sessionIdentityFor(ctx);
+                const taskPrepared = (ctx.taskId || taskIdentity)
                     ? (await callFor(ctx, "control_prepare_task_context", {
-                        task_id: ctx.taskId,
+                        ...(ctx.taskId ? { task_id: ctx.taskId } : {}),
+                        ...(taskIdentity ?? {}),
                         session_id: sessionKey,
                         host_run_id: ctx.runId,
                         agent_id: agentIdFor(ctx),
@@ -774,10 +802,11 @@ function register(api) {
                     delegatedResultSha256: prepared.result_sha256,
                     taskDeliveryId: taskPrepared?.delivery_id,
                     taskContextSha256: taskPrepared?.context_sha256,
+                    taskId: taskPrepared?.task_id ?? ctx.taskId,
                 });
-                if (ctx.taskId) {
+                if (taskPrepared) {
                     await recordBlackbox("task.context.prepared", undefined, ctx, {
-                        task_id: ctx.taskId,
+                        task_id: taskPrepared.task_id ?? ctx.taskId,
                         task_disposition: taskPrepared?.disposition ?? "withheld",
                         task_revision: taskPrepared?.revision,
                         task_context_sha256: taskPrepared?.context_sha256?.replace(/^sha256:/, ""),
@@ -1048,7 +1077,7 @@ function register(api) {
                 if (cached?.taskDeliveryId) {
                     await callFor(ctx, "control_task_exposure_shown", { delivery_id: cached.taskDeliveryId }, cfg.recall.timeoutMs);
                     await recordBlackbox("task.context.exposed", event.runId, ctx, {
-                        task_id: ctx.taskId,
+                        task_id: cached.taskId ?? ctx.taskId,
                         task_disposition: "injected",
                         task_context_sha256: cached.taskContextSha256?.replace(/^sha256:/, ""),
                     });
@@ -1676,6 +1705,121 @@ function register(api) {
                 };
             },
         }), { name: "atmem_forget_artifact" });
+        // --- governed task tools (Amendment A) -------------------------------
+        //
+        // A control-plane operation is invisible to a model. Without these
+        // registrations an agent receives a task checklist it has no way to tick,
+        // which is worse than receiving nothing: it looks like progress is being
+        // tracked when nothing is being recorded.
+        //
+        // Every one resolves through this conversation's own binding, so a model
+        // can only touch the task its conversation is bound to.
+        const taskScope = (toolCtx) => ({
+            agent_id: agentIdFor(toolCtx),
+            workspace_id: workspaceIdFor(toolCtx),
+        });
+        api.registerTool((toolCtx) => ({
+            name: "task_report_progress",
+            label: "Report Task Progress (atmem)",
+            description: "Report progress on the governed task this conversation is bound to. " +
+                "State the item and its new status. AtMem validates the change and " +
+                "decides; you are proposing, not writing. If no task is bound this " +
+                "does nothing.",
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: { type: "string", description: "Which task item changed" },
+                    status: {
+                        type: "string",
+                        enum: ["ready", "running", "blocked", "completed", "skipped", "failed"],
+                        description: "The item's new status",
+                    },
+                    base_revision: {
+                        type: "integer",
+                        description: "The task revision you read. If the task has moved since, this " +
+                            "returns a conflict instead of overwriting someone else's work.",
+                    },
+                    reason: { type: "string", description: "Why, in one line" },
+                },
+                required: ["item_id", "status", "base_revision"],
+            },
+            async execute(toolCallId, params) {
+                const identity = sessionIdentityForTool(toolCtx);
+                if (!identity)
+                    return refusal(NO_IDENTITY_MESSAGE);
+                const result = (await callFor(toolCtx, "control_propose_task_delta", {
+                    ...identity,
+                    ...taskScope(toolCtx),
+                    task_id: String(params.task_id ?? ""),
+                    base_revision: Number(params.base_revision ?? 0),
+                    // Derived from stable host identifiers, never from payload content
+                    // or a clock, so a retried tool call collapses to one decision.
+                    idempotency_key: `${toolCtx.runId ?? "run"}:${toolCallId}`,
+                    operations: [
+                        {
+                            kind: "set_item_status",
+                            item_id: String(params.item_id ?? ""),
+                            status: String(params.status ?? ""),
+                            reason: params.reason ? String(params.reason) : undefined,
+                        },
+                    ],
+                    adapter: "openclaw",
+                    // The tool call is the evidence. Completing an item requires some,
+                    // and a host reporting its own tool outcome is asserting rather
+                    // than independently verifying -- AtMem records it at exactly that
+                    // assurance and never upgrades it.
+                    evidence: [
+                        { kind: "tool_call", reference_id: `${toolCtx.runId ?? "run"}-${toolCallId}` },
+                    ],
+                    reason: params.reason ? String(params.reason) : "",
+                }));
+                return {
+                    content: [{ type: "text", text: describeDecision(result) }],
+                    details: { outcome: result.outcome ?? result.reason_code ?? null },
+                };
+            },
+        }), { name: "task_report_progress" });
+        api.registerTool((toolCtx) => ({
+            name: "task_binding_status",
+            label: "Governed Task Binding (atmem)",
+            description: "Show which governed task, if any, this conversation is bound to, and " +
+                "the exact command to bind it. Owner only.",
+            parameters: { type: "object", properties: {} },
+            async execute() {
+                if (!isConversationOwner(toolCtx))
+                    return refusal(NOT_OWNER_MESSAGE);
+                const identity = sessionIdentityForTool(toolCtx);
+                if (!identity)
+                    return refusal(NO_IDENTITY_MESSAGE);
+                const prepared = (await callFor(toolCtx, "control_prepare_task_context", {
+                    ...identity,
+                    ...taskScope(toolCtx),
+                }));
+                // Binding stays an authenticated operator action at the terminal, so
+                // the owner needs their own conversation's identity to run it. They
+                // cannot see it otherwise -- it is an internal host value -- and
+                // without it the whole feature is unreachable from inside OpenClaw.
+                // Handing the owner a ready-to-run command is the same "one useful
+                // next command" the CLI gives everywhere else. This discloses nothing
+                // a non-owner can obtain: the gate above already refused them.
+                const bindCommand = `atmem task bind DB_PATH TASK_ID --subject SUBJECT ` +
+                    `--agent ${agentIdFor(toolCtx)} --workspace ${workspaceIdFor(toolCtx) ?? "WORKSPACE"} ` +
+                    `--actor YOU --reason WHY --host-type ${identity.host_type} ` +
+                    `--session-key ${identity.session_key} --session-epoch ${identity.session_epoch} --yes`;
+                if (prepared.disposition !== "injected") {
+                    return ok({
+                        bound: false,
+                        reason: (prepared.reason_codes ?? []).join(", ") || "not bound",
+                        bind_with: bindCommand,
+                    });
+                }
+                return ok({
+                    bound: true,
+                    task_id: prepared.task_id ?? null,
+                    rebind_with: bindCommand,
+                });
+            },
+        }), { name: "task_binding_status" });
     }
     api.logger.info(`${TAG} registered (db=${cfg.dbPath}, subject=${cfg.subject}, ` +
         `recall=${cfg.recall.enabled}, capture=${cfg.capture.enabled}, ` +

package/dist/src/rpc-client.js

@@ -128,7 +128,7 @@ export class AtmemClient {
             capabilities: {},
             clientInfo: {
                 name: "openclaw-memory-atmem",
-                version: "2.2.6-beta.3",
+                version: "2.2.6-beta.4",
             },
         });
         this.notify("notifications/initialized", {});

package/dist/src/task-tools.js

@@ -0,0 +1,82 @@
+/**
+ * Model- and owner-facing governed task tools.
+ *
+ * Spec 007 Amendment A, FR-049 path (b) and FR-050.
+ *
+ * A manager method and an MCP operation are invisible to a model. For an agent
+ * to report progress at all, a tool has to be registered with the host through
+ * the same mechanism that publishes `memory_search`. That is what this file is.
+ *
+ * Two audiences, deliberately separated:
+ *
+ *  - `task_*` tools the model calls. They resolve through the conversation's
+ *    own binding, so a model can only affect the task its conversation is bound
+ *    to, and every outcome is reported back in words the model can act on -- a
+ *    rejection it cannot interpret is a rejection it will retry blindly.
+ *  - `task_bind` / `task_unbind` / `task_binding_status`, which an operator
+ *    runs from inside the conversation. These are gated on the host's own owner
+ *    signal. That signal is optional upstream, so anything other than an
+ *    explicit `true` is treated as *not* the owner: absence is never permission.
+ */
+/** The one place identity is derived, so no caller can assemble a partial one. */
+export function sessionIdentityForTool(ctx) {
+    const sessionKey = ctx.sessionKey ?? ctx.sessionId;
+    const sessionEpoch = ctx.sessionId;
+    if (!sessionKey || !sessionEpoch)
+        return undefined;
+    return {
+        host_type: "openclaw",
+        session_key: sessionKey,
+        session_epoch: sessionEpoch,
+    };
+}
+/** Absence is never permission. Only an explicit affirmative is the owner. */
+export function isConversationOwner(ctx) {
+    return ctx.senderIsOwner === true;
+}
+/**
+ * Turn one AtMem decision into something a model can act on.
+ *
+ * The outcome vocabulary is small and each value implies a different next
+ * move, so saying which one it is matters more than saying it failed.
+ */
+export function describeDecision(result) {
+    const outcome = String(result.outcome ?? "");
+    const reasons = Array.isArray(result.reason_codes)
+        ? result.reason_codes.join(", ")
+        : String(result.reason_code ?? "");
+    switch (outcome) {
+        case "accepted":
+            return `Recorded. The task is now at revision ${result.resulting_revision}.`;
+        case "no_change":
+            return `No change: the task already reflects this (${reasons}).`;
+        case "conflict":
+            return (`Conflict: the task moved while you were working (${reasons}). ` +
+                "Read it again with task_state and submit against the revision you get back.");
+        case "rejected":
+            return `Rejected (${reasons}). Do not retry this unchanged; the reason explains what AtMem will accept.`;
+        default:
+            break;
+    }
+    if (result.reason_code) {
+        return `Not applied (${result.reason_code}): ${String(result.message ?? "")}`;
+    }
+    return String(result.message ?? "No decision was returned.");
+}
+/** A refusal shaped like every other tool result, so a model reads one thing. */
+export function refusal(message) {
+    return {
+        content: [{ type: "text", text: JSON.stringify({ ok: false, message }) }],
+    };
+}
+export function ok(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify({ ok: true, ...payload }) }],
+    };
+}
+export const NOT_OWNER_MESSAGE = 
+// Identical whether a binding exists or not: a non-owner must not be able to
+// learn what this conversation is bound to by asking.
+"Only the owner of this conversation can manage its governed task binding.";
+export const NO_IDENTITY_MESSAGE = "This conversation has no usable session identity, so AtMem cannot tell " +
+    "which conversation it is. No task binding can be resolved or created.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-atmem",
-  "version": "2.2.6-beta.3",
+  "version": "2.2.6-beta.4",
   "description": "OpenClaw Agent Black Box and memory control-plane bridge for AtMem",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,9 +40,11 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node test/setup.mjs && node test/hooks.mjs && node test/delegated-context-contract.mjs",
-    "smoke": "node test/smoke.mjs",
-    "prepack": "npm run build && npm run typecheck && npm test && npm run smoke"
+    "test": "node test/hook-context-compat.mjs && node test/setup.mjs && node test/hooks.mjs && node test/task-tools.mjs && node test/delegated-context-contract.mjs",
+    "smoke": "node test/smoke.mjs && node test/task-journey.mjs",
+    "prepack": "npm run build && npm run typecheck && npm test && npm run smoke",
+    "hook-context": "node test/hook-context-compat.mjs",
+    "record-hook-context": "node test/lib/record-hook-context.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",