glm-5.1
de7fc88f99
- Remove src/call.ts (PendingRequestMap, CallEventSchema, CallError) — call protocol belongs in @alkdev/operations
- Add EventEnvelope type ({ type, id, payload }) as the cross-platform serialization contract
- Simplify createPubSub: replace PubSubPublishArgsByKey tuple model with PubSubEventMap; publish(type, id, payload) and subscribe(type, id) use explicit id for topic scoping
- Update Redis adapter to serialize/deserialize full EventEnvelope
- Expand operators: add take, reduce, toArray, batch, dedupe, window, flat, groupBy, chain, join
- Remove @alkdev/typebox runtime dependency (was only used by call.ts)
- Remove ./call sub-path export from package.json and tsup config
- Update all architecture docs to reflect transport-only scope, add Worker adapter, remove call protocol references
- Remove docs/architecture/call-protocol.md
- Update AGENTS.md with new source layout and transport-only principle
116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
## Memory Tools (via @alkdev/open-memory plugin)
|
|
|
|
You have access to two tools for managing your context and accessing session history:
|
|
|
|
### memory({tool: "...", args: {...}})
|
|
|
|
Read-only tool for introspecting your session history and context state. Available operations:
|
|
- `memory({tool: "help"})` — full reference with examples
|
|
- `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
|
|
- `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
|
|
- `memory({tool: "children", args: {sessionId: "ses_..."}})` — list sub-agent sessions spawned from a parent
|
|
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
|
|
- `memory({tool: "messages", args: {sessionId: "...", role: "assistant"}})` — read only assistant messages
|
|
- `memory({tool: "messages", args: {sessionId: "...", showTools: true}})` — include tool-call output
|
|
- `memory({tool: "message", args: {messageId: "msg_..."}})` — read a single message by ID
|
|
- `memory({tool: "search", args: {query: "..."}})` — search across all conversations
|
|
- `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
|
|
- `memory({tool: "context"})` — check your current context window usage
|
|
|
|
### memory_compact()
|
|
|
|
Trigger compaction on the current session. This summarizes the conversation so far to free context space.
|
|
|
|
**When to use memory_compact:**
|
|
- When context is above 80% (check with `memory({tool: "context"})`)
|
|
- When you notice you're losing track of earlier conversation details
|
|
- At natural breakpoints in multi-step tasks (after completing a subtask, before starting a new one)
|
|
- When the system prompt shows a yellow/red/critical context warning
|
|
- Proactively, rather than waiting for automatic compaction at 92%
|
|
|
|
**When NOT to use memory_compact:**
|
|
- When context is below 50% (it wastes a compaction cycle)
|
|
- In the middle of a complex edit that you need immediate context for
|
|
- When the task is nearly complete (just finish the task instead)
|
|
|
|
Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
|
|
|
|
## Worktree Tool (via @alkimiadev/open-coordinator plugin)
|
|
|
|
You have access to the `worktree` tool for git worktree management and session coordination. Call with `{action, args}`:
|
|
|
|
### Coordinator Operations (available when session is not spawned by another session)
|
|
|
|
- `worktree({action: "list"})` — List git worktrees
|
|
- `worktree({action: "dashboard"})` — Worktree dashboard with session info
|
|
- `worktree({action: "spawn", args: {tasks: [...], prompt: "..."}})` — Spawn parallel worktrees + sessions
|
|
- `worktree({action: "sessions"})` — Query spawned session status
|
|
- `worktree({action: "message", args: {sessionID: "...", message: "..."}})` — Message a session
|
|
- `worktree({action: "abort", args: {sessionID: "..."}})` — Abort a session
|
|
- `worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "..."}})` — Remove worktree
|
|
- `worktree({action: "help"})` — Show all available operations
|
|
|
|
### Implementation Operations (available when session is spawned by a coordinator)
|
|
|
|
- `worktree({action: "current"})` — Show your worktree mapping
|
|
- `worktree({action: "notify", args: {message: "...", level: "info|blocking"}})` — Report to coordinator
|
|
- `worktree({action: "status"})` — Show worktree git status
|
|
|
|
The plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree.
|
|
|
|
## Project: @alkdev/pubsub
|
|
|
|
Type-safe publish/subscribe with pluggable event target adapters (in-process, Redis, WebSocket, Worker, Iroh). Transport layer only — no call protocol or coordination semantics. Core is adapted from graphql-yoga (MIT). Dual-licensed MIT / Apache-2.0.
|
|
|
|
### Commands
|
|
|
|
- `npm run build` — Build with tsup (ESM + CJS + declarations)
|
|
- `npm run lint` — Type-check with `tsc --noEmit`
|
|
- `npm test` — Run tests with vitest
|
|
- `npm run test:watch` — Watch mode
|
|
- `npm run test:coverage` — Coverage report (v8)
|
|
|
|
### Architecture
|
|
|
|
See `docs/architecture/` for full spec. Key points:
|
|
|
|
- **EventEnvelope**: Every event is `{ type, id, payload }`. This is the cross-platform serialization contract.
|
|
- **Barrel + sub-path exports**: `src/index.ts` re-exports core + operators. Each adapter has its own sub-path entry (`@alkdev/pubsub/event-target-redis`, etc.).
|
|
- **Peer dep isolation**: Redis and Iroh adapters are optional peer deps. Consumers only install the ones they need.
|
|
- **TypedEventTarget contract**: All adapters implement the same `addEventListener`/`dispatchEvent`/`removeEventListener` interface. `createPubSub` is transport-agnostic.
|
|
- **Transport only**: No call protocol, no PendingRequestMap, no coordination. Those belong in `@alkdev/operations`.
|
|
- **No comments in source**: Do not add comments to code unless explicitly asked.
|
|
- **License headers**: Files adapted from graphql-yoga must preserve their MIT attribution headers.
|
|
|
|
### Source Layout
|
|
|
|
```
|
|
src/
|
|
index.ts — Barrel: re-exports core API + operators
|
|
types.ts — TypedEvent, TypedEventTarget, EventEnvelope (adapted from graphql-yoga)
|
|
create_pubsub.ts — createPubSub factory (adapted from graphql-yoga)
|
|
operators.ts — filter, map, pipe (adapted from graphql-yoga)
|
|
take, reduce, toArray, batch, dedupe, window,
|
|
flat, groupBy, chain, join (from async-utility reference)
|
|
repeater.ts — Inlined from @repeaterjs/repeater (MIT)
|
|
event-target-redis.ts — createRedisEventTarget (peer dep: ioredis)
|
|
# Future adapters:
|
|
# event-target-websocket.ts — (peer dep: none, web standard)
|
|
# event-target-worker.ts — (peer dep: none, web standard)
|
|
# event-target-iroh.ts — (peer dep: @rayhanadev/iroh)
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
Runtime: none (Repeater is inlined, TypeBox removed).
|
|
Peer (optional): `ioredis@^5.0.0` (Redis adapter), `@rayhanadev/iroh` (Iroh adapter, future).
|
|
Dev: `tsup`, `typescript`, `vitest`, `@vitest/coverage-v8`, `ioredis` (for type resolution).
|
|
|
|
### Adding an Adapter Checklist
|
|
|
|
1. Create `src/event-target-{name}.ts` implementing `TypedEventTarget`
|
|
2. Add entry to `tsup.config.ts` entry array
|
|
3. Add sub-path export to `package.json` exports map
|
|
4. Add peer dep to `package.json` peerDependencies (with peerDependenciesMeta optional: true)
|
|
5. Add to `src/index.ts` barrel re-export
|
|
6. Write tests in `test/event-target-{name}.test.ts` |