pubsub/AGENTS.md

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