@wrongstack/core 0.284.1 → 0.286.0

package/instructions/sections/tool/delegation-full.md

@@ -32,4 +32,4 @@ Check `stopReason` on the returned object:
 - `aborted` — the user or another tool stopped it; don't retry silently.
 - `error` — infrastructure problem; surface it.
 
-`delegate` auto-promotes you into director mode on first call — no setup tool needed. For fine-grained control over a long-running fleet, use `spawn_subagent` + `assign_task` + `await_tasks` directly. Fire-and-forget assigns report back automatically: a completed non-awaited task posts its result to your mailbox, injected before your next step.
+`delegate` is available only after Director mode is active. For fine-grained control over a long-running fleet, use `spawn_subagent` + `assign_task` + `await_tasks` directly. Fire-and-forget assigns report back automatically: a completed non-awaited task posts its result to your mailbox, injected before your next step.

package/instructions/system.md

@@ -30,6 +30,53 @@ For every non-trivial task, follow this four-phase loop:
 
 This loop separates intent, evidence, mutation, and validation. Do not skip phases unless the user explicitly asks for an immediate answer or the task is trivial and read-only.
 
+## Memory management — use it every turn
+
+WrongStack has a SuperMemory system that persists facts across sessions and automatically injects relevant memories into your context. **Using memory is essential to being effective.**
+
+### When to remember
+
+After discovering ANY of the following, call `remember` immediately:
+- **File paths** you frequently access (`type: "reference"`, tags: #path)
+- **Project conventions** you noticed (`type: "convention"`)
+- **Design decisions** made during the session (`type: "decision"`)
+- **Facts about the codebase** — architecture, dependencies, tooling (`type: "fact"`)
+- **User preferences** — coding style, naming, testing habits (`type: "preference"`)
+- **Anti-patterns** to avoid (`type: "anti_pattern"`)
+
+### Scope rules
+
+| Scope | When to use |
+|-------|------------|
+| `project-memory` | Codebase facts, file paths, conventions, architecture decisions |
+| `user-memory` | Personal preferences, workflow habits, naming style |
+| `project-agents` | Inter-agent coordination facts (other agents' roles, active work) |
+
+### Memory priority
+
+- `critical` — Security constraints, build commands, project-wide rules
+- `high` — Important for most tasks (directory structure, main patterns)
+- `medium` — Useful context (specific module details)
+- `low` — Nice to know (minor preferences)
+
+### Before every tool call
+
+Before calling `read`, `edit`, `grep`, `glob`, or `write` on a file or directory you haven't visited this session:
+1. `search_memory` for relevant context (path, topic, convention)
+2. Include a hint from memory in your reasoning — strengthens LLM context
+
+### After every significant discovery
+
+- **File found**: `remember` the path with tags #path
+- **Pattern noticed**: `remember` it with type `convention`
+- **Decision made**: `remember` it with type `decision`
+- **Bug found**: `remember` the root cause with type `fact`, tags #bug
+
+### Finding memories
+
+- `search_memory` — keyword/substring search
+- `find_related_memories` — graph traversal for connected knowledge
+
 ## Tool use and failures
 
 Call tools directly and let the permission flow decide — don't pre-announce that you "would like to" do something. When a tool fails, classify the failure and respond accordingly; never silently skip one:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/core",
-  "version": "0.284.1",
+  "version": "0.286.0",
   "license": "MIT",
   "description": "WrongStack core: kernel, types, defaults, and shared utilities for the WrongStack CLI agent.",
   "repository": {
@@ -87,18 +87,17 @@
   ],
   "wrongstackApiVersion": "0.1.10",
   "dependencies": {
-    "@wrongstack/kanban": "0.284.1"
+    "@wrongstack/kanban": "0.286.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "pnpm clean && tsup",
+    "build": "node ../../scripts/build-package.mjs",
     "build:prompts": "node scripts/build-prompts.mjs",
     "typecheck": "tsc --noEmit",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""

package/skills/docker-deploy/SKILL.md

@@ -143,7 +143,7 @@ trivy image --exit-code 1 --ignore-unfixed --severity HIGH,CRITICAL wrongstack:$
 ## WrongStack-specific notes
 
 - **WrongStack CLI entry point**: `packages/cli/dist/index.js` after build.
-- **pnpm workspaces**: Build from repo root — `pnpm -r build` before `docker build`.
+- **pnpm workspaces**: Build from repo root with `pnpm build` before `docker build`; WrongStack's build runner topologically orders workspace dependencies.
 - **Session storage**: Sessions are stored at `WRONGSTACK_SESSION_ROOT` — mount a volume for persistence.
 - **Config**: Config is at `WRONGSTACK_CONFIG_DIR` — mount for config persistence across restarts.
 

package/skills/node-modern/SKILL.md

@@ -163,7 +163,7 @@ while (true) {
 {
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsup",
+    "build": "node ../../scripts/build-package.mjs",
     "test": "vitest run"
   }
 }
@@ -188,4 +188,4 @@ while (true) {
 - `react-modern` — React Server Components with Node.js
 - `bug-hunter` — catching async/await bugs, unhandled rejections
 - `sdd` — for setting up new Node.js features with a spec first
-- `output-standards` — for standardized `<nextsteps>` formatting
+- `output-standards` — for standardized `<nextsteps>` formatting

package/skills/plugin-author/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when creating, reviewing, or refactoring a WrongStack plugin
   in `packages/plugins/`. Covers the Plugin interface, tool registration, config
   schema, the H1 audit pattern (teardown + health), PluginAPI extension for host
-  data, and the entry-point registration steps (tsup, package.json, index.ts).
+  data, and the entry-point registration steps (package.json and index.ts).
   Triggers: user says "new plugin", "add a plugin", "plugin teardown", "plugin
   health", "register a tool", "PluginAPI extension".
 version: 1.0.0
@@ -266,9 +266,11 @@ When a plugin needs host data not yet on `PluginAPI` (e.g.
 Precedent: commit `9bed619f` added `modelsRegistry?: ModelsRegistry` for
 cost-tracker's pricing hydration.
 
-## Entry-point registration (3 files)
+## Entry-point registration
 
-After writing `src/<name>/index.ts`, wire it into three files:
+After writing `src/<name>/index.ts`, wire it into two package files. The
+central `scripts/build-package.mjs` driver discovers plugin entry points from
+the exports map automatically.
 
 ### 1. `src/index.ts` — named re-export
 
@@ -276,16 +278,7 @@ After writing `src/<name>/index.ts`, wire it into three files:
 export { default as myPluginPlugin } from './my-plugin/index.js';
 ```
 
-### 2. `tsup.config.ts` — build entry
-
-```typescript
-entry: {
-  // ...
-  'my-plugin': 'src/my-plugin/index.ts',
-},
-```
-
-### 3. `package.json` — subpath export
+### 2. `package.json` — subpath export
 
 ```json
 "./my-plugin": {
@@ -294,7 +287,7 @@ entry: {
 }
 ```
 
-### 4. `packages/cli/src/wiring/plugins.ts` — built-in factory
+### 3. `packages/cli/src/wiring/plugins.ts` — built-in factory
 
 ```typescript
 async () => (await import('@wrongstack/plugins/my-plugin')).default,
@@ -334,10 +327,10 @@ For the H1 pattern, extend `tests/plugin-teardown.test.ts` with a
 2. **Write the Plugin object**: name, version, apiVersion, setup, teardown, health
 3. **Register tools/hooks** in `setup()`
 4. **Add state + teardown + health** following the H1 pattern
-5. **Wire into 3 files**: `index.ts`, `tsup.config.ts`, `package.json`
+5. **Wire the package entry**: `index.ts` and `package.json`
 6. **Add to `BUILTIN_PLUGIN_FACTORIES`** in CLI wiring
 7. **Write tests**: `<name>.test.ts` (unit) + extend `plugin-teardown.test.ts`
-8. **Run verification**: `npx vitest run packages/plugins` + `npx tsc --noEmit` + `npx tsup`
+8. **Run verification**: `pnpm --filter @wrongstack/plugins test` + `pnpm --filter @wrongstack/plugins typecheck` + `pnpm --filter @wrongstack/plugins build`
 9. **Update `src/index.ts` doc comment** — bump the plugin count
 
 ## Skills in scope

package/skills/wrongstack-mailbox/SKILL.md

@@ -371,18 +371,55 @@ setInterval(() => {
 }, 30_000);
 ```
 
-### Poll, don't long-poll
+### Real-time push via SSE (preferred) or polling
 
-The bridge does not support long-polling or websockets. Poll for new
-messages on a 5–10 s interval. Don't poll faster than 1 Hz — that's noisy
-and gives nothing useful.
+The bridge supports **Server-Sent Events (SSE)** on `GET /mailbox/events`
+for real-time push. This is the preferred approach — no polling needed.
 
-For normal inbox catch-up, prefer `/mailbox/check` over manual
-`/mailbox/query` + `/mailbox/ack-many`. It checks direct mail,
-`baseId` alias mail, and broadcasts in one call, dedupes messages, and
-can optionally mark them read or completed via one batch ack.
+```ts
+// Open an SSE connection that pushes events in real-time.
+const res = await fetch(`${url}/mailbox/events`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+const reader = res.body!.getReader();
+const decoder = new TextDecoder();
+
+for (;;) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const text = decoder.decode(value);
+  // SSE events arrive as: data: {"type":"message.sent",...}\n\n
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('data: ')) continue;
+    const event = JSON.parse(line.slice(6));
+    if (event.type === 'message.sent') {
+      console.log(`[${event.type}] ${event.from} → ${event.to}: ${event.messageId}`);
+      // Fetch the full message via /mailbox/query or /mailbox/check.
+    }
+  }
+}
+```
+
+**SSE event types:**
+
+| Event `type` | When | Payload fields |
+|--------------|------|---------------|
+| `message.sent` | A message was sent via `POST /mailbox/send` | `messageId`, `from`, `to`, `timestamp` |
+
+The SSE stream sends a `: connected` comment on open and a
+`: keepalive` comment every 15 s to prevent proxy/CDN timeouts.
+
+**Important:** SSE events carry only the message id and metadata — not
+the full message body. When you receive an event, call `/mailbox/check`
+or `/mailbox/query` to fetch the complete message content.
+
+**Fallback: polling.** If your HTTP client doesn't support SSE (or you're
+behind a proxy that buffers responses), poll on a 5–10 s interval. Don't
+poll faster than 1 Hz — the bridge enforces a rate limit of 120 requests
+per minute per bearer token.
 
 ```ts
+// Fallback: poll every 5 s when SSE is unavailable.
 async function pollOnce(): Promise<void> {
   const result = await mb('/mailbox/check', {
     agentId,
@@ -504,7 +541,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| POST | `/mailbox/send` | Send a message |
+| POST | `/mailbox/send` | Send a message (supports optional `ttlMs` for auto-expiry) |
 | POST | `/mailbox/query` | Query messages (filters: `to`, `from`, `unreadBy`, `type`, `minPriority`, `incompleteOnly`, `limit`, `since`) |
 | POST | `/mailbox/check` | Read inbox mail for `agentId`/`baseId` plus broadcasts; optionally `markRead=false`, `completed=true`, `outcome` |
 | POST | `/mailbox/ack` | Acknowledge one message |
@@ -516,6 +553,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 | POST | `/mailbox/heartbeat` | Update client heartbeat |
 | GET | `/mailbox/agents` | List all registered agents |
 | GET | `/mailbox/agents/online` | List agents with a live heartbeat (within 60 s) |
+| GET | `/mailbox/events` | **SSE stream** — real-time push of mailbox events (auth required) |
 | GET | `/healthz` | Liveness probe — does NOT require auth |
 
 ### Error shape
@@ -528,6 +566,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 |------|------|----------------------------|
 | `VALIDATION_ERROR` | 400 | Missing or wrong-type field. Read the message; it tells you which field. |
 | `UNAUTHORIZED` | 401 | Token mismatch. Re-read `~/.wrongstack/projects/<slug>/.mailbox.token` and try again — the bridge may have restarted. |
+| `RATE_LIMITED` | 429 | Rate limit exceeded (max 120 requests/min per token). Slow down or use SSE instead of polling. |
 | `NOT_FOUND` | 404 | Wrong route. Check the path table above. |
 | `INTERNAL_ERROR` | 500 | WrongStack-side failure. Retry once; if it persists, surface to the user. |
 
@@ -606,9 +645,9 @@ await mb('/mailbox/send', {
 - **Don't reuse one `agentId` across multiple external sessions.** If
   two processes register under the same id, heartbeats overwrite each
   other and read receipts become unreliable.
-- **Don't poll faster than 1 Hz.** The bridge isn't load-tested for
-  high-frequency polling, and there's no rate limit at the server side
-  — your noisy client can starve other agents.
+- **Don't poll faster than 1 Hz.** The bridge enforces a rate limit of
+  120 requests/min per bearer token (returns `429 RATE_LIMITED` beyond
+  that). Prefer SSE (`GET /mailbox/events`) over polling when possible.
 - **Don't include the token in any logged output.** It's the only
   credential. If you must print the URL, redact the token (`[REDACTED]`).
 - **Don't reply to a broadcast with another broadcast.** Replies should

package/dist/dispatcher-types.d-BBeXBQgS.d.ts

@@ -1,66 +0,0 @@
-import * as https from 'node:https';
-import { Dispatcher } from 'undici';
-
-/**
- * `dispatcher-types.d.ts` — Unify `https.Agent` and `undici.Dispatcher` types.
- *
- * Problem: `https.Agent` (Node.js built-in) and `undici.Dispatcher` implement the
- * same interface at runtime — `fetch`'s `RequestInit.dispatcher` accepts anything
- * with a `dispatch(req, opts)` method. However, TypeScript's type definitions
- * treat them as unrelated types because they come from different `@types/*` packages
- * (or undici@7 bundles its own Dispatcher type that conflicts with @types/node's
- * copy of the same concept via undici-types).
- *
- * Solution: This module augments the global `RequestInit` type so that
- * `https.Agent` is accepted as a valid `dispatcher` value without a cast.
- *
- * Usage:
- *   import '@wrongstack/core/utils/dispatcher-types';
- *   const agent = new https.Agent({ rejectUnauthorized: false });
- *   fetch(url, { dispatcher: agent }); // ✅ no cast needed
- *
- * Alternatively, use `as HttpsAgentAsDispatcher` to silence any remaining
- * conflicts at the call site.
- *
- * Verified at runtime: `https.Agent` has a `dispatch(req, opts)` method and
- * is callable by the built-in fetch implementation — this shim is a type-level
- * correction only, not a runtime polyfill.
- */
-
-
-
-/**
- * Marker type: a value that fetch's `RequestInit.dispatcher` accepts at runtime.
- * Both `https.Agent` and `undici.Dispatcher` satisfy this structural interface.
- */
-type HttpDispatcher = Pick<Dispatcher, 'dispatch'>;
-
-/**
- * Augment `RequestInit` so that `https.Agent` is a valid dispatcher type.
- * Without this, TypeScript rejects `https.Agent` for `dispatcher` because the
- * two agent types are not structurally compatible in the installed @types set.
- */
-declare global {
-  interface RequestInit {
-    /**
-     * Accepts `https.Agent` in addition to `undici.Dispatcher`.
-     * Runtime type-check is performed by Node.js / undici — this declaration
-     * only tells TypeScript the same thing.
-     */
-    dispatcher?: HttpDispatcher | undefined;
-  }
-}
-
-/**
- * Use this cast at call sites where `https.Agent` must be passed to a function
- * typed for `undici.Dispatcher`. Documents the trust boundary: the cast is safe
- * because both types share a `dispatch(req, opts)` method at runtime.
- *
- * @example
- * import type { HttpsAgentAsDispatcher } from '@wrongstack/core';
- * const agent = new https.Agent({ rejectUnauthorized: false });
- * fetch(url, { dispatcher: agent as HttpsAgentAsDispatcher });
- */
-type HttpsAgentAsDispatcher = https.Agent;
-
-export type { HttpDispatcher as H, HttpsAgentAsDispatcher as a };