@passioncode-ai/fabric-agent-adapter 0.4.2 → 0.5.0

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

@@ -46,6 +46,8 @@ _INSTANCE = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
 _KIND = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,5}$")
 _ORIGIN = re.compile(r"^http://127\.0\.0\.1:([0-9]{3,5})$")
 _CODE = re.compile(r"^[A-Za-z0-9_-]{16,256}$")
+_TRACE_ID = re.compile(r"^(?!0{32}$)[0-9a-f]{32}$")
+_SPAN_ID = re.compile(r"^(?!0{16}$)[0-9a-f]{16}$")
 
 
 class ServiceError(Exception):
@@ -404,8 +406,12 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
 # --- events ------------------------------------------------------------------
 
 def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subject: Optional[Dict[str, str]] = None,
-               link: Optional[str] = None, notify: bool = False) -> Dict[str, Any]:
-    """One activity event: one sentence a person reads, never a machine id."""
+               link: Optional[str] = None, notify: bool = False, trace_id: Optional[str] = None,
+               span_id: Optional[str] = None) -> Dict[str, Any]:
+    """One activity event: one sentence a person reads, never a machine id.
+
+    An event about traced work carries its trace as a pair, `trace_id` and `span_id`
+    (fabric-interop/0.1 C3.4 c); fabric_interop.trace_ids(traceparent) gives both."""
     if level not in LEVELS:
         raise ServiceError("level must be one of %s." % ", ".join(LEVELS))
     if not _KIND.match(kind):
@@ -415,6 +421,10 @@ def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subj
         raise ServiceError("An event needs a sentence.")
     if link is not None and (not link.startswith("/") or link.startswith("//")):
         raise ServiceError("link must be a path on this service.")
+    if (trace_id is None) != (span_id is None):
+        raise ServiceError("An event carries traceId and spanId together, or neither.")
+    if trace_id is not None and not (_TRACE_ID.match(trace_id) and _SPAN_ID.match(str(span_id))):
+        raise ServiceError("traceId is 32 and spanId 16 lowercase hex characters, not all zeros.")
     event: Dict[str, Any] = {"id": str(event_id), "at": at, "kind": kind, "level": level, "text": text[:500]}
     if subject:
         event["subject"] = subject
@@ -422,6 +432,8 @@ def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subj
         event["link"] = link
     if notify:
         event["notify"] = True
+    if trace_id is not None:
+        event["traceId"], event["spanId"] = trace_id, span_id
     return event
 
 

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

@@ -3,6 +3,9 @@
 
 It is the worked example the skill points at, the target check_service.py tests
 itself against, and the fixture Fabric Dashboards runs its end-to-end tests on.
+Over MCP (fabric-interop/0.1) it serves two capabilities: `sample.echo` answers at
+once, and `sample.draft` is a job that stops for a titled choice before it completes.
+`register` also writes the service's manifest, which names this descriptor.
 
   sample_service.py serve --port 47190 --data-dir DIR [--id sample] [--instance default]
   sample_service.py register --port 47190 --data-dir DIR [--services-dir DIR]
@@ -11,6 +14,7 @@ itself against, and the fixture Fabric Dashboards runs its end-to-end tests on.
 from __future__ import annotations
 
 import argparse
+import hashlib
 import html
 import json
 import os
@@ -24,6 +28,7 @@ from urllib.parse import parse_qs, urlparse
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402
+import fabric_interop as fi  # noqa: E402
 
 VERSION = "0.1.0"
 PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
