openclaw-memory-atmem 2.2.6-beta.1 → 2.2.6-beta.10

package/README.md

@@ -5,7 +5,7 @@ This npm package is the host bridge for AtMem. It is not a standalone memory eng
 Use the Python-owned installer:
 
 ```bash
-python -m pip install --pre --upgrade atmem==2.2.6b1
+python -m pip install --pre --upgrade atmem==2.2.6b10
 atmem openclaw install
 ```
 
@@ -22,6 +22,13 @@ Existing AtMem 2.1 users run `atmem openclaw upgrade` after upgrading the Python
 package. This preserves the current memory mode and migration, verifies the new
 bridge with a self-test flight, and rolls back the bridge on failure.
 
+Bridge `2.2.6-beta.10` adds Spec 007 exact task-context delivery. When the host
+supplies `taskId` in hook context, the bridge requests only that governed task,
+checks its byte digest, contributes it separately from recalled memory, and
+confirms exposure. With no `taskId`, task delivery stays off and existing
+memory-only behavior is unchanged. Guard detection is available, but this
+bridge does not claim it can block OpenClaw execution.
+
 In shadow mode the bridge observes native-memory changes without injecting AtMem context. In active mode it exposes compatible memory search/get tools, model-semantic capture, bounded recall and native-path protection. `atmem control restore` restores the saved OpenClaw configuration and native memory.
 
 The bridge also supplies Agent Black Box hooks. It records model/tool lifecycle digests and bounded metadata—not raw prompts, responses, parameters or results—so `atmem blackbox verify RUN_ID` can check timeline integrity and observed tool-hook closure. See the [Agent Black Box guide](../../docs/agent-blackbox.md) for the exact boundary.

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, resolveBoundTaskForTool, 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,6 +768,27 @@ function register(api) {
                     user_id: delegatedUserIdFor(ctx),
                     workspace_id: workspaceIdFor(ctx),
                 }, cfg.recall.timeoutMs));
