opencode-workspace-mailbox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renzo S. (mr-wolf-rsh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,348 @@
-# Temporary Holding Version
+# opencode-workspace-mailbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A per-project handoff mailbox for [OpenCode](https://opencode.ai) sessions.
+
+Every session gets it: a file-based inbox that other sessions write to, automatic delivery when the
+session goes idle, and loop guards so an agent can never talk itself into a spin. One global config
+serves a whole folder tree — **meta → account → repo** — because the tier is derived from the
+directory a session opens in, not from what you remember to configure.
+
+Built for OpenCode today; the storage layer is behind a `MailboxStore` interface, so the file
+backend can be swapped for SQLite or Engram — see [Backlog](#backlog).
+
+> Status: the code is complete (81 tests, `typecheck` and `build` green, repo at
+> [mr-wolf-rsh/opencode-workspace-mailbox](https://github.com/mr-wolf-rsh/opencode-workspace-mailbox)).
+> It is not yet published to npm — see [Install](#install).
+
+## The metaphor
+
+The mailbox is a **chain of command made of files**. Each tier owns a `handoffs/` folder holding its
+own `workspace.md` plus one file per immediate child. Messages only ever move along that ladder:
+escalate up, delegate down, or talk to a sibling.
+
+| In an organisation | In opencode-workspace-mailbox |
+|---|---|
+| The chief of staff | **Meta** tier — `D:\WORKSHOP` reads `handoffs/workspace.md` |
+| Account leads | **Account** tier — `mr-wolf-rsh` reads `mr-wolf-rsh/handoffs/workspace.md` |
+| The team doing the work | **Repo** tier — `<account>/handoffs/<project>.md` |
+| Memos, never rewrites | Append-only markdown; history is the audit trail |
+| "Received" stamp | `**Status:**` flips `OPEN` → `DONE`, one line, nothing else touched |
+| Handing over a task | `mailbox_send({ to: "absolute-scrapers", ... })` |
+| Standing instructions | `wake: true` — an idle session picks up new mail within one poll |
+| Opening a desk for the recipient | `spawnOnSend: true` — creates a session in the recipient's folder |
+| A message that needs a decision | Only then does the agent reply in chat |
+
+Tiers are **discovered from the folder tree**, not configured: a directory with `handoffs/` is a
+tier root, and anything under it resolves to its nearest ancestor that has one.
+
+## Why this exists
+
+Multi-repo workspaces talk through asynchronous handoffs: one file per project, append-only,
+addressed `from X → to Y`. The protocol works. The human relay does not.
+
+A message sits `OPEN` until somebody opens the right session, reads it, acts on it, and flips it to
+`DONE` — and "somebody remembers" is exactly the step that fails. Worse, once you have a parent
+strategy session and several implementation repos, the relay has to survive closed sessions,
+restarts, and a working day that never lines up.
+
+So this plugin closes the loop **inside the session that receives the message**. No daemon, no
+scheduler, no `opencode run` spawning a session per message: if a session is closed, the message
+simply waits in its file. When the session is open, the message surfaces on its own.
+
+The file format is the product, not an implementation detail: it is readable, diffable, reviewable
+in a PR, greppable, and it survives every process that ever touched it.
+
+## What it does
+
+Delivered as tools the agent calls and two hooks the runtime calls:
+
+- **`mailbox_read`** — list `OPEN` messages for a project (or any routed recipient).
+- **`mailbox_send`** — append a message to the recipient's mailbox, optionally spawning a session
+  in the recipient's directory.
+- **`mailbox_ack`** — flip one message's `**Status:**` line to `DONE`, byte-preserving everywhere
+  else.
+
+On `session.idle` (and, with `wake: true`, on a timer) the plugin reads the session's own mailbox,
+finds `OPEN` messages it has not handled yet, and prompts the session **once** to deal with them.
+
+### Delivery is automatic when you opt in
+
+`wake: true` makes an already-idle session notice new mail. Without it, the plugin only reacts to an
+idle *transition* — which means a session that has been sitting idle all afternoon never learns
+about the message your other session just wrote.
+
+### Spawning opens the recipient's desk
+
+`spawnOnSend: true` creates a session in the recipient's project directory when you send to it, so a
+project with nothing open can still be reached. Guarded so it cannot ping-pong — see
+[Spawn on send](#spawn-on-send).
+
+## Install
+
+1. Add the plugin to your `opencode.json`:
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": [
+       ["opencode-workspace-mailbox", {
+         "wake": true,
+         "spawnOnSend": true
+       }]
+     ]
+   }
+   ```
+
+   Both flags are off by default: `wake` costs tokens while nobody is watching, and spawning creates
+   sessions on its own. Turn them on deliberately.
+
+   Do **not** set `mailboxDir` unless you deliberately want one pinned mailbox: it disables tier
+   discovery, which is the whole point of a single global config.
+
+2. If your config directory declares plugin dependencies (some setups keep a `package.json` next to
+   `opencode.json`), add the package there too:
+
+   ```powershell
+   cd C:\Users\<you>\.config\opencode
+   npm install opencode-workspace-mailbox --save
+   ```
+
+3. Restart OpenCode.
+
+Local path variant during development (no publish needed — `prepare` builds it):
+
+```powershell
+npm install file:D:\WORKSHOP\mr-wolf-rsh\tools\opencode-workspace-mailbox --save
+```
+
+```jsonc
+["D:\\WORKSHOP\\mr-wolf-rsh\\tools\\opencode-workspace-mailbox", { "wake": true }]
+```
+
+## Configuration
+
+```jsonc
+["opencode-workspace-mailbox", {
+  // Master switch. false = the plugin does nothing at all.
+  "enabled": true,
+
+  // Pin ONE mailbox directory and disable tier discovery. Leave unset normally.
+  "mailboxDir": null,
+
+  // Override the derived identity ("workspace" for a tier root, else the folder name).
+  "project": null,
+
+  // Storage backend. "file" is the MVP; the store interface is pluggable.
+  "storage": "file",
+
+  // Auto-prompts in a row without progress, then one toast instead. 0..20.
+  "maxAutoRounds": 2,
+
+  // Minimum gap between auto-prompts (and between notices).
+  "cooldownMs": 30000,
+
+  // Poll the mailbox and wake an idle session on a new message.
+  "wake": false,
+  "pollMs": 10000,
+
+  // Create a session in the recipient's directory when sending.
+  "spawnOnSend": false,
+  "spawnCooldownMs": 60000,
+  "maxSpawnsPerTurn": 1,
+
+  // Explicit recipient -> directory map for spawning. Discovery covers most trees.
+  "projectDirs": {},
+
+  // Where dedupe/round/spawn state is persisted (must stay inside the project directory).
+  "stateFile": null
+}]
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master switch. |
+| `mailboxDir` | discovered | Pin a mailbox directory; disables discovery. |
+| `project` | resolved | Explicit identity override. |
+| `storage` | `file` | Backend selector (`file` implemented). |
+| `maxAutoRounds` | `2` | Auto-prompts in a row without progress, `0..20`. |
+| `cooldownMs` | `30000` | Gap between auto-prompts and notices. |
+| `wake` | `false` | Poll and wake an idle session. |
+| `pollMs` | `10000` | Wake poll interval, `100..600000`. |
+| `spawnOnSend` | `false` | Create a session in the recipient's directory. |
+| `spawnCooldownMs` | `60000` | Gap between spawns. |
+| `maxSpawnsPerTurn` | `1` | Spawns per human turn, `0..10`. |
+| `projectDirs` | `{}` | Explicit recipient → directory map. |
+| `stateFile` | `<dir>/.atl/mailbox-state.json` | Persisted dedupe/round/spawn state. |
+
+## Tiers and identity
+
+| Tier | Folder | Reads at start | Holds |
+|---|---|---|---|
+| **Meta** | `D:\WORKSHOP` | `handoffs/workspace.md` | `workspace.md` + one file per account |
+| **Account** | `D:\WORKSHOP\mr-wolf-rsh` | `mr-wolf-rsh/handoffs/workspace.md` | `workspace.md` + one file per repo |
+| **Repo** | `.../mr-wolf-rsh/tools/opencode-workspace-mailbox` | `mr-wolf-rsh/handoffs/opencode-workspace-mailbox.md` | its own file, at the account level |
+
+Discovery rules, for a session opened in `D`:
+
+1. `project` is set in config → use it verbatim (and `mailboxDir` if set).
+2. `D` has `handoffs/` → `D` is a tier root. Parent has one too → **account**, else **meta**.
+   Identity is `workspace`; its mailbox is `D/handoffs`.
+3. Otherwise → walk up to the nearest ancestor with `handoffs/`; that is the **account**, `D` is a
+   **repo**. Identity is `D`'s folder name, kebab-cased, and the mailbox is the account's
+   `handoffs/` — so bucket layouts like `<account>/tools/<repo>` work without configuration.
+
+For this workspace:
+
+| Session opened at | Tier | Mailbox |
+|---|---|---|
+| `D:\WORKSHOP` | meta | `D:\WORKSHOP\handoffs\workspace.md` |
+| `D:\WORKSHOP\mr-wolf-rsh` | account | `D:\WORKSHOP\mr-wolf-rsh\handoffs\workspace.md` |
+| `D:\WORKSHOP\mr-wolf-rsh\tools\opencode-workspace-mailbox` | repo | `D:\WORKSHOP\mr-wolf-rsh\handoffs\opencode-workspace-mailbox.md` |
+| `D:\WORKSHOP\absolute-labs-studio\absolute-scrapers` | repo | `D:\WORKSHOP\absolute-labs-studio\handoffs\absolute-scrapers.md` |
+
+### Routing
+
+- **`to: workspace`** → this tier's own `workspace.md`.
+- **`to: <account>`** → the root tier's `<account>.md` — escalate up, or lateral between accounts.
+- **`to: <anything else>`** — a sibling or child file in this tier: lateral, or delegate down.
+
+The inbox for a tier is created on first run; an account session also creates its file at the root.
+Unknown recipients are created on first send. Reads never create files.
+
+## Mailbox format
+
+Files are `<mailboxTier>/handoffs/<project>.md`. Append-only: messages are never rewritten,
+reordered, or "tidied". The **only** permitted edit to history is the `**Status:**` line.
+
+```markdown
+### YYYY-MM-DD HH:MM — from <source> → to <recipient>
+**Status:** OPEN | DONE
+**Topic:** one-line subject
+Body — what needs attention, the question, exact paths/commits/commands.
+```
+
+`mailbox_ack` replaces the status line's content with `DONE`, so an annotated
+`**Status:** OPEN (confirm the wording)` becomes `**Status:** DONE`. Every other byte — spacing
+elsewhere, line endings, bodies — is unchanged; the tests assert that on CRLF fixtures, and it was
+verified by hand against a real 113 KB mailbox file.
+
+## Storage
+
+Mailboxes sit behind a `MailboxStore` interface:
+
+```ts
+interface MailboxStore {
+  ensure(project: string): string
+  listOpen(project: string): MailboxMessage[]
+  read(project: string): MailboxMessage[]
+  append(project: string, input: AppendInput): SendResult
+  ack(project: string, target: { hash?: string; header?: string }): AckResult
+  query(project: string, filter?: MailboxFilter): MailboxMessage[]
+}
+```
+
+`createFileStore(dir)` is the reference backend. The message format and file layout are the contract:
+a SQLite backend (atomic append, indexed OPEN-by-project, WAL concurrency) or an Engram-backed store
+only has to implement those six operations — the tools, wake path, and spawning never change.
+
+## Loop guards
+
+| Guard | Behaviour |
+|---|---|
+| Hash dedupe | One prompt per message, persisted across restarts. |
+| Own writes | Messages this plugin appended never wake anybody. |
+| Round cap | `maxAutoRounds` prompts in a row without progress, then a toast instead. |
+| Progress reset | An `mailbox_ack`, or a drained inbox, restores the budget. |
+| Cooldown | `cooldownMs` between prompts; one notice per distinct pending set. |
+| Idempotent ack | Acking an already-`DONE` message is a no-op, not an error. |
+| Spawn guards | Opt-in, one per message hash, cooldown, per-turn cap, never from a spawned session, never when a session already exists. |
+
+## How delivery decides
+
+1. **Trigger** — `session.idle`, or a `wake` poll tick for the most recently active non-busy session.
+2. **Skip** — plugin is disabled, this session was just prompted by the plugin, or the session is
+   mid-turn.
+3. **Filter** — keep `OPEN` messages whose hash is not in `prompted` and not in `ownWrites`.
+4. **Budget** — if the inbox is empty, reset the round budget; if the cap or cooldown is hit, stop
+   (surfacing a one-line toast at most once per pending set).
+5. **Dispatch** — record every hash *before* prompting, then send one prompt: load the
+   `workspace-mailbox` skill, read the file, handle the messages, ack them, reply only if a decision
+   is needed.
+
+Hashes are recorded before dispatch on purpose: a failed prompt is retried, never silently dropped.
+
+## Spawn on send
+
+With `spawnOnSend: true`, `mailbox_send` also creates a session in the recipient's directory
+(`session.create` with `query.directory`), titled `mailbox: <recipient>`.
+
+**Directory resolution**, in order:
+
+1. `projectDirs[recipient]`, if configured.
+2. `workspace` → this tier's own root directory.
+3. An account name → that account's directory under the workspace root.
+4. A sibling of the mailbox directory, or a bounded search for a nested bucket
+   (`<account>/tools/<repo>`).
+
+If nothing resolves, the send still succeeds and the tool reports why no session was created. It
+never guesses a directory.
+
+**What spawning does not do:** it creates a server-side session; it does not attach a terminal
+window. A headless session that hits a permission prompt has nobody to answer it.
+
+## Limitations
+
+- **Delivery needs a plugin instance serving the recipient directory.** With no session there, the
+  message waits in its file. `spawnOnSend` creates a session but cannot attach a TUI to it.
+- **One project per plugin instance.** Cross-project activation beyond `session.create` is out of
+  scope; identity is resolved per session, never shared.
+- **`wake` spends tokens with nobody watching**, at the pace messages arrive. Leave it off for
+  idle-only delivery.
+- **No migration of old layouts.** Pointing the plugin at a mailbox directory that still holds
+  pre-hierarchy files leaves them in place; account files appear alongside.
+- **Busy detection is event-driven.** If a runtime never emits `session.status`, the wake path can
+  queue a prompt behind an active turn instead of waiting.
+- **Message bodies are data only.** They are never executed, evaluated, or turned into commands.
+- **New recipient files are not registered in the tier's `README.md`.** The plugin writes mailboxes,
+  not documentation.
+
+---
+
+## Backlog
+
+Ideas for the future — not implemented yet.
+
+- **SQLite backend** — implement `MailboxStore` over SQLite: atomic append, an index on
+  `(project, status)`, WAL for concurrent sessions, and `query` without re-parsing files. The
+  interface and the message format already allow it.
+- **Engram backend** — reuse the persistent-memory store for teams that want mailboxes outside the
+  repo. Same six operations.
+- **`to: all` broadcast** — the protocol allows a broadcast copied into every file in a tier; today
+  `all` is treated as a normal recipient name.
+- **Migration helper** — move legacy top-level files into the tier layout with an explicit,
+  reviewable command instead of leaving them behind.
+- **Watermark** — a `since` option so a fresh install does not replay a mailbox's entire `OPEN`
+  history on first contact.
+
+---
+
+## Development
+
+```bash
+npm install
+npm test          # vitest: parser, ack byte-identity, send, paths, wake, spawn, tiers, store
+npm run typecheck # tsc --noEmit
+npm run build     # tsc -> dist/
+```
+
+## Author
+
+- **Renzo S.** — [mr-wolf-rsh](https://github.com/mr-wolf-rsh/)
+
+## Contributing
+
+All sorts of suggestions and pull requests are welcome.
+
+## License
+
+[MIT](./LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+export type MailboxConfig = {
+    mailboxDir?: string;
+    project?: string | null;
+    maxAutoRounds?: number;
+    cooldownMs?: number;
+    enabled?: boolean;
+    stateFile?: string | null;
+    wake?: boolean;
+    pollMs?: number;
+    spawnOnSend?: boolean;
+    spawnCooldownMs?: number;
+    maxSpawnsPerTurn?: number;
+    projectDirs?: Record<string, string>;
+};
+export type NormalizedConfig = {
+    mailboxDir: string;
+    project: string;
+    /** True when mailboxDir came from options (disables folder-tree discovery). */
+    explicitMailboxDir: boolean;
+    storage: "file";
+    maxAutoRounds: number;
+    cooldownMs: number;
+    enabled: boolean;
+    stateFile: string;
+    wake: boolean;
+    pollMs: number;
+    spawnOnSend: boolean;
+    spawnCooldownMs: number;
+    maxSpawnsPerTurn: number;
+    projectDirs: Record<string, string>;
+};
+export declare function normalizeConfig(options: Record<string, unknown> | undefined, directory: string): NormalizedConfig;

package/dist/config.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { assertInside, isSafeRecipient } from "./paths.js";
+function clampInt(value, def, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return def;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function nonNegativeInt(value, def) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return def;
+    return Math.max(0, Math.floor(value));
+}
+/** Turn an arbitrary directory name into a lowercase kebab-case recipient id. */
+function toKebab(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function isStrictlyInside(base, candidate) {
+    const rel = path.relative(path.resolve(base), path.resolve(candidate));
+    return rel !== "" && !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep);
+}
+export function normalizeConfig(options, directory) {
+    const opts = options ?? {};
+    const configuredMailboxDir = typeof opts.mailboxDir === "string" && opts.mailboxDir.length > 0 ? opts.mailboxDir : null;
+    const mailboxDir = path.resolve(configuredMailboxDir ?? path.join(directory, "handoffs"));
+    // Only the file backend is implemented today; the field exists so a SQLite
+    // backend can be selected later without a config-format change.
+    const storage = "file";
+    const rawProject = opts.project;
+    const configuredProject = typeof rawProject === "string" && rawProject.length > 0 ? rawProject : null;
+    // Identity is resolved per session, not per config:
+    //   explicit `project` wins; otherwise a session whose directory *contains*
+    //   the shared mailbox directory is the workspace parent, and every other
+    //   session uses its own directory name. The containment rule only applies to
+    //   an explicitly configured mailboxDir, so the per-project default
+    //   (`<directory>/handoffs`) never turns every project into the parent.
+    const project = configuredProject ??
+        (configuredMailboxDir !== null && isStrictlyInside(directory, mailboxDir)
+            ? "workspace"
+            : toKebab(path.basename(path.resolve(directory))));
+    if (!isSafeRecipient(project)) {
+        throw new Error(configuredProject !== null
+            ? `Invalid project name "${configuredProject}": must be lowercase kebab-case`
+            : `Cannot derive a valid project name from "${directory}": set the "project" plugin option`);
+    }
+    const maxAutoRounds = clampInt(opts.maxAutoRounds, 2, 0, 20);
+    const cooldownMs = nonNegativeInt(opts.cooldownMs, 30000);
+    const enabled = typeof opts.enabled === "boolean" ? opts.enabled : true;
+    const wake = typeof opts.wake === "boolean" ? opts.wake : false;
+    const pollMs = clampInt(opts.pollMs, 10000, 100, 600000);
+    const spawnOnSend = typeof opts.spawnOnSend === "boolean" ? opts.spawnOnSend : false;
+    const spawnCooldownMs = nonNegativeInt(opts.spawnCooldownMs, 60000);
+    const maxSpawnsPerTurn = clampInt(opts.maxSpawnsPerTurn, 1, 0, 10);
+    const projectDirs = {};
+    if (opts.projectDirs && typeof opts.projectDirs === "object" && !Array.isArray(opts.projectDirs)) {
+        for (const [key, value] of Object.entries(opts.projectDirs)) {
+            if (typeof value === "string" && value.length > 0 && isSafeRecipient(key)) {
+                projectDirs[key] = path.resolve(value);
+            }
+        }
+    }
+    const rawStateFile = typeof opts.stateFile === "string" && opts.stateFile.length > 0
+        ? opts.stateFile
+        : path.join(directory, ".atl", "mailbox-state.json");
+    const stateFile = assertInside(directory, rawStateFile, "stateFile");
+    return {
+        mailboxDir,
+        project,
+        explicitMailboxDir: configuredMailboxDir !== null,
+        storage,
+        maxAutoRounds,
+        cooldownMs,
+        enabled,
+        stateFile,
+        wake,
+        pollMs,
+        spawnOnSend,
+        spawnCooldownMs,
+        maxSpawnsPerTurn,
+        projectDirs,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/discovery.d.ts

@@ -0,0 +1,41 @@
+export type Tier = "meta" | "account" | "repo" | "custom";
+export type TierContext = {
+    tier: Tier;
+    /** Mailbox identity inside its own tier: "workspace" for a tier root, else the directory name. */
+    project: string;
+    /** Directory holding this tier's files: `<tierRoot>/handoffs`. */
+    mailboxDir: string;
+    /** Session directory the context was derived from. */
+    directory: string;
+    /** The account directory (account or repo tier). */
+    accountRoot?: string;
+    accountName?: string;
+    /** The workspace root directory (meta tier, or the ancestor above an account). */
+    rootDir?: string;
+    /** The root tier's handoffs directory, when one exists above this tier. */
+    rootMailboxDir?: string;
+};
+/**
+ * Derive the tier from the folder tree:
+ *
+ *   - a directory with its own `handoffs/` is a tier root: meta when nothing
+ *     above it has one, account when the parent does;
+ *   - anything else belongs to the nearest ancestor that has one (repo tier),
+ *     whatever the bucket depth (`<account>/tools/<repo>` still resolves);
+ *   - an explicit `mailboxDir` in config overrides discovery entirely.
+ */
+export declare function discoverTier(directory: string, explicit?: {
+    mailboxDir?: string;
+    project?: string;
+}): TierContext;
+export type Route = {
+    mailboxDir: string;
+    project: string;
+};
+/**
+ * Where a message addressed to `to` belongs.
+ *   - `workspace`      -> this tier's own inbox (the tier root's `workspace.md`)
+ *   - an account name  -> the root tier's `<account>.md` (escalate up / lateral between accounts)
+ *   - anything else    -> a sibling/child file in this tier (lateral / delegate down)
+ */
+export declare function routeRecipient(to: string, ctx: TierContext): Route;

package/dist/discovery.js

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+function kebab(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function hasHandoffs(dir) {
+    return existsSync(path.join(dir, "handoffs", "workspace.md")) || existsSync(path.join(dir, "handoffs"));
+}
+/**
+ * Derive the tier from the folder tree:
+ *
+ *   - a directory with its own `handoffs/` is a tier root: meta when nothing
+ *     above it has one, account when the parent does;
+ *   - anything else belongs to the nearest ancestor that has one (repo tier),
+ *     whatever the bucket depth (`<account>/tools/<repo>` still resolves);
+ *   - an explicit `mailboxDir` in config overrides discovery entirely.
+ */
+export function discoverTier(directory, explicit) {
+    const dir = path.resolve(directory);
+    if (explicit?.mailboxDir) {
+        const mailboxDir = path.resolve(explicit.mailboxDir);
+        const inside = isStrictlyInside(dir, mailboxDir);
+        return {
+            tier: "custom",
+            project: explicit.project ?? (inside ? "workspace" : kebab(path.basename(dir))),
+            mailboxDir,
+            directory: dir,
+            rootDir: inside ? path.dirname(mailboxDir) : undefined,
+            rootMailboxDir: inside ? mailboxDir : undefined,
+        };
+    }
+    if (hasHandoffs(dir)) {
+        const parent = path.dirname(dir);
+        const above = parent !== dir && hasHandoffs(parent);
+        return {
+            tier: above ? "account" : "meta",
+            project: "workspace",
+            mailboxDir: path.join(dir, "handoffs"),
+            directory: dir,
+            accountRoot: above ? dir : undefined,
+            accountName: above ? kebab(path.basename(dir)) : undefined,
+            rootDir: above ? parent : dir,
+            rootMailboxDir: path.join(above ? parent : dir, "handoffs"),
+        };
+    }
+    let cursor = dir;
+    for (;;) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        if (hasHandoffs(parent)) {
+            const grand = path.dirname(parent);
+            return {
+                tier: "repo",
+                project: kebab(path.basename(dir)),
+                mailboxDir: path.join(parent, "handoffs"),
+                directory: dir,
+                accountRoot: parent,
+                accountName: kebab(path.basename(parent)),
+                rootDir: grand,
+                rootMailboxDir: hasHandoffs(grand) ? path.join(grand, "handoffs") : undefined,
+            };
+        }
+        cursor = parent;
+    }
+    return {
+        tier: "repo",
+        project: kebab(path.basename(dir)),
+        mailboxDir: path.join(dir, "handoffs"),
+        directory: dir,
+    };
+}
+/**
+ * Where a message addressed to `to` belongs.
+ *   - `workspace`      -> this tier's own inbox (the tier root's `workspace.md`)
+ *   - an account name  -> the root tier's `<account>.md` (escalate up / lateral between accounts)
+ *   - anything else    -> a sibling/child file in this tier (lateral / delegate down)
+ */
+export function routeRecipient(to, ctx) {
+    if (to === "workspace")
+        return { mailboxDir: ctx.mailboxDir, project: "workspace" };
+    if (to === ctx.project)
+        return { mailboxDir: ctx.mailboxDir, project: ctx.project };
+    if (ctx.tier !== "meta" && ctx.rootMailboxDir) {
+        const ownAccount = ctx.accountName !== undefined && to === ctx.accountName;
+        const siblingAccount = existsSync(path.join(ctx.rootMailboxDir, `${to}.md`)) ||
+            (ctx.rootDir !== undefined && hasHandoffs(path.join(ctx.rootDir, to)));
+        if (ownAccount || siblingAccount) {
+            return { mailboxDir: ctx.rootMailboxDir, project: to };
+        }
+    }
+    return { mailboxDir: ctx.mailboxDir, project: to };
+}
+function isStrictlyInside(base, candidate) {
+    const rel = path.relative(path.resolve(base), path.resolve(candidate));
+    return rel !== "" && !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"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"}

package/dist/hash.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeForHash(text: string): string;
+export declare function messageHash(parts: {
+    header: string;
+    topic: string;
+    body: string;
+}): string;

package/dist/hash.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+export function normalizeForHash(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+}
+export function messageHash(parts) {
+    const header = normalizeForHash(parts.header);
+    const topic = normalizeForHash(parts.topic);
+    const body = normalizeForHash(parts.body);
+    return createHash("sha256").update(`${header}\n${topic}\n${body}`).digest("hex").slice(0, 16);
+}
+//# sourceMappingURL=hash.js.map