@synadia-ai/agent-fabric-claude-code 0.1.0 → 0.3.0

package/skills/configure/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: configure
+description: Configure NATS channel - select context, set owner/session, sender identity, inbound trust, and permissions. Use when user asks to set up NATS, connect to NATS, change context, identity, trust, or permissions.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash(ls *)
+  - Bash(mkdir *)
+  - Bash(nats context ls *)
+  - Bash(cat *)
+  - Bash(*list-contexts*)
+effort: low
+---
+
+# /nats-channel:configure - NATS Channel Configuration
+
+Configures the NATS channel plugin: connection context, session name, sender
+identity, inbound sender trust, and permission handling. State lives in
+`~/.claude/channels/nats/config.json`.
+
+Arguments passed: `$ARGUMENTS`
+
+---
+
+## Dispatch on arguments
+
+### No args - status, list, and offer to change
+
+Read state and give the user a complete picture, then ask:
+
+1. **Current config** - read `~/.claude/channels/nats/config.json`. Show:
+   - Selected context name (or "none - using demo.nats.io")
+   - Owner override (if set)
+   - Session name override (if set)
+   - Sender identity mode (`off` or `signed`; default `off`)
+   - Minimum sender trust (`any` or `signed`; default `any`)
+   - Connection URL and description from the context file
+   - Permission mode (`terminal` or `query`) and whether permission prompts
+     will be relayed as NATS query chunks or handled in the local terminal
+
+2. **Available contexts** - run the `list-contexts.sh` script bundled
+   alongside this skill file to list all NATS CLI contexts with their
+   URL and description.
+
+3. **Ask the user** - show the numbered list of available contexts and
+   ask if they'd like to switch. Example:
+   - *"Currently using `<name>`. Available contexts:"*
+   - *(numbered list)*
+   - *"Would you like to switch? Enter a context name or number, or
+     'no' to keep the current selection."*
+   If no config is set, skip straight to asking them to pick one.
+
+### `list` - list available NATS contexts
+
+Two separate steps - do NOT combine into one Bash call:
+
+1. Bash: run the `list-contexts.sh` script bundled alongside this skill
+   file. It produces no stdout - it writes to a file.
+2. Read: open `~/.claude/channels/nats/.contexts` and present the
+   markdown table to the user.
+
+### `<context-name>` - select a context
+
+1. Treat `$ARGUMENTS` as the context name (trim whitespace).
+2. Verify `~/.config/nats/context/<name>.json` exists. If not, show
+   available contexts and error.
+3. Read the context file. Show the URL and description so the user can
+   confirm it's correct.
+4. `mkdir -p ~/.claude/channels/nats`
+5. Read existing `config.json` if present; update/add the `context` field,
+   preserve other fields (like `sessionName`, `permissions`). Write back.
+6. Confirm, then show the status view so the user sees where they stand.
+
+### `session <name>` - set session name override
+
+1. The session name is the 5th token in the v0.3 verb-first subject
+   `agents.prompt.cc.<owner>.<name>`. It defaults to the working directory
+   basename. This command overrides it.
+2. Read existing `config.json` (or start fresh). Set `sessionName` field.
+   Write back.
+3. Confirm the override.
+
+### `session clear` - remove session name override
+
+Remove the `sessionName` field from `config.json` so the default
+(CWD basename) is used.
+
+### `owner <name>` - set owner override
+
+1. The owner is the 4th token in the v0.3 verb-first subject
+   `agents.prompt.cc.<owner>.<name>`. It defaults to the sanitized
+   `$USER`. This command overrides it — useful for service accounts or
+   deployment-scoped owners.
+2. Read existing `config.json` (or start fresh). Set the `owner` field.
+   Write back.
+3. Confirm the override. Note: the `SYNADIA_CLAUDE_CODE_OWNER` and
+   `SYNADIA_OWNER` env vars take precedence over this config field.
+
+### `owner clear` - remove owner override
+
+Remove the `owner` field from `config.json` so the default (sanitized
+`$USER`) is used.
+
+### `identity off` - disable host identity
+
+Set `senderIdentity` to `"off"`. The channel performs no host identity lookup
+and registers no identity metadata. This is the default and works with
+token/password authentication and servers where user-info lookup is not
+permitted. It does not change inbound sender policy.
+
+### `identity signed` - use the connection identity
+
+Set `senderIdentity` to `"signed"`. The selected NATS context must contain a
+user seed (`creds`, `nkey`, or `user_jwt` plus `user_seed`). The same immutable
+credential snapshot supplies both connection authentication and signing; never
+ask for or add a second identity credential. Signed startup fails rather than
+downgrading when the connection cannot be bound to that signer.
+
+`NATS_SENDER_IDENTITY` overrides this config field. A plugin reload or Claude
+Code restart is required after changing it.
+
+### `trust any` - accept all sender trust classes
+
+Set `minSenderTrust` to `"any"`. Headerless, claimed, and verified prompts are
+admitted. This is the backward-compatible default and is independent of the
+channel's own identity.
+
+### `trust signed` - require verified senders
+
+Set `minSenderTrust` to `"signed"`. Headerless, claimed, malformed, stale, and
+replayed requests are rejected before an acknowledgement and before Claude sees
+the prompt. `NATS_MIN_SENDER_TRUST` overrides this config field.
+
+### `permissions terminal` - use terminal for permission prompts
+
+Set `permissions.mode` to `terminal`. Permission prompts will appear in the
+Claude Code terminal session. This is the simplest option when the operator
+has direct terminal access, and the default when no permissions block is set.
+
+1. Read existing `config.json` (or start fresh).
+2. Set `permissions` to `{ "mode": "terminal" }`.
+3. Write back and confirm.
+
+### `permissions query` - relay permissions as query chunks
+
+Set `permissions.mode` to `query`. When Claude needs permission to use a
+tool during an active NATS prompt, the plugin emits a protocol `query`
+chunk (§7 of the Synadia Agent Protocol for NATS) on the active stream's reply
+subject. The caller replies with `yes`/`no` on the query's dynamic reply
+inbox, and the plugin forwards the decision back to the Claude Code
+harness. The legacy value `"nats"` is accepted as an alias for
+backward compatibility.
+
+If Claude asks for permission while no NATS request is active, the request
+is denied (there is no open stream to carry a query chunk on). Operators
+who need terminal-style prompting in that case should use `permissions
+terminal` instead.
+
+1. Read existing `config.json` (or start fresh).
+2. Set `permissions` to `{ "mode": "query" }`.
+3. Write back and confirm.
+
+### `permissions clear` - reset to default
+
+Remove the `permissions` field from `config.json`, restoring the default
+behavior (terminal-mode prompts).
+
+### `clear` - remove config
+
+Delete `~/.claude/channels/nats/config.json`.
+
+---
+
+## Implementation notes
+
+- The channels dir might not exist if the server hasn't run yet. Missing
+  file = not configured, not an error.
+- The server reads `config.json` once at boot. Config changes need a
+  session restart or `/reload-plugins`. Say so after saving.
+- NATS CLI contexts live in `~/.config/nats/context/<name>.json`. Each
+  file contains `url`, `description`, `creds`, `nkey`, `user`, `password`,
+  `token`, `cert`, `key`, `ca`, and other fields.
+- Do not modify NATS CLI context files - only read them.
+- `senderIdentity` and `minSenderTrust` are independent. Do not enable strict
+  inbound policy merely because signed host identity was enabled.
+- Legacy configs with `"mode": "nats"` are still accepted and treated as
+  the new `"query"` mode; they do not need to be rewritten.
+- Legacy configs with `permissions.subject` are silently ignored - query
+  chunks use a dynamic reply inbox per request, not a fixed subject.