+                // 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", {
+                        ...(ctx.taskId ? { task_id: ctx.taskId } : {}),
+                        ...(taskIdentity ?? {}),
+                        session_id: sessionKey,
+                        host_run_id: ctx.runId,
+                        agent_id: agentIdFor(ctx),
+                        workspace_id: workspaceIdFor(ctx),
+                    }, cfg.recall.timeoutMs))
+                    : undefined;
+                if (taskPrepared?.disposition === "injected" &&
+                    (!taskPrepared.context || !taskPrepared.context_sha256 ||
+                        `sha256:${digestText(taskPrepared.context)}` !== taskPrepared.context_sha256)) {
+                    throw new Error("governed task context failed exact handoff digest validation");
+                }
                 pendingPrompts.set(sessionKey, {
                     text: userText,
                     ts: Date.now(),
@@ -758,7 +800,21 @@ function register(api) {
                     delegatedContextSha256: prepared.authority === "delegated" ? prepared.context_sha256 : undefined,
                     delegatedAuthority: prepared.authority,
                     delegatedResultSha256: prepared.result_sha256,
+                    taskDeliveryId: taskPrepared?.delivery_id,
+                    taskContextSha256: taskPrepared?.context_sha256,
+                    taskId: taskPrepared?.task_id ?? ctx.taskId,
                 });
+                if (taskPrepared) {
+                    await recordBlackbox("task.context.prepared", undefined, ctx, {
+                        task_id: taskPrepared.task_id ?? ctx.taskId,
+                        task_disposition: taskPrepared?.disposition ?? "withheld",
+                        task_revision: taskPrepared?.revision,
+                        ...(taskPrepared?.context_sha256
+                            ? { task_context_sha256: taskPrepared.context_sha256.replace(/^sha256:/, "") }
+                            : {}),
+                        task_reason_codes: taskPrepared?.reason_codes ?? [],
+                    });
+                }
                 if (prepared.authority === "delegated" &&
                     prepared.inject &&
                     (!prepared.context ||
@@ -794,6 +850,10 @@ function register(api) {
                     digest_profile: "atmem-context-envelope-canonical-json-v1",
                     context_chars: (prepared.context ?? "").length,
                     candidate_ids: prepared.candidate_ids ?? [],
+                    candidates_considered: prepared.retrieval?.eligible_candidate_count ?? 0,
+                    retrieval_support_class: prepared.retrieval?.decision?.support_class ?? "not_recorded",
+                    retrieval_reason_codes: prepared.retrieval?.decision?.reason_codes ?? [],
+                    retrieval_calibration_version: prepared.retrieval?.decision?.calibration_version,
                     exposure_id: prepared.exposure_id,
                     mode: prepared.mode,
                     context_location: prepared.inject
@@ -805,8 +865,21 @@ function register(api) {
                 if (prepared.inject && prepared.context) {
                     api.logger.info(`${TAG} memory control plane ${prepared.mode ?? "active"} context exposed`);
                     return prepared.authority === "delegated"
-                        ? { prependContext: prepared.context }
-                        : { appendContext: prepared.context };
+                        ? {
+                            prependContext: prepared.context,
+                            appendContext: taskPrepared?.disposition === "injected"
+                                ? taskPrepared.context
+                                : undefined,
+                        }
+                        : {
+                            appendContext: [
+                                prepared.context,
+                                taskPrepared?.disposition === "injected" ? taskPrepared.context : "",
+                            ].filter(Boolean).join("\n\n"),
+                        };
+                }
+                if (taskPrepared?.disposition === "injected" && taskPrepared.context) {
+                    return { appendContext: taskPrepared.context };
                 }
                 return;
             }
@@ -1007,6 +1080,14 @@ function register(api) {
                 if (cached?.exposureId) {
                     await callFor(ctx, "control_exposure_shown", { exposure_id: cached.exposureId }, cfg.recall.timeoutMs);
                 }
+                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: cached.taskId ?? ctx.taskId,
+                        task_disposition: "injected",
+                        task_context_sha256: cached.taskContextSha256?.replace(/^sha256:/, ""),
+                    });
+                }
                 if (event.success !== false) {
                     await callFor(ctx, "control_sync_openclaw_memory", {}, cfg.recall.timeoutMs);
                 }
@@ -1630,6 +1711,128 @@ 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 resolution = await resolveBoundTaskForTool(toolCtx, (identity) => callFor(toolCtx, "control_prepare_task_context", {
+                    ...identity,
+                    ...taskScope(toolCtx),
+                    host_run_id: toolCtx.runId,
+                }));
+                if (!resolution.ok) {
+                    return refusal(`${resolution.message} (${resolution.reasonCodes.join(", ")})`);
+                }
+                const result = (await callFor(toolCtx, "control_propose_task_delta", {
+                    ...resolution.identity,
+                    ...taskScope(toolCtx),
+                    // Redundant checked assertion. Authority came from the current
+                    // conversation focus above, never from the model's parameters.
+                    task_id: resolution.taskId,
+                    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.1",
+                version: "2.2.6-beta.10",
             },
         });
         this.notify("notifications/initialized", {});

package/dist/src/task-tools.js

@@ -0,0 +1,105 @@
+/**
+ * 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,
+    };
+}
+/** Resolve authority from the authenticated conversation, never model input. */
+export async function resolveBoundTaskForTool(ctx, prepare) {
+    const identity = sessionIdentityForTool(ctx);
+    if (!identity) {
+        return { ok: false, message: NO_IDENTITY_MESSAGE, reasonCodes: ["host_identity_missing"] };
+    }
+    const prepared = (await prepare(identity));
+    if (prepared.disposition !== "injected" || !prepared.task_id) {
+        const reasons = (prepared.reason_codes ?? []).map(String);
+        return {
+            ok: false,
+            message: "This conversation has no active governed task focus. " +
+                "No task progress was recorded.",
+            reasonCodes: reasons.length ? reasons : ["task_context_selection_required"],
+        };
+    }
+    return {
+        ok: true,
+        identity,
+        taskId: String(prepared.task_id),
+        revision: prepared.revision,
+    };
+}
+/** 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/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-atmem",
   "name": "Memory (atmem)",
   "description": "OpenClaw bridge installed and managed by the AtMem memory control plane.",
-  "version": "2.2.6-beta.1",
+  "version": "2.2.6-beta.10",
   "commandAliases": ["memory-atmem"],
   "activation": {
     "onStartup": true,
@@ -16,7 +16,9 @@
       "atmem_search",
       "atmem_forget",
       "atmem_observe",
-      "atmem_forget_artifact"
+      "atmem_forget_artifact",
+      "task_report_progress",
+      "task_binding_status"
     ]
   },
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-atmem",
-  "version": "2.2.6-beta.1",
+  "version": "2.2.6-beta.10",
   "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/manifest.mjs && 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 && node test/delegated-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",