@passioncode-ai/fabric-agent-adapter 0.9.0 → 0.11.1

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_interop.py

@@ -279,14 +279,17 @@ class JobStore:
         return dict(record["job"])
 
     def create(self, capability: str, arguments: Any, traceparent: Optional[str] = None,
-               poll_interval_ms: Optional[int] = None) -> Dict[str, Any]:
+               poll_interval_ms: Optional[int] = None, delegation: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """Start a job; returns the handle a job-capable tool puts in structuredContent."""
         job_id = "job_" + secrets.token_hex(12)
         job: Dict[str, Any] = {"id": job_id, "status": "working"}
         if poll_interval_ms:
             job["pollIntervalMs"] = int(poll_interval_ms)
-        self._save({"job": job, "private": {"capability": capability, "input": arguments,
-                                            "traceparent": traceparent if parse_traceparent(traceparent) else None}})
+        private: Dict[str, Any] = {"capability": capability, "input": arguments,
+                                   "traceparent": traceparent if parse_traceparent(traceparent) else None}
+        if delegation:  # DEC-0039: who started it; only they read, cancel or answer it
+            private["delegation"] = {"principal": delegation.get("principal"), "caller": delegation.get("caller")}
+        self._save({"job": job, "private": private})
         return {"job": {"id": job_id, "status": "working"}}
 
     def get(self, job_id: str) -> Dict[str, Any]:
@@ -361,16 +364,19 @@ class JobStore:
 class CallContext:
     """What a tool handler gets: the child span it runs in, and a way to start a job."""
 
-    def __init__(self, server: "McpToolServer", tool: str, arguments: Any, traceparent: str):
+    def __init__(self, server: "McpToolServer", tool: str, arguments: Any, traceparent: str,
+                 delegation: Optional[Dict[str, Any]] = None):
         self.server = server
         self.tool = tool
         self.arguments = arguments
         self.traceparent = traceparent
+        # DEC-0039: the accepted delegation (principal, caller, chain, claims) when the server has a gate.
+        self.delegation = delegation
 
     def start_job(self, poll_interval_ms: Optional[int] = None) -> Dict[str, Any]:
         if self.server.jobs is None:
             raise InteropError("This server has no job store.")
-        handle = self.server.jobs.create(self.tool, self.arguments, self.traceparent, poll_interval_ms)
+        handle = self.server.jobs.create(self.tool, self.arguments, self.traceparent, poll_interval_ms, self.delegation)
         self.server.job_started(handle["job"]["id"], self)
         return handle
 
@@ -471,7 +477,12 @@ class McpToolServer:
 
     def __init__(self, name: str, version: str, jobs: Optional[JobStore] = None,
                  on_job_started: Optional[Callable[[str, CallContext], None]] = None,
-                 on_input: Optional[OnInput] = None):
+                 on_input: Optional[OnInput] = None,
+                 authorize: Optional[Callable[[str, Any], Dict[str, Any]]] = None):
+        # authorize(tool, headers) runs before every handler (fabric_delegation.delegation_gate, DEC-0039):
+        # a refusal is answered in the DL-19 shape and the handler never runs. The built-in job tools are
+        # gated by the job's own capability, and answered only for the principal and caller that started it.
+        self._authorize = authorize
         self.info = {"name": name, "version": version}
         self.jobs = jobs
         self.tools: List[Dict[str, Any]] = []
@@ -540,17 +551,39 @@ class McpToolServer:
         name = params.get("name")
         arguments = params.get("arguments") or {}
         if name in ("fabric.job.get", "fabric.job.cancel") and self.jobs is not None:
-            return {"jsonrpc": "2.0", "id": rid, "result": self._job_call(name, arguments, span)}
+            verdict = None
+            if self._authorize is not None:
+                job_id = str(arguments.get("id", ""))
+                try:
+                    private = self.jobs.private(job_id)
+                except UnknownJob:
+                    return {"jsonrpc": "2.0", "id": rid, "result": unknown_job_result(job_id, traceparent=span)}
+                verdict = self._authorize(private["capability"], headers)
+                owner = private.get("delegation")
+                if verdict.get("ok") and owner and (owner.get("principal"), owner.get("caller")) != (verdict.get("principal"), verdict.get("caller")):
+                    verdict = {"ok": False, "code": "scope-not-granted", "detail": "job-of-another-caller"}
+                if not verdict.get("ok"):
+                    import fabric_delegation as _fd  # noqa: E402 - only a gated server needs it
+                    return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(verdict, traceparent=span)}
+            return {"jsonrpc": "2.0", "id": rid, "result": self._job_call(name, arguments, span, verdict)}
         handler = self.handlers.get(name)
         if handler is None:
             return self._error(rid, -32602, "Unknown tool: %s." % name)
