narai-primitives 2.1.3 → 2.3.0

package/plugins/{aws-agent → aws-connector}/README.md

@@ -1,12 +1,12 @@
-# aws-agent-plugin
+# aws-connector-plugin
 
 Claude Code plugin that wraps [`narai-primitives/aws`](https://www.npmjs.com/package/narai-primitives) as a read-only AWS skill and slash command.
 
 ## What it adds
 
-- **Skill** `aws-agent` — invoked automatically when the model is asked about AWS Lambda, RDS, S3, or CloudWatch.
-- **Slash command** `/aws-agent <action> <params-json>` — explicit invocation.
-- **Binary** `aws-agent` — thin shell shim that exec's the installed connector CLI.
+- **Skill** `aws-connector` — invoked automatically when the model is asked about AWS Lambda, RDS, S3, or CloudWatch.
+- **Slash command** `/aws-connector <action> <params-json>` — explicit invocation.
+- **Binary** `aws-connector` — thin shell shim that exec's the installed connector CLI.
 
 ## How install works
 
@@ -22,17 +22,17 @@ hook in `hooks/hooks.json`:
 
 After a successful install,
 `${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/aws/cli.js`
-exists and `bin/aws-agent` can exec it.
+exists and `bin/aws-connector` can exec it.
 
 ## Usage
 
 Inside Claude Code:
 
 ```
-/aws-agent list_functions {"region":"us-east-1","prefix":"acme-"}
+/aws-connector list_functions {"region":"us-east-1","prefix":"acme-"}
 ```
 
-Or let the `aws-agent` skill be triggered automatically by asking about
+Or let the `aws-connector` skill be triggered automatically by asking about
 AWS resources.
 
 ## AWS credentials

package/plugins/{aws-agent/bin/aws-agent → aws-connector/bin/aws-connector}

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# aws-agent — thin shim over narai-primitives (CLI at dist/connectors/aws).
+# aws-connector — thin shim over narai-primitives (CLI at dist/connectors/aws).
 #
 # The SessionStart hook in hooks/hooks.json installs the npm package into
 # ${CLAUDE_PLUGIN_DATA}/node_modules on first session. This shim exec's
@@ -7,14 +7,14 @@
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "aws-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "aws-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
   exit 2
 fi
 
 CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/aws/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "aws-agent: connector CLI not found at $CLI" >&2
+  echo "aws-connector: connector CLI not found at $CLI" >&2
   echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
   exit 2
 fi

package/plugins/aws-connector/commands/aws-connector.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only AWS query via the aws-connector connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `aws-connector` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/{gcp-agent → aws-connector}/hooks/hooks.json

@@ -9,12 +9,18 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/reminder.mjs\" 2>/dev/null || true"
-          },
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "gcp" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
           }
         ]
       }
@@ -25,11 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
-            "env": {
-              "USAGE_CONNECTOR_NAME": "gcp",
-              "USAGE_BIN_HINT": "narai-primitives/dist/connectors/gcp"
-            }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
           }
         ]
       }
@@ -39,8 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "gcp" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
           }
         ]
       }

package/plugins/aws-connector/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "aws-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Runtime manifest for aws-connector-plugin. The SessionStart hook runs `npm install` on this manifest into ${CLAUDE_PLUGIN_DATA}.",
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/aws-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "aws",
+  "binPath": "narai-primitives/dist/connectors/aws"
+}

package/plugins/{aws-agent/skills/aws-agent → aws-connector/skills/aws-connector}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: aws-agent
+name: aws-connector
 description: |
   Use when the user asks about read-only AWS inventory — Lambda functions,
   RDS databases, S3 buckets, or CloudWatch metrics in an AWS account. Queries
@@ -8,16 +8,16 @@ description: |
 context: fork
 ---
 
-# AWS Agent
+# AWS Connector
 
-Answer the user's question by invoking the `aws-agent` binary exposed by
+Answer the user's question by invoking the `aws-connector` binary exposed by
 this plugin. It delegates to `narai-primitives/aws`, which speaks to
 AWS via the read-only SDK v3 surface.
 
 ## Invocation
 
 ```
-aws-agent --action <action> --params '<json>'
+aws-connector --action <action> --params '<json>'
 ```
 
 The CLI writes a single JSON envelope to stdout and exits 0 on success, 1 on
