mlclaw 0.4.10 → 0.5.0

package/Dockerfile

@@ -1,8 +1,8 @@
 ARG OPENCLAW_VERSION=2026.7.1
 ARG OPENCLAW_BASE_IMAGE=ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}
 ARG BROKERKIT_PLUGIN_VERSION=0.4.1
-ARG BROKERKIT_VERSION=hf-broker/v0.5.2
-ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/huggingface/mlclaw:0.4.10-openclaw-2026.7.1
+ARG BROKERKIT_VERSION=hf-broker/v0.6.2
+ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/huggingface/mlclaw:0.5.0-openclaw-2026.7.1
 
 FROM golang:1.26.5-bookworm AS hf-broker-build
 ARG BROKERKIT_VERSION
@@ -43,6 +43,7 @@ RUN apt-get update \
   && rm -rf /var/lib/apt/lists/*
 RUN python3 -m pip install --break-system-packages --no-cache-dir \
   "huggingface_hub==1.19.0" \
+  "hf-xet==1.5.2" \
   "datasets==5.0.0" \
   "safetensors==0.8.0" \
   "fastapi==0.137.1" \

package/README.md

@@ -384,8 +384,15 @@ across Space rebuilds, local container replacement, and gateway migration. The
 Space does not use `HF_TOKEN` or `HUGGINGFACE_HUB_TOKEN` secrets. Its broad
 credential is stored as `MLCLAW_BROKER_HF_TOKEN`, written to a broker-owned
 `0600` file during startup, and removed from child-process environments.
-OpenClaw uses only the generated broker agent credential. Broker grant and
-event state and encrypted control credentials live under the root-owned
+OpenClaw uses only the generated broker agent credential. At startup, ML Claw
+asks HF Broker to render the active policy with the exact deployment state
+bucket protected. Agent requests against that bucket are denied before an
+approval is created. Other repository paths and bucket key prefixes can use
+operator-approved grants lasting up to 24 hours or seven days; the installed
+`hf-broker` skill explains request, wait, recovery, write, read, and revocation
+workflows.
+
+Broker grant and event state and encrypted control credentials live under the root-owned
 `/var/lib/mlclaw-protected` tree. They are included in the durable snapshot
 through a root-only `.mlclaw-protected` staging step, then restored outside the
 agent-owned live directory before OpenClaw starts. Rebuildable Git mirrors, the

package/assets/hf-tooling/manifest.json

@@ -23,6 +23,7 @@
   "python": {
     "packages": {
       "huggingface_hub": "1.19.0",
+      "hf_xet": "1.5.2",
       "datasets": "5.0.0",
       "safetensors": "0.8.0"
     }
@@ -30,7 +31,15 @@
   "skills": {
     "source": "https://github.com/huggingface/skills",
     "revision": "89d91fd4d0e6d4330471ba35f1c388489e94b496",
+    "managed": [
+      {
+        "name": "hf-broker",
+        "source": "https://github.com/osolmaz/brokerkit",
+        "revision": "hf-broker/v0.6.2"
+      }
+    ],
     "installed": [
+      "hf-broker",
       "hf-cli",
       "huggingface-spaces",
       "huggingface-datasets",

package/assets/hf-tooling/skills/hf-broker/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: hf-broker
+description: Use ML Claw's HF Broker for protected Hugging Face repository and bucket reads, writes, temporary grants, recovery, and revocation. Use instead of asking for or exposing a Hugging Face access token.
+metadata:
+  { "openclaw": { "emoji": "🤗", "requires": { "bins": ["hf-broker"] } } }
+---
+
+# Hugging Face Broker
+
+Use the preconfigured HF Broker for protected Hugging Face operations. Never
+ask for, print, copy, or export the broker's Hugging Face token. Do not run
+`hf auth login` to work around a broker decision.
+
+## Choose a workflow
+
+Use the advertised `hf_*` MCP tools for ordinary typed operations and grant
+management. Use `hf-broker client` when a local file must enter or leave the
+protected stream store. The runtime already provides the broker endpoint and a
+limited agent credential.
+
+Every mutation needs a stable request ID. Reuse it only for an exact retry of
+the same operation. If a response is lost, recover the existing operation or
+grant instead of submitting another mutation.
+
+## Request reusable write access
+
+Request a temporary grant only when repeated writes are needed. Keep the scope
+as narrow as possible. A day is 1,440 minutes and a week is 10,080 minutes.
+These repeated-write examples explicitly request the deployment policy's
+25-use ceiling; the operator may approve a smaller use budget.
+
+For one bucket key prefix:
+
+```sh
+hf-broker client grant request bucket.object.write OWNER/BUCKET \
+  --key 'artifacts/**' \
+  --minutes 10080 \
+  --max-uses 25 \
+  --reason "Write the requested artifacts for one week" \
+  --request-id STABLE-GRANT-REQUEST-ID
+```
+
+For one repository path prefix:
+
+```sh
+hf-broker client grant request repo.commit.create OWNER/REPO \
+  --type dataset \
+  --path 'data/**' \
+  --minutes 1440 \
+  --max-uses 25 \
+  --reason "Update the requested dataset path for one day" \
+  --request-id STABLE-GRANT-REQUEST-ID
+```
+
+Normal append-only Git pushes can also use a scoped `git.push.append` grant.
+Keep the repository type, ref, and path selectors exact. Force pushes, ref
+deletion, repository deletion, visibility changes, and access management stay
+short-lived or single-use.
+
+A pending grant requires an operator decision. Keep waiting on the same grant
+rather than creating another request:
+
+```sh
+hf-broker client grant wait --wait-timeout 15m GRANT-ID
+hf-broker client grant get GRANT-ID
+```
+
+MCP grant calls use bounded waits. If `hf_grant_request` or `hf_grant_wait`
+returns `pending`, call `hf_grant_wait` again with the same grant ID. Use
+`hf_grant_cancel` for an unapproved request and `hf_grant_revoke` when reusable
+access is no longer needed.
+
+## Write and read bucket objects
+
+Upload a local file through the broker's stream store. File bytes do not belong
+in MCP JSON, chat messages, plans, approvals, or logs.
+
+```sh
+hf-broker client bucket object write \
+  --target-json '{"kind":"bucket","namespace":"OWNER","name":"BUCKET"}' \
+  --arguments-json '{"path":"artifacts/result.bin"}' \
+  --source ./result.bin \
+  --media-type application/octet-stream \
+  --reason "Upload the requested result" \
+  --request-id STABLE-WRITE-REQUEST-ID \
+  --wait=true \
+  --wait-timeout 15m
+```
+
+Set `"overwrite":true` only when replacing the currently observed object is
+intentional. The broker checks the bound precondition again before commit.
+
+Read into a new destination and let the client verify the returned stream:
+
+```sh
+hf-broker client bucket object read \
+  --target-json '{"kind":"bucket","namespace":"OWNER","name":"BUCKET"}' \
+  --arguments-json '{"path":"artifacts/result.bin"}' \
+  --output ./downloaded-result.bin \
+  --reason "Read the requested result" \
+  --wait=true \
+  --wait-timeout 15m
+```
+
+Use `hf_bucket_object_list` or the matching client command to inspect only the
+approved bucket prefix. Do not use the ML Claw state bucket for agent work. Its
+exact target is denied by deployment policy, and approval cannot override that
+deny.
+
+## Recover operations
+
+A timeout may leave a durable operation pending. Continue with its operation ID
+or recover it by request ID:
+
+```sh
+hf-broker client operation get OPERATION-ID
+hf-broker client operation wait --wait-timeout 15m OPERATION-ID
+hf-broker client operation cancel OPERATION-ID
+```
+
+If the operation ID was lost, call the `hf_operation_list` MCP tool with the
+stable `request_id`, then continue with the returned operation ID.
+
+Stop only after a terminal result, explicit cancellation, or an unrecoverable
+broker error. Revocation and expiry prevent later matching writes from reaching
+Hugging Face.

package/dist/hf-tooling-seed.js

@@ -140,6 +140,13 @@ conflict is durable: inspect the existing operation instead of restarting the
 broker. Protected actions appear in the ML Claw BrokerKit control and may also
 be sent through configured OpenClaw channels.
 
+For repeated repository or bucket writes, request the narrowest temporary grant
+with \`hf_grant_request\`. A bounded wait may return a pending grant; continue
+with \`hf_grant_wait\` using the same grant ID. Revoke the grant when the work is
+finished. Use the installed \`hf-broker\` client for local file upload and
+verified download streams. Never use the deployment state bucket for agent
+work; its exact target is denied by policy.
+
 After repository creation, use the brokered Git transport for repository
 contents. The limited broker credential is not a Hugging Face Hub token; do
 not report it as missing Hub access.
@@ -210,11 +217,21 @@ function assertToolingManifest(value) {
   if (!skills || !Array.isArray(skills.installed) || !skills.installed.every((skill) => typeof skill === "string")) {
     throw new Error("HF tooling manifest must list installed skills");
   }
+  if (!Array.isArray(skills.managed) || !skills.managed.every(isManagedSkillSource)) {
+    throw new Error("HF tooling manifest must list managed skill sources");
+  }
   const python = record.python;
   if (!python || typeof python.packages !== "object" || python.packages === null) {
     throw new Error("HF tooling manifest must list Python packages");
   }
 }
+function isManagedSkillSource(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const source = value;
+  return [source.name, source.source, source.revision].every(
+    (field) => typeof field === "string" && field.trim().length > 0
+  );
+}
 async function copyMissingTree(sourceRoot, targetRoot) {
   const copied = [];
   await assertDirectory(sourceRoot, "HF tooling templates");

package/dist/mlclaw.mjs

@@ -15383,9 +15383,9 @@ function nextLink(header) {
 
 // src/mlclaw/release-config.generated.ts
 var RELEASE_CONFIG = {
-  "packageVersion": "0.4.10",
+  "packageVersion": "0.5.0",
   "openclawVersion": "2026.7.1",
-  "brokerkitVersion": "hf-broker/v0.5.2",
+  "brokerkitVersion": "hf-broker/v0.6.2",
   "brokerkitPluginVersion": "0.4.1",
   "runtimeImageRepository": "ghcr.io/huggingface/mlclaw"
 };
@@ -15530,6 +15530,7 @@ RUN apt-get update \\
   && rm -rf /var/lib/apt/lists/*
 RUN python3 -m pip install --break-system-packages --no-cache-dir \\
   "huggingface_hub==1.19.0" \\
+  "hf-xet==1.5.2" \\
   "datasets==5.0.0" \\
   "safetensors==0.8.0" \\
   "fastapi==0.137.1" \\

package/entrypoint.sh

@@ -9,6 +9,8 @@ export MLCLAW_OPENCLAW_UID="$OPENCLAW_UID"
 export MLCLAW_OPENCLAW_GID="$OPENCLAW_GID"
 HF_BROKER_ENABLED=0
 HF_BROKER_RUN_DIR="/run/mlclaw-hf-broker"
+HF_BROKER_POLICY_DIR="$HF_BROKER_RUN_DIR/policy"
+HF_BROKER_SCOPE_FILE="$HF_BROKER_POLICY_DIR/scope.json"
 STATE_HF_TOKEN=""
 RESTORED_PROTECTED_STATE_DIR="$LIVE_DIR/.mlclaw-protected"
 PROTECTED_STATE_DIR="/var/lib/mlclaw-protected"
@@ -50,6 +52,8 @@ prepare_hf_broker() {
 
   export MLCLAW_HF_BROKER_URL="http://127.0.0.1:7863"
   export MLCLAW_HF_BROKER_AGENT_SECRET_FILE="$agent_secret_file"
+  export HF_BROKER_AGENT_ENDPOINT="tcp://127.0.0.1:7863"
+  export HF_BROKER_SHARED_SECRET_FILE="$agent_secret_file"
   if [ "${MLCLAW_GATEWAY_LOCATION:-}" = "local" ]; then
     export MLCLAW_TRUSTED_HF_TOKEN_FILE="$token_file"
   fi
@@ -81,6 +85,32 @@ restore_protected_state() {
   chmod 0700 "$PROTECTED_STATE_DIR/control" "$HF_BROKER_STATE_DIR"
 }
 
+render_hf_broker_policy() {
+  if [ "$HF_BROKER_ENABLED" != "1" ]; then
+    return
+  fi
+
+  local state_bucket="${OPENCLAW_HF_STATE_BUCKET:-}"
+  local protected_target=()
+  if [ -n "$state_bucket" ]; then
+    protected_target=(--protect-bucket "$state_bucket")
+  fi
+
+  install -d -m 0700 -o hf-broker -g hf-broker "$HF_BROKER_POLICY_DIR"
+  gosu hf-broker:hf-broker /usr/local/bin/hf-broker policy render \
+    --preset request-all-agent-operations \
+    --client default \
+    --profile-out "$HF_BROKER_POLICY_DIR/profile.json" \
+    --output "$HF_BROKER_SCOPE_FILE" \
+    --manifest-out "$HF_BROKER_POLICY_DIR/manifest.json" \
+    --replace \
+    "${protected_target[@]}"
+  gosu hf-broker:hf-broker /usr/local/bin/hf-broker doctor policy \
+    --profile "$HF_BROKER_POLICY_DIR/profile.json" \
+    --scope "$HF_BROKER_SCOPE_FILE" \
+    --manifest "$HF_BROKER_POLICY_DIR/manifest.json"
+}
+
 start_hf_broker() {
   if [ "$HF_BROKER_ENABLED" != "1" ]; then
     return
@@ -95,7 +125,8 @@ start_hf_broker() {
   HF_BROKER_OPERATOR_SECRETS_FILE="$HF_BROKER_RUN_DIR/operator-secrets.conf" \
   HF_BROKER_AGENT_ENDPOINT=tcp://127.0.0.1:7863 \
   HF_BROKER_OPERATOR_ENDPOINT=tcp://127.0.0.1:7864 \
-  HF_BROKER_SCOPE_FILE=/app/hf-broker.scope.json \
+  HF_BROKER_SCOPE_FILE="$HF_BROKER_SCOPE_FILE" \
+  HF_BROKER_XET_PYTHON=/usr/bin/python3 \
   HF_BROKER_STATE_DIR="$HF_BROKER_STATE_DIR" \
   gosu hf-broker:hf-broker /usr/local/bin/hf-broker &
   HF_BROKER_PID=$!
@@ -172,6 +203,7 @@ mkdir -p "$LIVE_DIR" "$WORKSPACE_DIR" "$STATE_DIR"
 chown_openclaw_live
 install -d -m 0710 -o root -g hf-broker "$PROTECTED_STATE_DIR"
 install -d -m 0700 -o root -g root "$PROTECTED_STATE_DIR/control"
+render_hf_broker_policy
 start_hf_broker
 
 if [ -n "${OPENCLAW_AGENT_NAME:-}" ]; then

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "mlclaw",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "license": "MIT",
   "config": {
     "openclawVersion": "2026.7.1",
-    "brokerkitVersion": "hf-broker/v0.5.2",
+    "brokerkitVersion": "hf-broker/v0.6.2",
     "brokerkitPluginVersion": "0.4.1",
     "runtimeImageRepository": "ghcr.io/huggingface/mlclaw"
   },