@passioncode-ai/fabric-agent-adapter 0.78.0 → 0.80.2

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/dashboard-only/dashboard_service.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""The entry of a dashboard-only fabric-service/0.1 service (FAA-268), the descriptor install.py wrote.
+
+  python3 dashboard_service.py serve --descriptor <path>
+
+It serves the well-known document (surfaces `dashboard` and `events`, no `mcp`, no `usage`: it calls no model and
+offers no capability), its events feed, the login code and the signed-in page. The page shows `<folder>/snapshot.json`,
+which the person's agent writes from what it read through the Fabric Dashboards MCP (`list_services`, `spend`,
+`connections`) and Project Observatory; the service holds no token but its own and calls nobody. A missing snapshot,
+one that cannot be read and one older than a day are reported in `degraded`, never shown as data.
+
+snapshot.json: {"takenAt": "<RFC 3339>", "sections": [{"title": str, "source": str, "columns": [str], "rows": [[str]]}]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import html
+import json
+import os
+import sys
+import time
+from http.server import BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib.parse import parse_qs, urlparse
+
+if str(Path(__file__).resolve().parent) not in sys.path:  # the kit installed beside it, under `python3 -I` too
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+try:
+    import fabric_service as fs
+except ImportError:  # in the adapter's repository: the kit is two folders up
+    sys.path.append(str(Path(__file__).resolve().parents[2] / "scripts"))
+    import fabric_service as fs
+
+VERSION = "0.1.0"
+STALE_SECONDS = 24 * 3600
+MAX_SNAPSHOT_BYTES = 1048576
+_HERE = Path(__file__).resolve().parent
+KIT_DIR = next((d for d in (_HERE / "kit", _HERE.parents[1] / "assets" / "dashboard-kit")
+                if (d / "fabric-dashboard.css").is_file()), None)
+KIT_FILES = {"/kit/fabric-dashboard.css": ("fabric-dashboard.css", "text/css; charset=utf-8"),
+             "/kit/fabric-dashboard.js": ("fabric-dashboard.js", "text/javascript; charset=utf-8")}
+CONNECTIONS = [{"id": "snapshot", "kind": "store", "target": "snapshot.json",
+                "purpose": "what the person's agent read through the Fabric Dashboards MCP and Project Observatory"}]
+PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>{name}</title>
+<link rel="stylesheet" href="/kit/fabric-dashboard.css"><script src="/kit/fabric-dashboard.js" defer></script>
+</head><body><div class="fd-chrome"><header class="fd-header"><p class="fd-title">{name}</p>
+<span class="fd-chip fd-s-{chip}"><span class="fd-dot"></span>Status: {status}</span></header></div>
+<main class="fd-page">{body}</main></body></html>"""
+
+
+def read_snapshot(path: Path, now: Optional[float] = None) -> Dict[str, Any]:
+    """{"sections": [...], "takenAt": str} or {"degraded": reason}: missing, unreadable, invalid, stale."""
+    try:
+        if path.stat().st_size > MAX_SNAPSHOT_BYTES:
+            return {"degraded": "too-large"}
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {"degraded": "missing"}
+    except (OSError, ValueError, RecursionError):
+        return {"degraded": "unreadable"}
+    sections = doc.get("sections") if isinstance(doc, dict) else None
+    taken = doc.get("takenAt") if isinstance(doc, dict) else None
+    try:
+        at = _dt.datetime.fromisoformat(str(taken).replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return {"degraded": "invalid"}
+    if not isinstance(sections, list) or not all(isinstance(s, dict) for s in sections):
+        return {"degraded": "invalid"}
+    if (now if now is not None else time.time()) - at > STALE_SECONDS:
+        return {"degraded": "stale", "takenAt": taken}
+    return {"sections": sections, "takenAt": taken}
+
+
+def _cell(value: Any) -> str:
+    return html.escape(value if isinstance(value, str) else json.dumps(value, ensure_ascii=False))
+
+
+def render_sections(snapshot: Dict[str, Any]) -> str:
+    if "degraded" in snapshot:
+        return ('<section><h2>No data</h2><p class="fd-hint">The snapshot is %s. Ask your agent to read the Fabric '
+                'Dashboards MCP and Project Observatory and write snapshot.json.</p></section>' % html.escape(snapshot["degraded"]))
+    out = ['<p class="fd-hint">Read at %s.</p>' % _cell(snapshot["takenAt"])]
+    for section in snapshot["sections"]:
+        columns = section.get("columns") if isinstance(section.get("columns"), list) else []
+        rows = section.get("rows") if isinstance(section.get("rows"), list) else []
+        head = "".join("<th>%s</th>" % _cell(c) for c in columns)
+        body = "".join("<tr>%s</tr>" % "".join("<td>%s</td>" % _cell(c) for c in (r if isinstance(r, list) else [r]))
+                       for r in rows[:500])
+        out.append('<section><h2>%s</h2><p class="fd-hint">From %s.</p><table><thead><tr>%s</tr></thead><tbody>%s</tbody>'
+                   "</table></section>" % (_cell(section.get("title", "")), _cell(section.get("source", "")), head, body))
+    return "".join(out)
+
+
+class Service:
+    def __init__(self, descriptor_file: Path):
+        d = json.loads(Path(descriptor_file).read_text(encoding="utf-8"))
+        problems = fs.validate_descriptor(d)
+        if problems:
+            raise fs.ServiceError("Descriptor is invalid: %s." % "; ".join(problems))
+        self.id, self.instance, self.name = d["id"], d["instance"], d["name"]
+        self.port = fs.port_of(d["origin"])
+        self.data = Path(d["paths"]["data"])
+        self.token_file = Path(d["auth"]["tokenFile"]).expanduser()
+        self.started_at = fs.now_iso()
+        self.build = {"commit": os.environ.get("FABRIC_BUILD_COMMIT", "0000000"), "builtAt": self.started_at}
+        self.drain = fs.Drain()
+
+    def start(self) -> None:
+        self.lock = fs.hold_single_instance(self.data)  # the lock before any side effect
+        self.token = fs.ensure_token(self.token_file)
+        self.log = fs.JsonlEventLog(self.data / "events.jsonl")
+        self.codes = fs.LoginCodes(self.data / "auth", token=self.token)
+        self.log.append("service.started", "info", "%s started on build %s." % (self.name, self.build["commit"]))
+
+    def snapshot(self) -> Dict[str, Any]:
+        return read_snapshot(self.data / "snapshot.json")
+
+    def well_known(self) -> Dict[str, Any]:
+        snap = self.snapshot()
+        degraded = [{"source": "snapshot", "reason": snap["degraded"]}] if "degraded" in snap else []
+        return fs.build_well_known(
+            service_id=self.id, instance=self.instance, name=self.name, version=VERSION, build=self.build,
+            started_at=self.started_at, status="ready", degraded=degraded,
+            summary=[{"label": "Sections", "value": len(snap.get("sections") or [])}],
+            surfaces={"dashboard": {"path": "/", "login": True}, "events": {"path": "/fabric/v1/events"}},
+            extensions=dict(fs.dashboard_extension() if KIT_DIR is not None else {},
+                            **fs.connections_extension(CONNECTIONS, degraded=degraded)))
+
+
+def make_handler(svc: Service):
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "fabric-dashboard-only/" + VERSION
+
+        def log_message(self, fmt: str, *args: Any) -> None:
+            return
+
+        def _send(self, status: int, body: Any = None, headers: Optional[Dict[str, str]] = None,
+                  content_type: str = "application/json") -> None:
+            payload = b"" if body is None else (body.encode() if isinstance(body, str) else json.dumps(body).encode())
+            self.send_response(status)
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Content-Security-Policy", "default-src 'none'; style-src 'self'; script-src 'self'; "
+                             "connect-src 'self'; frame-ancestors 'self'")
+            if body is not None:
+                self.send_header("Content-Type", content_type)
+                self.send_header("Content-Length", str(len(payload)))
+            for key, value in (headers or {}).items():
+                self.send_header(key, value)
+            self.end_headers()
+            if payload:
+                self.wfile.write(payload)
+
+        def _guard(self) -> bool:
+            reason = fs.check_request(svc.port, self.headers.get("Host"), self.headers.get("Origin"),
+                                      self.headers.get("Sec-Fetch-Site"))
+            if reason:
+                self._send(403, {"error": reason})
+                return False
+            return True
+
+        def _token_ok(self) -> bool:
+            if fs.token_matches(self.headers.get("Authorization"), svc.token):
+                return True
+            self._send(401, {"error": "The service token is required."}, {"WWW-Authenticate": "Bearer"})
+            return False
+
+        def do_GET(self) -> None:  # noqa: N802
+            if not self._guard():
+                return
+            url = urlparse(self.path)
+            query = parse_qs(url.query)
+            if url.path == "/.well-known/fabric-service":
+                return self._send(200, svc.well_known())
+            if url.path == "/fabric/v1/events":
+                if not self._token_ok():
+                    return
+                try:
+                    limit = fs.parse_limit((query.get("limit") or [None])[0])
+                    return self._send(200, fs.events_page(svc.log.fetch, (query.get("after") or [None])[0], limit))
+                except fs.ServiceError as exc:
+                    return self._send(400, {"error": str(exc)})
+            if url.path == "/fabric/v1/login":
+                cookie = svc.codes.redeem((query.get("code") or [None])[0])
+                if not cookie:
+                    return self._send(403, "This sign-in link was already used or has expired.", content_type="text/plain")
+                return self._send(302, None, {"Location": "/", "Set-Cookie": fs.session_cookie_header(cookie)})
+            if url.path in KIT_FILES and KIT_DIR is not None:
+                name, kind = KIT_FILES[url.path]
+                return self._send(200, (KIT_DIR / name).read_text(encoding="utf-8"), content_type=kind)
+            if url.path == "/":
+                if not svc.codes.session_valid(fs.cookie_value(self.headers.get("Cookie"))):
+                    return self._send(401, "Open this dashboard from Fabric Dashboards.", content_type="text/plain")
+                snap = svc.snapshot()
+                status, chip = ("degraded", "warn") if "degraded" in snap else ("ready", "ok")
+                return self._send(200, PAGE.format(name=html.escape(svc.name), status=status, chip=chip,
+                                                   body=render_sections(snap)), content_type="text/html; charset=utf-8")
+            self._send(404, {"error": "Not found."})
+
+        def do_POST(self) -> None:  # noqa: N802
+            if not self._guard():
+                return
+            url = urlparse(self.path)
+            if url.path == "/fabric/v1/login-code":
+                if not self._token_ok():
+                    return
+                return self._send(200, svc.codes.issue())
+            if url.path == "/logout":
+                if self.headers.get("X-Fabric-Request") != "1":  # another site's form never signs the operator out
+                    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()})
+            self._send(404, {"error": "Not found."})
+
+    return Handler
+
+
+def serve(descriptor_file: Path) -> int:
+    svc = Service(descriptor_file)
+    svc.start()
+    server = fs.LoopbackHTTPServer(("127.0.0.1", svc.port), make_handler(svc))
+    svc.drain.install(lambda drained: server.shutdown(),
+                      on_stopping=lambda: svc.log.append("service.stopping", "info", "%s is stopping." % svc.name))
+    try:
+        server.serve_forever(poll_interval=0.2)
+    finally:
+        server.server_close()
+        svc.lock.release()
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    fs.add_supervisor_argument(parser)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("serve")
+    fs.add_supervisor_argument(p)
+    p.add_argument("--descriptor", required=True, help="the path install.py printed")
+    args = parser.parse_args(argv)
+    try:
+        return serve(Path(args.descriptor))
+    except (fs.ServiceError, OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/dashboard-only/install.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Install a dashboard-only fabric-service/0.1 service (FAA-268): the twin of install.py, the same flags, the same
+// descriptor bytes (but installedAt) and the same last stdout line. Read install.py's docstring for the rules.
+//   node install.mjs --id <id> --folder <folder> [--instance default] [--name NAME] [--repository URI]
+//                    [--port N] [--label LABEL --plist PLIST] [--services-dir DIR] [--json]
+// Exit codes: 0 installed or already installed, 1 refused (the reason on stderr), 2 usage.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const beside = path.join(here, 'fabric-service.mjs'); // the kit installed beside it, else the adapter's repository
+const k = await import(pathToFileURL(fs.existsSync(beside) ? beside : path.join(here, '..', '..', 'scripts', 'fabric-service.mjs')).href);
+
+export const VERSION = '0.1.0';
+export const TOOL = `dashboard-only install ${VERSION}`;
+export const PORT_FIRST = 47300;
+export const PORT_LAST = 47999;
+const ATTEMPTS = 8;
+
+function claimedPorts(services, me) {
+  const ports = new Set();
+  for (const [, other] of k.readDescriptors(services)) {
+    if (`${other.id}.${other.instance ?? 'default'}` === me || other.placement === 'remote') continue;
+    try { ports.add(k.portOf(String(other.origin ?? ''))); } catch { /* an app names no port */ }
+  }
+  return ports;
+}
+
+function freeNow(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen({ host: '127.0.0.1', port, exclusive: true }, () => server.close(() => resolve(true)));
+  });
+}
+
+async function candidates(services, me, wanted) {
+  if (wanted !== undefined) return [wanted];
+  const taken = claimedPorts(services, me);
+  const out = [];
+  for (let p = PORT_FIRST; p <= PORT_LAST && out.length < ATTEMPTS; p += 1) {
+    if (!taken.has(p) && await freeNow(p)) out.push(p);
+  }
+  return out;
+}
+
+function gitOrigin(folder) {
+  try {
+    const url = execFileSync('git', ['-C', folder, 'config', '--get', 'remote.origin.url'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+    if (!url.startsWith('https://')) return null;
+    return url.endsWith('.git') ? url.slice(0, -4) : url;
+  } catch { return null; }
+}
+
+// As Python's Path.resolve(): the longest existing ancestor with its links resolved, then the rest as written.
+function resolved(p) {
+  let head = path.resolve(p);
+  const rest = [];
+  while (!fs.existsSync(head) && path.dirname(head) !== head) { rest.unshift(path.basename(head)); head = path.dirname(head); }
+  return path.join(fs.realpathSync(head), ...rest);
+}
+
+// The line install.py prints: json.dumps(result, ensure_ascii=False), key order descriptor, key, port.
+export const line = (r) => `{"descriptor": ${JSON.stringify(r.descriptor)}, "key": ${JSON.stringify(r.key)}, "port": ${r.port}}`;
+
+function answer(file, d) {
+  return { descriptor: file, key: `${d.id}.${d.instance}`, port: k.portOf(d.origin) };
+}
+
+function build(a, folder, port, repository) {
+  const d = {
+    protocol: k.PROTOCOL, id: a.id, instance: a.instance, name: a.name || a.id,
+    summary: 'A dashboard-only service: no capabilities, no provider keys.',
+    origin: `http://127.0.0.1:${port}`,
+    auth: { tokenFile: path.join(folder, 'service.token') },
+    lifecycle: a.label ? { manager: 'launchd', label: a.label, plist: a.plist } : { manager: 'none' },
+    paths: { data: folder, logs: [] },
+    installedAt: k.nowIso(),
+    installedBy: { by: 'person', role: 'operator', tool: TOOL },
+  };
+  if (repository) d.source = { repository };
+  return d;
+}
+
+export async function install(a) {
+  const services = a.servicesDir ? k.expand(a.servicesDir) : k.servicesDir();
+  const folder = resolved(k.expand(a.folder));
+  const me = `${a.id}.${a.instance}`;
+  const installed = k.descriptorPath(a.id, a.instance, services);
+  if (fs.existsSync(installed) && fs.statSync(installed).isFile()) {
+    let current;
+    try { current = JSON.parse(fs.readFileSync(installed, 'utf8')); } catch (err) {
+      throw new k.ServiceError(`The installed descriptor ${installed} cannot be read (${err.message}); nothing was written.`);
+    }
+    const by = current?.installedBy;
+    if (!(by && typeof by === 'object' && String(by.tool ?? '').startsWith('dashboard-only install'))) {
+      throw new k.ServiceError(`${me} is installed by another installer (${installed}); nothing was written.`);
+    }
+    if (String(current.paths?.data ?? '') !== folder) {
+      throw new k.ServiceError(`${me} is installed with the folder ${current.paths?.data}, not ${folder}; nothing was written.`);
+    }
+    return { result: answer(installed, current), already: true };
+  }
+  if (a.label && !a.plist) throw new k.ServiceError("--label needs --plist, the launchd job's plist path.");
+  const repository = a.repository || gitOrigin(folder);
+  const ports = await candidates(services, me, a.port);
+  if (!ports.length) throw new k.ServiceError(`No free port in ${PORT_FIRST}-${PORT_LAST} that no other descriptor claims.`);
+  let last = null;
+  for (const port of ports) {
+    const d = build(a, folder, port, repository);
+    const problems = k.validateDescriptor(d);
+    const refusal = problems.length ? `Descriptor is invalid: ${problems.join('; ')}.` : k.sourceRefusal(d, services);
+    if (refusal) throw new k.ServiceError(refusal); // before any side effect
+    let file;
+    try { // the descriptor first: a port claim the kit refuses leaves no folder and no token behind
+      file = k.writeDescriptor(d, services);
+    } catch (err) {
+      if (!String(err.message).includes('already claimed') || a.port !== undefined) throw err;
+      last = err;
+      continue;
+    }
+    try {
+      k.ensurePrivateDir(folder);
+      k.ensureToken(path.join(folder, 'service.token')); // 0600, never printed
+    } catch (err) {
+      k.removeDescriptor(a.id, a.instance, services); // no descriptor names a token that is not there
+      throw err;
+    }
+    return { result: answer(file, d), already: false };
+  }
+  throw last;
+}
+
+async function main(argv) {
+  let a;
+  try {
+    const { values } = parseArgs({ args: argv, strict: true, options: {
+      id: { type: 'string' }, folder: { type: 'string' }, instance: { type: 'string', default: 'default' },
+      name: { type: 'string' }, repository: { type: 'string' }, port: { type: 'string' }, label: { type: 'string' },
+      plist: { type: 'string' }, 'services-dir': { type: 'string' }, json: { type: 'boolean', default: false } } });
+    if (!values.id || !values.folder) throw new Error('--id and --folder are required');
+    if (values.port !== undefined && !/^[0-9]{1,5}$/.test(values.port)) throw new Error('--port is a number');
+    a = { ...values, servicesDir: values['services-dir'], port: values.port === undefined ? undefined : Number(values.port) };
+  } catch (err) {
+    process.stderr.write(`usage: node install.mjs --id <id> --folder <folder> [--json] (${err.message})\n`);
+    return 2;
+  }
+  try {
+    const { result, already } = await install(a);
+    if (!a.json) process.stdout.write(`${already ? 'Already installed:' : 'Installed'} ${result.key} on port ${result.port}: ${result.descriptor}\n`);
+    process.stdout.write(`${line(result)}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+}
+
+// Through a symlinked folder too (board thread b42e16b7): argv[1] is the link, import.meta.url the resolved file.
+const invoked = (() => { try { return fs.realpathSync(process.argv[1] ?? ''); } catch { return null; } })();
+if (invoked === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/dashboard-only/install.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Install a dashboard-only fabric-service/0.1 service (FAA-268): a descriptor with a dashboard and nothing else.
+
+  python3 install.py --id <id> --folder <folder> [--instance default] [--name NAME] [--repository URI]
+                     [--port N] [--label LABEL --plist PLIST] [--services-dir DIR] [--json]
+
+The service has no capabilities, no provider keys and no token of anybody else: its page shows what the person's agent
+reads through the Fabric Dashboards MCP (`list_services`, `spend`, `connections`) and Project Observatory and writes
+into `<folder>/snapshot.json`. The installer picks a loopback port no other descriptor claims and that is free now,
+writes the token file (0600) and the descriptor through the kit's `write_descriptor`, whose port claim check refuses a
+port another descriptor declares. The last stdout line is `{"descriptor": <path>, "key": "<id>.<instance>", "port": <n>}`
+(`--json` prints only it). A repeat with the same `--id` changes nothing and answers the same line. The HA-1 port claim
+file per OS account is not written: its schema waits on the contract's CT-228.
+
+Exit codes: 0 installed or already installed, 1 refused (the reason on stderr), 2 usage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+if str(Path(__file__).resolve().parent) not in sys.path:  # the kit installed beside it, under `python3 -I` too
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+try:
+    import fabric_service as fs
+except ImportError:  # in the adapter's repository: the kit is two folders up
+    sys.path.append(str(Path(__file__).resolve().parents[2] / "scripts"))
+    import fabric_service as fs
+
+VERSION = "0.1.0"
+TOOL = "dashboard-only install %s" % VERSION
+PORT_FIRST, PORT_LAST = 47300, 47999  # the recipe's range; a port another descriptor claims is skipped
+ATTEMPTS = 8  # a port taken between the check and the write is retried on the next one
+
+
+def claimed_ports(services: Optional[Path], me: str) -> set:
+    ports = set()
+    for _path, other in fs.read_descriptors(services):
+        if "%s.%s" % (other.get("id"), other.get("instance", "default")) == me or other.get("placement") == "remote":
+            continue
+        try:
+            ports.add(fs.port_of(str(other.get("origin", ""))))
+        except fs.ServiceError:
+            continue
+    return ports
+
+
+def free_now(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("127.0.0.1", port))
+            return True
+        except OSError:
+            return False
+
+
+def candidates(services: Optional[Path], me: str, wanted: Optional[int]) -> List[int]:
+    if wanted is not None:
+        return [wanted]
+    taken = claimed_ports(services, me)
+    return [p for p in range(PORT_FIRST, PORT_LAST + 1) if p not in taken and free_now(p)][:ATTEMPTS]
+
+
+def git_origin(folder: Path) -> Optional[str]:
+    """The folder's own `origin`, when it is an https URL the kit accepts as source.repository."""
+    try:
+        out = subprocess.run(["git", "-C", str(folder), "config", "--get", "remote.origin.url"],
+                             capture_output=True, text=True, timeout=5)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    url = out.stdout.strip()
+    if out.returncode != 0 or not url.startswith("https://"):
+        return None
+    return url[:-4] if url.endswith(".git") else url
+
+
+def answer(descriptor_file: Path, descriptor: Dict[str, Any]) -> Dict[str, Any]:
+    return {"descriptor": str(descriptor_file), "key": "%s.%s" % (descriptor["id"], descriptor["instance"]),
+            "port": fs.port_of(descriptor["origin"])}
+
+
+def build(args: argparse.Namespace, folder: Path, port: int, repository: Optional[str]) -> Dict[str, Any]:
+    descriptor: Dict[str, Any] = {
+        "protocol": fs.PROTOCOL, "id": args.id, "instance": args.instance, "name": args.name or args.id,
+        "summary": "A dashboard-only service: no capabilities, no provider keys.",
+        "origin": "http://127.0.0.1:%d" % port,
+        "auth": {"tokenFile": str(folder / "service.token")},
+        "lifecycle": {"manager": "launchd", "label": args.label, "plist": args.plist} if args.label else {"manager": "none"},
+        "paths": {"data": str(folder), "logs": []},
+        "installedAt": fs.now_iso(),
+        "installedBy": {"by": "person", "role": "operator", "tool": TOOL},
+    }
+    if repository:
+        descriptor["source"] = {"repository": repository}
+    return descriptor
+
+
+def install(args: argparse.Namespace) -> Dict[str, Any]:
+    services = Path(args.services_dir).expanduser() if args.services_dir else None
+    folder = Path(args.folder).expanduser().resolve()
+    me = "%s.%s" % (args.id, args.instance)
+    installed = fs.descriptor_path(args.id, args.instance, services)
+    if installed.is_file():
+        try:
+            current = json.loads(installed.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise fs.ServiceError("The installed descriptor %s cannot be read (%s); nothing was written." % (installed, exc))
+        by = current.get("installedBy") if isinstance(current, dict) else None
+        if not (isinstance(by, dict) and str(by.get("tool", "")).startswith("dashboard-only install")):
+            raise fs.ServiceError("%s is installed by another installer (%s); nothing was written." % (me, installed))
+        if Path(str((current.get("paths") or {}).get("data", ""))) != folder:
+            raise fs.ServiceError("%s is installed with the folder %s, not %s; nothing was written."
+                                  % (me, (current.get("paths") or {}).get("data"), folder))
+        return answer(installed, current)
+    if args.label and not args.plist:
+        raise fs.ServiceError("--label needs --plist, the launchd job's plist path.")
+    repository = args.repository or git_origin(folder)
+    ports = candidates(services, me, args.port)
+    if not ports:
+        raise fs.ServiceError("No free port in %d-%d that no other descriptor claims." % (PORT_FIRST, PORT_LAST))
+    last: Optional[Exception] = None
+    for port in ports:
+        descriptor = build(args, folder, port, repository)
+        problems = fs.validate_descriptor(descriptor)
+        refusal = ("Descriptor is invalid: %s." % "; ".join(problems) if problems else fs.source_refusal(descriptor, services))
+        if refusal:  # before any side effect: a refused install leaves nothing behind
+            raise fs.ServiceError(refusal)
+        try:  # the descriptor first: a port claim the kit refuses leaves no folder and no token behind
+            path = fs.write_descriptor(descriptor, services)
+        except fs.ServiceError as exc:  # the kit's port claim: another descriptor declared it in between
+            if "already claimed" not in str(exc) or args.port is not None:
+                raise
+            last = exc
+            continue
+        try:
+            fs.ensure_private_dir(folder)
+            fs.ensure_token(folder / "service.token")  # 0600, never printed
+        except (OSError, fs.ServiceError):
+            fs.remove_descriptor(args.id, args.instance, services)  # no descriptor names a token that is not there
+            raise
+        return answer(path, descriptor)
+    raise fs.ServiceError(str(last))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--id", required=True)
+    parser.add_argument("--folder", required=True, help="the service's own folder: token, data, snapshot")
+    parser.add_argument("--instance", default="default")
+    parser.add_argument("--name")
+    parser.add_argument("--repository", help="the repository its code is built from (default: the folder's https origin)")
+    parser.add_argument("--port", type=int, help="this port and no other")
+    parser.add_argument("--label", help="a launchd job's label, with --plist")
+    parser.add_argument("--plist")
+    parser.add_argument("--services-dir", help="the descriptor directory (default: FABRIC_SERVICES_DIR, else the OS's)")
+    parser.add_argument("--json", action="store_true", help="print only the JSON line")
+    args = parser.parse_args(argv)
+    try:
+        installed_before = fs.descriptor_path(args.id, args.instance,
+                                              Path(args.services_dir).expanduser() if args.services_dir else None).is_file()
+        result = install(args)
+    except (fs.ServiceError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if not args.json:
+        print("%s %s on port %d: %s" % ("Already installed:" if installed_before else "Installed", result["key"],
+                                       result["port"], result["descriptor"]))
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/key-delivery-door/README.md

@@ -0,0 +1,57 @@
+# Recipe: a key-delivery door
+
+A door is the command a service's owner ships so an agent gets a key for one recipient without anybody seeing it: it
+asks the issuer for the key and hands it on sealed. This template (FAA-238) asks once, prints the key as one
+`fabric-credential-envelope/1` (contract DEC-0111, [credentials](https://github.com/passioncode-ai/fabric-agent-contract/blob/main/docs/specification/credentials.md#the-envelope))
+on stdout, and **writes into no store**: the receiver writes the recipient's slot. Twins: `door.py` and `door.mjs`,
+the same flags, exit codes and line. Tests: `test/test_recipe_key_delivery_door.py` (both twins, a fake issuer and a
+test sealer that encrypts nothing).
+
+It follows Project Observatory's V2 spec (*Receive a key from an external issue door*, sections 3.2 and 8, agreed on
+board thread `e7fbd27d`) until Observatory's OBS-360 ships `receive`: the receiver is
+
+```bash
+python "$(project-observatory full-path)/tools/vault.py" receive PROJECT ENV NAME --from-command --json -- \
+  python3 door.py --slot EXAMPLE_KEY --provider example-issuer --agent-ref urn:fabric:agent:example:example-agent \
+    --recipient m-b#kem --context personal --issuer-command "example-issuer mint" --seal-command "example-sealer"
+```
+
+so the agent names the door and the slot and sees only the receiver's answer, never the key. A plan that says the door
+"writes into the recipient's slot" is met this way: the slot is written, by the receiver that runs the door. When
+OBS-360 lands with other names, the door's line and exit codes stay; only the command above changes.
+
+## The two commands
+
+The door owner supplies them; a value crosses only their stdin and stdout, in memory, and never argv, the environment,
+a file or a log.
+
+- `--issuer-command` reads the request on stdin (`{slot, provider, agentRef, context, requestId?}`: names only) and
+  prints `{"value": "<key>", "credentialExpiresAt"?: "<RFC 3339>"}`, or `{"refused": {"code": "<slug>"}}`. Exit 75
+  (`EX_TEMPFAIL`) is a transport failure; any other non-zero exit is a refusal.
+- `--seal-command` reads `{"value", "header"}` (the header fields the door fixes: type, recipient, context, agentRef,
+  slot, provider, and in an organization's context requestId and credentialExpiresAt) and prints the envelope: HPKE
+  base mode suite `[16, 1, 1]` to the recipient's `#kem`, signed as DEC-0111 says (the contract's `sealCredential`; its
+  sequence per `(context, agentRef, slot)` is the sealer's to keep). The standard library has no HPKE, so the template
+  never seals by itself.
+
+Before printing, the door checks the envelope against the schema's shape at the adapter's pin and against what it
+asked for (the same slot, recipient, context, agentRef, provider and requestId; `exp` at most 24 hours after `iat`;
+`credentialExpiresAt` at most 30 days, in an organization's context only), and refuses an envelope that carries the
+value in clear. It decrypts and verifies nothing: that is the target's `checkCredentialEnvelope`. A child's stderr is
+never forwarded, and the door's own messages never hold the value.
+
+## Exit codes
+
+As Observatory's `receive --from-command` maps them (V2 section 8, from the access agent's door):
+
+| Exit | Means | Observatory reads |
+|---|---|---|
+| 0 | delivered: the envelope is the one line on stdout | the envelope |
+| 2 | usage: a flag missing or out of shape (an organization's context needs `--request-id`, a personal one takes none) | `issuer-usage` |
+| 3 | the issuer refused (its code, when it gave a slug) | `issuer-refused` |
+| 4 | no key in the issuer's answer | `issuer-no-key` |
+| 5 | the store refused: the sealer refused, or its envelope fails the checks above | `store-refused` |
+| 1 | a transport failure that outlived its retries | `issuer-command-failed` |
+
+Only a transport failure is retried: three tries in all, one and then two seconds apart. A refusal, a missing key and a
+sealing failure are answered at once, since asking again would ask the issuer for a second key.