@synadia-ai/agent-fabric-pi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@synadia-ai/agent-fabric-pi` are recorded here. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — unreleased
+
+### Added
+
+- The extension module for the PI channel plugin, named in `SYNADIA_PI_EXTENSIONS`: `fabricTracing()` on the plugin's service and agent-tools client.
+- The `X-Synadia-Thread-ID` and `X-Synadia-Root-ID` headers on PI's own model calls, with each served request's scope bound at PI's events.
+- The `409` loop guard in front of PI's handler.
+- The edge subject setting: `options.edgeSubject`, `SYNADIA_FABRIC_EDGE_SUBJECT`, or `TRACE.edges`.
+- ScratchPad: the shared skill with the sp command line for darwin and linux, its variables for `scripts/sp`, references in and out, and grant requests.
+
+[0.1.0]: https://github.com/synadia-ai/agent-fabric-sdk/tree/main/plugins/pi

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and
+      on Your sole responsibility, not on behalf of any other Contributor,
+      and only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Synadia Communications
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md

@@ -0,0 +1,281 @@
+# @synadia-ai/agent-fabric-pi
+
+The Synadia Agent Fabric add-on for the PI channel plugin
+(`@synadia-ai/nats-pi-channel`, `agents/pi` in
+[`synadia-agents`](https://github.com/synadia-ai/synadia-agents)). One
+extension module in the shape the plugin loads: named in
+`SYNADIA_PI_EXTENSIONS`, it puts the fabric package's tracing on the
+plugin's service and on the client its agent tools prompt through, the
+fabric's two headers on PI's own model calls, and the `409` loop guard in
+front of PI's handler. It also ships ScratchPad's skill with the sp command
+line, so PI's model reads, publishes and shares ScratchPad content through
+its bash tool. Without it the plugin is the plain plugin. The contract it
+fills is the plugin's `agents/EXTENSIONS.md`; the spec is
+[`docs/plugins.md`](https://github.com/synadia-ai/agent-fabric-sdk/blob/main/docs/plugins.md) §2, §3.1, §3.2 and §9.
+
+## What it does
+
+The factory, the module's default export, calls `fabricTracing()` once and
+hands the plugin its three hooks, so PI is on the wire exactly what an
+SDK-built agent is:
+
+- **On the service, per prompt:** the envelope's `thread_id` and `root_id`
+  are adopted, or a root minted when neither is there; a half pair or a
+  malformed id is refused with `400` before the handler runs; the handler
+  runs inside the trace scope.
+- **On the client PI's agent tools prompt through, per prompt:** the child
+  thread is minted and the pair put into the envelope, and the signed `edge`
+  record is published on `TRACE.edges` before the prompt goes out, with the
+  model's tool-call ID, which the plugin passes to `execute()`. A delegation
+  PI's model makes hangs under its tool call in the console.
+- **On the heartbeat:** `records_published` and `records_dropped`.
+
+The harness piece is the scope. PI's loop does not run in the handler's
+async context, so the add-on keeps each served request's scope by the
+plugin's request id and binds it where the plugin says the request is being
+worked on:
+
+| Event                                | What the add-on does                                                                                                                                                                                                                                             |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `promptAccepted(request)`            | keeps `activeTrace()`, the scope tracing bound for this request, by `request.id`                                                                                                                                                                                 |
+| `aroundInject(request, run)`         | runs `run` inside `bindActiveTrace(scope, …)`, which replaces the ambient context: the plugin injects the next queued prompt from the previous turn's settle hook, whose context is the previous request's                                                       |
+| `providerHeaders(request)`           | returns `X-Synadia-Thread-ID` and `X-Synadia-Root-ID` for the request, so the proxy files PI's own model calls on the served thread; each call counts against the scope, so an edge PI's model spawns later says how many calls came before it, retries included |
+| `aroundToolCall(request, tool, run)` | binds the request's scope around `run`, so the edge of a `prompt_agent` PI's model calls is filed under the served thread even if PI's tool runner did not inherit the injected context                                                                          |
+| `promptEnded(request)`               | forgets the request                                                                                                                                                                                                                                              |
+
+A request the add-on never saw (no scope kept) is left alone: no headers,
+`run` called as it is.
+
+**The `409` loop guard.** PI serves one turn at a time and cannot serve a
+prompt while its model waits on a call to another agent, so a prompt of a
+tree PI is waiting in is refused at once with `409` instead of queueing
+behind the wait it is part of. PI waits from the moment its model sends a
+prompt until every call the served request has open has settled: a
+blocking `prompt_agent` until it returns, a call started with `wait: false`
+for as long as it is open. With no call open, a prompt of the tree is
+admitted. The guard is two more interceptors and a wrapper: its request
+interceptor, after tracing's, keeps the served request by the scope tracing
+bound for the handler's duration and refuses an arriving prompt whose root
+a served request is waiting in, before `next()`, with
+`RequestRejectedError(409, …)`; its prompt interceptor, on the plugin's
+client, runs in the tool call's context and marks that request as waiting;
+its `aroundToolCall`, inside the add-on's, lifts the mark when a tool
+result counts no open call and no other agent-tool call of the request
+runs. A call that fails or expires while the model runs no agent tool keeps
+the mark until the next agent-tool result or the served prompt's end. The
+root is read from the scope tracing bound, never from the envelope. Stated
+honestly: this also refuses a legitimate second prompt of the same tree
+that arrives while PI waits in it, such as a sibling delegation issued with
+`wait: false` by the same coordinator; PI would have queued it anyway, and
+the guard turns the queue into a refusal the caller sees at once.
+
+**What it does not do.** No `served` record: PI's calls carry the headers,
+so they need none, and PI writes nothing to `TRACE.edges` but the edges of
+its own delegations. No `stopping`: an edge is published before the prompt
+it describes and counted as it goes, so there is nothing to flush.
+
+## Naming it
+
+Installed where PI runs, `npm install @synadia-ai/agent-fabric-pi`, and
+named to the plugin by package name when that directory is the plugin's or
+an ancestor of it, by absolute path otherwise (a package directory with
+`dist/` built):
+
+```sh
+SYNADIA_PI_EXTENSIONS=/opt/fabric/node_modules/@synadia-ai/agent-fabric-pi pi …
+```
+
+or in `nats-channel.json`, where an entry may carry options:
+
+```json
+{
+  "extensions": [
+    { "module": "@synadia-ai/agent-fabric-pi", "options": { "edgeSubject": "TRACE.edges" } }
+  ]
+}
+```
+
+`SYNADIA_PI_EXTENSIONS` wins over `SYNADIA_AGENT_EXTENSIONS`, which wins
+over the config field. The plugin's connect line and `/nats-status` list
+`extensions=agent-fabric` when the module is loaded.
+
+## The one setting
+
+The edge subject: the entry's `options.edgeSubject`, else the variable
+`SYNADIA_FABRIC_EDGE_SUBJECT`, else `TRACE.edges`. `null` in the options is
+propagate-only: lineage forwarded, no record published, no counts on the
+heartbeat. A subject that can never be published to (empty, an empty token,
+whitespace, a wildcard, not a string) stops the factory; the plugin logs
+`extension "…" not loaded: …` and starts plain, so the mistake is visible at
+start. There is no `tracing` setting: the add-on's presence is the switch.
+
+## ScratchPad
+
+The package carries ScratchPad's skill, adapted for an agent on the fabric,
+in `skill/scratchpad/`: `SKILL.md`, `scripts/sp`, and `bin/` with the sp
+command line for darwin and linux on arm64 and amd64. It is the one skill
+every add-on ships, kept in `../scratchpad-skill` and installed here by
+`npm run build:sp`. The model runs
+`scripts/sp` through PI's bash tool; the harness's tools stay as the
+operator configured them, and PI asks no permission for any command.
+
+**The operator's step.** Start PI with the skill and the bash tool on:
+
+```sh
+pi --mode rpc … \
+  -e <plugin>/extensions/nats-channel.ts \
+  --skill <add-on>/skill/scratchpad \
+  --tools bash,discover_agents,prompt_agent,answer_agent
+```
+
+`--skill` loads the directory even under `--no-skills`. PI lists the skill
+to the model only when its `bash` or `read` tool is on, so
+`--no-builtin-tools` alone hides it; `--tools` naming `bash` and the
+plugin's tools keeps them. Then name a volume for PI's identity, reserved
+by the ScratchPad operator: the extension entry's `options.scratchpad`, or
+the variable.
+
+```json
+{ "module": "@synadia-ai/agent-fabric-pi", "options": { "scratchpad": { "volume": "PiVol" } } }
+```
+
+**Where the settings come from.** Once the service is up, the add-on
+resolves each from the entry's `options.scratchpad` (`volume`, `dir`, `url`,
+`creds`), else the variable (`SCRATCHPAD_VOLUME`, `SCRATCHPAD_DIR`,
+`NATS_URL`, `NATS_CREDS`), else, for the URL and the credentials file, the
+plugin's own NATS context (`NATS_CONTEXT`, or `context` in
+`nats-channel.json`), which sp cannot read itself. The workspace defaults to
+`scratchpad/` in the plugin's state directory (`~/.pi/agent/scratchpad`),
+created if missing; keep it across restarts. Without a volume ScratchPad is
+off; without a URL and a credentials file it is off with a warning.
+
+**What `scripts/sp` gets.** The add-on sets these in PI's process, and PI's
+bash tool passes them to every command (measured on PI 0.85.1):
+
+| Variable                              | Set                                                           | `scripts/sp` adds                                                              |
+| ------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `SP_NATS_URL`, `SP_NATS_CREDS`        | at start                                                      | `--url`, `--creds`, every call                                                 |
+| `SCRATCHPAD_DIR`                      | at start                                                      | `--dir`, every call                                                            |
+| `SCRATCHPAD_VOLUME`                   | at start                                                      | `--volume`, on `init` only: a read refuses a volume other than the reference's |
+| `SP_CREATOR`                          | at start: PI's prompt address                                 | `--creator`, on `publish-file`                                                 |
+| `SP_THREAD_ID`, `SP_ROOT_ID`          | per served prompt, from its hand-over to PI's loop to its end | `--thread-id`, `--root-id`, every call                                         |
+| `SP_CALLER_ACCOUNT`, `SP_CALLER_USER` | the same, for a verified caller                               | `--grantee-account`, `--grantee-user`, on `grant` and after `publish-file`     |
+| `SP_GRANTS_FILE`                      | at start: `<workspace>.grants`                                | nothing: it records there each grant sp confirmed, for grant requests          |
+
+The connection has names of its own, not `NATS_URL` and `NATS_CREDS`, which
+a plugin may read as its own connection. The model passes none of these
+flags; `scripts/sp` refuses them, and refuses a `grant` when no served
+prompt has a verified caller, so PI grants read on what it publishes to the
+agent that prompted it and to no other. A `publish-file` during a served
+prompt with a verified caller also makes that grant, as an SDK-built agent
+grants the caller its reply: the result carries `granted_to_caller`, or
+`caller_grant_error`. Models skip a separate grant step often enough that
+the publication makes it (`docs/plugins.md` §9.12).
+On a platform sp is not built for, `scripts/sp` says so, in sp's own error
+shape with exit 2. `SCRATCHPAD_BIN` names another sp binary.
+
+**References in and out.** With ScratchPad on, the add-on registers PI as
+reading references (`scratchpad_refs_ok: "true"` through the extension's
+`metadata`), so discovery shows `reads_scratchpad_references: true` and a
+caller's `prompt_agent` hands them to PI. And the references PI's model puts
+into its own `prompt_agent` go through the fabric package's ScratchPad
+extension, as an SDK-built agent's do: a receiver that reads references is
+granted read, first-hand, right before the prompt goes out; any other gets
+the text without them and the call's result says how many were removed; a
+reference PI was neither given nor made is refused. A reference into PI's
+own volume counts as made by PI, since its model publishes with
+`scripts/sp`, which the extension does not see. The extension's own grants
+run the packaged sp directly, with the settings above.
+
+**Grant requests.** A caller PI handed a reference to may hand it on
+through its own agent tools; its ScratchPad extension then asks the creator,
+PI, to grant the receiver read (the grant request, `grant-request.ts` in
+the fabric package). The add-on answers on PI's service, by the rule every
+SDK-built agent answers by: the reference must point into PI's volume, the
+requester must hold a live read grant PI made it first-hand, the grantee
+must be another agent, and the grant is one path, read only, ten minutes at
+most, recorded as made on request, which entitles no one to ask again. The
+grants PI's model makes go through `scripts/sp`, which the add-on does not
+see, so `scripts/sp` records each one sp confirms in `SP_GRANTS_FILE`
+(`<workspace>.grants`), and the add-on counts a live one as first-hand: it
+went to the agent whose prompt PI was serving.
+
+## Identity
+
+Records are signed, so the plugin needs `senderIdentity: "signed"` with a
+NATS context carrying PI's own credentials. With identity off the add-on
+warns once at `started`, the fabric package warns once more when the first
+record is due, every record owed counts as dropped on the heartbeat, and
+PI's model calls still file under the caller's thread, since the headers
+need no signature.
+
+## What the console shows
+
+PI's model calls on the child thread the caller's edge created, PI the
+executor, its depth `full`; the caller's `asked` row names PI. A delegation
+PI's model makes is a grandchild under its tool call, PI's edge signed and
+verified. No outcome or duration from a pair: PI publishes none, and the
+thread's calls carry its timing.
+
+## Public API
+
+|                                                                                                                                                                               |                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default`, `fabricExtension(ctx, env?)`                                                                                                                                       | the factory of the contract: resolves ScratchPad, then builds the extension; `env` is where the variables are read and ScratchPad's are set, `process.env` by default |
+| `createFabricExtension(ctx, env?, scratchPad?)`                                                                                                                               | the same, synchronous, from settings already resolved                                                                                                                 |
+| `resolveEdgeSubject(options, env?)`                                                                                                                                           | the setting's precedence, as above                                                                                                                                    |
+| `SCRATCHPAD_OPTION`, `SP_VARS`, `ScratchPadHandOn`, `spBinary(env)`                                                                                                           | ScratchPad's option key, the variables `scripts/sp` reads, the tool extension, the packaged sp's path                                                                 |
+| `EXTENSION_NAME`, `EDGE_SUBJECT_OPTION`, `EDGE_SUBJECT_VAR`, `IDENTITY_OFF_WARNING`                                                                                           | the constants                                                                                                                                                         |
+| `loopGuard()`, `LOOP_GUARD_CODE`, `loopGuardDescription(rootId)`                                                                                                              | the guard on its own: `requestInterceptor`, `promptInterceptor`, `aroundToolCall(scope, run)`, `serving(rootId)`, `waiting(rootId)`                                   |
+| `AgentExtensionContext`, `AgentExtension`, `HarnessEvents`, `ServedRequest`, `Outcome`, `AgentExtensionHandles`, `AgentExtensionSettings`, `Harness`, `AgentExtensionFactory` | the plugin's contract, declared structurally so this package imports nothing of the plugin or of PI                                                                   |
+
+The setting's precedence, the loop guard and the contract's types live in
+`@synadia-ai/agent-fabric`, shared by every add-on under `plugins/`; this
+package re-exports them, the contract's `PluginHarness` as `Harness`.
+
+## Development
+
+Built like the fabric package (tsup, ESM and CJS, vitest, eslint,
+prettier). It links `@synadia-ai/agent-fabric` at `file:../../typescript`,
+built first, and the two protocol SDK packages by the same `file:` links
+the fabric package uses; its `package-lock.json` is committed, and a clean clone
+installs with `npm ci`. The tests: unit, a fake of the plugin driving the events
+(`test/support/fake-plugin.ts`); integration, the factory's hooks on a real
+`AgentService` and `Agents` over a local `nats-server` in operator mode,
+the edges on the wire validated against `test-fixtures/schemas/edge.json`.
+
+`npm run build:sp` installs the skill from `../scratchpad-skill` into
+`skill/scratchpad`. It downloads the four published binaries pinned in
+`../scratchpad-skill/release.json` and verifies their archive and executable
+hashes with Node 20+. `npm pack` runs it too (`prepack`). `skill/` is
+gitignored. No Go compiler or service checkout is required. The
+[binary guide](https://github.com/synadia-ai/agent-fabric-sdk/blob/main/docs/scratchpad-binaries.md) covers authenticated
+downloads, offline archives, cache checks, and the included licenses.
+`test/unit/scripts-sp.test.ts` drives the shared `scripts/sp` with fake
+binaries and a fake `uname`, and runs the real binary for this machine
+through the installed copy when it is built.
+
+```sh
+(cd ../../typescript && npm install && npm run build)
+npm install
+npm run build:sp
+npm run typecheck && npm run lint && npm run format:check
+npm test
+npm run build
+```
+
+## License
+
+Apache-2.0, like the fabric package. See [LICENSE](https://github.com/synadia-ai/agent-fabric-sdk/blob/main/plugins/pi/LICENSE).
+
+Short artifact references
+-------------------------
+
+The shared wrapper and grant records accept `sp-r1:` short tokens and existing `sp-ref:` tokens.
+Publication uses the short form when the service and the selected client support it.
+Short-token reads and resolution require a compatible `sp` binary selected through
+`SCRATCHPAD_BIN`. The bundled CLI release is pinned independently; this change
+does not advance that pin.
+Copy the returned token unchanged into prompts and replies.
+The token survives client restarts; each content read still requires current authorization.
+See the [native client contract](https://github.com/synadia-ai/agent-fabric-sdk/blob/main/docs/scratchpad-native.md) for recovery and capability fallback.

package/dist/index.cjs

@@ -0,0 +1,154 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var agentFabric = require('@synadia-ai/agent-fabric');
+var url = require('url');
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+var SKILL_DIR = url.fileURLToPath(new URL("../skill/scratchpad", importMetaUrl));
+function spBinary(env) {
+  return agentFabric.spBinary(env, SKILL_DIR);
+}
+function spPort(settings, creator, env) {
+  return agentFabric.spPort(settings, creator, env, SKILL_DIR);
+}
+
+// src/extension.ts
+var EXTENSION_NAME = "agent-fabric";
+var IDENTITY_OFF_WARNING = `${EXTENSION_NAME}: senderIdentity is off; trace records are signed, so none will be published and each counts as dropped on the heartbeat. Set senderIdentity to signed.`;
+async function fabricExtension(ctx, env = process.env) {
+  return createFabricExtension(ctx, env, await agentFabric.resolveScratchPad(ctx, env));
+}
+function createFabricExtension(ctx, env = process.env, scratchPad) {
+  const edgeSubject = agentFabric.resolveEdgeSubject(ctx.options, env);
+  const tracing = agentFabric.fabricTracing({ edgeSubject });
+  const guard = agentFabric.loopGuard();
+  const log = ctx.logger;
+  const scopes = /* @__PURE__ */ new Map();
+  const scopeOf = (request) => request === void 0 ? void 0 : scopes.get(request.id);
+  let warnedIdentityOff = false;
+  const scratchPadOn = scratchPad !== void 0;
+  const promptEnv = new agentFabric.ServedPromptEnv(env);
+  if (scratchPad !== void 0) agentFabric.exportScratchPad(scratchPad, env);
+  const handOn = scratchPad !== void 0 ? new agentFabric.ScratchPadHandOn() : void 0;
+  return {
+    name: EXTENSION_NAME,
+    // The service: tracing first, so the guard runs inside the scope tracing
+    // bound and a malformed pair is refused with 400 before the guard
+    // looks; the plugin appends its own (the tools' scope) after these.
+    // The ScratchPad extension's, last, remembers the references each
+    // served prompt brings, which PI may hand on.
+    requestInterceptors: [
+      tracing.requestInterceptor,
+      guard.requestInterceptor,
+      ...handOn !== void 0 ? [handOn.requestInterceptor] : []
+    ],
+    // The client PI's agent tools prompt through: the edge and the pair,
+    // then the waiting mark. Both read the ambient scope, so the order
+    // between them does not matter.
+    promptInterceptors: [tracing.promptInterceptor, guard.promptInterceptor],
+    heartbeatExtras: tracing.heartbeatExtras,
+    ...handOn !== void 0 ? {
+      // References in PI's `prompt_agent`: granted to a receiver that
+      // reads them, removed with a note for any other.
+      toolExtensions: [handOn],
+      // So a caller's `prompt_agent` hands references to PI.
+      metadata: { [agentFabric.READS_REFERENCES_KEY]: "true" }
+    } : {},
+    // No `stopping`: an
+    // edge record is published before the prompt it describes and counted
+    // as it goes, so there is nothing to flush when the plugin stops.
+    started({ agents, service }) {
+      if (ctx.settings.senderIdentity !== "signed" && !warnedIdentityOff) {
+        warnedIdentityOff = true;
+        log.warn(IDENTITY_OFF_WARNING);
+      }
+      log.info(
+        `${EXTENSION_NAME}: tracing ${service.subject.prompt}` + (edgeSubject === null ? " (propagate-only: lineage forwarded, no edge record published)" : `, edge records on ${edgeSubject}`)
+      );
+      if (scratchPad !== void 0 && handOn !== void 0) {
+        env[agentFabric.SP_VARS.creator] = service.subject.prompt;
+        const port = spPort(scratchPad, service.subject.prompt, env);
+        if (port !== void 0) handOn.start({ scratchPad: port, agents, service, logger: log });
+        else
+          log.warn(
+            `${EXTENSION_NAME}: no sp for this platform (set SCRATCHPAD_BIN); references in prompt_agent are not handed on, and grant requests not answered`
+          );
+        log.info(
+          `${EXTENSION_NAME}: ScratchPad volume ${scratchPad.volume}` + (scratchPad.dir !== void 0 ? `, workspace ${scratchPad.dir}` : ", no workspace") + ", for the skill's scripts/sp"
+        );
+      }
+    },
+    events: {
+      promptAccepted(request) {
+        const scope = agentFabric.activeTrace();
+        if (scope !== void 0) scopes.set(request.id, scope);
+      },
+      promptEnded(request) {
+        scopes.delete(request.id);
+        promptEnv.leave(request);
+      },
+      aroundInject(request, run) {
+        const scope = scopes.get(request.id);
+        if (scratchPadOn) promptEnv.enter(request, scope);
+        return scope === void 0 ? run() : agentFabric.bindActiveTrace(scope, run);
+      },
+      providerHeaders(request) {
+        const scope = scopes.get(request.id);
+        return scope === void 0 ? void 0 : agentFabric.bindActiveTrace(scope, agentFabric.traceHeaders);
+      },
+      aroundToolCall(request, _toolName, run) {
+        const scope = scopeOf(request);
+        return scope === void 0 ? run() : agentFabric.bindActiveTrace(scope, () => guard.aroundToolCall(scope, run));
+      }
+    }
+  };
+}
+
+Object.defineProperty(exports, "EDGE_SUBJECT_OPTION", {
+  enumerable: true,
+  get: function () { return agentFabric.EDGE_SUBJECT_OPTION; }
+});
+Object.defineProperty(exports, "EDGE_SUBJECT_VAR", {
+  enumerable: true,
+  get: function () { return agentFabric.EDGE_SUBJECT_VAR; }
+});
+Object.defineProperty(exports, "LOOP_GUARD_CODE", {
+  enumerable: true,
+  get: function () { return agentFabric.LOOP_GUARD_CODE; }
+});
+Object.defineProperty(exports, "SCRATCHPAD_OPTION", {
+  enumerable: true,
+  get: function () { return agentFabric.SCRATCHPAD_OPTION; }
+});
+Object.defineProperty(exports, "SP_VARS", {
+  enumerable: true,
+  get: function () { return agentFabric.SP_VARS; }
+});
+Object.defineProperty(exports, "ScratchPadHandOn", {
+  enumerable: true,
+  get: function () { return agentFabric.ScratchPadHandOn; }
+});
+Object.defineProperty(exports, "loopGuard", {
+  enumerable: true,
+  get: function () { return agentFabric.loopGuard; }
+});
+Object.defineProperty(exports, "loopGuardDescription", {
+  enumerable: true,
+  get: function () { return agentFabric.loopGuardDescription; }
+});
+Object.defineProperty(exports, "resolveEdgeSubject", {
+  enumerable: true,
+  get: function () { return agentFabric.resolveEdgeSubject; }
+});
+exports.EXTENSION_NAME = EXTENSION_NAME;
+exports.IDENTITY_OFF_WARNING = IDENTITY_OFF_WARNING;
+exports.createFabricExtension = createFabricExtension;
+exports.default = fabricExtension;
+exports.fabricExtension = fabricExtension;
+exports.spBinary = spBinary;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map