package/skills/configure/list-contexts.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# List NATS CLI contexts as a markdown table.
+# Writes to ~/.claude/channels/nats/.contexts for the skill to Read.
+
+CONTEXT_DIR="${HOME}/.config/nats/context"
+STATE_DIR="${HOME}/.claude/channels/nats"
+OUT="${STATE_DIR}/.contexts"
+
+mkdir -p "$STATE_DIR"
+
+if [ ! -d "$CONTEXT_DIR" ]; then
+  echo "No NATS contexts found (${CONTEXT_DIR} does not exist)" > "$OUT"
+  exit 0
+fi
+
+{
+  echo "| Name | URL | Description |"
+  echo "|------|-----|-------------|"
+  jq -r 'input_filename as $f |
+    [($f | split("/") | last | rtrimstr(".json")), (.url // "-"), (.description // "-")] |
+    "| \(.[0]) | \(.[1]) | \(.[2]) |"' "$CONTEXT_DIR"/*.json 2>/dev/null
+} > "$OUT"

package/skills/scratchpad/SKILL.md

@@ -26,7 +26,7 @@ shell command can then allow `scripts/sp` by its path, and does not ask.
 the NATS server, this agent's credentials, its workspace, its volume on
 `init`, the trace of the prompt you are serving, your address as the
 creator of what you publish, and the agent that prompted you as the grantee
-of a grant. Never pass `--url`, `--creds`, `--dir`, `--volume`,
+of a grant. Never pass `--url`, `--creds`, `--dir`, `--volume`, `--bootstrap-file`,
 `--thread-id`, `--root-id`, `--creator`, `--grantee-account` or
 `--grantee-user` yourself; `scripts/sp` refuses them.
 
@@ -39,8 +39,8 @@ The workspace is private to this agent and persists across restarts.
 Each successful command prints JSON.
 Read the returned receipt before reporting that publication succeeded.
 An upload alone does not publish a checkpoint.
-Retention preserves the root until explicit release.
-Its deadline permits later client cleanup.
+Retention preserves the root for its recorded promise.
+A finite deadline permits later cleanup by the client or the private lifecycle worker.
 A grant separately permits one authenticated principal to read that root and path.
 Do not print credential contents.
 
@@ -68,13 +68,27 @@ An expired reference or refused grant does not authorize another identity or pat
 
 ```sh
 scripts/sp info
-scripts/sp init --operation-id "$CREATE_ID"
+scripts/sp init
 scripts/sp describe
 ```
 
 `info` returns this agent's authenticated principal, owned scope allowances, and request limits.
 It needs no initialized workspace and changes no recovery state.
 The scope byte and object figures are configured allowances; `describe` shows current usage.
+
+### Import the configured bootstrap
+
+When `SCRATCHPAD_BOOTSTRAP_FILE` is configured, the wrapper supplies it on `init`.
+The public file selects one volume, admission binding, and complete saved creation Action.
+It contains no credentials and supplies no authentication authority.
+Run `scripts/sp init` without inventing a creation operation identifier.
+Keep both the file and the private workspace across restarts.
+An exact matching import preserves existing commands, writer state, and unknown outcomes.
+A different creation request refuses; an `exists` result never permits adoption.
+Saved creation recovery uses the owner's connection and does not need admin ensure.
+An expiry or closed refusal alone does not settle an earlier possibly sent creation.
+An explicit later admission needs a separate workspace; never erase the earlier one to continue.
+A configured custom volume must match the file. Unsupported command lines refuse the import.
 An empty scope list needs an operator admission check before this agent can publish.
 Volumes readable through another owner's grant are not listed; their granted references can still be read.
 If `info` reports an unknown command, an older binary was selected; continue with the existing commands and ask the operator for the allowances.
@@ -83,6 +97,10 @@ If `info` reports an unknown command, an older binary was selected; continue wit
 Rerun the saved creation action after an unknown outcome.
 An established writer whose journal disappeared requires an explicit reset.
 Initialization cannot silently reset that writer.
+For a reusable lifetime, `info` also returns its admission binding.
+`init` saves that binding before its first creation request and reuses it after a restart.
+A saved creation cannot adopt a later admission with the same volume name.
+Preserve the workspace after a refusal; do not erase it to bypass lifetime fencing.
 
 ## Publish a file and share it with the agent that prompted you
 
@@ -194,9 +212,12 @@ scripts/sp maintain --apply
 ```
 
 The first command reports the proposed maintenance.
-The second releases unprotected expired pins, closes the volume, traces retained dependencies, collects unreachable objects, and reopens it.
+The second releases unprotected expired pins and closes a collection interval.
+On a reusable deployment, private maintenance traces retained dependencies,
+collects unreachable objects and reopens that interval. The client observes its completion.
+On an existing deployment, the client performs that collection.
 Maintenance does not scrub retained file payloads.
-If interrupted, recover the saved request or repeat maintenance against the durable closed state.
+If interrupted, recover the saved request. A newer collection interval fences that request.
 Capacity refusal requires maintenance or an explicit operator decision; it never permits eviction of retained content.
 
 ## Capacity
@@ -207,3 +228,63 @@ Objects include chunks, file metadata, and directories.
 Retained results and unfinished uploads consume the same allowance.
 Replacing unique content needs room for both versions until old retention is released and collection completes.
 Local spools also need enough private disk space for the prepared artifact.
+
+### Choose what to remove at capacity
+
+On a reusable volume, `describe` includes `lifetime` with the lease, grace period,
+recovery-read state and reserved metadata allowance.
+Choose a path from the current head to remove. The service never chooses a live
+file to evict because the volume is full.
+
+```sh
+scripts/sp remove --path "$ARTIFACT_PATH" --operation-id "$REMOVE_ID"
+scripts/sp remove --path "$ARTIFACT_PATH" --operation-id "$REMOVE_ID" --apply
+```
+
+The first command reports a plan without changing the head.
+Applying saves the exact command and uses reserved metadata space within the reported bounds.
+The receipt confirms the new head. Retention or grants can still protect the removed content.
+Private maintenance returns space after that content is no longer protected.
+After an unknown result, use `recover`; do not change the saved path or operation identifier.
+Older binaries or deployments can refuse this command; that refusal does not permit eviction.
+
+### Keep or end a reusable lifetime
+
+A volume with `lifetime.expires_at` equal to zero is durable.
+For a managed lease, request one absolute Unix deadline in seconds:
+
+```sh
+scripts/sp renew --until "$UNTIL"
+```
+
+Save and retry the same deadline. Renewal must win before retirement begins.
+An already achieved renewal can still recover after that deadline passes.
+If recovery reports definite `expired` for an unachieved saved deadline, only the
+renewal intent is cleared. Request a new absolute deadline if the same lifetime is
+still renewable, then recover the unchanged ordinary pending operation.
+An unknown result keeps the saved renewal pending; do not replace its deadline.
+During recorded grace, recovery reads can remain available while ordinary writes are closed.
+Do not infer disposal authority from an agent disconnect, an idle volume, or full quota.
+
+Whole-volume retirement ends all head, retention, grant and access promises in its plan.
+It can permanently delete every artifact. Use it only when the user has authorized
+ending those promises and any required export has been restored and checked.
+
+```sh
+scripts/sp retire --operation-id "$RETIRE_ID"
+scripts/sp retire --operation-id "$RETIRE_ID" --end-promises --apply
+```
+
+Review the first result before applying. The exact terminal operation persists for recovery.
+If recovery proves a strictly newer nonterminal plan for the same incarnation,
+slot, generation, target, and saved request, it clears only the old release intent
+and reports `fenced`. The lifetime remains nonterminal. Inspect the reported
+lifetime and renew before ordinary work if needed. Review a new plan before
+applying again; this refusal does not mean that artifacts were disposed or capacity returned.
+Unknown or mismatched evidence and an already accepted terminal fence stay pending.
+`disposed` reports physical disposal; only `capacity_returned` confirms admission capacity is free.
+If a successor generation proves the old lifetime ended but this workspace never
+observed its own release fence, recovery also reports `acceptance_unknown: true`.
+That result confirms capacity return while leaving the original operation's acceptance unknown.
+Preserve the old workspace through completion. A later admission is a different lifetime,
+and old references and receipts do not select it.

package/skills/scratchpad/scripts/sp

@@ -50,7 +50,7 @@ refuse() {
 }
 
 # The command: the first argument that is not a flag or a flag's value, as
-# sp itself finds it. Every sp flag but --apply and --help takes a value.
+# sp itself finds it. --apply, --end-promises and --help take no value.
 # On the way, the operation id and the expiry, for the caller's grant after
 # a publication, and the reference, for the record of a grant.
 command=
@@ -70,7 +70,7 @@ for arg in "$@"; do
   fi
   case $arg in
     --) break ;;
-    -apply | --apply | -help | --help | -h) ;;
+    -apply | --apply | -end-promises | --end-promises | -help | --help | -h) ;;
     -*=*)
       name=${arg%%=*}
       case ${name#-} in
@@ -94,7 +94,7 @@ for arg in "$@"; do
   case $arg in
     -*)
       case $name in
-        url | creds | dir | volume | thread-id | root-id | tool-call-id | creator | grantee-account | grantee-user)
+        url | creds | dir | volume | bootstrap-file | thread-id | root-id | tool-call-id | creator | grantee-account | grantee-user)
           refuse "--$name is set by the agent, not passed; run the command without it" ;;
       esac
       ;;
@@ -102,12 +102,12 @@ for arg in "$@"; do
 done
 
 if [ -n "${SP_ENV_FILE:-}" ] && [ -f "$SP_ENV_FILE" ]; then
-  unset SP_THREAD_ID SP_ROOT_ID SP_CALLER_ACCOUNT SP_CALLER_USER
+  unset SP_THREAD_ID SP_ROOT_ID SP_CALLER_ACCOUNT SP_CALLER_USER SCRATCHPAD_VOLUME SCRATCHPAD_BOOTSTRAP_FILE
   while IFS= read -r line || [ -n "$line" ]; do
     case $line in
       *=*)
         case ${line%%=*} in
-          SP_NATS_URL | SP_NATS_CREDS | SCRATCHPAD_DIR | SCRATCHPAD_VOLUME | SP_CREATOR | \
+          SP_NATS_URL | SP_NATS_CREDS | SCRATCHPAD_DIR | SCRATCHPAD_VOLUME | SCRATCHPAD_BOOTSTRAP_FILE | SP_CREATOR | \
             SP_THREAD_ID | SP_ROOT_ID | SP_CALLER_ACCOUNT | SP_CALLER_USER | SP_GRANTS_FILE)
             # The name is one of these; the value is assigned as it is.
             eval "${line%%=*}=\${line#*=}"
@@ -150,8 +150,14 @@ fi
 
 case $command in
   init)
-    [ -n "${SCRATCHPAD_VOLUME:-}" ] || refuse "ScratchPad has no volume for this agent: SCRATCHPAD_VOLUME is unset"
-    set -- --volume "$SCRATCHPAD_VOLUME" "$@"
+    if [ -n "${SCRATCHPAD_BOOTSTRAP_FILE:-}" ]; then
+      set -- --bootstrap-file "$SCRATCHPAD_BOOTSTRAP_FILE" "$@"
+    else
+      [ -n "${SCRATCHPAD_VOLUME:-}" ] || refuse "ScratchPad has no volume or bootstrap file for this agent"
+    fi
+    if [ -n "${SCRATCHPAD_VOLUME:-}" ]; then
+      set -- --volume "$SCRATCHPAD_VOLUME" "$@"
+    fi
     ;;
   publish-file)
     if [ -n "${SP_CREATOR:-}" ]; then

package/CHANGELOG.md

@@ -1,18 +0,0 @@
-# Changelog
-
-All notable changes to `@synadia-ai/agent-fabric-claude-code` 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 Claude Code channel plugin, named in `SYNADIA_CLAUDE_CODE_EXTENSIONS`: `fabricTracing()` on the plugin's service and agent-tools client.
-- The signed `served` pair binding each served prompt to the Claude Code session, its `end` at the turn's `Stop`.
-- The `409` loop guard in front of the channel's handler.
-- The settings: the edge subject (`options.edgeSubject`, `SYNADIA_FABRIC_EDGE_SUBJECT`, or `TRACE.edges`) and `options.stopWaitMs`.
-- The Claude Code plugin `agent-fabric`: the ScratchPad skill with the sp command line for darwin and linux, and the `SessionStart` hook that names the file `scripts/sp` reads.
-- ScratchPad: references in and out, and grant requests.
-
-[0.1.0]: https://github.com/synadia-ai/agent-fabric-sdk/tree/main/plugins/claude-code