@passioncode-ai/fabric-agent-adapter 0.35.3 → 0.36.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/share-registration.schema.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fabric.passioncode.ai/agent-contract/0.1.0/schemas/share-registration.schema.json",
+  "title": "Share registration, share-registration/1, and its receipt (DEC-0086)",
+  "description": "How an organization server learns which agent a share grant into it runs: the sharer's enrolled node registers each such grant over the device transport (devices.md, the DEC-0056 signature by the enrollment's #sig key), and the server answers a receipt or a typed refusal. The server takes the organization from the certificate and the registrant from the user bound to its epoch, never from the body, and keys what it holds by (that user, grantId). docs/specification/share-registration.md.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/registration"
+    },
+    {
+      "$ref": "#/$defs/receipt"
+    },
+    {
+      "$ref": "#/$defs/refusal"
+    }
+  ],
+  "$defs": {
+    "registration": {
+      "type": "object",
+      "description": "What the sharer's enrolled node sends to the organization server of one of its enrollments for one share grant into that organization (DEC-0086 items 1 to 3): active, with the grant's revision, the agentRef its placements run and the grant's window; or withdrawn, with the time it ended. Nothing else: no estate id or revision, machine, principal, issuer, project, capability, spend or free text.",
+      "required": [
+        "type",
+        "grantId",
+        "context",
+        "state"
+      ],
+      "properties": {
+        "type": {
+          "const": "share-registration/1"
+        },
+        "grantId": {
+          "$ref": "#/$defs/shareGrantId",
+          "description": "The share grant's meta.id, compared as written (FAC-SEM-117)."
+        },
+        "context": {
+          "$ref": "#/$defs/orgContextId",
+          "description": "The grant's own context, org:<orgId>: the receiver refuses one that is not org: and its certificate's org.id as written (wrong-organization)."
+        },
+        "state": {
+          "enum": [
+            "active",
+            "withdrawn"
+          ]
+        },
+        "grantRevision": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "The grant's meta.revision in the estate revision the node applied. A higher one replaces the held registration; a lower one is stale-revision; the same one with other bytes revision-conflict."
+        },
+        "agentRef": {
+          "$ref": "#/$defs/agentRef",
+          "description": "The one agentRef every placement of the revision in this context that names the grant runs (FAC-SEM-117)."
+        },
+        "startsAt": {
+          "$ref": "#/$defs/instant",
+          "description": "The grant's startsAt, as written."
+        },
+        "expiresAt": {
+          "$ref": "#/$defs/instant",
+          "description": "The grant's expiresAt, as written; after startsAt (FAC-SEM-118)."
+        },
+        "withdrawnAt": {
+          "$ref": "#/$defs/instant",
+          "description": "When the share ended: the earliest revokedAt of the grant's revocations in the revision or the applied delta entries, or the issuedAt of the revision that no longer lists the grant."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "state": {
+                "const": "active"
+              }
+            },
+            "required": [
+              "state"
+            ]
+          },
+          "then": {
+            "required": [
+              "grantRevision",
+              "agentRef",
+              "startsAt",
+              "expiresAt"
+            ],
+            "properties": {
+              "grantRevision": true,
+              "agentRef": true,
+              "startsAt": true,
+              "expiresAt": true,
+              "withdrawnAt": false
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "state": {
+                "const": "withdrawn"
+              }
+            },
+            "required": [
+              "state"
+            ]
+          },
+          "then": {
+            "required": [
+              "withdrawnAt"
+            ],
+            "properties": {
+              "withdrawnAt": true,
+              "grantRevision": false,
+              "agentRef": false,
+              "startsAt": false,
+              "expiresAt": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "receipt": {
+      "type": "object",
+      "description": "The receiver's 200 answer: what it holds now for the device's bound user and the grant.",
+      "required": [
+        "type",
+        "grantId",
+        "state",
+        "digest"
+      ],
+      "properties": {
+        "type": {
+          "const": "share-registration-receipt/1"
+        },
+        "grantId": {
+          "$ref": "#/$defs/shareGrantId"
+        },
+        "state": {
+          "enum": [
+            "registered",
+            "unchanged",
+            "withdrawn"
+          ],
+          "description": "registered: an active registration was taken; withdrawn: a withdrawal was taken; unchanged: the same bytes again, or a second withdrawal (of two, the earliest withdrawnAt is kept)."
+        },
+        "digest": {
+          "$ref": "#/$defs/sha256",
+          "description": "sha256: and the hex SHA-256 of the UTF-8 RFC 8785 form of the registration the receiver holds after this request (shareRegistrationDigest)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "refusal": {
+      "type": "object",
+      "description": "The receiver's refusal of a registration after the request authenticated (devices.md transport steps 0 to 8) and its revision is one it reads: 400 malformed, 403 wrong-organization or unassigned-device, 409 already-withdrawn, agent-mismatch, stale-revision or revision-conflict.",
+      "required": [
+        "error"
+      ],
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "malformed",
+                "wrong-organization",
+                "unassigned-device",
+                "already-withdrawn",
+                "agent-mismatch",
+                "stale-revision",
+                "revision-conflict"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "instant": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-5][0-9](\\.[0-9]{1,3})?([Zz]|[+-][0-9]{2}:[0-9]{2})$",
+      "description": "An RFC 3339 date-time with an offset, seconds 00 to 59 (no leap second, which date-time admits) and at most three fraction digits: every port compares the same instants, at millisecond precision (DEC-0085, DEC-0086)."
+    },
+    "orgContextId": {
+      "type": "string",
+      "pattern": "^org:[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
+      "description": "DEC-0086: an organization's context, org:<orgId>: contextId without personal. What a share registration and a grant.usage carry, the grant's own context. Compared as written (docs/specification/contexts.md)."
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "shareGrantId": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^urn:fabric:share:(?!0{32}$)[0-9a-f]{32}$",
+      "description": "DEC-0086, FAC-SEM-117: the meta.id of a share grant into an organization: urn:fabric:share: and 32 lower-case hex digits, 128 bits from a CSPRNG, never derived from a name, an address, an estate id, an agentRef or the organization, and never all zeros. The pattern admits only its own normal form (DEC-0076), so it is compared as written; it holds no person's name, address or estate id (docs/specification/share-registration.md)."
+    },
+    "agentRef": {
+      "type": "string",
+      "maxLength": 146,
+      "pattern": "^urn:fabric:agent:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+      "description": "urn:fabric:agent:<publisher>:<id> — one agent across its versions (FAC-SEM-066)."
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.35.3"
+  version: "0.36.0"
   contract-version: "0.1.0"
-  contract-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
+  contract-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
 ---
 
 # Creating Fabric-compatible agents
@@ -124,7 +124,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
 The effect class is declared, never defaulted: ask the author what the agent does outside itself when the request
 does not say. Cost presets are only for a run whose cost varies; their amounts come from the author or measured runs.
 
-Pin exactly contract `0.1.0` at commit `d8146cfb0a1c74fc6432284c4356bb0c864b37b5` and
+Pin exactly contract `0.1.0` at commit `07042181bfae2a481aa0da1a5651f24c76669c48` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/resilience-and-autonomy.md

@@ -19,9 +19,14 @@ mechanism that held after the fix. Every rule is cheaper to build in than to ret
 
 ## Limits are pauses
 
-1. **A provider or subscription limit pauses the job; it never fails it.** Store a typed pause
-   (`quota_exhausted`, `retryable: true`, the reset time when known) and resume from the same
-   stage. Failing it cost callers whole jobs and resubmits.
+1. **A provider or subscription limit pauses the job; it never fails it.** Keep the job `working` and
+   write its `statusMessage` in the contract's pause grammar, `quota-exhausted` or
+   `quota-exhausted until <UTC instant>` (optionally `: <text>`, at most 500 characters), with
+   `pollIntervalMs` reaching the reset; resume from the same stage. Only a job its provider will not
+   resume ends `failed` with `error: {code: "quota-exhausted", message, data: {retryable, resetsAt?}}`:
+   `retryable: false` when a person must act, and `resetsAt` (UTC, `T` and `Z`, at most three
+   fraction digits) only when `retryable: true` (contract DEC-0087, `FAC-SEM-119`). Failing a job a
+   limit only paused cost callers whole jobs and resubmits.
 2. **Resume first.** Every worker reads its own state — checkpoint, worktree, branches, open
    pull requests, notes — before it acts, and continues from there. Relaunching from scratch
    after a limit recreated work over committed work and re-issued credentials already held.
@@ -88,7 +93,11 @@ mechanism that held after the fix. Every rule is cheaper to build in than to ret
 4. **A resend of an unknown outcome reuses its idempotency key — or does not happen.** Derive
    keys from the intent (action and entity, or run and step), never from a clock or a random
    value, and make them unique in storage: time-and-random keys let redelivered requests charge
-   again. A write whose effect is uncertain stops as `outcome_unknown`; a new key there pays twice.
+   again. A write whose effect is uncertain ends `failed` with the code `outcome-unknown`; only an
+   observed result settles it, and a new key there pays twice. A caller acts on each answer as the
+   contract's `jobCallerAction` does: wait out a pause, resend a retryable `quota-exhausted` under the
+   same key after `resetsAt`, hand a non-retryable one or `limit-reached` to a person, reconcile an
+   `outcome-unknown`, and never resend it.
 5. **A client error at submit is a rejection, not a lost task.** Settle it with known usage (zero
    if none), release the reserved money in the same transaction, and never resend the identical
    request; a 4xx while polling is still a lost task.

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -19,7 +19,7 @@ compatibility: >-
   this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.35.3"
+  version: "0.36.0"
 ---
 
 # Working with Fabric

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md

@@ -87,6 +87,9 @@ only variable names are looked at, never a value (two of them carry the session'
 - **Start a second Fabric session.** A `fabric-mcp` started on its own would enroll a new session, and Fabric ends a
   binding's oldest live session past eight (ADR-0134 amendment 2) — the agent's own. The worker and `watch-mail` run
   `fabric-mcp --rejoin-only --runtime-session-id <id>`, and only when Fabric advertises `session-hooks/1`.
+- **Rejoin more than once a minute.** Every rejoin spends the agent's Fabric request budget, which every session of
+  the machine shares. A turn within 60 s of the session's last successful rejoin (the worker marks it as `rejoined`
+  in the session's folder) is spooled and waits for the next worker; the end of a session always starts one (FAA-53).
 - **Retry in a loop.** A refused call is logged by its error code and dropped; an answer that never came is logged
   as `outcome=unknown`. The calls carry an `idempotencyKey`, so a repeat is the same event.
 

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -56,6 +56,9 @@ LOCK_STALE_S = 30.0
 #: A session folder untouched this long belongs to a session that will not spool again: its worker failed, or the
 #: session ended without SessionEnd. Nothing retries it, so the next spooling hook removes it (FAA-50).
 SESSION_STALE_S = 7 * 86400
+#: A session rejoins at most once in this span (FAA-53): every rejoin spends Fabric's per-agent request budget, which
+#: every session of the machine shares; a turn inside it waits in the spool for the next worker, an end never waits.
+REJOIN_MIN_INTERVAL_S = 60.0
 READ_CAP = 64 * 1024
 CONFIG_CAP = 32 * 1024 * 1024
 WATCH_MIN_INTERVAL_S = 10
@@ -63,7 +66,7 @@ WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 LOCAL_ORIGIN = re.compile(r'"origin": "http://(?:127\.0\.0\.1|localhost)')
-VERSION = "0.35.3"
+VERSION = "0.36.0"
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code",
          "hermes": "Hermes", "opencode": "OpenCode", "openclaw": "OpenClaw", "pi": "Pi"}
 NATIVE_PLUGIN_HOSTS = frozenset(("hermes", "opencode", "openclaw", "pi"))
@@ -559,10 +562,21 @@ def hook_spool(payload: Dict[str, Any], event: str, env: Optional[Dict[str, str]
     if event == "end" and isinstance(payload.get("reason"), str):
         entry["reason"] = payload["reason"][:64]
     spool(directory, entry)
-    if event == "end" or not lock_held(directory):
-        spawn(directory)
-        return "spooled: worker started"
-    return "spooled: a worker is running"
+    if event != "end" and lock_held(directory):
+        return "spooled: a worker is running"
+    if event != "end" and rejoined_recently(directory):
+        return "spooled: rejoined recently"
+    spawn(directory)
+    return "spooled: worker started"
+
+
+def rejoined_recently(directory: Path, now: Optional[float] = None) -> bool:
+    """Whether this session's last rejoin succeeded within REJOIN_MIN_INTERVAL_S (the worker marks it)."""
+    try:
+        mark = (directory / "rejoined").stat().st_mtime
+    except OSError:
+        return False
+    return 0 <= (time.time() if now is None else now) - mark < REJOIN_MIN_INTERVAL_S
 
 
 def _remove_tree(directory: Path) -> None:
@@ -801,6 +815,7 @@ def deliver(directory: Path, env: Optional[Dict[str, str]] = None, deadline_s: f
                                       "clientInfo": {"name": "fabric-agent-adapter-hooks", "version": VERSION}})
         client.notify("notifications/initialized")
         names = _wait_for_session_tools(client, deadline)
+        _write_private(directory / "rejoined", "")
         while entries:
             for path in entries:
                 entry = json.loads(read_small(path) or "{}")