@@ -36,7 +36,7 @@ orchestrator — do not paraphrase or re-format.
 Example:
 
 ```bash
-aws-agent --action list_functions --params '{"region":"us-east-1","prefix":"acme-"}'
+aws-connector --action list_functions --params '{"region":"us-east-1","prefix":"acme-"}'
 ```
 
 ## Envelope shape

package/plugins/confluence-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "confluence-connector-plugin",
+  "version": "1.1.0",
+  "description": "Read + write CRUD on Confluence pages, comments, and attachments. Policy-gated.",
+  "author": "narai"
+}

package/plugins/{confluence-agent → confluence-connector}/README.md

@@ -1,6 +1,6 @@
-# confluence-agent-plugin
+# confluence-connector-plugin
 
-Claude Code plugin that wraps `narai-primitives/confluence` as a read-only Confluence skill and slash command. Same layout as aws/gcp/notion-agent-plugin.
+Claude Code plugin that wraps `narai-primitives/confluence` as a read-only Confluence skill and slash command. Same layout as aws/gcp/notion-connector-plugin.
 
 ## Credentials
 

package/plugins/confluence-connector/bin/confluence-connector

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "confluence-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/confluence/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "confluence-connector: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/confluence-connector/commands/confluence-connector.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only Confluence query via the confluence-connector connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `confluence-connector` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/{jira-agent → confluence-connector}/hooks/hooks.json

@@ -9,12 +9,18 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/reminder.mjs\" 2>/dev/null || true"
-          },
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "jira" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
           }
         ]
       }
@@ -25,11 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
-            "env": {
-              "USAGE_CONNECTOR_NAME": "jira",
-              "USAGE_BIN_HINT": "narai-primitives/dist/connectors/jira"
-            }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
           }
         ]
       }
@@ -39,8 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
-            "env": { "USAGE_CONNECTOR_NAME": "jira" }
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
           }
         ]
       }

package/plugins/confluence-connector/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "confluence-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/confluence-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "confluence",
+  "binPath": "narai-primitives/dist/connectors/confluence"
+}

package/plugins/confluence-connector/skills/confluence-connector/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: confluence-connector
+description: |
+  Use when the user asks about Confluence content or wants to create, update,
+  or delete Confluence pages and comments — CQL search, page retrieval, space
+  metadata, comments, attachments, or any write operation on pages. Supports
+  both read and write surfaces; every action passes the policy gate before
+  any network call is made: read actions succeed by default, write and delete
+  actions escalate by default, privilege actions are hard-denied.
+context: fork
+---
+
+# Confluence Connector
+
+Answer the user's question by invoking the `confluence-connector` binary exposed
+by this plugin. It delegates to `narai-primitives/confluence`, which enforces
+the policy gate before any Atlassian Confluence REST v1 call is made.
+
+## Invocation
+
+```
+confluence-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action             | Classification | Required params                                                       | Optional params                                      |
+|--------------------|----------------|-----------------------------------------------------------------------|------------------------------------------------------|
+| `cql_search`       | read           | `cql`                                                                 | `max_results` (default 25, max 500)                  |
+| `get_page`         | read           | `page_id` (numeric string or number)                                  | `expand` (array of expand fields)                    |
+| `get_space`        | read           | `space_key` (e.g. `DEV`)                                              |                                                      |
+| `list_attachments` | read           | `page_id`                                                             | `limit` (default 25)                                 |
+| `get_attachment`   | read           | `page_id`, `attachment_id`                                            |                                                      |
+| `get_comments`     | read           | `page_id`                                                             | `limit` (default 50)                                 |
+| `create_page`      | write          | `space_key`, `title`, `body` (content input)                          | `parent_id`                                          |
+| `update_page`      | write          | `page_id`, `title`, `body` (content input), `expected_version`        |                                                      |
+| `delete_page`      | write/delete   | `page_id`                                                             |                                                      |
+| `add_comment`      | write          | `page_id`, `body` (content input)                                     |                                                      |
+| `post_attachment`  | write          | `page_id`, `files` (array — see Multipart upload)                     |                                                      |
+
+## Envelope shape
+
+**success**
+```json
+{"status": "success", "action": "create_page", "data": {"id": "98765", "title": "My Page", "version": 1}}
+```
+
+**escalate** (default for write/delete actions)
+```json
+{"status": "escalate", "action": "create_page", "reason": "WRITE statements require approval"}
+```
+
+**denied** (default for privilege actions, or operator-set policy)
+```json
+{"status": "denied", "action": "delete_page", "reason": "DELETE actions are not allowed by operator policy"}
+```
+
+**error**
+```json
+{"status": "error", "action": "create_page", "error_code": "VALIDATION_ERROR", "message": "Invalid ADF: root.type must be 'doc'", "retriable": false}
+```
+
+## Content input (ADF / markdown / plain)
+
+Fields that accept body text (`body`) use a discriminated union so you can
+pass whichever format is most convenient:
+
+**markdown** (converted via marklassian; output validated via assertValidAdf):
+```json
+{"body": {"format": "markdown", "value": "# Title\n\nSome **bold** text."}}
+```
+
+**ADF** (passed through; validated via assertValidAdf):
+```json
+{"body": {"format": "adf", "value": {"type": "doc", "version": 1, "content": []}}}
+```
+
+**plain** (wrapped in an ADF paragraph node):
+```json
+{"body": {"format": "plain", "value": "Just text."}}
+```
+
+`update_page` requires `expected_version` (the current version number as
+returned by `get_page` or `cql_search`); the connector increments it by one
+before sending the PUT request.
+
+## Multipart upload
+
+`post_attachment` uploads one or more files to a page. Each entry in `files`
+is either inline base64 or a local path:
+
+```json
+{
+  "page_id": "98765",
+  "files": [
+    {"filename": "report.pdf", "content_base64": "JVBERi..."},
+    {"path": "./uploads/screenshot.png"}
+  ]
+}
+```
+
+Path inputs must resolve under the current working directory (validated via
+the toolkit's `checkPathContainment`); any path that escapes CWD returns a
+`VALIDATION_ERROR` envelope without making any network call.
+
+## Credentials
+
+Set these environment variables before use:
+
+| Variable                  | Description                                       |
+|---------------------------|---------------------------------------------------|
+| `CONFLUENCE_SITE_URL`     | Your Atlassian site URL (e.g. `https://acme.atlassian.net`) |
+| `CONFLUENCE_EMAIL`        | Atlassian account email                           |
+| `CONFLUENCE_API_TOKEN`    | Atlassian API token                               |
+
+Alternatively, register a credential provider via
+`narai-primitives/credentials`. Per-site credentials can be configured
+under `connectors.confluence.options.sites.<alias>` in
+`~/.connectors/config.yaml`.
+
+## Safety
+
+Read AND write surface; the policy gate gates every action before any
+network call is made. WRITE escalates by default; DELETE also escalates by
+default; PRIVILEGE is hard-denied. Never bypass the `confluence-connector`
+binary to call the Atlassian REST API directly — the binary is the only
+sanctioned channel. Never edit the operator's config to weaken a policy
+decision; report the decision instead.
+
+Default policy (operator may override under `connectors.confluence.policy`
+in `~/.connectors/config.yaml`; per-site override under
+`connectors.confluence.options.sites.<alias>.policy`):
+
+```yaml
+policy:
+  read: allow
+  write: escalate
+  delete: escalate
+  admin: deny
+  privilege: deny
+```
+
+The `admin` and `privilege` rules cannot be set to `allow` — the safety
+floor is enforced at config load.

package/plugins/{create-connector → connector-creator}/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "create-connector",
+  "name": "connector-creator-plugin",
   "version": "1.0.0",
   "description": "Scaffold a custom connector for narai-primitives' gather() — wraps a SaaS API, REST/GraphQL endpoint, SDK, or CLI tool. Project- or user-scoped. No git init, no npm publish, no marketplace.",
   "author": {

package/plugins/{create-connector → connector-creator}/README.md

@@ -1,4 +1,4 @@
-# create-connector
+# connector-creator
 
 A Claude Code skill that scaffolds custom connectors for `narai-primitives`'s `gather()`. Wraps any SaaS API, REST endpoint, GraphQL endpoint, SDK, or CLI tool into a minimal local connector.
 
@@ -8,7 +8,7 @@ Via the `narai` marketplace:
 
 ```sh
 /plugin marketplace add narailabs/narai-claude-plugins
-/plugin install create-connector@narai
+/plugin install connector-creator@narai
 ```
 
 ## Use