+        delegation = None
+        if self._authorize is not None:
+            verdict = self._authorize(name, headers)
+            if not verdict.get("ok"):
+                import fabric_delegation as _fd  # noqa: E402 - only a gated server needs it
+                return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(verdict, traceparent=span)}
+            delegation = verdict
         try:
-            structured = handler(arguments, CallContext(self, name, arguments, span))
+            structured = handler(arguments, CallContext(self, name, arguments, span, delegation))
         except InteropError as exc:
             return {"jsonrpc": "2.0", "id": rid, "result": tool_result({"error": {"code": "tool-error", "message": str(exc)}}, is_error=True, traceparent=span)}
         return {"jsonrpc": "2.0", "id": rid, "result": tool_result(structured, traceparent=span)}
 
-    def _job_call(self, name: str, arguments: Dict[str, Any], span: str) -> Dict[str, Any]:
+    def _job_call(self, name: str, arguments: Dict[str, Any], span: str,
+                  delegation: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         job_id = str(arguments.get("id", ""))
         try:
             job_span = self.jobs.traceparent(job_id) or span
@@ -566,7 +599,7 @@ class McpToolServer:
                 matched = self.jobs.answer(job_id, responses)
                 if matched and self._on_input:
                     private = self.jobs.private(job_id)
-                    self._on_input(job_id, matched, CallContext(self, private["capability"], private["input"], job_span))
+                    self._on_input(job_id, matched, CallContext(self, private["capability"], private["input"], job_span, delegation))
             return tool_result({"job": self.jobs.get(job_id)}, traceparent=job_span)
         except UnknownJob:
             return unknown_job_result(job_id, traceparent=span)

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_service.py

@@ -63,6 +63,9 @@ DEFAULT_EXIT_TIMEOUT = 15
 LOG_MAX_BYTES = 5 * 1024 * 1024
 LOG_BACKUPS = 5
 LOGIN_CODE_TTL_SECONDS = 120
+# DEC-0039 (service.md "The session's lifetime"): the longest a service may keep an operator session.
+OPERATOR_SESSION_IDLE_SECONDS = 12 * 60 * 60
+OPERATOR_SESSION_MAX_SECONDS = 7 * 24 * 60 * 60
 EVENTS_DEFAULT_LIMIT = 50
 EVENTS_MAX_LIMIT = 200
 LEVELS = ("info", "notice", "warning", "error")
@@ -1203,17 +1206,35 @@ class Drain:
 # --- operator login ----------------------------------------------------------
 
 class LoginCodes:
-    """Single-use login codes (<=120 s), recorded as used BEFORE they are honoured,
-    and HMAC-signed session cookies revoked by rotating the key."""
+    """Single-use login codes (<=120 s), recorded as used BEFORE they are honoured, and operator
+    sessions with the DEC-0039 lifetime: a session ends 12 h after its last use, 7 days after the code
+    was redeemed, on logout, and when the descriptor token rotates. The server enforces all four: the
+    cookie carries a signed claim (session id, sign-in time, token revision) and the code store keeps a
+    record per session (last use, logout). Rotating the key with revoke_all() ends every session."""
 
     def __init__(self, state_dir: Optional[Path], ttl: int = LOGIN_CODE_TTL_SECONDS, *,
-                 store: Optional["MemoryCodeStore"] = None, key: Optional[bytes] = None):
-        # A local service keeps codes and the key in files. An online one (DEC-0019) usually has no
-        # durable disk: pass state_dir=None with store=MemoryCodeStore() (a restart forgets every
-        # code, so none can be replayed) and key= bytes from a platform secret (sessions survive a deploy).
+                 store: Optional["MemoryCodeStore"] = None, key: Optional[bytes] = None,
+                 token: "Optional[str | Callable[[], str]]" = None,
+                 idle_seconds: int = OPERATOR_SESSION_IDLE_SECONDS,
+                 max_seconds: int = OPERATOR_SESSION_MAX_SECONDS,
+                 clock: Callable[[], float] = time.time):
+        # A local service keeps codes, sessions and the key in files. An online one (DEC-0019) usually has
+        # no durable disk: pass state_dir=None with store=MemoryCodeStore() and key= bytes from a platform
+        # secret. A memory store forgets codes AND sessions on a restart, so a deploy signs the operator
+        # out (the host signs in again on the page's 401); pass a durable store to keep sessions.
+        # token= is the descriptor token, or a callable returning the current one: a session begun under
+        # one token is refused once it rotates. A service MAY shorten either bound, never lengthen one.
         self.ttl = min(ttl, LOGIN_CODE_TTL_SECONDS)