@@ -32,6 +37,24 @@ PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
 </head><body><h1>{name}</h1><p>Status: {status}</p><ul>{rows}</ul></body></html>"""
 
 
+def _schema(name: str, body: Dict[str, Any]) -> Dict[str, Any]:
+    return {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "urn:fabric:schema:%s" % name, **body}
+
+
+TEXT = {"type": "object", "additionalProperties": False, "properties": {"text": {"type": "string", "maxLength": 2000}}, "required": ["text"]}
+CAPABILITIES = [
+    {"name": "sample.echo", "effect": "none", "idempotency": "required", "job": False,
+     "description": "Returns the text it was given.",
+     "input": _schema("sample.echo-input", TEXT), "output": _schema("sample.echo-output", TEXT)},
+    {"name": "sample.draft", "effect": "draft", "idempotency": "none", "job": True,
+     "description": "Drafts a short note on a topic; asks which title to use.",
+     "input": _schema("sample.draft-input", {"type": "object", "additionalProperties": False,
+                                               "properties": {"topic": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["topic"]}),
+     "output": _schema("sample.draft-output", {"type": "object", "additionalProperties": False,
+                                                 "properties": {"title": {"type": "string"}, "body": {"type": "string"}}, "required": ["title", "body"]})},
+]
+
+
 class Service:
     def __init__(self, args: argparse.Namespace):
         self.id = args.id
@@ -50,14 +73,57 @@ class Service:
         self.token = fs.ensure_token(self.token_file)
         self.log = fs.JsonlEventLog(self.data / "events.jsonl")
         self.codes = fs.LoginCodes(self.data / "auth")
+        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:
+            handler = self.echo if cap["name"] == "sample.echo" else self.draft
+            self.mcp.add_tool(fi.tool_for_capability(cap, cap["input"], cap["output"]), handler)
         self.log.append("service.started", "info", "%s started on build %s." % (self.name, self.build["commit"]))
 
+    # --- fabric-interop/0.1: the two capabilities ------------------------------------
+    def echo(self, args: Dict[str, Any], ctx: fi.CallContext) -> Dict[str, Any]:
+        if not isinstance(args.get("text"), str):
+            raise fi.InteropError("sample.echo needs text.")
+        return {"text": args["text"]}
+
+    def draft(self, args: Dict[str, Any], ctx: fi.CallContext) -> Dict[str, Any]:
+        if not isinstance(args.get("topic"), str) or not args["topic"].strip():
+            raise fi.InteropError("sample.draft needs a topic.")
+        return ctx.start_job(poll_interval_ms=1000)
+
+    def draft_started(self, job_id: str, ctx: fi.CallContext) -> None:
+        topic = str(ctx.arguments.get("topic"))
+        titles = [("plain", "About %s" % topic), ("question", "What is %s?" % topic)]
+        self.jobs.request_input(job_id, {"title_choice": fi.choice_request("Pick the title for the note.", "title", titles, "Title")},
+                                "Two titles are ready.")
+        self.log.append("job.awaiting_choice", "notice", "A note about %s is waiting for you to pick its title." % topic,
+                        notify=True, **fi.trace_ids(ctx.traceparent))
+
+    def draft_answered(self, job_id: str, answers: Dict[str, Any], ctx: fi.CallContext) -> None:
+        answer = answers.get("title_choice", {})
+        topic = str(ctx.arguments.get("topic"))
+        if answer.get("action") != "accept":
+            self.jobs.cancel(job_id)
+            self.log.append("job.cancelled", "info", "The note about %s was dropped: no title was chosen." % topic, **fi.trace_ids(ctx.traceparent))
+            return
+        choice = str((answer.get("content") or {}).get("title"))
+        title = "About %s" % topic if choice == "plain" else "What is %s?" % topic
+        body = "%s. This sample note was written by the sample service." % title
+        self.jobs.complete(job_id, fi.result_envelope(
+            done=[{"claimId": "NOTE", "statement": "A note titled %s was drafted." % title}], proof=[],
+            scope={"project": "urn:fabric:project:sample", "run": "urn:fabric:run:%s" % job_id, "node": "urn:fabric:node:draft",
+                   "binding": {"id": "urn:fabric:binding:sample.draft", "revision": 1, "contentHash": "sha256:" + "0" * 64}, "writeScopes": []},
+            not_verified=[{"claim": "NOTE", "reason": "no checker has read the note"}],
+            output={"title": title, "body": body}, usage={"inputTokens": 0, "outputTokens": 0, "wallMs": 1}))
+        self.log.append("job.completed", "info", "The note %s is drafted." % title, **fi.trace_ids(ctx.traceparent))
+
     def well_known(self) -> Dict[str, Any]:
         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=self.degraded,
             summary=[{"label": "Events", "value": len(self.log.fetch(None, fs.EVENTS_MAX_LIMIT))}],
-            surfaces={"dashboard": {"path": "/", "login": True}, "events": {"path": "/fabric/v1/events"}},
+            surfaces={"dashboard": {"path": "/", "login": True}, "events": {"path": "/fabric/v1/events"},
+                      "mcp": {"path": "/mcp", "transport": "streamable-http", "capabilities": [c["name"] for c in CAPABILITIES]}},
         )
 
 
@@ -137,6 +203,16 @@ def make_handler(svc: Service):
             if not self._guard():
                 return
             url = urlparse(self.path)
+            if url.path == "/mcp":
+                if not self._token_ok():
+                    return
+                length = min(int(self.headers.get("Content-Length") or 0), 1048576)
+                try:
+                    message = json.loads(self.rfile.read(length) or b"null")
+                except ValueError:
+                    return self._send(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error."}})
+                response = svc.mcp.handle(message)
+                return self._send(202) if response is None else self._send(200, response)
             if url.path == "/fabric/v1/login-code":
                 if not self._token_ok():
                     return
@@ -180,8 +256,46 @@ def serve(args: argparse.Namespace) -> int:
     return 0
 
 
+def write_manifest(args: argparse.Namespace, data: Path) -> Path:
+    """The provider manifest for this service, naming its descriptor (G-07), with its schemas beside it."""
+    schemas = data / "fabric" / "schemas"
+    for cap in CAPABILITIES:
+        for side in ("input", "output"):
+            fs.atomic_write(schemas / ("%s-%s.schema.json" % (cap["name"], side)),
+                            (json.dumps(cap[side], indent=2) + "\n").encode(), 0o600)
+    origin = "http://127.0.0.1:%d" % args.port
+    capabilities = []
+    for cap in CAPABILITIES:
+        capabilities.append({
+            "id": "urn:fabric:capability:%s" % cap["name"], "name": cap["name"], "description": cap["description"],
+            "inputSchema": cap["input"]["$id"], "outputSchema": cap["output"]["$id"],
+            "effect": cap["effect"], "idempotency": cap["idempotency"], "dataClasses": ["public"],
+            "profile": {"kind": "mcp", "protocolRevision": fi.MCP_REVISION,
+                        "connection": {"mode": "streamable-http", "url": origin + "/mcp"},
+                        "requiredFeatures": ["tool:%s" % cap["name"]],
+                        "probes": [{"id": "%s-shape" % cap["name"].replace(".", "-"), "inputFixture": "urn:fabric:fixture:%s" % cap["name"],
+                                    "outputSchema": cap["output"]["$id"], "timeoutMs": 5000, "sideEffectCeiling": "none",
+                                    "assertions": ["returns a value valid against its output schema"]}]},
+            "extensions": {fi.EXTENSION_KEY: {"job": cap["job"]}},
+        })
+    digest = hashlib.sha256(json.dumps(capabilities, sort_keys=True).encode()).hexdigest()
+    subject = "urn:fabric:provider:%s" % args.id
+    manifest = {
+        "contractVersion": "0.1.0",
+        "provider": {"id": subject, "revision": 1, "contentHash": "sha256:" + digest, "createdAt": fs.now_iso(),
+                     "createdBy": "urn:fabric:adapter:sample-service", "name": args.name,
+                     "identity": {"subject": subject, "method": "local-install"}, "supportedContractVersions": ["0.1.0"],
+                     "extensions": {fs.EXTENSION_KEY: {"descriptor": "%s.%s" % (args.id, args.instance)}}},
+        "capabilities": capabilities,
+    }
+    path = data / "fabric-agent.json"
+    fs.atomic_write(path, (json.dumps(manifest, indent=2) + "\n").encode(), 0o600)
+    return path
+
+
 def register(args: argparse.Namespace) -> int:
     data = Path(args.data_dir)
+    manifest = write_manifest(args, data)
     descriptor = {
         "protocol": fs.PROTOCOL, "id": args.id, "instance": args.instance, "name": args.name,
         "summary": "Sample fabric-service/0.1 service.",
@@ -190,6 +304,7 @@ def register(args: argparse.Namespace) -> int:
         "lifecycle": {"manager": "launchd", "label": args.label, "plist": args.plist} if args.label
         else {"manager": "none"},
         "paths": {"data": str(data), "logs": []},
+        "fabricManifest": str(manifest),
         "installedAt": fs.now_iso(), "installedBy": "sample_service.py register",
     }
     try:

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

@@ -1,13 +1,13 @@
 ---
 name: creating-fabric-agents
 description: Use when designing and building a NEW agent or provider that must be Fabric-compatible from its first commit — «создай агента, совместимого с фабрикой Passion Code», «новый агент под Fabric», "create a fabric-compatible agent", "build a new Fabric provider", "fabric-ready agent from scratch". Runs the intake grill (capability, named consumer, workflow-or-agent, MCP/A2A/local-runner profile, effect declarations), distils source projects into a knowledge pack whose recorded failures become planted eval fixtures, scaffolds the pinned contract bundle, and sets the two-clock eval expectation with the conformance report. NOT for adapting an existing project (use adapting-projects-to-fabric), building the Fabric host or orchestrator, or generic agent design where Fabric compatibility is not part of the request.
-license: MIT
+license: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned private fabric-agent-contract checkout. 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.4.2"
+  author: PassionCode.ai
+  version: "0.5.0"
   contract-version: "0.1.0"
-  contract-commit: "20a818e648a4c09a60df0126d11626922e8b9094"
+  contract-commit: "a22dea359ba04b8fe549abe81a5131552cb90eff"
 ---
 
 # Creating Fabric-compatible agents
@@ -30,6 +30,17 @@ Use this skill to design and build a new provider. Do not use it to:
 - claim admission: the deliverable is an admission-ready provider bundle, never a
   connected provider.
 
+## Handing off to neighbouring skills
+
+- The agent's own loop — tool calls, routing and fallback, memory, sub-agents — is
+  designed with `agent-orchestrator` (agent-stack).
+- Its eval suite beyond the step-2 observables — trajectories, judges, regression
+  fixtures from traces — is built with `agent-evals` (agent-stack).
+- Packaging the agent as an Agent Skill or Claude Code plugin goes through `make-skill`.
+
+When one of them is not installed, do that part by hand against its own documentation
+and say in the report which skill was missing.
+
 ## Step 0 — the intake grill
 
 No file is created until every row has an answer. An answer of "later" fails the grill.
@@ -82,7 +93,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 `20a818e648a4c09a60df0126d11626922e8b9094` and
+Pin exactly contract `0.1.0` at commit `a22dea359ba04b8fe549abe81a5131552cb90eff` 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
@@ -91,6 +102,12 @@ contract's `docs/guides/connecting-compatible-agents.md` and mark the structural
 The generated placeholders are deliberate blockers; a bundle still containing one is not
 ready for admission.
 
+A new agent is called the `fabric-interop/0.1` way from its first version: add `--job`
+for a capability whose work may outlive one request, serve each capability as the MCP
+tool of its name, and carry the caller's trace (the `building-fabric-services` interop
+reference). An agent that is not a service is announced with a provider entry
+(`adapting-projects-to-fabric`, `scripts/fabric_provider.py`).
+
 ## Step 4 — implement against the observables
 
 If the agent keeps running on the operator's computer — it answers other agents, runs