@passioncode-ai/passioncode 0.1.8 → 0.1.10

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -15,10 +15,10 @@ license: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). No network or package install; the contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.4.3"
+  version: "0.5.1"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "a5a27092ba0dcc5facfbeae8b359146dfb403e9a"
+  extension-commit: "9cd778eb6f14b977f9a5b4930826f62dc95c5619"
 ---
 
 # Building Fabric services
@@ -73,6 +73,13 @@ Answer before writing code, and record the answers in the project README:
 Read [the surfaces and auth reference](references/surfaces-and-auth.md) when wiring
 MCP registration into a client config, the login flow or the CSRF header.
 
+When other agents or Fabric call the service over MCP, it follows `fabric-interop/0.1`:
+each manifest capability is the tool of its name, long work is a job with a stable id,
+a question for a person is an elicitation, and every call carries one trace. Read
+[the interop reference](references/interop.md) before writing an MCP tool; the helpers
+are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
+[`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs).
+
 ## Step 2 — the non-negotiables
 
 1. **Loopback only.** Bind `127.0.0.1`. Refuse any `Host` other than
@@ -144,6 +151,13 @@ On every request call `check_request(port, host, origin, sec_fetch_site)` and an
 `SIGTERM` drains in-flight work within `ExitTimeOut`, then exits; interrupted work
 resumes on the next start.
 
+The MCP surface (`POST /mcp`, service token) is `fabric_interop.McpToolServer.handle`
+in Python; jobs live in `fabric_interop.JobStore(dirs["data"] / "jobs")`, created after
+the lock like every other piece of state. Add `"mcp": {"path": "/mcp", "transport":
+"streamable-http", "capabilities": [...]}` to the well-known surfaces, and point the
+descriptor's `fabricManifest` at a manifest whose service key names this
+`<id>.<instance>` — `sample_service.py register` shows both.
+
 ## Step 4 — install it
 
 The installer, not the service, owns the plist and the descriptor. Sequence:
@@ -186,7 +200,9 @@ python3 <skill-dir>/scripts/check_service.py <id>[.<instance>]
 It reports `PASS`, `FAIL` or `NOT_RUN` per rule (descriptor, port claim, well-known
 shape, identity, latency, Host/Origin/cross-site guards, loopback bind, token file,
 events auth and shape, single-use login, state outside code, instance lock, plist,
-launchd pid equals answering pid) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
+launchd pid equals answering pid, and the `interop.*` rules: manifest link, capability
+list, tools equal to the manifest, job tools, unknown job, trace propagation, event
+trace pairs) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
 name it in the report.
 
 Then prove the lock: start a second copy by hand against the same data directory; it

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md

@@ -0,0 +1,77 @@
+# Being called: `fabric-interop/0.1`
+
+Normative source: the Fabric Agent Contract's `docs/specification/interop.md` (DEC-0016, rulings DEC-0017)
+at the commit this plugin pins. This page says how the kit implements it; where the two
+differ, the contract is right.
+
+A service that other agents — and Fabric — call does five things. Each has one helper in
+`scripts/fabric_interop.py` (Python) and `scripts/fabric-interop.mjs` (Node).
+
+| Rule | What the service does | Helper |
+|---|---|---|
+| C3.1 capability = tool | serves each `mcp` capability of its manifest as the MCP tool of the same name, with the manifest's input schema unchanged, its output schema unchanged — or, for a job, wrapped as `oneOf[result envelope, job handle]` — and annotations from the effect | `tool_for_capability` / `toolForCapability`, `job_tool_output_schema`, `expected_annotations` |
+| C3.2 long work = job | a capability whose work can outlive one request declares `"job": true` in its interop block, returns `{"job": {"id", "status": "working"}}`, and serves `fabric.job.get` and `fabric.job.cancel` | `JobStore`, `McpToolServer` (Python), `unknown_job_result` |
+| C3.2 result | a completed job carries the full result envelope — the shape a synchronous call returns: `id`, `contractVersion`, `outcome`, `done`, `proof`, `scope`, `notVerified`, `artifacts`, `createdAt`, `producer`, `output`, `usage`, and its `trace` | `result_envelope` / `resultEnvelope` |
+| C3.3 a person decides | the job goes `input_required` with an elicitation: a titled single-select in form mode, and URL mode for anything secret | `choice_request`, `form_request`, `url_request` |
+| C3.4 trace | every call runs as a child span of the caller's `_meta.traceparent`; outgoing calls carry the same trace; the result envelope records it; events about traced work carry `traceId` and `spanId`, events about untraced work none | `child_traceparent`, `trace_ids`, `make_event(..., trace_id=, span_id=)` |
+
+The interop block sits in the manifest under the capability's `extensions`:
+
+```json
+"extensions": { "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1": { "job": true } }
+```
+
+That key has one spelling (the contract's `src/extensions.ts`); copy it, never retype it.
+
+## The kit
+
+```python
+import fabric_interop as fi
+
+jobs = fi.JobStore(data_dir / "jobs")               # one private JSON file per job; ids survive restarts
+server = fi.McpToolServer("example-agent", "1.0.0", jobs=jobs,
+                          on_job_started=start_report, on_input=resume_report)
+server.add_tool(fi.tool_for_capability(capability, input_schema, output_schema), handler)
+response = server.handle(json_rpc_message)          # POST /mcp body in, JSON response out (None: 202)
+```
+
+- A handler returns the value for `structuredContent`; for a job it returns
+  `ctx.start_job()`, and `on_job_started(job_id, ctx)` does or schedules the work.
+- `jobs.request_input(job_id, {"title_choice": fi.choice_request(...)}, "Two titles are ready.")`
+  stops for a person. Fabric answers through `fabric.job.get` with `inputResponses`; the
+  server calls `on_input(job_id, answers, ctx)` with the answers that matched.
+- `jobs.complete(job_id, fi.result_envelope(outcome=..., producer=..., ...))`,
+  `jobs.fail(job_id, code, message)`, `jobs.cancel(job_id)`. A terminal job never changes
+  again. A result with unverified claims is `partial`, never `succeeded`.
+- The envelope's `trace` is authoritative for a stored result (DEC-0017): `complete` fills
+  it with the span of the call that started the job and refuses one naming another span,
+  and `fabric.job.get` answers with that same traceparent in `_meta` (FAC-SEM-022). The
+  contract's FAC-SEM-019 records a result without a trace as an incomplete span.
+- Log events about the work with `**fi.trace_ids(ctx.traceparent)` so the pair lands on
+  the event.
+
+`McpToolServer` answers `server/discover`, `tools/list` and `tools/call` with JSON
+responses — enough for Fabric and for the probe. A service already on an MCP SDK keeps
+the SDK and uses only the helpers. The Node kit has the helpers and the same job file
+format, without the dispatcher. `scripts/sample_service.py` is the worked example:
+`sample.echo` answers at once, `sample.draft` is a job that stops for a title choice.
+
+The contract owner's rulings (DEC-0017) the kit follows: a job tool's `outputSchema` is the
+self-contained union `oneOf[result envelope, job handle]` (`job_tool_output_schema`), so
+its `structuredContent` always conforms; an event about untraced work carries no trace pair.
+
+## What the probe checks
+
+`check_service.py` adds these rules; they read, and never call a capability.
+
+| Rule | PASS when | NOT_RUN when |
+|---|---|---|
+| `interop.manifest-link` | the manifest `fabricManifest` names carries the service key with this `<id>.<instance>` (G-07) | the descriptor names no manifest |
+| `interop.well-known-capabilities` | every name in `surfaces.mcp.capabilities` is a manifest capability | the surface lists none |
+| `interop.tools-match` | every `mcp` capability is served as its tool, schemas equal to the files beside the manifest (matched by `$id`; a job's output wrapped in the DEC-0017 union), annotations derived | no manifest, no MCP surface, or a schema is not beside the manifest |
+| `interop.job-tools` | a `job: true` capability comes with `fabric.job.get` and `fabric.job.cancel` | no capability is a job |
+| `interop.unknown-job` | `fabric.job.get` for a made-up id answers `isError` with `unknown-job` | `fabric.job.get` is not served |
+| `interop.trace-propagation` | the answer's `_meta.traceparent` has the probe's trace id and a new span | the answer carries no traceparent |
+| `interop.events-trace` | every event with a trace carries both `traceId` and `spanId`, well formed | no events page was read |
+
+`python3 scripts/check_service.py <id>` prints them with the rest; `--json` for a machine.

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1 — wire reference
 
-Pinned to `fabric-agent-contract` commit `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`
+Pinned to `fabric-agent-contract` commit `9cd778eb6f14b977f9a5b4930826f62dc95c5619`
 (`docs/specification/service.md`, DEC-0015). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.

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

@@ -8,6 +8,10 @@
 Every rule gets PASS, FAIL or NOT_RUN with its evidence. Exit 0 when nothing
 FAILs, 1 when something does, 2 on a usage error. The probe only reads, except
 that it redeems one login code it asked for itself (that creates one session).
+
+The interop.* rules (fabric-interop/0.1) read the manifest the descriptor names and
+the service's MCP surface: tools/list, and fabric.job.get for an id that does not
+exist. They never call a capability.
 """
 
 from __future__ import annotations
@@ -20,6 +24,7 @@ import os
 from pathlib import Path
 import plistlib
 import re
+import secrets
 import shutil
 import stat
 import subprocess
@@ -29,6 +34,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402
+import fabric_interop as fi  # noqa: E402
 
 Result = Dict[str, str]
 
@@ -42,6 +48,8 @@ class Probe:
         self.results: List[Result] = []
         self.wk: Optional[Dict[str, Any]] = None
         self.token: Optional[str] = None
+        self.events: Optional[List[Dict[str, Any]]] = None
+        self.sent_traceparent: Optional[str] = None
         try:
             self.port = fs.port_of(str(descriptor.get("origin", "")))
         except fs.ServiceError:
@@ -184,6 +192,7 @@ class Probe:
         except (ValueError, KeyError, AssertionError):
             self.add("events.page", "FAIL", "not an events page")
             return
+        self.events = events
         bad = []
         for e in events:
             if e.get("level") not in fs.LEVELS or not re.match(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$", str(e.get("kind", ""))):
@@ -215,6 +224,173 @@ class Probe:
         self.add("login.single-use", "PASS" if ok else "FAIL",
                  "first redeem HTTP %d (%s), second HTTP %d" % (status1, "cookie ok" if "HttpOnly" in cookie else "no HttpOnly cookie", status2))
 
+    # interop (fabric-interop/0.1) ----------------------------------------------------
+    # #region probe-interop — docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md#what-the-probe-checks
+    def mcp_call(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """One JSON-RPC request to the MCP surface, as a child of a fresh probe trace."""
+        path = (((self.wk or {}).get("surfaces") or {}).get("mcp") or {}).get("path", "/mcp")
+        self.sent_traceparent = fi.child_traceparent(None)
+        body = dict(params)
+        body["_meta"] = {"io.modelcontextprotocol/protocolVersion": fi.MCP_REVISION,
+                         "io.modelcontextprotocol/clientCapabilities": {}, "traceparent": self.sent_traceparent}
+        headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream",
+                   "MCP-Protocol-Version": fi.MCP_REVISION}
+        headers.update(self.auth_headers())
+        message = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": body}).encode()
+        status, resp_headers, raw = self.request("POST", path, headers, message)
+        if status != 200:
+            raise OSError("HTTP %d from %s" % (status, path))
+        if resp_headers.get("content-type", "").startswith("text/event-stream"):
+            data = [line[5:].strip() for line in raw.decode().splitlines() if line.startswith("data:")]
+            raw = (data[-1] if data else "null").encode()
+        return json.loads(raw)
+
+    def load_manifest(self) -> Tuple[Optional[Dict[str, Any]], Optional[Path], str]:
+        named = self.d.get("fabricManifest")
+        if not named:
+            return None, None, "the descriptor names no fabricManifest"
+        try:
+            path = fs.expand(str(named))
+            return json.loads(path.read_text(encoding="utf-8")), path, str(path)
+        except (fs.ServiceError, OSError, ValueError) as exc:
+            return None, None, "manifest %s does not resolve: %s" % (named, exc)
+
+    def resolve_schema(self, manifest_path: Path, uri: str) -> Optional[Dict[str, Any]]:
+        """A schema named by URI, found by its $id among the JSON files beside the manifest. Nothing is fetched."""
+        for candidate in sorted(manifest_path.parent.glob("fabric/schemas/*.json")) + sorted(manifest_path.parent.glob("*.schema.json")):
+            try:
+                doc = json.loads(candidate.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            if isinstance(doc, dict) and doc.get("$id") == uri:
+                return doc
+        return None
+
+    def interop_rules(self) -> None:
+        manifest, manifest_path, where = self.load_manifest()
+        me = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
+        if manifest is None:
+            self.add("interop.manifest-link", "NOT_RUN" if not self.d.get("fabricManifest") else "FAIL", where)
+        else:
+            block = ((manifest.get("provider") or {}).get("extensions") or {}).get(fs.EXTENSION_KEY) or {}
+            named = block.get("descriptor")
+            self.add("interop.manifest-link", "PASS" if named == me else "FAIL",
+                     "%s names %s" % (where, named) if named else "%s carries no %s block naming %s" % (where, fs.EXTENSION_KEY, me))
+        capabilities = [c for c in (manifest or {}).get("capabilities", []) if isinstance(c, dict)]
+        names = {c.get("name") for c in capabilities}
+        mcp_surface = ((self.wk or {}).get("surfaces") or {}).get("mcp")
+        listed = (mcp_surface or {}).get("capabilities")
+        if listed is None or manifest is None:
+            self.add("interop.well-known-capabilities", "NOT_RUN", "no capability list on the MCP surface" if listed is None else where)
+        else:
+            extra = sorted(set(listed) - names)
+            self.add("interop.well-known-capabilities", "FAIL" if extra else "PASS",
+                     ("listed but not in the manifest: " + ", ".join(extra)) if extra else "%d listed, all in the manifest" % len(listed))
+        if not mcp_surface or not self.token:
+            for rule in ("interop.tools-match", "interop.job-tools", "interop.unknown-job", "interop.trace-propagation"):
+                self.add(rule, "NOT_RUN", "no MCP surface" if not mcp_surface else "no readable token")
+        else:
+            try:
+                listing = self.mcp_call("tools/list", {})
+            except (OSError, ValueError) as exc:
+                self.add("interop.tools-match", "FAIL", "tools/list failed: %s" % exc)
+                listing = None
+            if listing is not None:
+                sent = self.sent_traceparent
+                tools = {t.get("name"): t for t in (listing.get("result") or {}).get("tools", []) if isinstance(t, dict)}
+                self.tools_match_rule(capabilities, manifest_path, tools)
+                self.job_tools_rule(capabilities, tools)
+                self.unknown_job_rule(list(tools))
+                self.trace_rule(listing, sent)
+        self.events_trace_rule(self.events)
+
+    def tools_match_rule(self, capabilities: List[Dict[str, Any]], manifest_path: Optional[Path], tools: Dict[str, Any]) -> None:
+        """FAC-SEM-017: each mcp capability is served as the tool of its name, with its schemas and derived annotations."""
+        served = [c for c in capabilities if (c.get("profile") or {}).get("kind") == "mcp"]
+        if manifest_path is None or not served:
+            self.add("interop.tools-match", "NOT_RUN", "no manifest with an mcp capability")
+            return
+        problems, unresolved = [], []
+        for cap in served:
+            name = cap.get("name")
+            tool = tools.get(name)
+            if tool is None:
+                problems.append("%s is not served as a tool" % name)
+                continue
+            for side in ("inputSchema", "outputSchema"):
+                schema = self.resolve_schema(manifest_path, str(cap.get(side)))
+                if schema is None:
+                    unresolved.append("%s %s" % (name, cap.get(side)))
+                elif side == "outputSchema" and fi.is_job_capability(cap):
+                    if tool.get(side) != fi.job_tool_output_schema(schema):
+                        problems.append("%s is a job: its outputSchema must be oneOf[result envelope, job handle] around %s (DEC-0017)" % (name, cap.get(side)))
+                elif tool.get(side) != schema:
+                    problems.append("%s serves an %s that differs from %s" % (name, side, cap.get(side)))
+            annotations = tool.get("annotations") or {}
+            for hint, value in fi.expected_annotations(cap.get("effect", ""), cap.get("idempotency", "")).items():
+                if annotations.get(hint) is not value:
+                    problems.append("%s lacks %s (effect %s, idempotency %s)" % (name, hint, cap.get("effect"), cap.get("idempotency")))
+        if problems:
+            self.add("interop.tools-match", "FAIL", "; ".join(problems))
+        elif unresolved:
+            self.add("interop.tools-match", "NOT_RUN", "schemas not found beside the manifest: " + ", ".join(unresolved))
+        else:
+            self.add("interop.tools-match", "PASS", "%d capabilities served with their schemas and annotations" % len(served))
+
+    def job_tools_rule(self, capabilities: List[Dict[str, Any]], tools: Dict[str, Any]) -> None:
+        jobs = [c.get("name") for c in capabilities if ((c.get("extensions") or {}).get(fi.EXTENSION_KEY) or {}).get("job") is True]
+        if not jobs:
+            self.add("interop.job-tools", "NOT_RUN", "no capability declares job: true")
+            return
+        missing = [n for n in ("fabric.job.get", "fabric.job.cancel") if n not in tools]
+        self.add("interop.job-tools", "FAIL" if missing else "PASS",
+                 ("job capabilities %s, but %s not served" % (", ".join(jobs), " and ".join(missing))) if missing else "fabric.job.get and fabric.job.cancel served")
+
+    def unknown_job_rule(self, tool_names: List[str]) -> None:
+        """C3.2: an unknown id answers isError with unknown-job, never a fresh job."""
+        if "fabric.job.get" not in tool_names:
+            self.add("interop.unknown-job", "NOT_RUN", "fabric.job.get is not served")
+            return
+        probe_id = "probe-unknown-" + secrets.token_hex(6)
+        try:
+            answer = self.mcp_call("tools/call", {"name": "fabric.job.get", "arguments": {"id": probe_id}})
+        except (OSError, ValueError) as exc:
+            self.add("interop.unknown-job", "FAIL", "fabric.job.get failed: %s" % exc)
+            return
+        result = answer.get("result") or {}
+        ok = result.get("isError") is True and "unknown-job" in json.dumps(result)
+        self.add("interop.unknown-job", "PASS" if ok else "FAIL",
+                 "isError with unknown-job for %s" % probe_id if ok else "an unknown id did not answer isError with unknown-job")
+
+    def trace_rule(self, answer: Dict[str, Any], sent: Optional[str]) -> None:
+        """C3.4: work runs as a child span of the caller — same trace, new span."""
+        answered = fi.parse_traceparent(((answer.get("result") or {}).get("_meta") or {}).get("traceparent"))
+        mine = fi.parse_traceparent(sent)
+        if answered is None or mine is None:
+            self.add("interop.trace-propagation", "NOT_RUN", "the answer carries no _meta.traceparent (C3.4 does not require it)")
+        elif answered["trace_id"] == mine["trace_id"] and answered["span_id"] != mine["span_id"]:
+            self.add("interop.trace-propagation", "PASS", "answered as a child span of trace %s" % mine["trace_id"])
+        else:
+            self.add("interop.trace-propagation", "FAIL", "answered with trace %s span %s to a call in trace %s span %s"
+                     % (answered["trace_id"], answered["span_id"], mine["trace_id"], mine["span_id"]))
+
+    def events_trace_rule(self, events: Optional[List[Dict[str, Any]]]) -> None:
+        """C3.4 c: an event about traced work carries traceId and spanId together, well formed."""
+        if events is None:
+            self.add("interop.events-trace", "NOT_RUN", "no events page was read")
+            return
+        bad, traced = [], 0
+        for e in events:
+            has = ("traceId" in e, "spanId" in e)
+            if has == (False, False):
+                continue
+            traced += 1
+            if has != (True, True) or not fi.parse_traceparent("00-%s-%s-01" % (e.get("traceId"), e.get("spanId"))):
+                bad.append(str(e.get("id")))
+        self.add("interop.events-trace", "FAIL" if bad else "PASS",
+                 ("events with a broken trace pair: " + ", ".join(bad)) if bad else "%d of %d events traced, every pair whole" % (traced, len(events)))
+    # #endregion probe-interop
+
     # lifecycle ----------------------------------------------------------------
     def lifecycle_rules(self) -> None:
         life = self.d.get("lifecycle") or {}
@@ -315,6 +491,7 @@ class Probe:
             self.network_rules()
             self.auth_rules()
             self.login_rules()
+            self.interop_rules()
         self.lifecycle_rules()
         return self.results
 

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-interop.mjs

@@ -0,0 +1,215 @@
+// Reference kit for the fabric-interop/0.1 extension — Node.js 20+, no dependencies.
+// The Node twin of fabric_interop.py: the same rules and the same job file format, so a
+// job written by one kit is read by the other. The minimal MCP dispatcher is Python-only;
+// a Node service uses the official MCP SDK for the wire and these helpers for the rules.
+// Normative source: fabric-agent-contract docs/specification/interop.md (DEC-0016, rulings DEC-0017).
+// #region interop-kit-node — docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md#the-kit
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ServiceError, atomicWrite, ensurePrivateDir, nowIso } from './fabric-service.mjs';
+
+export const PROTOCOL = 'fabric-interop/0.1';
+export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1';
+export const MCP_REVISION = '2026-07-28';
+export const TERMINAL = ['completed', 'failed', 'cancelled'];
+export const CONTRACT_VERSION = '0.1.0';
+const OUTCOMES = ['succeeded', 'partial', 'failed', 'cancelled', 'blocked'];
+const ENVELOPE_REQUIRED = ['id', 'contractVersion', 'outcome', 'done', 'proof', 'scope', 'notVerified', 'artifacts', 'createdAt', 'producer', 'output', 'usage'];
+// The job handle inline, as a job tool's outputSchema carries it (contract interop-job-handle.schema.json).
+export const JOB_HANDLE_SCHEMA = {
+  type: 'object', required: ['job'], additionalProperties: false,
+  properties: { job: { type: 'object', required: ['id', 'status'], additionalProperties: false,
+    properties: { id: { type: 'string', minLength: 1, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$' }, status: { const: 'working' } } } },
+};
+
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const JOB_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const KEY = /^[A-Za-z0-9_.-]{1,64}$/;
+const SECRET_WORDS = /pass(word|phrase)|secret|api[\s_-]?key|access[\s_-]?key|private[\s_-]?key|(access|auth|bearer|refresh|session)[\s_-]?token|^token$|credential/i;
+const USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'costUsd', 'wallMs'];
+
+export class InteropError extends ServiceError {}
+export class UnknownJob extends InteropError {
+  constructor(jobId) { super(`unknown-job: no job ${jobId} here.`); this.jobId = jobId; }
+}
+
+// --- C3.4 trace context ---------------------------------------------------------------
+export function parseTraceparent(value) {
+  const m = typeof value === 'string' ? TRACEPARENT.exec(value) : null;
+  if (!m) return null;
+  const [, version, traceId, spanId, flags] = m;
+  if (version === 'ff' || /^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
+  return { version, traceId, spanId, flags };
+}
+
+const spanIdNew = () => { for (;;) { const v = crypto.randomBytes(8).toString('hex'); if (!/^0+$/.test(v)) return v; } };
+
+export function childTraceparent(parent) {
+  const p = parseTraceparent(parent);
+  return `00-${p ? p.traceId : crypto.randomBytes(16).toString('hex')}-${spanIdNew()}-${p ? p.flags : '01'}`;
+}
+
+export const traceIds = (traceparent) => {
+  const p = parseTraceparent(traceparent);
+  return p ? { traceId: p.traceId, spanId: p.spanId } : {};
+};
+
+// --- C3.1 capabilities as tools ----------------------------------------------------------
+export function expectedAnnotations(effect, idempotency) {
+  const hints = {};
+  if (effect === 'none') hints.readOnlyHint = true;
+  if (['delete', 'merge', 'deploy', 'change-policy'].includes(effect)) hints.destructiveHint = true;
+  if (idempotency === 'required') hints.idempotentHint = true;
+  return hints;
+}
+
+// DEC-0017: a job-backed tool serves oneOf[result envelope, job handle]; the manifest keeps the pure output schema.
+export const jobToolOutputSchema = (outputSchema) => ({ oneOf: [{ type: 'object', required: [...ENVELOPE_REQUIRED], properties: { output: outputSchema } }, JOB_HANDLE_SCHEMA] });
+export const isJobCapability = (capability) => capability.job === true || capability.extensions?.[EXTENSION_KEY]?.job === true;
+
+export function toolForCapability(capability, inputSchema, outputSchema, title) {
+  const served = isJobCapability(capability) ? jobToolOutputSchema(outputSchema) : outputSchema;
+  const tool = { name: capability.name, inputSchema, outputSchema: served, annotations: expectedAnnotations(capability.effect, capability.idempotency) };
+  if (capability.description) tool.description = capability.description;
+  if (title) tool.title = title;
+  return tool;
+}
+
+export function toolResult(structured, { isError = false, traceparent } = {}) {
+  const result = { resultType: 'complete', content: [{ type: 'text', text: JSON.stringify(structured) }], structuredContent: structured, isError };
+  if (traceparent) result._meta = { traceparent };
+  return result;
+}
+
+export const unknownJobResult = (jobId, traceparent) =>
+  toolResult({ error: { code: 'unknown-job', message: `No job ${jobId} here.` } }, { isError: true, traceparent });
+
+// --- C3.2 the result envelope --------------------------------------------------------------
+function checkUsage(usage) {
+  if (!usage || typeof usage !== 'object') throw new InteropError('usage must be an object.');
+  for (const key of ['inputTokens', 'outputTokens', 'wallMs']) if (!(key in usage)) throw new InteropError(`usage.${key} is required.`);
+  for (const [key, value] of Object.entries(usage)) {
+    if (!USAGE_KEYS.includes(key)) throw new InteropError(`usage.${key} is not a usage field.`);
+    const ok = typeof value === 'number' && value >= 0 && (key === 'costUsd' || Number.isInteger(value));
+    if (!ok) throw new InteropError(`usage.${key} must be a non-negative ${key === 'costUsd' ? 'number' : 'integer'}.`);
+  }
+  return { ...usage };
+}
+
+// The full result envelope (contract result.schema.json, DEC-0017): the shape a synchronous call returns.
+export function resultEnvelope({ outcome, done, proof, scope, notVerified, output, usage, producer, artifacts = [], traceparent, id, createdAt }) {
+  if (!OUTCOMES.includes(outcome)) throw new InteropError(`outcome must be one of ${OUTCOMES.join(', ')}.`);
+  for (const [label, value] of [['done', done], ['proof', proof], ['notVerified', notVerified], ['artifacts', artifacts]]) {
+    if (!Array.isArray(value)) throw new InteropError(`${label} must be a list, even when empty.`);
+  }
+  if (outcome === 'succeeded' && notVerified.length) throw new InteropError('A succeeded result cannot keep unverified claims (FAC-SEM-001); report partial.');
+  if (!scope || typeof scope !== 'object' || !producer || typeof producer !== 'object') throw new InteropError('scope and producer must be objects.');
+  const envelope = {
+    id: id ?? `urn:fabric:result:${crypto.randomBytes(12).toString('hex')}`, contractVersion: CONTRACT_VERSION, outcome,
+    done: [...done], proof: [...proof], scope: { ...scope }, notVerified: [...notVerified], artifacts: [...artifacts],
+    createdAt: createdAt ?? nowIso(), producer: { ...producer }, output, usage: checkUsage(usage),
+  };
+  if (parseTraceparent(traceparent)) envelope.trace = { traceparent };
+  return envelope;
+}
+
+// --- C3.3 awaiting a choice ------------------------------------------------------------------
+export function formRequest(message, properties, required) {
+  for (const [field, schema] of Object.entries(properties)) {
+    const words = ['title', 'description', 'format'].map((k) => schema[k] ?? '').join(' ');
+    if (SECRET_WORDS.test(field) || SECRET_WORDS.test(words)) throw new InteropError(`Form mode cannot ask for ${field}: a secret goes through urlRequest.`);
+    if (!['string', 'number', 'integer', 'boolean', 'array'].includes(schema.type)) throw new InteropError(`Form field ${field} must be a primitive.`);
+  }
+  const requestedSchema = { type: 'object', properties };
+  if (required?.length) requestedSchema.required = [...required];
+  return { method: 'elicitation/create', params: { mode: 'form', message, requestedSchema } };
+}
+
+export function choiceRequest(message, field, options, title) {
+  const schema = { type: 'string', oneOf: options.map(([value, label]) => ({ const: value, title: label })) };
+  if (title) schema.title = title;
+  return formRequest(message, { [field]: schema }, [field]);
+}
+
+export function urlRequest(message, url) {
+  if (!/^(https:\/\/|http:\/\/127\.0\.0\.1|http:\/\/localhost)/.test(url)) throw new InteropError('A URL-mode request needs an https URL (or this machine\'s loopback).');
+  return { method: 'elicitation/create', params: { mode: 'url', message, url } };
+}
+
+// --- C3.2 jobs: the same file format as fabric_interop.JobStore ------------------------------
+export class JobStore {
+  constructor(dir) { this.dir = dir; }
+
+  file(jobId) {
+    if (!JOB_ID.test(jobId ?? '')) throw new UnknownJob(String(jobId));
+    return path.join(this.dir, `${jobId}.json`);
+  }
+
+  load(jobId) {
+    let text;
+    try { text = fs.readFileSync(this.file(jobId), 'utf8'); } catch (e) { if (e.code === 'ENOENT') throw new UnknownJob(jobId); throw e; }
+    try { return JSON.parse(text); } catch { throw new InteropError(`Job ${jobId} is unreadable on disk.`); }
+  }
+
+  save(record) {
+    record.job.updatedAt = nowIso();
+    ensurePrivateDir(this.dir);
+    atomicWrite(this.file(record.job.id), `${JSON.stringify(record)}\n`, 0o600);
+    return { ...record.job };
+  }
+
+  create(capability, input, { traceparent, pollIntervalMs } = {}) {
+    const id = `job_${crypto.randomBytes(12).toString('hex')}`;
+    const job = { id, status: 'working' };
+    if (pollIntervalMs) job.pollIntervalMs = Math.trunc(pollIntervalMs);
+    this.save({ job, private: { capability, input, traceparent: parseTraceparent(traceparent) ? traceparent : null } });
+    return { job: { id, status: 'working' } };
+  }
+
+  get(jobId) { return { ...this.load(jobId).job }; }
+  traceparent(jobId) { return this.load(jobId).private.traceparent ?? null; }
+
+  transition(jobId, status, fields = {}) {
+    const record = this.load(jobId);
+    if (TERMINAL.includes(record.job.status)) throw new InteropError(`Job ${jobId} is already ${record.job.status}; a terminal job does not change.`);
+    for (const key of ['inputRequests', 'result', 'error', 'statusMessage']) delete record.job[key];
+    record.job.status = status;
+    for (const [key, value] of Object.entries(fields)) if (value !== undefined && value !== null) record.job[key] = value;
+    return this.save(record);
+  }
+
+  working(jobId, statusMessage) { return this.transition(jobId, 'working', { statusMessage }); }
+
+  requestInput(jobId, inputRequests, statusMessage) {
+    const entries = Object.entries(inputRequests ?? {});
+    if (!entries.length) throw new InteropError('input_required needs at least one input request.');
+    for (const [key, request] of entries) if (!KEY.test(key) || request?.method !== 'elicitation/create') throw new InteropError(`Input request ${key} must be a keyed elicitation/create request.`);
+    return this.transition(jobId, 'input_required', { inputRequests, statusMessage });
+  }
+
+  answer(jobId, inputResponses) {
+    const job = this.get(jobId);
+    if (job.status !== 'input_required') return {};
+    const matched = Object.fromEntries(Object.entries(inputResponses ?? {}).filter(([key, value]) =>
+      key in (job.inputRequests ?? {}) && ['accept', 'decline', 'cancel'].includes(value?.action)));
+    if (Object.keys(matched).length) this.working(jobId);
+    return matched;
+  }
+
+  // The envelope carries the job's trace, authoritative for the stored result (DEC-0017, FAC-SEM-022).
+  complete(jobId, envelope) {
+    if (!envelope || !ENVELOPE_REQUIRED.every((k) => k in envelope)) throw new InteropError('A completed job carries the full result envelope; build it with resultEnvelope.');
+    const stored = this.traceparent(jobId);
+    const given = envelope.trace?.traceparent;
+    const ids = (v) => { const p = parseTraceparent(v); return p ? `${p.traceId}-${p.spanId}` : null; };
+    if (stored && given && ids(given) !== ids(stored)) throw new InteropError(`Job ${jobId} ran in span ${stored}; its result names another trace.`);
+    const result = stored && !given ? { ...envelope, trace: { traceparent: stored } } : envelope;
+    return this.transition(jobId, 'completed', { result });
+  }
+
+  fail(jobId, code, message) { return this.transition(jobId, 'failed', { error: { code, message } }); }
+  cancel(jobId) { return this.transition(jobId, 'cancelled'); }
+}
+// #endregion interop-kit-node

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

@@ -22,6 +22,8 @@ const INSTANCE = /^[a-z][a-z0-9-]{0,31}$/;
 const KIND = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,5}$/;
 const ORIGIN = /^http:\/\/127\.0\.0\.1:([0-9]{3,5})$/;
 const CODE = /^[A-Za-z0-9_-]{16,256}$/;
+const TRACE_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
+const SPAN_ID = /^(?!0{16}$)[0-9a-f]{16}$/;
 const O_EXLOCK = 0x20; // BSD/macOS: open(2) takes flock(LOCK_EX); absent from fs.constants
 
 export class ServiceError extends Error {}
@@ -281,16 +283,21 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
   return doc;
 }
 
-export function makeEvent(id, at, kind, level, text, { subject, link, notify } = {}) {
+// An event about traced work carries traceId and spanId together (fabric-interop/0.1 C3.4 c);
+// traceIds(traceparent) in fabric-interop.mjs gives both.
+export function makeEvent(id, at, kind, level, text, { subject, link, notify, traceId, spanId } = {}) {
   if (!LEVELS.includes(level)) throw new ServiceError(`level must be one of ${LEVELS.join(', ')}.`);
   if (!KIND.test(kind)) throw new ServiceError(`kind ${kind} must be dotted lowercase.`);
   const sentence = String(text).split(/\s+/).filter(Boolean).join(' ');
   if (!sentence) throw new ServiceError('An event needs a sentence.');
   if (link !== undefined && (!link.startsWith('/') || link.startsWith('//'))) throw new ServiceError('link must be a path on this service.');
+  if ((traceId === undefined) !== (spanId === undefined)) throw new ServiceError('An event carries traceId and spanId together, or neither.');
+  if (traceId !== undefined && !(TRACE_ID.test(traceId) && SPAN_ID.test(spanId))) throw new ServiceError('traceId is 32 and spanId 16 lowercase hex characters, not all zeros.');
   const event = { id: String(id), at, kind, level, text: sentence.slice(0, 500) };
   if (subject) event.subject = subject;
   if (link) event.link = link;
   if (notify) event.notify = true;
+  if (traceId !== undefined) Object.assign(event, { traceId, spanId });
   return event;
 }