+        self.idle_seconds = _session_bound(idle_seconds, OPERATOR_SESSION_IDLE_SECONDS)
+        self.max_seconds = _session_bound(max_seconds, OPERATOR_SESSION_MAX_SECONDS)
+        # One lock around every load-modify-save, so a concurrent refresh never saves over a logout or a
+        # burned code (a threading server checks sessions on several threads; the instance lock keeps
+        # other processes out of the state directory).
+        self._lock = threading.RLock()
         self._store = store
         self._fixed_key = key
+        self._token = token
+        self._clock = clock
         if state_dir is not None:
             self.dir = ensure_private_dir(Path(state_dir))
             self._key_path = self.dir / "session.key"
@@ -1239,7 +1260,7 @@ class LoginCodes:
             return {}
 
     def _save(self, codes: Dict[str, Any]) -> None:
-        horizon = time.time() - 3600
+        horizon = self._clock() - 3600
         codes = {k: v for k, v in codes.items() if v.get("expires", 0) > horizon}
         if self._store is not None:
             self._store.save(codes)
@@ -1247,39 +1268,101 @@ class LoginCodes:
         atomic_write(self._codes_path, json.dumps(codes).encode(), 0o600)
 
     def issue(self) -> Dict[str, str]:
-        code = secrets.token_urlsafe(24)
-        expires = time.time() + self.ttl
-        codes = self._load()
-        codes[hashlib.sha256(code.encode()).hexdigest()] = {"expires": expires, "used": False}
-        self._save(codes)
-        at = _dt.datetime.fromtimestamp(expires, _dt.timezone.utc).replace(microsecond=0)
-        return {"url": "/fabric/v1/login?code=" + code, "expiresAt": at.isoformat().replace("+00:00", "Z")}
+        with self._lock:
+            code = secrets.token_urlsafe(24)
+            expires = self._clock() + self.ttl
+            codes = self._load()
+            codes[hashlib.sha256(code.encode()).hexdigest()] = {"expires": expires, "used": False}
+            self._save(codes)
+            at = _dt.datetime.fromtimestamp(expires, _dt.timezone.utc).replace(microsecond=0)
+            return {"url": "/fabric/v1/login?code=" + code, "expiresAt": at.isoformat().replace("+00:00", "Z")}
 
     def redeem(self, code: Optional[str]) -> Optional[str]:
         """Return a session cookie value, or None. The code is burned even when it has expired."""
-        if not code or not _CODE.match(code):
+        with self._lock:
+            if not code or not _CODE.match(code):
+                return None
+            digest = hashlib.sha256(code.encode()).hexdigest()
+            codes = self._load()
+            entry = codes.get(digest)
+            if not entry or entry.get("used"):
+                return None
+            entry["used"] = True
+            self._save(codes)
+            now = self._clock()
+            if entry.get("expires", 0) < now:
+                return None
+            session_id = secrets.token_urlsafe(18)
+            signed_in = int(now)
+            codes[self._record_key(session_id)] = {"expires": signed_in + self.max_seconds,
+                                                   "signedInAt": signed_in, "lastUsedAt": now}
+            self._save(codes)
+            claim = "v2.%s.%d.%s" % (session_id, signed_in, self._token_revision())
+            return claim + "." + self._mac(claim)
+
+    def session_valid(self, cookie_value: Optional[str]) -> bool:
+        """True while the session is live; a use within the bounds refreshes the idle bound."""
+        with self._lock:
+            parsed = self._parse(cookie_value)
+            if parsed is None:
+                return False
+            session_id, signed_in = parsed
+            now = self._clock()
+            if now >= signed_in + self.max_seconds:
+                return False
+            codes = self._load()
+            record = codes.get(self._record_key(session_id))
+            if not record or record.get("signedInAt") != signed_in or record.get("loggedOutAt") is not None:
+                return False
+            last = float(record.get("lastUsedAt", 0))
+            if now >= last + self.idle_seconds:
+                return False
+            if now - last >= min(60, max(1, self.idle_seconds // 10)):
+                record["lastUsedAt"] = now
+                self._save(codes)
+            return True
+
+    def logout(self, cookie_value: Optional[str]) -> bool:
+        """End this session on the server: every copy of the cookie is refused from now on. Clear the
+        browser's copy with expired_session_cookie_header(). False when there was no live record."""
+        with self._lock:
+            parsed = self._parse(cookie_value)
+            if parsed is None:
+                return False
+            codes = self._load()
+            record = codes.get(self._record_key(parsed[0]))
+            if not record or record.get("signedInAt") != parsed[1] or record.get("loggedOutAt") is not None:
+                return False
+            record["loggedOutAt"] = self._clock()
+            self._save(codes)
+            return True
+
+    def _parse(self, cookie_value: Optional[str]) -> Optional[Tuple[str, int]]:
+        """The signed claim of a cookie under the current key and token, or None."""
+        if not isinstance(cookie_value, str) or not cookie_value.isascii():
+            return None
+        parts = cookie_value.split(".")
+        if len(parts) != 5 or parts[0] != "v2" or not parts[1] or not parts[2].isdigit():
             return None
-        digest = hashlib.sha256(code.encode()).hexdigest()
-        codes = self._load()
-        entry = codes.get(digest)
-        if not entry or entry.get("used"):
+        claim, mac = ".".join(parts[:4]), parts[4]
+        if not hmac.compare_digest(mac, self._mac(claim)):
             return None
-        entry["used"] = True
-        self._save(codes)
-        if entry.get("expires", 0) < time.time():
+        if not hmac.compare_digest(parts[3], self._token_revision()):
             return None
-        return self._sign(secrets.token_urlsafe(18))
+        return parts[1], int(parts[2])
 
-    def _sign(self, session_id: str) -> str:
-        mac = hmac.new(self._key(), session_id.encode(), hashlib.sha256).hexdigest()
-        return session_id + "." + mac
+    def _mac(self, claim: str) -> str:
+        return hmac.new(self._key(), claim.encode(), hashlib.sha256).hexdigest()
 
-    def session_valid(self, cookie_value: Optional[str]) -> bool:
-        if not cookie_value or "." not in cookie_value:
-            return False
-        session_id, mac = cookie_value.rsplit(".", 1)
-        expected = hmac.new(self._key(), session_id.encode(), hashlib.sha256).hexdigest()
-        return hmac.compare_digest(mac, expected)
+    def _token_revision(self) -> str:
+        token = self._token() if callable(self._token) else self._token
+        if not token:
+            return "-"
+        return hmac.new(self._key(), b"token-revision\0" + token.encode(), hashlib.sha256).hexdigest()[:16]
+
+    @staticmethod
+    def _record_key(session_id: str) -> str:
+        return "s:" + hashlib.sha256(session_id.encode()).hexdigest()
 
     def revoke_all(self) -> None:
         if self._fixed_key is not None:
@@ -1287,6 +1370,13 @@ class LoginCodes:
         atomic_write(self._key_path, secrets.token_bytes(32), 0o600)
 
 
+def _session_bound(value: Any, longest: int) -> int:
+    """A session bound in seconds: a finite number, never longer than the contract's (DEC-0039)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value != value or value in (float("inf"), float("-inf")):
+        raise ServiceError("a session bound must be a finite number of seconds.")
+    return min(int(value), longest)
+
+
 class MemoryCodeStore:
     """DEC-0019: a login-code store held in memory — for an online service with no durable disk."""
 
@@ -1304,15 +1394,21 @@ SESSION_COOKIE = "fabric_session"
 REMOTE_SESSION_COOKIE = "__Host-fabric_session"
 
 
-def session_cookie_header(value: str, max_age: int = 30 * 86400) -> str:
+def session_cookie_header(value: str, max_age: int = OPERATOR_SESSION_MAX_SECONDS) -> str:
+    """The cookie lives no longer than the absolute bound (DEC-0039); the server ends it sooner."""
     return "%s=%s; Path=/; HttpOnly; SameSite=Strict; Max-Age=%d" % (SESSION_COOKIE, value, max_age)
 
 
-def remote_session_cookie_header(value: str, max_age: int = 30 * 86400) -> str:
+def remote_session_cookie_header(value: str, max_age: int = OPERATOR_SESSION_MAX_SECONDS) -> str:
     """DEC-0019: the remote cookie — __Host- name, Secure, no Domain, Path=/."""
     return "%s=%s; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=%d" % (REMOTE_SESSION_COOKIE, value, max_age)
 
 
+def expired_session_cookie_header(remote: bool = False) -> str:
+    """The header that clears the browser's session cookie, sent with a logout."""
+    return (remote_session_cookie_header if remote else session_cookie_header)("", 0)
+
+
 def check_remote_request(origin: str, host: Optional[str], request_origin: Optional[str] = None,
                          sec_fetch_site: Optional[str] = None, forwarded_proto: Optional[str] = None) -> Optional[str]:
     """DEC-0019: the request guard of an online service; returns the refusal sentence or None.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/sample-remote-service.mjs

@@ -27,7 +27,9 @@ if (!origin || k.remoteOriginProblems(origin).length) { console.error(`origin: $
 if (token.length < 16) { console.error('the service token is missing or shorter than 16 characters'); process.exit(2); }
 
 const startedAt = k.nowIso();
-const codes = new k.LoginCodes(null, 120, { store: new k.MemoryCodeStore(), key });
+// DEC-0039: sessions end 12 h after last use, 7 days after sign-in, on logout and when the token rotates.
+// The memory store forgets them on a deploy; the host signs in again on the page's 401.
+const codes = new k.LoginCodes(null, 120, { store: new k.MemoryCodeStore(), key, token });
 const events = [k.makeEvent('1', startedAt, 'service.started', 'info', 'The example agent started.')];
 const tlsSelf = Boolean(args['tls-cert']);
 
@@ -65,6 +67,12 @@ function handler(req, res) {
     if (!session) return send(res, 403, 'This login link has expired or was used. Open the dashboard from Fabric again.', { 'Content-Type': 'text/plain; charset=utf-8' });
     return send(res, 302, null, { Location: '/', 'Set-Cookie': k.remoteSessionCookieHeader(session) });
   }
+  if (req.method === 'POST' && url.pathname === '/logout') {
+    // A browser write: the custom header keeps another site's form from signing the operator out.
+    if (req.headers['x-fabric-request'] !== '1') return send(res, 403, 'Missing request header.', { 'Content-Type': 'text/plain; charset=utf-8' });
+    codes.logout(k.cookieValue(req.headers.cookie, k.REMOTE_SESSION_COOKIE));
+    return send(res, 204, null, { 'Set-Cookie': k.expiredSessionCookieHeader(true) });
+  }
   if (req.method === 'GET' && url.pathname === '/') {
     if (!codes.sessionValid(k.cookieValue(req.headers.cookie, k.REMOTE_SESSION_COOKIE))) return send(res, 401, 'Sign in from Fabric Dashboards.', { 'Content-Type': 'text/plain; charset=utf-8' });
     return send(res, 200, '<!doctype html><meta charset="utf-8"><title>Example Agent</title><h1>Example Agent</h1>', { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': "default-src 'none'" });

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/sample_service.py

@@ -84,7 +84,8 @@ class Service:
         self.log = fs.JsonlEventLog(self.data / "events.jsonl")
         self.usage = fs.JsonlUsageLedger(self.data / "usage.jsonl")  # DEC-0021
         self.usage.prune()
-        self.codes = fs.LoginCodes(self.data / "auth")
+        # DEC-0039: the token= revision ends sessions begun under a token that has since rotated.
+        self.codes = fs.LoginCodes(self.data / "auth", token=self.token)
         self.jobs = fi.JobStore(self.data / "jobs")
         self.mcp = fi.McpToolServer(self.id, VERSION, jobs=self.jobs, on_job_started=self.draft_started, on_input=self.draft_answered)
         for cap in CAPABILITIES:
@@ -255,6 +256,12 @@ def make_handler(svc: Service):
                 if not self._token_ok():
                     return
                 return self._send(200, svc.codes.issue())
+            if url.path == "/logout":
+                # A browser write: the custom header keeps another site's form from signing the operator out.
+                if self.headers.get("X-Fabric-Request") != "1":
+                    return self._send(403, {"error": "Missing request header."})
+                svc.codes.logout(fs.cookie_value(self.headers.get("Cookie")))
+                return self._send(204, None, {"Set-Cookie": fs.expired_session_cookie_header()})
             if url.path == "/api/emit":
                 if not (self._session_ok() or fs.token_matches(self.headers.get("Authorization"), svc.token)):
                     return self._send(401, {"error": "Sign in first."})

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.9.0"
+  version: "0.11.1"
   contract-version: "0.1.0"
-  contract-commit: "a83bec6b47776af688402c18efec507143061f68"
+  contract-commit: "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5"
 ---
 
 # Creating Fabric-compatible agents
@@ -119,7 +119,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
   --schema-base <immutable-base-uri>
 ```
 
-Pin exactly contract `0.1.0` at commit `a83bec6b47776af688402c18efec507143061f68` and
+Pin exactly contract `0.1.0` at commit `8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5` 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