@synap-core/cli 1.12.2 → 1.13.0

package/dist/lib/wake-state.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The wake hook's memory between runs — `~/.synap/wake/<key>.json`.
+ *
+ * Claude Code runs an `asyncRewake` Stop hook as a NEW background process on
+ * every Stop, and never kills the previous one ("Each execution creates a
+ * separate background process", code.claude.com/docs/en/hooks). So two waiters
+ * for one terminal overlap whenever the person types again before the first
+ * gives up. This file keeps them honest:
+ *
+ *   - `owner`: the newest waiter's token. An older waiter sees it change and
+ *     exits quietly at its next read — the terminal has one doorbell, not two.
+ *   - `since`: the feed cursor, so the next run resumes where the last one
+ *     read (never a replay, never a gap) — the pod's `nextSince`.
+ *   - `delivered`: event ids already handed to the agent, so an older waiter
+ *     whose read was in flight and a newer one cannot both wake it for the
+ *     same event.
+ *   - `carried`: events read (and so marked read by the pod) that do not wake
+ *     — an fyi, a done, a held wake — kept until the next wake shows them.
+ *
+ * Best-effort by design: a lost write costs at most one duplicate line, and a
+ * file that cannot be read is a fresh start, never a crash in someone's hook.
+ * The read-modify-writes are unlocked: two waiters racing inside the same
+ * milliseconds can both wake the agent once.
+ *
+ * Stated limits, both from the pod's contract rather than this file:
+ *   - the pod marks a message read when it HANDS it out (there is no ack), so
+ *     a hook killed between that read and its stderr write (the session ended,
+ *     the hook's timeout) loses that one wake — the message stays in the room;
+ *   - after the first run the hook reads in CURSOR mode (`since`), which sees
+ *     owner messages written while the agent worked its turn, but not a post
+ *     whose row commits after a concurrent read already moved the cursor past
+ *     its timestamp (unread mode would; it would also drop those owner messages).
+ */
+import type { SessionFeedEvent } from "./session-feed.js";
+export interface WakeState {
+    owner?: string;
+    pid?: number;
+    since?: string | null;
+    delivered?: string[];
+    carried?: SessionFeedEvent[];
+    updatedAt?: string;
+}
+/** One file per (Claude Code conversation, focus session). */
+export declare function wakeStatePath(conversationId: string | undefined, sessionId: string): string;
+export declare function readWakeState(file: string): WakeState;
+/** Claim the doorbell: this run becomes the owner. Returns its token. */
+export declare function claimWake(file: string): string;
+export declare function isWakeOwner(file: string, owner: string): boolean;
+/** Advance the cursor (never backwards) and carry events that did not wake. */
+export declare function recordRead(file: string, p: {
+    since: string | null;
+    carry?: SessionFeedEvent[];
+}): void;
+/**
+ * Hand events to the agent: drop any already delivered (by another waiter),
+ * mark the rest delivered, and release the carried ones with them. Returns
+ * what to show; `events` empty = someone else already woke the agent for them.
+ */
+export declare function takeDelivery(file: string, p: {
+    events: SessionFeedEvent[];
+    since: string | null;
+}): {
+    events: SessionFeedEvent[];
+    carried: SessionFeedEvent[];
+};

package/dist/lib/wake-state.js

@@ -0,0 +1,122 @@
+/**
+ * The wake hook's memory between runs — `~/.synap/wake/<key>.json`.
+ *
+ * Claude Code runs an `asyncRewake` Stop hook as a NEW background process on
+ * every Stop, and never kills the previous one ("Each execution creates a
+ * separate background process", code.claude.com/docs/en/hooks). So two waiters
+ * for one terminal overlap whenever the person types again before the first
+ * gives up. This file keeps them honest:
+ *
+ *   - `owner`: the newest waiter's token. An older waiter sees it change and
+ *     exits quietly at its next read — the terminal has one doorbell, not two.
+ *   - `since`: the feed cursor, so the next run resumes where the last one
+ *     read (never a replay, never a gap) — the pod's `nextSince`.
+ *   - `delivered`: event ids already handed to the agent, so an older waiter
+ *     whose read was in flight and a newer one cannot both wake it for the
+ *     same event.
+ *   - `carried`: events read (and so marked read by the pod) that do not wake
+ *     — an fyi, a done, a held wake — kept until the next wake shows them.
+ *
+ * Best-effort by design: a lost write costs at most one duplicate line, and a
+ * file that cannot be read is a fresh start, never a crash in someone's hook.
+ * The read-modify-writes are unlocked: two waiters racing inside the same
+ * milliseconds can both wake the agent once.
+ *
+ * Stated limits, both from the pod's contract rather than this file:
+ *   - the pod marks a message read when it HANDS it out (there is no ack), so
+ *     a hook killed between that read and its stderr write (the session ended,
+ *     the hook's timeout) loses that one wake — the message stays in the room;
+ *   - after the first run the hook reads in CURSOR mode (`since`), which sees
+ *     owner messages written while the agent worked its turn, but not a post
+ *     whose row commits after a concurrent read already moved the cursor past
+ *     its timestamp (unread mode would; it would also drop those owner messages).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { writeFileAtomic } from "./atomic-file.js";
+/** Ids remembered as delivered (the newest win). */
+const DELIVERED_MAX = 200;
+/** Events carried to the next wake (the newest win). */
+const CARRIED_MAX = 20;
+function wakeDir() {
+    return path.join(os.homedir(), ".synap", "wake");
+}
+/** One file per (Claude Code conversation, focus session). */
+export function wakeStatePath(conversationId, sessionId) {
+    const safe = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(wakeDir(), `${safe(conversationId ?? "terminal")}__${safe(sessionId)}.json`);
+}
+export function readWakeState(file) {
+    try {
+        const v = JSON.parse(fs.readFileSync(file, "utf8"));
+        return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeWakeState(file, state) {
+    try {
+        writeFileAtomic(file, JSON.stringify({ ...state, updatedAt: new Date().toISOString() }, null, 2) + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* best-effort — see the header */
+    }
+}
+/** The later of two millisecond ISO cursors (they compare as strings). */
+function laterCursor(a, b) {
+    if (!a)
+        return b ?? null;
+    if (!b)
+        return a;
+    return a > b ? a : b;
+}
+/** Claim the doorbell: this run becomes the owner. Returns its token. */
+export function claimWake(file) {
+    const owner = randomBytes(8).toString("hex");
+    writeWakeState(file, { ...readWakeState(file), owner, pid: process.pid });
+    return owner;
+}
+export function isWakeOwner(file, owner) {
+    return readWakeState(file).owner === owner;
+}
+/** Advance the cursor (never backwards) and carry events that did not wake. */
+export function recordRead(file, p) {
+    const s = readWakeState(file);
+    const delivered = new Set(s.delivered ?? []);
+    const carried = [...(s.carried ?? [])];
+    for (const e of p.carry ?? []) {
+        if (!delivered.has(e.id) && !carried.some((c) => c.id === e.id))
+            carried.push(e);
+    }
+    writeWakeState(file, {
+        ...s,
+        since: laterCursor(s.since, p.since),
+        carried: carried.slice(-CARRIED_MAX),
+    });
+}
+/**
+ * Hand events to the agent: drop any already delivered (by another waiter),
+ * mark the rest delivered, and release the carried ones with them. Returns
+ * what to show; `events` empty = someone else already woke the agent for them.
+ */
+export function takeDelivery(file, p) {
+    const s = readWakeState(file);
+    const delivered = new Set(s.delivered ?? []);
+    const events = p.events.filter((e) => !delivered.has(e.id));
+    const carried = events.length > 0 ? (s.carried ?? []).filter((e) => !delivered.has(e.id)) : [];
+    for (const e of [...events, ...carried])
+        delivered.add(e.id);
+    writeWakeState(file, {
+        ...s,
+        since: laterCursor(s.since, p.since),
+        delivered: [...delivered].slice(-DELIVERED_MAX),
+        carried: events.length > 0 ? [] : s.carried,
+    });
+    return { events, carried: carried.filter((c) => !events.some((e) => e.id === c.id)) };
+}
+//# sourceMappingURL=wake-state.js.map

package/dist/lib/wake-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-state.js","sourceRoot":"","sources":["../../src/lib/wake-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,oDAAoD;AACpD,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,wDAAwD;AACxD,MAAM,WAAW,GAAG,EAAE,CAAC;AAWvB,SAAS,OAAO;IACd,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,cAAkC,EAAE,SAAiB;IACjF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,cAAc,IAAI,UAAU,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;QAC/D,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAgB;IACpD,IAAI,CAAC;QACH,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;YACvG,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;IACpC,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,SAAS,WAAW,CAAC,CAA4B,EAAE,CAA4B;IAC7E,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,IAAI,IAAI,CAAC;IACzB,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7C,cAAc,CAAC,IAAI,EAAE,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC;AAC7C,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,CAAuD;IAC9F,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,cAAc,CAAC,IAAI,EAAE;QACnB,GAAG,CAAC;QACJ,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC;KACrC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,CAAuD;IAEvD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,cAAc,CAAC,IAAI,EAAE;QACnB,GAAG,CAAC;QACJ,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC;QACpC,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC;QAC/C,OAAO,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;KAC5C,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACxF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/cli",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Connect any AI agent (Claude Code, Codex, Cursor and more) to your own Synap data pod: shared memory, structured data and human-approved changes.",
   "type": "module",
   "bin": {
@@ -13,10 +13,13 @@
     "prepublishOnly": "npm run sync-skills && npm run build",
     "postbuild": "chmod +x dist/index.js",
     "test": "vitest run",
-    "verify-artifact": "node scripts/verify-artifact.mjs"
+    "verify-artifact": "node scripts/verify-artifact.mjs",
+    "docs:cli": "node scripts/gen-cli-reference.mjs",
+    "docs:cli:check": "node scripts/gen-cli-reference.mjs --check"
   },
   "dependencies": {
     "@synap-core/hub-rest-client": "^1.1.1",
+    "@synap-core/types": "^1.12.1",
     "@synap-core/workspace-templates": ">=0.12.0 <1.0.0",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",

package/skills/README.md

@@ -71,7 +71,7 @@ Each skill is portable and works unchanged in:
 - **Any agent that reads skill folders** — drop into its skill directory; env vars pick up the pod URL and key
 - **Claude Code** — install to `~/.claude/skills/synap/`
 - **Claude Desktop** — does NOT read local skill folders. Skills in Claude Desktop sync from claude.ai — upload the three skill directories there (Settings → Skills → Upload). Claude Desktop CAN still use the pod via an MCP bridge — see `synap-cli/src/lib/targets.ts` `installClaudeDesktop` for the stdio-bridge config.
-- **Raycast** — the Raycast extension is a separate package with its own tool bindings; it reads these skills as context
+- **Raycast** — Raycast AI connects to the pod's `/mcp` as an HTTP MCP server (`synap connect --target=raycast`) and reads these skills through `synap_load_skill`, like any MCP client
 
 The install metadata (required env, capabilities) is namespaced under `metadata.synap`, so consumers that don't recognize it ignore it cleanly.
 

package/skills/agent-os/SKILL.md

@@ -6,7 +6,7 @@ description: >
   my company", "launch agent OS", "build my company OS", "onboard my company",
   "add a Marketing workspace", "this project doesn't have a CRM". NOT for a
   lasting goal a project pursues (grow the newsletter, the build) — that is a
-  track (synap_start_track), not a workspace. Find existing
+  goal (synap_start_track), not a workspace. Find existing
   workspace → marketplace template → confirm → packages/apply. NOT the skill
   for "the user stated an intent, what graph should exist" — that conductor is
   system/synap/from-intent (orient, questions, extend-first, then load THIS
@@ -179,7 +179,7 @@ For each domain slug, apply the template's `PackageDefinition`. If you have a
 stamps `project --uses--> workspace` as an INDEX** of domains this engagement
 runs through — not an ACL, and not a nested project. Seed entities still file
 via `belongs_to_project`. **Do not invent a child/nested project** for "the
-Marketing half" — that index edge is enough; a lasting goal is a track, a unit of
+Marketing half" — that index edge is enough; a lasting goal is a goal (a track), a unit of
 work is a session (below).
 
 Templates come from `@synap-core/workspace-templates` (shared by CLI, CP
@@ -262,22 +262,22 @@ skill for the exact sequence.)
 the **<project>** project when one exists, otherwise pod-wide. Then: "I've
 onboarded CRM (pipeline + 4 accounts). Want to onboard the others now, or later?"
 
-## Goals → tracks; "sub-project", blockers → sessions (never nested projects)
+## Goals (tracks); "sub-project", blockers → sessions (never nested projects)
 
 There are **no nested projects**, and a workspace never stands for a goal or a method.
 
 - **A lasting goal the project pursues** ("grow the newsletter", "the
-  build") is a **track**: `synap_list_tracks` → none? `synap_start_track`
+  build") is a **goal** (a _track_ in tool names; say "goal" to the person): `synap_list_tracks` → none? `synap_start_track`
   (`name`, `direction`; no method, no stages). Work in it = `synap_start_session`
   with `trackId`. A repeatable way to do that work is a playbook a session or
-  worker follows (`work-model`). Installing a pack does not start its tracks —
+  worker follows (`work-model`). Installing a pack does not start its goals —
   start each one.
 - **"Sub-project", "blocked on X", one bounded piece of work** is a
   **session**: `synap_start_session` with `projectId` and a clear `goal`, plus
-  `trackId` when it belongs to a track. Decompose with `parentSessionId` and/or
+  `trackId` when it belongs to a goal. Decompose with `parentSessionId` and/or
   `blockedBySessionIds` (edges `spawned_from` / `blocked_by`).
 
-Keep the project as the long-lived commitment; tracks are its lasting goals;
+Keep the project as the long-lived commitment; goals (tracks) are what it pursues;
 sessions are the short work.
 
 ## Adding ONE domain to an existing project (the common in-conversation case)
@@ -286,7 +286,7 @@ You don't only run this for whole-company setup. The frequent case: you're
 working inside a project and notice it's **missing an operational domain it
 needs** — new kinds of things must be recorded that no workspace owns (see the
 "notice a missing method or domain" reflex in the core `synap` skill; a missing
-_goal_ is a track, not this loop) —
+_goal_ is `synap_start_track`, not this loop) —
 you're logging leads but there's no CRM, or drafting posts with no Content OS to hold them. Offer it
 in one line; if the user says yes, run a **trimmed Loop 1** for that single
 domain: