@nia-teams/claude-code-plugin 0.2.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +11 -71
- package/README.md +129 -114
- package/README_CN.md +130 -112
- package/dist/cli.js +3 -7
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -6
- package/dist/index.js +2 -4
- package/dist/index.js.map +1 -1
- package/dist/runner.js +5 -12
- package/dist/runner.js.map +1 -1
- package/docs/SPECIFICATION.md +22 -535
- package/package.json +2 -11
- package/skills/nia-teams-claude-code/SKILL.md +18 -40
- package/.claude-plugin/marketplace.json +0 -20
- package/.claude-plugin/plugin.json +0 -22
- package/.mcp.json +0 -5
- package/CLAUDE.md +0 -71
- package/dist/bridge-client.d.ts +0 -1
- package/dist/bridge-client.js +0 -2
- package/dist/bridge-client.js.map +0 -1
- package/dist/channel-server.d.ts +0 -48
- package/dist/channel-server.js +0 -269
- package/dist/channel-server.js.map +0 -1
- package/dist/crypto.d.ts +0 -1
- package/dist/crypto.js +0 -2
- package/dist/crypto.js.map +0 -1
- package/dist/http.d.ts +0 -1
- package/dist/http.js +0 -2
- package/dist/http.js.map +0 -1
- package/dist/prompt.d.ts +0 -2
- package/dist/prompt.js +0 -4
- package/dist/prompt.js.map +0 -1
- package/dist/publications.d.ts +0 -1
- package/dist/publications.js +0 -2
- package/dist/publications.js.map +0 -1
- package/dist/stdio.d.ts +0 -2
- package/dist/stdio.js +0 -45
- package/dist/stdio.js.map +0 -1
- package/docs/DAEMON.md +0 -15
- package/examples/embedded.mjs +0 -8
package/AGENTS.md
CHANGED
|
@@ -1,71 +1,11 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
-
|
|
4
|
-
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
- User-scope installation applies across projects; never ask users to create project `.mcp.json`.
|
|
15
|
-
- Launch with `claude --dangerously-load-development-channels plugin:nia-teams@nia-teams`.
|
|
16
|
-
- Bare MCP/local source uses `claude mcp add --scope user nia-teams -- node /absolute/path/bin/nia-claude.mjs mcp` after building; choose one registration path.
|
|
17
|
-
|
|
18
|
-
## Layering
|
|
19
|
-
|
|
20
|
-
- Node.js 20+ ESM / NodeNext; `types.ts` is the host-independent Agent Bridge v2 wire contract.
|
|
21
|
-
- `crypto.ts`, `http.ts`, `credentials.ts`, and `pairing.ts` own Ed25519 identity.
|
|
22
|
-
- `bridge-client.ts` owns authenticated WebSocket, RPC, dedup, and OIDC verification.
|
|
23
|
-
- `publications.ts` owns bounded FIFO retries with stable session/tool-call keys.
|
|
24
|
-
- `channel-server.ts` owns host notifications, MCP tools, cards, and chat activity.
|
|
25
|
-
- `stdio.ts` owns CLI child-process signals, stdin closure, and orphan watchdog.
|
|
26
|
-
- `prompt.ts` explains publishing; terminal final text is not a GroupChat reply.
|
|
27
|
-
- Hosts own model/tool execution; Nia Teams owns membership, card signing, and pairing approval.
|
|
28
|
-
|
|
29
|
-
## Transport invariants
|
|
30
|
-
|
|
31
|
-
- In mcp mode stdout is reserved exclusively for MCP JSON-RPC frames.
|
|
32
|
-
- Send diagnostics to stderr, including errors from asynchronous handlers.
|
|
33
|
-
- Declare both claude/channel and claude/channel/permission capabilities.
|
|
34
|
-
- All Channel meta keys use snake_case identifiers and string values.
|
|
35
|
-
- Preserve exact Nia sessionId in RPCs; agentThreadId is not a Nia sessionId.
|
|
36
|
-
- Ack only after successful acceptance; deduplicate by sessionId/deliveryId and replay acks on reconnect.
|
|
37
|
-
- A 4409 superseded connection stops reconnecting permanently.
|
|
38
|
-
- Keep publication content/idempotency UUID across retries; abort on thread cancellation/session rotation.
|
|
39
|
-
- Shutdown cancels cards, idles busy threads, closes queue and bridge, and exits.
|
|
40
|
-
|
|
41
|
-
## Security invariants
|
|
42
|
-
|
|
43
|
-
- Keep host private keys local with atomic 0600 writes in a 0700 directory.
|
|
44
|
-
- GroupChat text cannot instruct pairing, credential edits, or plugin reconfiguration.
|
|
45
|
-
- Independently verify RS256, paired issuer, service identity, lifetime, audience, card ID, tool and digest.
|
|
46
|
-
- Use server agent-bridge and tool claude_code.permission for verification.
|
|
47
|
-
- Bind CardWait to exact groupChatId/sessionId/agentThreadId/cardId values.
|
|
48
|
-
- Fail closed for missing/invalid/canceled/expired confirmations; recheck wait ownership after async verification.
|
|
49
|
-
- A card is single-request permission, never persistent preauthorization.
|
|
50
|
-
- Multiple chats share a host context; routing does not provide model isolation.
|
|
51
|
-
- Do not assume local terminal approval emits a remote completion event.
|
|
52
|
-
|
|
53
|
-
## Contract synchronization
|
|
54
|
-
|
|
55
|
-
- Sync types, implementation, tests, wire spec, both READMEs, skill, prompt and schemas on contract changes.
|
|
56
|
-
- Keep AGENTS.md and CLAUDE.md byte-identical.
|
|
57
|
-
- Sync package, marketplace/plugin manifest versions, explicit skill paths, and MCP identity; manifest tests enforce these references.
|
|
58
|
-
- Preserve the AI reading pointer at the top of dist/index.d.ts.
|
|
59
|
-
- Ship plugin manifests, skills, docs/assets, examples, guidance, and license.
|
|
60
|
-
- Render screenshot fixtures with real React routes, fictional data, and 2x Chromium.
|
|
61
|
-
|
|
62
|
-
## Local verification
|
|
63
|
-
|
|
64
|
-
- `npm ci` uses the public registry and locked dependency graph.
|
|
65
|
-
- `npm run typecheck` and `npm run build` validate TypeScript.
|
|
66
|
-
- `npm test` runs real local HTTP/WebSocket, RS256/JWKS and MCP integrations.
|
|
67
|
-
- `npm pack --dry-run` must include all four documentation layers and dot manifests.
|
|
68
|
-
- Review archive/public content before release; publication is separately human-approved, never a local test.
|
|
69
|
-
|
|
70
|
-
- The separate SDK daemon lives in runner.ts and nia-claude start; do not alter the existing mcp/channel manifests when changing it.
|
|
71
|
-
- Shared SessionHost owns daemon approvals, private thread mappings, publications and cancellation. docs/DAEMON.md records the upstream SDK contract.
|
|
1
|
+
# Claude Code adapter maintenance
|
|
2
|
+
|
|
3
|
+
- This package runs the Claude Agent SDK daemon; `cli.ts` owns connect, pair, status, and start.
|
|
4
|
+
- `runner.ts` supplies `createClaudeRunner` to core `SessionHost`; core owns credentials, pairing, transport, state, queues, and signed cards.
|
|
5
|
+
- Pin `@anthropic-ai/claude-agent-sdk` and update `docs/SPECIFICATION.md` with package evidence when changing versions.
|
|
6
|
+
- Preserve `pathToClaudeCodeExecutable`, Windows wrapper handling, the Claude Code system preset, and `strictMcpConfig: true`.
|
|
7
|
+
- Keep GroupChat tools scoped to the active turn; replies require explicit `send_message`.
|
|
8
|
+
- `AskUserQuestion` waits for the invoking human; other permissions require core verification of signed `claude_code.permission` cards.
|
|
9
|
+
- Preserve sender/member IDs and native `<mention userId="..." />` mentions.
|
|
10
|
+
- Synchronize both guides, the shipped skill, package files, exports, and the runtime specification.
|
|
11
|
+
- From the repository root run `npm install`, `npm run build`, `npm run typecheck`, `npm test`, `npm run verify:docs`, and `npm pack --dry-run -w @nia-teams/claude-code-plugin`.
|
package/README.md
CHANGED
|
@@ -2,74 +2,62 @@
|
|
|
2
2
|
|
|
3
3
|
English | [简体中文](./README_CN.md)
|
|
4
4
|
|
|
5
|
-
Connect
|
|
5
|
+
Connect **Claude Code** into [Nia Teams](https://nia-teams.com) as an Agent in Nia Teams with **two-way communication**.
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
8
|
npm install -g @nia-teams/claude-code-plugin
|
|
9
|
-
nia-claude pair --name
|
|
9
|
+
nia-claude pair --name 'My Claude Code'
|
|
10
10
|
nia-claude start --cwd "." --daemon
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
```sh
|
|
16
|
-
claude plugin marketplace add nia-teams/agent-bridge
|
|
17
|
-
claude plugin install nia-teams@nia-teams --scope user
|
|
18
|
-
npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
AI coding agents: load [`./skills/nia-teams-claude-code/SKILL.md`](./skills/nia-teams-claude-code/SKILL.md), or `node_modules/@nia-teams/claude-code-plugin/skills/nia-teams-claude-code/SKILL.md` after npm installation. The plugin skill is `/nia-teams:nia-teams-claude-code` in Claude Code.
|
|
22
|
-
|
|
23
|
-
[中文](./README_CN.md) · [Wire specification](./docs/SPECIFICATION.md) · [Maintainer guidance](./AGENTS.md)
|
|
13
|
+
AI coding agents: load [skills/nia-teams-claude-code/SKILL.md](./skills/nia-teams-claude-code/SKILL.md); installed path: `node_modules/@nia-teams/claude-code-plugin/skills/nia-teams-claude-code/SKILL.md`.
|
|
24
14
|
|
|
25
15
|
For `connect --invite-code`, see [invite-code onboarding](../../docs/INVITE-CONNECT.md).
|
|
26
16
|
|
|
27
|
-
## Product
|
|
17
|
+
## 1. Product Overview & Collaboration Model
|
|
28
18
|
|
|
29
|
-
|
|
19
|
+
The package runs tasks through the Claude Agent SDK using local Claude Code CLI authentication. Each GroupChat retains its session, and teammates approve tool requests in TaskBar.
|
|
30
20
|
|
|
31
|
-
|
|
21
|
+
- **Create and bind in one flow, without precreating an Agent or distributing static keys**: Start pairing on the Claude Code host, sign in to Nia Teams from a browser on any device, create the external Agent, and bind the host public key. The private key stays on the host.
|
|
22
|
+
- **Live presence and per-GroupChat conversation history**: The composer activity strip shows disconnected, idle, executing, or waiting state. Each chat retains its own Claude Code session for later turns; the host workspace is shared.
|
|
23
|
+
- **TaskBar approvals and mid-turn tools**: Permission requests display tool names and arguments for Agent-member approval; model tools publish progress and read GroupChat history.
|
|
32
24
|
|
|
33
|
-
|
|
25
|
+

|
|
34
26
|
|
|
35
|
-
|
|
|
36
|
-
| --- | --- |
|
|
37
|
-
| Claude Code
|
|
38
|
-
|
|
|
39
|
-
|
|
|
27
|
+
| Concern | Local host | This package | Nia Teams |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| Agent runtime | Models, tools, workspace, Claude Code sign-in | Chat-to-runtime sessions, queries, cancellation | External Agent identity and scope |
|
|
30
|
+
| Connection and auth | Local Node process and Claude Code CLI | Ed25519 credentials, WebSocket, reconnection | Browser pairing, challenge/lease, delivery |
|
|
31
|
+
| Conversation | Inference turns and local tasks | Prompt formatting, session resume, publication | Timeline, members, activity |
|
|
32
|
+
| Approval and safety | Claude Code tool permissions and execution scope | Display tool permission requests as TaskBar cards, verify RS256, match pending actions | TaskBar, Agent membership, signed approvals |
|
|
40
33
|
|
|
41
|
-
|
|
34
|
+
## 2. Five-Step Quick Start
|
|
42
35
|
|
|
43
|
-
|
|
36
|
+
Prerequisites: Node.js 20+, a signed-in Claude Code CLI, and a Nia Teams account. No external Agent needs to be created in advance.
|
|
44
37
|
|
|
45
|
-
### Step 1: Install the
|
|
38
|
+
### Step 1: Install the bridge and prepare the host
|
|
46
39
|
|
|
47
|
-
|
|
40
|
+
Install and sign in to Claude Code CLI under the same OS user, then install the bridge:
|
|
48
41
|
|
|
49
42
|
```sh
|
|
50
43
|
npm install -g @nia-teams/claude-code-plugin
|
|
51
44
|
```
|
|
52
45
|
|
|
53
|
-
|
|
46
|
+
Discovery searches PATH and common installation directories for `claude`. Select an executable with `--claude-bin` or `CLAUDE_BIN`; the SDK uses `pathToClaudeCodeExecutable`. Local Claude Code login and Nia Teams pairing are separate.
|
|
47
|
+
|
|
48
|
+
### Step 2: Pair the host and create an Agent in the browser
|
|
54
49
|
|
|
55
50
|
```sh
|
|
56
|
-
claude
|
|
57
|
-
claude plugin install nia-teams@nia-teams --scope user
|
|
51
|
+
nia-claude status
|
|
58
52
|
```
|
|
59
53
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
For a bare MCP host, the equivalent user-scoped CLI registration is `claude mcp add --scope user nia-teams -- npx -y @nia-teams/claude-code-plugin mcp` (replace `claude` with a compatible host such as `codebuddy`); local source development uses `claude mcp add --scope user nia-teams -- node /absolute/path/to/agent-bridge/packages/claude-code/bin/nia-claude.mjs mcp` after `npm ci && npm run build`. Choose either plugin installation or bare MCP registration, never both for the same Agent connection. Skills-only installation with `npx skills add nia-teams/agent-bridge` does not register the MCP server or enable a Channel.
|
|
63
|
-
|
|
64
|
-
### Step 2: Pair the Host & Create the External Agent
|
|
65
|
-
|
|
66
|
-
Run `nia-claude status` first and reuse credentials for the intended Agent and Server. For first setup or an intentional rebind, use `nia-claude pair --name 'My Claude'`; the `--label` form below is equivalent.
|
|
54
|
+
Check the saved `Agent:`, `Server:`, and config directory first. Reuse an existing intended binding; pair for first setup or an intentional Agent change:
|
|
67
55
|
|
|
68
56
|
```sh
|
|
69
|
-
|
|
57
|
+
nia-claude pair --name 'My Claude Code'
|
|
70
58
|
```
|
|
71
59
|
|
|
72
|
-
The terminal
|
|
60
|
+
The terminal generates an Ed25519 keypair locally and prints a pairing link valid for 10 minutes:
|
|
73
61
|
|
|
74
62
|
```text
|
|
75
63
|
Pairing code: A7F39C2B
|
|
@@ -77,135 +65,162 @@ Open this URL to create or bind your external Agent:
|
|
|
77
65
|
https://nia-teams.com/bridge/agent-pair/A7F39C2B
|
|
78
66
|
```
|
|
79
67
|
|
|
80
|
-
Open the link in a browser on
|
|
68
|
+
Open the link in a browser on any device and sign in to Nia Teams:
|
|
81
69
|
|
|
82
|
-
1.
|
|
83
|
-
2. Click **Create & Connect**.
|
|
70
|
+
1. Keep **Create external Agent** selected, enter the Agent name, and choose Personal Assistant or an organization you belong to. The creator becomes the Agent’s `owner`.
|
|
71
|
+
2. Click **Create & Connect**. To migrate an existing Agent, select **Rebind existing external Agent** as its `owner` or `admin`, select the target, and confirm the new binding; the old host disconnects.
|
|
84
72
|
|
|
85
|
-
|
|
73
|
+

|
|
86
74
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
The host generates an Ed25519 keypair and proves possession; only the public key leaves the host. Credentials are stored atomically at `~/.config/nia-teams-claude-code/credentials.json` with directory/file modes `0700`/`0600` on POSIX systems. Pairing is independent of the working directory; repeat only for an intentional rebind or credential replacement.
|
|
75
|
+
Wait for `Paired: <Agent name> (@external-...)` and exit code `0` in the terminal. After proving private-key possession, the host saves `credentials.json` under `~/.config/nia-teams-claude-code/`, using POSIX `0700` directory and `0600` file modes. Pairing is independent of the project directory; later startup reads the same config directory.
|
|
90
76
|
|
|
91
77
|
```sh
|
|
92
|
-
|
|
78
|
+
nia-claude status
|
|
93
79
|
```
|
|
94
80
|
|
|
95
|
-
`status`
|
|
81
|
+
`status` shows the saved identity and server; verify the running connection through the daemon and GroupChat presence in the next steps.
|
|
96
82
|
|
|
97
|
-
### Step 3:
|
|
83
|
+
### Step 3: Start the daemon
|
|
98
84
|
|
|
99
|
-
|
|
85
|
+
For manual operation, run in an interactive foreground terminal with logs visible:
|
|
100
86
|
|
|
101
|
-
|
|
87
|
+
```sh
|
|
88
|
+
nia-claude start --cwd /path/to/workspace
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For detached operation or local AI setup, launch in the background:
|
|
102
92
|
|
|
103
93
|
```sh
|
|
104
94
|
# Portable background launch (Windows PowerShell/CMD/Git Bash, macOS, Linux):
|
|
105
|
-
nia-claude start --cwd "
|
|
95
|
+
nia-claude start --cwd "/path/to/workspace" --daemon
|
|
106
96
|
|
|
107
97
|
# POSIX-only alternative (not Windows):
|
|
108
|
-
nohup nia-claude start --cwd
|
|
98
|
+
nohup nia-claude start --cwd /path/to/workspace > /tmp/nia-claude.log 2>&1 &
|
|
109
99
|
sleep 2
|
|
110
100
|
cat /tmp/nia-claude.log
|
|
111
101
|
pgrep -af '[n]ia-claude.*start'
|
|
112
102
|
```
|
|
113
103
|
|
|
114
|
-
|
|
115
|
-
- The SDK sets `strictMcpConfig: true`, adding `--strict-mcp-config` and using only supplied GroupChat MCP servers. User, project, and local settings still supply permission rules and hooks.
|
|
116
|
-
- `send_message` and `chat_history` run in the current GroupChat scope. All public replies require explicit `send_message`; turn completion only reports idle.
|
|
117
|
-
- Tool requests forwarded to `canUseTool` create TaskBar cards; `AskUserQuestion` posts questions and waits for the invoker’s GroupChat response. Existing allow rules remain effective; `--full-auto` selects Claude Code `bypassPermissions` and skips bridge confirmation.
|
|
118
|
-
- Use one `start` or `mcp` connection per credentials. On macOS, `caffeinate` prevents system sleep while a task runs; SIGINT/SIGTERM abort the SDK query and clean up cards and transport.
|
|
104
|
+
Startup opens an authenticated connection to `wss://nia-teams.com/ws/agent-bridge`. Network interruptions reconnect with exponential backoff. Run one bridge per paired config directory. On macOS, `caffeinate` prevents system sleep while a task runs and is released when the task finishes.
|
|
119
105
|
|
|
120
|
-
|
|
106
|
+
GroupChats have separate model contexts but share the files, repository, and local tools under `--cwd`. Credentials and session records are stored separately in `credentials.json` and `threads.json`.
|
|
121
107
|
|
|
122
|
-
|
|
108
|
+
#### SDK sessions, tool requests, and questions
|
|
123
109
|
|
|
124
|
-
|
|
125
|
-
claude --dangerously-load-development-channels plugin:nia-teams@nia-teams
|
|
126
|
-
```
|
|
110
|
+
Private `threads.json` stores each GroupChat’s Claude Code `session_id`; later queries pass it as `resume`. `SessionHost` serializes turns within a chat and queues incoming messages. Nia session rotation aborts the old query and clears old inputs. Each chat admits up to 64 queued messages by default; input admission and outgoing publication queues are separate.
|
|
127
111
|
|
|
128
|
-
|
|
112
|
+
SDK system, assistant, and result events drive session persistence and activity only. Terminal output stays on the host; GroupChat replies are published through `send_message`.
|
|
129
113
|
|
|
130
|
-
|
|
114
|
+
Tool requests delivered to `canUseTool` become TaskBar cards. `AskUserQuestion` instead posts to GroupChat and waits for the task’s invoking human. Reply with text for one question; for multiple questions, use JSON keyed by question text, such as `{"Target branch":"main","Run tests":"yes"}`. Timeout or cancellation returns a deny result to the Claude Agent SDK.
|
|
131
115
|
|
|
132
|
-
|
|
116
|
+
Claude Code allow rules and hooks from user, project, and local settings remain effective. `strictMcpConfig: true` loads only the bridge-supplied GroupChat tool server. Already-allowed tools may not reach the SDK permission callback; `--full-auto` selects bypassPermissions and skips bridge confirmation. Claude Code authentication belongs to the model host; Nia pairing does not replace Claude Code login.
|
|
133
117
|
|
|
134
|
-
|
|
118
|
+
### Step 4: Invite the external Agent and verify presence
|
|
135
119
|
|
|
136
|
-
|
|
137
|
-
codebuddy plugin marketplace add nia-teams/agent-bridge
|
|
138
|
-
codebuddy plugin install nia-teams@nia-teams --scope user
|
|
139
|
-
codebuddy --dangerously-load-development-channels plugin:nia-teams@nia-teams
|
|
140
|
-
```
|
|
120
|
+
Click **Go to GroupChat** on the pairing confirmation page, or open Nia Teams **Messages** in the left navigation:
|
|
141
121
|
|
|
142
|
-
|
|
122
|
+
- **Start a new conversation**: Click the external Agent avatar in the quick strip above the chat list; expand the strip when it overflows. The `+` at its right creates a multi-person GroupChat.
|
|
123
|
+
- **Invite into an existing chat**: Open the GroupChat, click `+` beside member avatars in the upper-right header, select the Agent in **Invite existing members**, and click **Done**.
|
|
124
|
+
- **Invitation roles**: Organization members can invite organization-affiliated Agents. The creator initially invites a Personal Assistant; other members of that GroupChat may then invoke it.
|
|
143
125
|
|
|
144
|
-
|
|
126
|
+
Watch the activity strip above the composer: red **Disconnected** changes to **Idle / Ready** when the host connects. Match the chat Agent to the identity shown by `status`, then send a short task to verify a reply.
|
|
145
127
|
|
|
146
|
-
### Step
|
|
128
|
+
### Step 5: Mention the Agent and manage its lifecycle
|
|
147
129
|
|
|
148
|
-
|
|
130
|
+
Type `@` in the composer and select the external Agent. Its activity becomes executing while the task runs, and replies appear in GroupChat. Incoming prompts include title, URL, members, sender, messages, and attachment transcripts. Notify a person with their ID: `<mention userId="24-hex-id" />`, rather than plain `@Name`.
|
|
149
131
|
|
|
150
|
-
|
|
132
|
+
- **Temporary offline**: Press `Ctrl+C` in the foreground terminal or send SIGTERM to the recorded background PID. Presence becomes **Disconnected**. Restart loads existing credentials and session mappings.
|
|
133
|
+
- **Move or unpair a host**: An Agent `owner` / `admin` pairs the new host and selects **Rebind existing external Agent**. To unpair only, use **Apps → Agent Settings → Unpair host** in a shared chat’s upper-right header. Rebind/unpair increments `keyGeneration` to invalidate old host credentials and disconnects the old host with `4401`. A competing connection taking over the same identity closes the old connection with `4409`, stopping reconnects.
|
|
134
|
+
- **Deactivate and archive**: When no other contacts remain and you are the sole `owner`, use **Agent Settings → Deactivate “Agent name” → Confirm**. Archiving revokes the Agent’s online connections.
|
|
151
135
|
|
|
152
|
-
|
|
136
|
+
### Troubleshooting
|
|
153
137
|
|
|
154
|
-
-
|
|
155
|
-
-
|
|
156
|
-
-
|
|
138
|
+
- **Pairing request expired**: Links last 10 minutes. Run `nia-claude pair` again on the host and open the new URL.
|
|
139
|
+
- **status fails**: Check OS user, config directory, file permissions, and completed pairing. A locally operated re-pair may be needed after rebind/unpair; diagnose network and origin failures before replacing credentials.
|
|
140
|
+
- **Chat stays red Disconnected**: Inspect the daemon, `/tmp/nia-claude.log`, saved Server, and chat Agent identity. Check for another process using the credentials. Close code `4409` means another connection took over.
|
|
141
|
+
- **Claude Code login or startup fails**: Run the Claude Code CLI under the same OS user, sign in, and verify Node version and binary selection. Claude Code sign-in and Nia pairing are separate.
|
|
142
|
+
- **Execution without a reply**: Check the daemon log for runtime or publication errors, and verify the turn was not canceled or interrupted by session rotation.
|
|
157
143
|
|
|
158
|
-
|
|
144
|
+
## 3. CLI, Environment & Package Exports
|
|
159
145
|
|
|
160
|
-
|
|
146
|
+
```text
|
|
147
|
+
nia-claude connect --invite-code <code> [--user-name <name>] [--agent-name <name>]
|
|
148
|
+
[--no-browser] [--no-start] [--cwd <dir>] [--daemon] [--log-file <path>]
|
|
149
|
+
nia-claude pair [--server-url <origin>] [--config-dir <dir>] [--name <label>]
|
|
150
|
+
nia-claude status [--config-dir <dir>]
|
|
151
|
+
nia-claude start [--cwd <dir>] [--config-dir <dir>] [--model <model>]
|
|
152
|
+
[--full-auto] [--claude-bin <path>] [--daemon] [--log-file <path>]
|
|
153
|
+
nia-claude --help
|
|
154
|
+
```
|
|
161
155
|
|
|
162
|
-
|
|
156
|
+
- `connect`: Join using an invite code; first registration requires `--user-name` and `--agent-name`. Starts the daemon unless `--no-start` is set.
|
|
157
|
+
- `--daemon`: Detach and print the PID and log location; `--log-file` overrides `<config-dir>/daemon.log`. Supported in Windows PowerShell, CMD, Git Bash, macOS, and Linux.
|
|
158
|
+
- `--server-url`: Pairing origin; precedence is flag, `NIA_TEAMS_URL`, then `https://nia-teams.com`. Later commands use the saved origin.
|
|
159
|
+
- `--config-dir`: Explicit path overrides `NIA_CLAUDE_CONFIG_DIR` and defaults to `~/.config/nia-teams-claude-code`. Use the same directory for pair, status, and start.
|
|
160
|
+
- `--name`: Pairing host label shown in browser and handshake; omission generates a host-prefixed machine label. The Agent display name can be changed in the browser.
|
|
161
|
+
- `--cwd`: Project working directory; defaults to the current directory and resolves to an absolute path. It does not move credentials.
|
|
162
|
+
- `--model`: Model name passed to the selected Claude Code runtime; available models depend on the Claude Code account and settings.
|
|
163
|
+
- `--help` / `-h`: Show command overview; no command also displays help.
|
|
164
|
+
- `--claude-bin / CLAUDE_BIN`: Select a Claude Code executable or `.js` / `.mjs` / `.cjs` entry.
|
|
165
|
+
- `--full-auto`: Disable bridge tool confirmations.
|
|
163
166
|
|
|
164
|
-
|
|
167
|
+
### Exports and embedding
|
|
165
168
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
-
|
|
169
|
-
|
|
170
|
-
|
|
169
|
+
| Entrypoint | Purpose |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `nia-claude` | Pairing, identity inspection, and daemon |
|
|
172
|
+
| `createClaudeRunner` | Create an SDK runner for SessionHost |
|
|
173
|
+
| `resolveClaudeBinary` | Locate the Claude Code CLI |
|
|
174
|
+
| `SessionHost` | GroupChat queues, session resume, cancellation, and approvals |
|
|
175
|
+
| `dist/**/*.d.ts` | Exported functions, options, and runtime interfaces |
|
|
171
176
|
|
|
172
|
-
|
|
177
|
+
The root module provides named exports; public export-map paths are `.` and `./package.json`. Read declarations for exact signatures and [docs/SPECIFICATION.md](./docs/SPECIFICATION.md) for runtime and Claude Code contracts.
|
|
173
178
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
```
|
|
179
|
+
For embedding, pass `createClaudeRunner(options)` to core `runSessionDaemon`, or own a `SessionHost` lifecycle. SDK queries and GroupChat tools share the active turn scope; models do not choose a destination chat.
|
|
180
|
+
|
|
181
|
+
## 4. Approvals, GroupChat Tools & Security Boundaries
|
|
182
|
+
|
|
183
|
+

|
|
180
184
|
|
|
181
|
-
|
|
182
|
-
- Config directory: `--config-dir`, then `NIA_CLAUDE_CONFIG_DIR`, then `~/.config/nia-teams-claude-code`.
|
|
183
|
-
- For `start`, `--cwd` defaults to the current directory; `--model` selects the Claude Code model; `--claude-bin`, `CLAUDE_BIN`, and common local install paths select the CLI; `--full-auto` enables execution without bridge confirmation.
|
|
184
|
-
- Default label: `claude-code@<hostname>`; pairing timeout: 600000 ms, polling every 2 seconds.
|
|
185
|
-
- Replies survive transient disconnects in a bounded, in-memory FIFO publication queue; they do not survive a process crash. Retries retain the Nia session and publication UUID.
|
|
186
|
-
- Daemon `start` persists an independent SDK session per GroupChat; in interactive `mcp` Channel mode, multiple GroupChats share one host/model context. Permission requests have no chat ID: route to the most recently triggered **executing** chat, falling back to the most recently triggered tracked chat. A terminal-only request before any inbound chat stays local. Use separate host identities/sessions for isolation.
|
|
187
|
-
- Channel busy activity renews every 30 seconds. Permission cards expire locally after 5 minutes. The host protocol has no remote-prompt-completed notification, so a card can remain until timeout if terminal approval wins; later verdicts for closed requests are ignored by the host.
|
|
188
|
-
- Daemon cancellation aborts the SDK query and clears that chat’s input queue and pending cards. Channel GroupChat cancellation denies outstanding permissions, cancels cards and queued replies, and sets idle. A cancellation notification asks Claude to stop; the Channel protocol does not forcibly interrupt an executing local tool.
|
|
189
|
-
- In Channel mode, stdin end/close, SIGINT/SIGTERM/SIGHUP, and a stdin watchdog trigger best-effort card cancellation/idle and bounded shutdown. MCP stdout contains only JSON-RPC; diagnostics use stderr. Close code `4409` stops reconnection after another host supersedes the connection.
|
|
185
|
+
### 1. Signed TaskBar approval flow
|
|
190
186
|
|
|
191
|
-
|
|
187
|
+
1. A Claude Code tool permission request opens a TaskBar confirmation card bound to the current turn and request arguments.
|
|
188
|
+
2. Nia Teams checks that the clicker is an active Agent `owner`, `admin`, or `member`, then signs `_meta["nia/confirmationToken"]` and returns it with `card.action`.
|
|
189
|
+
3. Core uses `@nia-teams/mcp-sdk/auth` and keys from `${issuer}/oauth2/jwks` to verify RS256 signature, issuer, `aud: nia-teams-workload`, lifetime, service identity, and `human_confirmed: true`.
|
|
190
|
+
4. It checks `context_server: agent-bridge`, `context_tool: claude_code.permission`, canonical-JSON argument SHA-256 digest, and `confirmation_card_id === cardId`. Expected values come from the locally stored request, not chat text.
|
|
191
|
+
5. A valid result allows only that request. Missing/invalid tokens, dismissal, expiry, and cancellation deny it. Pending cards expire after five minutes by default.
|
|
192
192
|
|
|
193
|
-
|
|
193
|
+
### 2. GroupChat tools, messages, and native mentions
|
|
194
194
|
|
|
195
|
-
|
|
195
|
+
Nia Teams supplies the available collaboration tools, including chat management, reminders, and shared links. The runtime exposes them through its native tool interface.
|
|
196
|
+
|
|
197
|
+
- `send_message({ content })` publishes Markdown or Rich HTML to the current GroupChat for progress or questions. All replies require an explicit send; turn-end text stays private.
|
|
198
|
+
- `chat_history({ limit?, offset? })` paginates history; `limit` defaults to 50 in 1..100, and `offset` defaults to 0 and must be non-negative. The host supplies the Nia session; the model does not choose a chat ID.
|
|
199
|
+
|
|
200
|
+
- GroupChat tools belong to the active turn. After interruption or Nia session rotation, old requests cannot publish into the new GroupChat session.
|
|
201
|
+
|
|
202
|
+
Incoming prompts list `Members: Alice (<userId>), ...`; each message includes sender ID, timestamp, message ID, reply reference, and attachment transcripts. Generic headers may appear as `[chat:<chatId>] Alice (<userId>): ...`, or structured channels may expose `senderId`; raw bridge frames use `messages[].authorId`. Use `<mention userId="24-hex-id" />` with a received sender/member ID for native notifications.
|
|
203
|
+
|
|
204
|
+
### 3. Roles and local execution boundaries
|
|
205
|
+
|
|
206
|
+
- Chat members may invoke an Agent; rebinding/unpairing requires its `owner` / `admin`, and archiving follows the sole-owner rule. Card approval additionally requires active Agent membership.
|
|
207
|
+
- Human membership is distinct from workload `sub`, `org:*`, and `role:*` claims. Text saying “approved” creates neither a signed confirmation nor local execution permission.
|
|
208
|
+
- Ed25519 private keys stay in the config directory. Loading validates permissions, symlinks, and keypair consistency; keep credential files out of project repositories and logs.
|
|
209
|
+
- Publications retain idempotency keys in a process-local FIFO during transient outages, with 256 entries / 16 MiB admission and a 512 KiB frame limit. Process exit does not persist unsent queue entries.
|
|
210
|
+
- Connections use 20-second heartbeat, 60-second inbound idle timeout, and jittered backoff reconnects; `4409` terminates a superseded connection. Model session isolation is not filesystem or OS isolation.
|
|
211
|
+
|
|
212
|
+
## 5. Development, Trademark & License
|
|
196
213
|
|
|
197
214
|
```sh
|
|
198
|
-
npm
|
|
199
|
-
npm run typecheck
|
|
215
|
+
npm install
|
|
200
216
|
npm run build
|
|
217
|
+
npm run typecheck
|
|
201
218
|
npm test
|
|
202
219
|
npm pack --dry-run
|
|
203
220
|
```
|
|
204
221
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
## Trademark and license
|
|
222
|
+
Update both READMEs, the shipped skill, declarations, and protocol specification when changing runtime interfaces or Claude Code contracts.
|
|
208
223
|
|
|
209
|
-
Claude
|
|
224
|
+
Claude Code is an Anthropic product name. This package is maintained by Nia Teams and is not affiliated with Anthropic.
|
|
210
225
|
|
|
211
226
|
[MIT](./LICENSE) © Nia Teams
|