@joe-broadhead/opencode-mem 0.6.1 → 0.7.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 +140 -17
- package/SECURITY.md +8 -4
- package/assets/icon.svg +14 -0
- package/package.json +459 -6
- package/src/commands.js +1 -0
- package/src/credentials.js +151 -15
- package/src/index.js +11 -1
- package/src/runtime.js +3 -1
- package/src/tools/status.js +1 -0
- package/src/views/contracts.js +239 -0
- package/src/views/rpc.js +412 -0
- package/views/home.html +184 -0
- package/views/memory.html +487 -0
package/README.md
CHANGED
|
@@ -140,26 +140,69 @@ keys plugins and their secrets by, and its `package.json` carries a `jelly`
|
|
|
140
140
|
declaration. Inside Jelly the plugin is opt-in: a host has it installed, and a
|
|
141
141
|
person adds it to an agent.
|
|
142
142
|
|
|
143
|
+
**The `memory` resource.** The declaration names `"resources": ["memory"]`.
|
|
144
|
+
Jelly gives an agent's engine the identity accessor for a resource only when
|
|
145
|
+
one of the plugins given to that agent declares it, and its host answers
|
|
146
|
+
`invalid_target` for any other name. `resources` is not in `requires`, on
|
|
147
|
+
purpose: a Jelly that does not know the field ignores it and still loads the
|
|
148
|
+
plugin, which then uses the pasted key.
|
|
149
|
+
|
|
143
150
|
**Credentials, first match wins** (`src/credentials.js`):
|
|
144
151
|
|
|
145
152
|
1. the `token` option or `MEMORY_TOKEN` (not set inside Jelly; the engine starts
|
|
146
153
|
with an empty environment);
|
|
147
154
|
2. Jelly's identity accessor, `globalThis[Symbol.for("jelly.identity")]`, when
|
|
148
|
-
the host is signed in to a Jelly account
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
answers
|
|
155
|
+
its `resources()` lists `memory`: the host is signed in to a Jelly account
|
|
156
|
+
whose Jelly ID offers `memory`, and the agent was given this plugin. The
|
|
157
|
+
plugin asks `token("memory")` for a ten-minute token, keeps it in memory
|
|
158
|
+
until 60 s before it expires, and asks again once when the gateway answers
|
|
159
|
+
`401`;
|
|
152
160
|
3. the **Memory key** setting: the key pasted from the memory site's `/account`
|
|
153
161
|
page, read with
|
|
154
162
|
`globalThis[Symbol.for("jelly.plugin-secrets")].get("@joe-broadhead/opencode-mem", "token")`.
|
|
155
163
|
|
|
164
|
+
**When Jelly refuses the token.** `token("memory")` rejects with a code. Jelly's
|
|
165
|
+
host maps Jelly ID's `400` to `invalid_target`, `401` to `not_enrolled`, `403`
|
|
166
|
+
to `access_denied`, and everything else, a `503` included, to `unavailable`, so
|
|
167
|
+
the plugin cannot tell an outage from Jelly ID turning memory off. The host
|
|
168
|
+
holds each refusal for 30 s, and so does the plugin: Jelly is not asked again
|
|
169
|
+
until the 30 s pass.
|
|
170
|
+
|
|
171
|
+
| Code | What the request does |
|
|
172
|
+
|---|---|
|
|
173
|
+
| `invalid_target`, `not_enrolled`, `unavailable` | Uses the pasted key, when one is saved. With no key, it fails with "this agent's Jelly sign-in can't be used for memory: … (`<code>`), and no memory key is saved in the plugin's settings"; a finished turn is spooled for later |
|
|
174
|
+
| `access_denied` | Fails: "the Jelly account is disabled or marked for deletion (access_denied); a saved memory key is not used in its place". No fallback |
|
|
175
|
+
|
|
176
|
+
Why no fallback on `access_denied`: Jelly says the account behind this agent is
|
|
177
|
+
disabled or about to be deleted. Writing on with a pasted key would get round
|
|
178
|
+
the switch that stops that account, so the plugin stops instead. A `401` from
|
|
179
|
+
the gateway never switches sources: a refused Jelly token is replaced by a new
|
|
180
|
+
Jelly token or not at all, and a refused pasted key is not retried.
|
|
181
|
+
|
|
182
|
+
`mem_status` and `/mem-status` show the credential in use, for example
|
|
183
|
+
`credential: plugin-secret (Jelly refused a memory token: unavailable; Jelly is
|
|
184
|
+
asked again within 30 s)`, and the log has one warning per refusal (its code,
|
|
185
|
+
never a token).
|
|
186
|
+
|
|
187
|
+
**Accepted risk.** If a person's Jelly sign-in and pasted key belong to two
|
|
188
|
+
different memory users, a request that falls back writes as the key's user,
|
|
189
|
+
into that user's memory, until Jelly answers again. Paste a key from the same
|
|
190
|
+
account you sign in to Jelly with.
|
|
191
|
+
|
|
156
192
|
**Gateway origin:** the **Memory address** setting (`controlURL`), else the
|
|
157
|
-
`url` of the identity accessor's `memory` resource
|
|
158
|
-
`knowledgeURL` default to `<origin>/core` and `<origin>/knowledge`.
|
|
193
|
+
`url` of the identity accessor's `memory` resource, during a fallback too.
|
|
194
|
+
`baseURL` and `knowledgeURL` default to `<origin>/core` and `<origin>/knowledge`.
|
|
159
195
|
|
|
160
196
|
A token is never logged, spooled, or written to a file. With no credential the
|
|
161
|
-
plugin still loads and registers its nine tools; each
|
|
162
|
-
saying why memory is unavailable, and nothing is
|
|
197
|
+
plugin still loads and registers its nine tools and its view RPC; each tool
|
|
198
|
+
answers one sentence saying why memory is unavailable, and nothing is
|
|
199
|
+
captured, spooled, or sent.
|
|
200
|
+
|
|
201
|
+
**Icon.** The declaration's `icon` is `assets/icon.svg`, shipped in the
|
|
202
|
+
package: a flat brain mark on a square `viewBox`, made only of the elements
|
|
203
|
+
and attributes Jelly's `cleanPluginIcon` keeps. Jelly drops an icon that does
|
|
204
|
+
not clean, without an error, and draws a monogram instead, so
|
|
205
|
+
`npm run check:jelly` runs the file through Jelly's own cleaner.
|
|
163
206
|
|
|
164
207
|
**Settings** (`jelly.contributes.settings`):
|
|
165
208
|
|
|
@@ -167,7 +210,7 @@ saying why memory is unavailable, and nothing is captured, spooled, or sent.
|
|
|
167
210
|
|---|---|---|
|
|
168
211
|
| `controlURL` | string | Memory address. Empty: the Jelly account's memory origin |
|
|
169
212
|
| `capture` | boolean | On by default. Off: the tools still work and nothing is captured, the compaction checkpoint included |
|
|
170
|
-
| `token` | secret | Memory key, for a host without a Jelly sign-in that offers memory. A saved key reaches the plugin at the engine's next start |
|
|
213
|
+
| `token` | secret | Memory key, for a host without a Jelly sign-in that offers memory, and the fallback when Jelly refuses a token (not after `access_denied`). A saved key reaches the plugin at the engine's next start |
|
|
171
214
|
|
|
172
215
|
**Tools and permissions.** Each tool is declared as `name: "mem.<tool>"`,
|
|
173
216
|
`permission: "mem_<tool>"`, `effect: "allow"`:
|
|
@@ -195,16 +238,31 @@ Why this mapping:
|
|
|
195
238
|
write. Jelly denies them to the read-only helpers (researcher, reviewer).
|
|
196
239
|
`mem_wiki` reads too, but it is one tool, so the helpers lose its reads.
|
|
197
240
|
|
|
198
|
-
**
|
|
199
|
-
|
|
200
|
-
`memory.promote`, `memory.promote.revoke`, `wiki.write
|
|
201
|
-
|
|
202
|
-
|
|
241
|
+
**Team writes ask inside Jelly.** A team-visible write asserts the plugin's own
|
|
242
|
+
approval actions, with the space as the resource: `memory.remember`,
|
|
243
|
+
`memory.forget`, `memory.promote`, `memory.promote.revoke`, `wiki.write`.
|
|
244
|
+
Jelly's default rules (`agents/default/opencode.jsonc`) set all five to `ask`,
|
|
245
|
+
so a person approves each write to a shared space. Private writes, the default,
|
|
246
|
+
assert nothing and never ask. These five action names are a contract with
|
|
247
|
+
Jelly: do not rename one, or add one, without telling Jelly, or a team write
|
|
248
|
+
runs without a prompt there.
|
|
249
|
+
|
|
250
|
+
**`asks`.** The declaration lists the same five actions in `"asks"`, so Jelly
|
|
251
|
+
can read from the plugin, not only from its own default rules, which run-time
|
|
252
|
+
actions to ask a person about. Like `resources`, it is additive and not in
|
|
253
|
+
`requires`: a Jelly that does not know the field leaves it out and still loads
|
|
254
|
+
the plugin. `test/jelly-declaration.test.js` and `npm run check:jelly` both
|
|
255
|
+
compare `asks` with the actions the tools really assert
|
|
256
|
+
(`scripts/approval-actions.mjs`), so the two cannot drift apart.
|
|
203
257
|
|
|
204
258
|
The declaration has no sign-ins: the Jelly account is the host's sign-in, and
|
|
205
259
|
the pasted key is a secret setting. `npm run check:jelly -- <Jelly checkout>`
|
|
206
|
-
parses the declaration with Jelly's own `PluginDeclarationSchema
|
|
207
|
-
`
|
|
260
|
+
parses the declaration with Jelly's own `PluginDeclarationSchema`, checks that
|
|
261
|
+
`resources` is kept and not required, that `asks` is not required and is kept
|
|
262
|
+
when that Jelly knows it, runs the icon through Jelly's `cleanPluginIcon`,
|
|
263
|
+
and checks the views ([Views in Jelly](#views-in-jelly));
|
|
264
|
+
`test/jelly-declaration.test.js` and `test/views-contract.test.js` check the
|
|
265
|
+
same in CI, with the rules restated.
|
|
208
266
|
|
|
209
267
|
**One memory per person.** Every Jelly engine runs the OpenCode agent `agent`,
|
|
210
268
|
so a person's Jelly agents read and write one personal memory, under agent
|
|
@@ -212,6 +270,69 @@ so a person's Jelly agents read and write one personal memory, under agent
|
|
|
212
270
|
persona and scenarios of their other OpenCode agents (`build`, `plan`, …),
|
|
213
271
|
which are keyed by agent name. `agent` is not a reserved name.
|
|
214
272
|
|
|
273
|
+
### Views in Jelly
|
|
274
|
+
|
|
275
|
+
Memory's screens in Jelly are the plugin's own views (`jelly.views`), shown
|
|
276
|
+
with the person's Jelly sign-in: there is no second sign-in, and Jelly holds
|
|
277
|
+
no screen of its own for memory. Each page is a static file in the package
|
|
278
|
+
(`views/*.html`), run by Jelly in a sealed frame with no network; it reaches
|
|
279
|
+
only this plugin's read-only RPC, and only for the agent it is shown for.
|
|
280
|
+
|
|
281
|
+
| View | Place | Shows | Grants |
|
|
282
|
+
|---|---|---|---|
|
|
283
|
+
| `home` "Memory" | Home tile, small | Whether conversations are remembered, and how many memories are kept | `rpc`: `memory.overview` |
|
|
284
|
+
| `memory` "Your memory" | This plugin's card in Settings → Plugins | Four tabs: **Overview** (what memory is, the sign-in in use, the address, Remember conversations, health, counts), **Spaces**, **Wiki** (browse and read), **Recent** (the newest 100 memories, with Forget) | `data`, `rpc`: all six methods, `open-agent` |
|
|
285
|
+
|
|
286
|
+
**The RPC** (`src/views/rpc.js`, schemas in `src/views/contracts.js`). The
|
|
287
|
+
plugin registers it with the engine under its package name, the only id Jelly
|
|
288
|
+
calls for its views. Jelly holds each call to the agent's rules for the
|
|
289
|
+
method's permission, the one the matching tool reads under, before the plugin
|
|
290
|
+
sees it:
|
|
291
|
+
|
|
292
|
+
| Method | Permission | Reads |
|
|
293
|
+
|---|---|---|
|
|
294
|
+
| `memory.overview` | `mem_status` | The credential source, the address, capture as this engine runs it, health, the personal space and its counts |
|
|
295
|
+
| `spaces.list` | `mem_spaces` | `GET /v1/spaces` |
|
|
296
|
+
| `memories.recent` | `mem_recall` | The personal space's newest L1 atoms (`/v3/atomic/query`), 50 a page, two pages |
|
|
297
|
+
| `wiki.list`, `wiki.pages`, `wiki.read` | `mem_wiki` | The personal space's wikis, a wiki's pages, one page (at most 48,000 characters) |
|
|
298
|
+
|
|
299
|
+
Every call is a read the tools already make, through the gateway with the
|
|
300
|
+
credential chain above, so no gateway route is added for the views and the
|
|
301
|
+
gateway scopes each one to the caller. A view never names a user, a space or
|
|
302
|
+
a container. Reads are under the engine's own primary agents
|
|
303
|
+
(`ctx.agent.list()`, which inside Jelly is `agent`), or the `agent` option
|
|
304
|
+
when it is set. A wiki or page id from another person's memory is refused.
|
|
305
|
+
With no credential the overview says why and what to do, and every other
|
|
306
|
+
read refuses with the same sentence the tools give.
|
|
307
|
+
|
|
308
|
+
**Writes go through the agent.** Forget on a recent memory fills the
|
|
309
|
+
composer with "Forget this memory: “<its first 80 characters>” (<id>)." The id
|
|
310
|
+
is all `mem_forget` needs: it finds the memory under the agent the person is
|
|
311
|
+
talking to, which is the agent the views read under, so no agent name is
|
|
312
|
+
written. The person sends it, and `mem_forget` runs under
|
|
313
|
+
their rules, as any forget does. **Remember conversations** stays a declared
|
|
314
|
+
setting on the plugin's card: the Overview shows it and says where to change
|
|
315
|
+
it, and notes when a saved change waits for the engine's next start.
|
|
316
|
+
|
|
317
|
+
**No recall view yet.** Jelly runs the memory tools through Code Mode, and a
|
|
318
|
+
view is not given the result of a call made inside it, so there is no view
|
|
319
|
+
behind `mem_recall`, and its result is exactly 0.6.2's. What Jelly would need:
|
|
320
|
+
[jelly-views-later.md](docs/design/jelly-views-later.md).
|
|
321
|
+
|
|
322
|
+
**No `pattern` in the schemas.** The pinned engine's RPC refuses to register a
|
|
323
|
+
method whose schema has a `pattern` ("Patterns may block validation and are
|
|
324
|
+
disabled"), so the schemas bound ids by length and the handlers check their
|
|
325
|
+
form, refusing a bad one in words. `check:jelly` and the tests refuse a
|
|
326
|
+
`pattern`.
|
|
327
|
+
|
|
328
|
+
`npm run check:jelly` checks the views against Jelly's own code: the subset
|
|
329
|
+
rules, each method's schemas through Jelly's reader with a sample answer of
|
|
330
|
+
each (`test/fixtures/view-answers.js`), and each page carrying Jelly's bridge
|
|
331
|
+
helper as it is (`views/jelly-view.js`, pasted into every page). With a
|
|
332
|
+
Chrome, `npm run shots:views -- <Jelly checkout> <out dir>` draws every
|
|
333
|
+
screen, in Jelly and Jelly Night, under the policy Jelly serves pages with,
|
|
334
|
+
and fails on any refusal or page error.
|
|
335
|
+
|
|
215
336
|
## Spaces, grants, and memory
|
|
216
337
|
|
|
217
338
|
Each user has one personal space, in a memory container of its own: upstream
|
|
@@ -257,7 +378,9 @@ The auth service serves the console at `/console/` and its API at
|
|
|
257
378
|
force-directed wiki graph, code indexes, pipeline state, the crew manifest, and
|
|
258
379
|
spaces, collections, resources, grants, and members.
|
|
259
380
|
Grant and member mutations go through the control plane. The browser holds only
|
|
260
|
-
a Better Auth session or API key; service keys stay server-side.
|
|
381
|
+
a Better Auth session or API key; service keys stay server-side. A gateway
|
|
382
|
+
with Jelly ID as its only way in has no sign-in page: the console and `/login`
|
|
383
|
+
say that people use Memory from Jelly. See [docs/mission-control.md](docs/mission-control.md).
|
|
261
384
|
|
|
262
385
|
## Operations
|
|
263
386
|
|
package/SECURITY.md
CHANGED
|
@@ -44,15 +44,17 @@ This is the summary.
|
|
|
44
44
|
`secret_ref` are server-side routing data.
|
|
45
45
|
- The browser holds a Better Auth session (console and `/account` only); the
|
|
46
46
|
plugin and CLI hold a Better Auth API key, or inside a Jelly host a
|
|
47
|
-
ten-minute Jelly ID resource token for the memory resource
|
|
48
|
-
|
|
47
|
+
ten-minute Jelly ID resource token for the memory resource, and the API key
|
|
48
|
+
a person pasted, used while Jelly refuses a token (never after
|
|
49
|
+
`access_denied`). None of them ever holds a gateway, knowledge, admin, or
|
|
50
|
+
per-cell key.
|
|
49
51
|
|
|
50
52
|
### Credentials
|
|
51
53
|
|
|
52
54
|
| Credential | Lives in | Purpose |
|
|
53
55
|
|---|---|---|
|
|
54
56
|
| Better Auth API key | Client | Authenticates one user to the gateway; expires after `AUTH_KEY_TTL_DAYS` (90); revocable on `/account` or with `deploy/auth/scripts/revoke-user-keys.mjs` |
|
|
55
|
-
| Jelly ID resource token | Client (a Jelly host, in memory only) | Authenticates the host's owner to the gateway for ten minutes; verified with the issuer's Ed25519 keys, audience-bound
|
|
57
|
+
| Jelly ID resource token | Client (a Jelly host, in memory only) | Authenticates the host's owner to the gateway for ten minutes; verified with the issuer's Ed25519 keys, audience-bound; at the gateway a refused one never falls back to another credential kind ([docs/design/adr-personal-containers.md](docs/design/adr-personal-containers.md)). The plugin's own fallback to a pasted key is a separate request with that key ([README](README.md#running-inside-jelly)) |
|
|
56
58
|
| `CONTROL_TOKEN` | Gateway | Authenticates the gateway to control; must equal `CONTROL_SERVICE_TOKEN` |
|
|
57
59
|
| `CONTROL_SERVICE_TOKEN` | Control service | Verifies the gateway's `x-control-user` assertion; never grants admin |
|
|
58
60
|
| `CONTROL_ADMIN_TOKEN` | Operator/infrastructure, the exporter, the `cell-health` job | Cell and placement administration; separate from the service token |
|
|
@@ -91,7 +93,9 @@ equal, and a service token never sets `admin`.
|
|
|
91
93
|
verifications per address; Better Auth's limiter is on. The shipped
|
|
92
94
|
Caddyfiles cap bodies at the edge as well.
|
|
93
95
|
- With Google sign-in, `GOOGLE_HD` is required (or an explicit `*`); the dev
|
|
94
|
-
password refuses to start on an https origin.
|
|
96
|
+
password refuses to start on an https origin. The gateway refuses to start
|
|
97
|
+
with no way in at all; Jelly ID alone is enough, and then `/login` offers no
|
|
98
|
+
sign-in.
|
|
95
99
|
|
|
96
100
|
### No links-file path
|
|
97
101
|
|
package/assets/icon.svg
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
|
|
2
|
+
<rect width="64" height="64" rx="14" fill="#3B3486"/>
|
|
3
|
+
<g fill="none" stroke="#F4F1FF" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round">
|
|
4
|
+
<path d="M32 15C28.5 11 21.5 11.5 19.5 17C14.5 17.5 11.5 22.5 14 27C10 30 10.5 36 15 38C13.5 43.5 18 48 23 47C25 51 30 51.5 32 48"/>
|
|
5
|
+
<path d="M32 15C35.5 11 42.5 11.5 44.5 17C49.5 17.5 52.5 22.5 50 27C54 30 53.5 36 49 38C50.5 43.5 46 48 41 47C39 51 34 51.5 32 48"/>
|
|
6
|
+
<path d="M32 15V48"/>
|
|
7
|
+
<path d="M19.5 17C20.5 20.5 23.5 22 26.5 21"/>
|
|
8
|
+
<path d="M14 27C17.5 28.5 21 27.5 22.5 25"/>
|
|
9
|
+
<path d="M15 38C18 36.5 21.5 37 24 39.5"/>
|
|
10
|
+
<path d="M44.5 17C43.5 20.5 40.5 22 37.5 21"/>
|
|
11
|
+
<path d="M50 27C46.5 28.5 43 27.5 41.5 25"/>
|
|
12
|
+
<path d="M49 38C46 36.5 42.5 37 40 39.5"/>
|
|
13
|
+
</g>
|
|
14
|
+
</svg>
|