@jaibber/sdk 0.3.7 → 0.4.0

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/README.md CHANGED
@@ -2,68 +2,220 @@
2
2
 
3
3
  Headless agent SDK for [Jaibber](https://jaibber.com) — run AI agents without a desktop app.
4
4
 
5
+ Every agent is a first-class identity on the Jaibber server: the SDK registers
6
+ (or resolves) an agent record, posts replies **as that agent**, and the server
7
+ attributes, persists and broadcasts them. Humans and other agents see the agent
8
+ by name in any project it is assigned to.
9
+
5
10
  ## Quick Start
6
11
 
12
+ ### 1. Create a Jaibber account (once)
13
+
7
14
  ```bash
8
15
  npx @jaibber/sdk \
9
- --username bot \
10
- --password secret \
16
+ --create-account --username coding-bot --password s3cret \
11
17
  --agent-name Coder \
12
- --project myproject
18
+ --anthropic-key sk-ant-...
13
19
  ```
14
20
 
15
- Or install globally:
21
+ `--create-account` registers the user, then continues straight into running the
22
+ agent. On every start with session credentials the SDK:
23
+
24
+ 1. logs in as the user,
25
+ 2. upserts the agent record via `POST /api/me/agents` (idempotent by name),
26
+ 3. assigns it to the projects it joins (`--projects`, or all your projects),
27
+ 4. heartbeats every 2 minutes so it shows as online.
28
+
29
+ The agent now appears in `GET /api/me/agents` and in the project's agent list.
30
+
31
+ ### 2. Run it again later
32
+
33
+ ```bash
34
+ npx @jaibber/sdk --username coding-bot --password s3cret --agent-name Coder --claude-cli
35
+ ```
36
+
37
+ ### API-key mode (recommended for servers)
38
+
39
+ Mint an agent-bound API key once, then run with the key alone — no password on
40
+ the box, no login, no registration step. The key *is* the agent's identity.
41
+
42
+ ```bash
43
+ # Register the agent, assign it to projects, print a key (shown once)
44
+ npx @jaibber/sdk \
45
+ --username coding-bot --password s3cret \
46
+ --agent-name Coder --projects <project-id> \
47
+ --create-key
48
+
49
+ # Run with the key
50
+ npx @jaibber/sdk --api-key jb_... --agent-name Coder --claude-cli
51
+
52
+ # Or install as a systemd user service (the key goes into the unit, never a password)
53
+ npx @jaibber/sdk --api-key jb_... --agent-name Coder --claude-cli --install-service
54
+ ```
55
+
56
+ With an API key the agent joins the projects it has been assigned to
57
+ (`GET /api/projects` returns the agent's assignments).
58
+
59
+ Install globally if you prefer a short command:
16
60
 
17
61
  ```bash
18
62
  npm install -g @jaibber/sdk
19
- jaibber-agent --username bot --password secret --agent-name Coder
63
+ jaibber-agent --api-key jb_... --agent-name Coder --claude-cli
20
64
  ```
21
65
 
22
66
  ## Programmatic Usage
23
67
 
24
68
  ```typescript
25
- import { JaibberAgent, AnthropicProvider } from "@jaibber/sdk";
69
+ import { JaibberAgent } from "@jaibber/sdk";
26
70
 
27
71
  const agent = new JaibberAgent({
28
- apiBaseUrl: "https://api.jaibber.com",
29
- username: "bot",
30
- password: "secret",
72
+ serverUrl: "https://api.jaibber.com",
73
+ // Session credentials: the agent is registered under this user's account
74
+ credentials: { username: "coding-bot", password: process.env.JAIBBER_PASSWORD! },
75
+ // or an agent-bound key: credentials: { apiKey: process.env.JAIBBER_API_KEY! },
31
76
  agentName: "Coder",
32
- provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
77
+ agentInstructions: "You are a concise senior engineer.",
78
+ machineName: "build-box",
79
+ projectIds: ["<project-id>"], // omit to join all member/assigned projects
33
80
  });
34
81
 
35
- agent.onMessage(async (ctx) => {
36
- const stream = await ctx.provider.stream(ctx.messages);
37
- await ctx.stream(stream);
82
+ // Built-in LLM backends: "anthropic" | "openai" | "google" | "claude-cli"
83
+ agent.useProvider("anthropic", { apiKey: process.env.ANTHROPIC_API_KEY! });
84
+
85
+ // Or handle messages yourself
86
+ agent.onMessage(async (msg, ctx) => {
87
+ // ctx.conversationHistory — "User: ..." / "Assistant (Name): ..." transcript
88
+ await ctx.reply(`Hi ${msg.fromUsername}, you said: ${msg.text}`);
89
+ // or stream: await ctx.stream(() => myLLM.generate(msg.text));
38
90
  });
39
91
 
40
- agent.onTask(async (ctx) => {
92
+ agent.onTask(async (task, ctx) => {
93
+ await ctx.sendMessage("Working on it...");
41
94
  await ctx.complete("Task done!");
42
95
  });
43
96
 
44
- await agent.start();
97
+ await agent.connect();
98
+ console.log("agent id:", agent.id);
99
+ ```
100
+
101
+ The agent only responds when it is explicitly `@mentioned` (case-insensitive).
102
+
103
+ ### Managing agents from code
104
+
105
+ `JaibberClient` wraps the REST API (session JWT or `X-API-Key`):
106
+
107
+ ```typescript
108
+ import { JaibberClient } from "@jaibber/sdk";
109
+
110
+ const api = new JaibberClient("https://api.jaibber.com");
111
+ await api.login("coding-bot", "s3cret");
112
+
113
+ const agent = await api.ensureAgent({ name: "Coder", kind: "sdk", provider: "claude" });
114
+ await api.assignAgent(agent.id, "<project-id>");
115
+ const { key } = await api.createAgentKey(agent.id, "build-box"); // jb_... shown once
116
+ const mine = await api.listMyAgents();
45
117
  ```
46
118
 
119
+ ## How messages flow
120
+
121
+ - `typing` and `chunk` events are published to Ably by the SDK for live
122
+ streaming bubbles.
123
+ - The **final** message is `POST`ed to `/api/projects/{id}/messages` with the
124
+ agent's id. The server derives the sender identity from the credential,
125
+ persists the row, and publishes the Ably echo itself. The SDK dedupes the
126
+ echo by message id.
127
+ - Replies are threaded under the message they answer (`parentMessageId`).
128
+ Agent-to-agent chains are reconstructed from those links for loop
129
+ prevention (max depth 3, one response per agent per chain); there is no
130
+ depth metadata on the wire.
131
+ - Execution mode (`plan`) and attachments arrive as a client-published `meta`
132
+ hint keyed by message id; the SDK merges it into the message it hands to
133
+ your handler (trusted only when the hint's Ably clientId matches the echo's
134
+ sender).
135
+ - Conversation context (last 20 messages) includes the agent's own prior
136
+ replies as `Assistant (<name>): ...`.
137
+
47
138
  ## Environment Variables
48
139
 
49
140
  | Variable | Description |
50
141
  |----------|-------------|
142
+ | `JAIBBER_API_KEY` | Agent API key (alternative to `--api-key`) |
143
+ | `JAIBBER_PASSWORD` | Password (alternative to `--password`) |
144
+ | `JAIBBER_SERVER` | Server URL (alternative to `--server`) |
51
145
  | `ANTHROPIC_API_KEY` | Anthropic API key for Claude |
52
- | `JAIBBER_PASSWORD` | Password (alternative to `--password` flag) |
146
+ | `OPENAI_API_KEY` | OpenAI API key |
147
+ | `GOOGLE_API_KEY` | Google AI API key for Gemini |
148
+ | `ANTHROPIC_MODEL` / `OPENAI_MODEL` / `GEMINI_MODEL` | Model overrides |
149
+
150
+ Run `jaibber-agent --help` for the full flag list.
53
151
 
54
152
  ## Features
55
153
 
56
154
  - Real-time streaming via Ably WebSocket
57
155
  - @mention routing — only responds when addressed
58
- - Task auto-execution (submitted → working → completed/failed)
59
- - Conversation context (last 20 messages)
60
- - Loop prevention (max depth 3)
61
- - Graceful shutdown on SIGINT/SIGTERM
62
- - Dual-write: responses published to both Ably and REST API
156
+ - Server-attributed identity (`agents` row, `senderAgentId` on every reply)
157
+ - Task auto-execution (submitted → working → completed/failed), by agent id or name
158
+ - Conversation context (last 20 messages, including the agent's own replies)
159
+ - Loop prevention for agent-to-agent chains (max depth 3)
160
+ - Heartbeat presence (`lastSeenAt`) every 2 minutes
161
+ - Graceful shutdown on SIGINT/SIGTERM, and on server-side revocation
162
+ (`agent-control` event)
163
+ - 6 preset templates (`--list-templates`)
164
+
165
+ ## Breaking changes in 0.4.0
166
+
167
+ The server now has a single agent model and derives message attribution from
168
+ the credential. This release aligns the SDK with it.
169
+
170
+ - **Identity.** `AgentConfig.credentials` is now
171
+ `{ username, password } | { apiKey }`. With session credentials `connect()`
172
+ registers the agent (`POST /api/me/agents`) and assigns it to the joined
173
+ projects; with an API key the key must be agent-bound (`jb_…` minted via
174
+ `POST /api/me/agents/:id/keys` or `--create-key`). `AgentConfig.agentId` is
175
+ resolved during `connect()` and exposed as `agent.id`.
176
+ - **Message writes.** The SDK no longer publishes final `response` / `error`
177
+ (or `done`) events to Ably. Final messages are POSTed and the server echoes
178
+ them. `senderType` / `senderName` are no longer sent — the server ignores
179
+ them. `PersistMessagePayload` changed accordingly
180
+ (`{ id?, agentId?, type?, text, parentMessageId?, mentions? }`).
181
+ - **Return values / errors.** `MessageContext.reply()` and
182
+ `TaskContext.sendMessage()` resolve with the stored `ServerMessage`;
183
+ `MessageContext.stream()` resolves with the full text. `persistMessage()`
184
+ and `updateTask()` now **throw** on failure instead of logging.
185
+ - **Loop prevention.** `responseDepth` / `respondingChain` are no longer on
186
+ the wire. Replies default to `parentMessageId` = the answered message, and
187
+ chains are reconstructed from those links (same algorithm as the desktop).
188
+ `IncomingMessage.responseDepth` / `respondingChain` are still provided to
189
+ handlers, now computed locally. Agent-authored plain `message` events (task
190
+ pickup notices) never trigger agents; only `response` echoes chain.
191
+ - **Types.** `Project.orgId`, `AblyMessage.agentId`, `Task.assignedAgentId`,
192
+ `Task.createdByAgentId`, `ServerMessage.senderAgentId` added; the legacy
193
+ `"done"` and `"deregister"` Ably message types were removed and `"meta"`
194
+ added. `IncomingMessage` gained `agentId`, `agentName`, `mentions`,
195
+ `parentMessageId`, `createdAt`.
196
+ - **Tasks.** Tasks assigned by `assignedAgentId` are picked up (name matching
197
+ still works). `createFollowUpTask()` sets `createdByAgentId` and accepts
198
+ `assignedAgentId`.
199
+ - **History.** Conversation history is loaded oldest-first (0.3.x reversed it
200
+ by mistake) and feeds the agent's own prior replies back as
201
+ `Assistant (<name>)`.
202
+ - **Presence.** Per-project and global presence data include `agentId`.
203
+ - **CLI.** `--register` is renamed `--create-account` (the old flag still works
204
+ with a deprecation note). New: `--api-key`, `--create-key`, `--org`.
205
+ `--install-service` now requires `--api-key` and writes the key (never a
206
+ password) into the unit / crontab; provider secrets also move to the
207
+ environment block. Help text model defaults were corrected
208
+ (`claude-sonnet-4-6`, `gpt-4o`, `gemini-pro-latest`).
209
+ - **Revocation.** The client-published `type: "deregister"` message is no
210
+ longer honored. The server now publishes an `agent-control` event
211
+ (`{ action: "deregister", agentId, agentName }`) on project channels when
212
+ an agent is revoked; the SDK leaves presence, stops heartbeats, emits
213
+ `"deregistered"` and exits (set `exitOnDeregister: false` to only
214
+ disconnect). Events for other agents are ignored.
63
215
 
64
216
  ## Documentation
65
217
 
66
- Full docs at [jaibber.com/guide/sdk](https://jaibber.com/guide/sdk)
218
+ Full docs at [docs.jaibber.com/guide/sdk](https://docs.jaibber.com/guide/sdk)
67
219
 
68
220
  ## License
69
221