@somacheck/vibecheck 0.6.1 → 0.6.2

package/README.md

@@ -1,7 +1,7 @@
 # @somacheck/vibecheck
 
-An MCP server that lets an AI agent ask its human a question and get back an
-answer given with a physical wrist gesture, through the SomaCheck iOS app.
+An MCP server that lets an AI agent, with a person's consent, send one statement
+for that person to test with a physical wrist gesture in the SomaCheck iOS app.
 
 Your agent has your context. It does not have your gut. This is the bridge.
 
@@ -9,7 +9,7 @@ Your agent has your context. It does not have your gut. This is the bridge.
 
 Fair. Here is what you need, without executing anything.
 
-**What the `link` command does.** `npx -y @somacheck/vibecheck@0.6.1 link <CODE> --client <CLIENT>`
+**What the `link` command does.** `npx -y @somacheck/vibecheck@0.6.2 link <CODE> --client <CLIENT>`
 exchanges a short-lived pairing code, generated inside the SomaCheck iOS app, for
 a bearer token. It writes that token to `~/.sensie/config.json` with mode `0600`,
 offers to configure supported agent clients found on the computer, and checks the
@@ -78,9 +78,9 @@ before the pairing code is redeemed.
 To configure or repair a client later:
 
 ```text
-npx -y @somacheck/vibecheck@0.6.1 setup codex
-npx -y @somacheck/vibecheck@0.6.1 setup claude
-npx -y @somacheck/vibecheck@0.6.1 doctor
+npx -y @somacheck/vibecheck@0.6.2 setup codex
+npx -y @somacheck/vibecheck@0.6.2 setup claude
+npx -y @somacheck/vibecheck@0.6.2 doctor
 ```
 
 Manual registration remains available:
@@ -90,13 +90,13 @@ Manual registration remains available:
      "mcpServers": {
        "vibecheck": {
          "command": "npx",
-        "args": ["-y", "@somacheck/vibecheck@0.6.1", "serve", "--client", "codex"]
+        "args": ["-y", "@somacheck/vibecheck@0.6.2", "serve", "--client", "codex"]
        }
      }
    }
    ```
 
-   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.6.1 serve --client claude`
+   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.6.2 serve --client claude`
 
 The link step writes only the bearer token in `~/.sensie/config.json`. The client
 setup step asks Codex or Claude to add the pinned MCP command to that client's own
@@ -107,6 +107,39 @@ If `doctor` reports another MCP server named `somacheck`, that is the legacy
 hosted connector and is separate from this local package. The setup command
 will explain it and leave it alone. The canonical local MCP key is `vibecheck`.
 
+## Teach your agent when to offer a check-in
+
+[`SKILL.md`](SKILL.md) teaches compatible agents two behaviors: act immediately
+when the person explicitly requests a vibecheck, and offer one optional
+vibecheck when work drifts, a consequential decision is imminent, or recent
+messages show multiple stress signals. It uses `request_vibecheck`, not the
+reflection-feed batch tool. It includes transcript-grounded heuristics,
+statement templates, a two-hour decline cooldown, privacy rules, and the
+requirement to treat every result as context rather than authorization.
+
+For Claude Code, add this repository as a marketplace and install the skill in
+one terminal command:
+
+```text
+claude plugin marketplace add sensie-app/Somacheck && claude plugin install vibecheck@somacheck
+```
+
+Inside Claude Code, the equivalent commands are:
+
+```text
+/plugin marketplace add sensie-app/Somacheck
+/plugin install vibecheck@somacheck
+```
+
+For agents supported by the Skills CLI:
+
+```text
+npx skills add sensie-app/Somacheck --skill vibecheck
+```
+
+The skill expects the `@somacheck/vibecheck` MCP server to already be linked as
+`vibecheck`. Installing the skill does not copy or replace the bearer token.
+
 ## Tools
 
 | Tool | What it does |
@@ -122,21 +155,33 @@ will explain it and leave it alone. The canonical local MCP key is `vibecheck`.
 
 Ask when you genuinely need a read you cannot infer — not to check in. A good
 prompt is **a statement for the person to test**, not a question about facts:
-"you are more worried about the launch than the roadmap suggests." Offer it as
-something to test, never as a claim about them. If it is wrong, their body says
-`unaligned`, and that is a useful answer rather than a failure.
+“I feel more concerned about the launch than the roadmap suggests.” Offer it as
+something to test, never as a claim about them. An `unaligned` result is another
+signal to consider; the person decides whether it matches what they notice.
 
 Setup and linking are not permission for future asks. If the person's current
-message explicitly asks you to use SomaCheck and includes the exact statement,
-that is consent for this one vibecheck; do not ask them to confirm twice.
-Otherwise, first show the exact statement and invite the person plainly:
+message explicitly asks for a SomaCheck vibecheck, that is consent for one ask.
+Use their exact statement when supplied. If they delegated the choice, select
+the most useful first-person statement from the current conversation, goal,
+decision, or tension and send it immediately—do not ask them for wording or a
+second confirmation. Remembered context may identify a general tension, but an
+agent-selected statement must not name a project, build, branch, wave, ticket,
+task status, or supposedly open/closed work. Abstract it into a present-tense
+first-person experience or choice, such as “I want to keep consolidating what is
+already in motion rather than start something new.” Preserve exact wording the
+person supplied. If meaningful context is unavailable, use the neutral fallback
+“I feel clear about what deserves my attention right now.”
+
+If their message did not explicitly request a vibecheck, first show the exact
+statement and invite the person plainly:
 
 > Want a quick vibecheck before I continue? I'll send this statement to your
 > phone; you answer with your wrist gesture, and I'll use the result as a
 > signal—not a verdict.
 
-Call `request_vibecheck` with `human_confirmed: true` and a new UUID in
-`idempotency_key` only after one of those per-ask consent paths. Reuse that UUID
+Call `request_vibecheck` with `consent_basis: "user_requested_vibecheck"` for a
+direct request or `consent_basis: "user_approved_statement"` after approval of
+agent-proposed wording, plus a new UUID in `idempotency_key`. Reuse that UUID
 only when retrying the same statement. The tool keeps the one created request
 open for a bounded wait and returns `completed` when the exact answer arrives.
 On timeout or a result-read failure it returns the same pending `live:<uuid>`
@@ -146,6 +191,24 @@ idempotency key, but the cancelled MCP transport may suppress that pending
 response. Do not continuously poll or re-ask the same decision to obtain a
 preferred result.
 
+Standard MCP cannot start a new agent turn after that bounded tool call has
+ended. The local Claude Code runtime therefore also advertises Anthropic's
+opt-in `claude/channel` capability. When Claude Code is launched with the
+SomaCheck server enabled as a channel, one local background watcher follows
+only the exact pending request. It emits one hardcoded, secret-free channel
+event when that request becomes answered, expired, or cancelled. The event
+contains the constrained lifecycle result and opaque handle, never the private
+statement or link token, and it cannot create another phone request.
+
+Claude Code channels are currently a research preview and only receive events
+while the opted-in session remains open. For local QA of this candidate, launch
+Claude Code with `--dangerously-load-development-channels server:vibecheck`.
+Production distribution requires the SomaCheck channel plugin to be accepted by
+Anthropic's channel allowlist (or explicitly allowed by an organization).
+Claude Desktop, hosted connectors, Codex, and other standard MCP hosts retain
+the bounded tool response and stable-handle fallback; this Claude-specific
+channel must never be presented as provider-neutral behavior.
+
 The 45-second whole-call deadline also covers the one create request. If that
 network request is aborted after an ambiguous commit, retry the exact same
 statement with the same `idempotency_key`; never create a replacement ask.

package/dist/client-setup.js

@@ -135,12 +135,13 @@ function isManagedSomaCheckRegistration(client, stdout) {
     if (legacyWithoutClient)
         return true;
     // 0.5 introduced the exact local runtime identity required by Live Ask.
-    // It is safe to replace only the canonical command generated by 0.5 or the
-    // exact 0.6.0 release being patched. Custom wrappers, extra arguments,
+    // It is safe to replace only the canonical command generated by 0.5 or an
+    // earlier exact 0.6 patch release. Custom wrappers, extra arguments,
     // disabled entries, later versions, and registrations naming the other
     // client remain user-owned.
     const previousExactClient = (/^@somacheck\/vibecheck@0\.5\.\d+$/.test(packageArg)
-        || packageArg === "@somacheck/vibecheck@0.6.0")
+        || packageArg === "@somacheck/vibecheck@0.6.0"
+        || packageArg === "@somacheck/vibecheck@0.6.1")
         && args.length === 5
         && args[0] === "-y"
         && args[1] === packageArg

package/dist/constants.js

@@ -2,7 +2,7 @@
 export const SUPABASE_URL = "https://pbldcmniommltbdwuykk.supabase.co";
 export const SUPABASE_PUBLISHABLE_KEY = "sb_publishable_af-lUNI2FqEcb-oGy-4uxQ_cnm6kY85";
 export const PACKAGE_NAME = "@somacheck/vibecheck";
-export const PACKAGE_VERSION = "0.6.1";
+export const PACKAGE_VERSION = "0.6.2";
 export const PACKAGE_SPEC = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MCP_SERVER_NAME = "vibecheck";
 export const LEGACY_HOSTED_MCP_SERVER_NAME = "somacheck";

package/dist/server.js

@@ -8,6 +8,9 @@ const LIVE_ASK_POLL_DELAYS_MS = [
     1_000, 1_000, 2_000, 2_000, 3_000, 3_000,
     4_000, 4_000, 5_000, 5_000, 5_000, 5_000,
 ];
+const CLAUDE_CHANNEL_POLL_INTERVAL_MS = 2_000;
+const CLAUDE_CHANNEL_MAX_WATCH_MS = 15 * 60 * 1_000;
+const CLAUDE_CHANNEL_RESULT_TIMEOUT_MS = 10_000;
 function abortAwareSleep(milliseconds, signal) {
     if (signal.aborted || milliseconds <= 0)
         return Promise.resolve();
@@ -109,16 +112,20 @@ const contextShareSchema = {
 };
 const SERVER_INSTRUCTIONS = [
     "SomaCheck lets you offer the person a statement to test through a quick phone check-in.",
+    "MANDATORY COMMAND RULE: when the current user message says 'Give me a SomaCheck vibecheck', 'Request a SomaCheck vibecheck', or otherwise explicitly asks for one, you must call request_vibecheck in that same turn after any read-only context/status calls. Do not present a draft, ask 'Want me to send this?', or wait for another yes. The request itself is one-ask consent for you to select and send the statement.",
     "Call get_vibecheck_context and get_vibecheck_status at the start of a session or background run, and call status again after a completed check-in.",
     "Treat gesture outcomes as contextual signals, never fixed facts or blanket authorization.",
     "Use request_vibecheck when a current choice would benefit from the person's own felt response; never use it to evaluate someone else.",
     "A setup or link is not blanket consent for future vibechecks.",
-    "If the person's current message explicitly tells you to request a SomaCheck vibecheck and includes the exact statement, that message is consent for that one ask; set human_confirmed to true and do not ask them to confirm twice.",
+    "If the person's current message explicitly requests a SomaCheck vibecheck, that message is consent for one ask. If they supplied exact wording, use it. Otherwise, choose one useful statement from the current conversation, goal, decision, or tension and send it immediately; do not ask them to supply wording or confirm twice.",
+    "DELEGATED SELECTION RULE: when you choose the wording, remembered context may identify a general tension but the statement itself must not name a project, build, branch, wave, ticket, task status, or supposedly open/closed work. Abstract it into a present-tense first-person experience or choice, such as 'I want to keep consolidating what is already in motion rather than start something new.' This restriction does not alter exact wording supplied by the person.",
+    "When choosing the statement, prefer the most consequential unresolved first-person decision or tension you already understand. Treat recalled project status, task lists, and old summaries as potentially stale. Never use them as a factual premise for agent-selected wording, even if they were recalled in the current turn. If context is thin, use the neutral fallback 'I feel clear about what deserves my attention right now.' Never diagnose, judge another person, or claim certainty about the user.",
     "Otherwise, first show the exact statement and ask: Want a quick vibecheck before I continue? I'll send this statement to your phone; you answer with your wrist gesture, and I'll use the result as a signal—not a verdict. Call only after the person accepts.",
     "Use at most one vibecheck per decision. Never re-ask to obtain a preferred answer.",
     "An immediate vibecheck is separate from the asynchronous reflection feed. Do not use it to replenish cached propositions.",
     "Use a fresh idempotency_key for each new vibecheck, and reuse that exact key only when retrying the same statement.",
     "request_vibecheck waits boundedly for the exact answer. If it returns completed, continue in the same turn and explain what changes. If it returns pending, retain that exact handle and read it once later; never create a replacement ask.",
+    "If request_vibecheck returns pending, never promise that you will check back on your own. Only continue automatically after an actual SomaCheck channel event arrives for that exact request.",
     "After a completed result, say what the signal changes in your next action. Never say 'your body decided'; a typed human response always overrides the signal.",
     "When you have meaningful user-authorized context, call share_somacheck_context with concise derived observations before creating propositions.",
     "Never share raw conversation text, photos, credentials, private identifiers, or diagnostic claims.",
@@ -129,7 +136,34 @@ const SERVER_INSTRUCTIONS = [
     "Do not poll continuously. Queued means the proposition is cached until the person advances their feed.",
 ].join(" ");
 export function createVibecheckServer(dependencies) {
-    const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    const supportsClaudeChannel = dependencies.identity?.kind === "local"
+        && dependencies.identity.client_key === "claude";
+    const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION }, {
+        instructions: SERVER_INSTRUCTIONS,
+        ...(supportsClaudeChannel
+            ? { capabilities: { experimental: { "claude/channel": {} } } }
+            : {}),
+    });
+    const claudeChannelWatches = new Set();
+    const claudeChannelNotified = new Set();
+    const startClaudeChannelWatch = (created, token, identity) => {
+        if (!supportsClaudeChannel || dependencies.claudeChannelWatch === false)
+            return;
+        if (created.state !== "pending"
+            || created.delivery_state === "failed"
+            || created.delivery_state === "skipped")
+            return;
+        const requestId = parseLiveVibecheckHandle(created.request_id);
+        if (requestId === null
+            || claudeChannelWatches.has(requestId)
+            || claudeChannelNotified.has(requestId))
+            return;
+        claudeChannelWatches.add(requestId);
+        void watchForClaudeChannelResult(created, token, identity, dependencies, async (notification) => {
+            claudeChannelNotified.add(requestId);
+            await server.server.notification(notification);
+        }).finally(() => claudeChannelWatches.delete(requestId));
+    };
     server.registerTool("get_vibecheck_context", {
         title: "Vibecheck Context",
         description: "Read recent completed check-ins for this linked agent, newest first. Use the outcomes as contextual signals and replenish the feed when status requests it.",
@@ -280,14 +314,14 @@ export function createVibecheckServer(dependencies) {
     });
     server.registerTool("request_vibecheck", {
         title: "Request a Vibecheck",
-        description: "Send one plain-language statement to the person's phone for a vibecheck answered with a wrist gesture. A current user command that explicitly requests SomaCheck and includes the exact statement counts as confirmation for that one ask; do not ask twice. Otherwise, first show the exact statement and call only after the person accepts. Setup or linking is not blanket consent. Use this only when their own felt response would help with the current choice, not for routine feed content or to judge another person. The call waits boundedly for the exact result and returns completed when available. A timeout returns the same stable pending request_id for one later read. Caller cancellation stops result reads without creating another request; the cancelled transport may suppress the pending response.",
+        description: "Send one plain-language statement to the person's phone for a vibecheck answered with a wrist gesture. A current user message that explicitly requests a SomaCheck vibecheck is confirmation for one ask. Use their exact wording when supplied; otherwise choose and send one present-tense first-person experience or choice immediately without asking for wording or reconfirmation. When you choose the wording, remembered context may identify only the general tension: never put a named project, build, branch, wave, ticket, task status, or supposedly open/closed work into the statement, even when recalled in the current turn. Abstract it, for example: 'I want to keep consolidating what is already in motion rather than start something new.' If context is thin, use the neutral fallback 'I feel clear about what deserves my attention right now.' Otherwise, first show the exact statement and call only after the person accepts. Setup or linking is not blanket consent. Use this only when their own felt response would help with the current choice, not for routine feed content, diagnosis, or judging another person. The call waits boundedly for the exact result and returns completed when available. A timeout returns the same stable pending request_id for one later read. Caller cancellation stops result reads without creating another request; the cancelled transport may suppress the pending response.",
         inputSchema: {
             statement: z.string().trim().min(1).max(1000)
-                .describe("One plain-language statement for the person to test; offer a signal, not a fact, diagnosis, or instruction."),
+                .describe("One plain-language statement for the person to test; offer a signal, not a fact, diagnosis, or instruction. If the agent selected the wording, it must be a present-tense first-person experience or choice and must not name remembered projects, builds, branches, waves, tickets, task status, or supposedly open/closed work. Preserve exact wording supplied by the person."),
             idempotency_key: z.string().uuid()
                 .describe("A new UUID for this logical ask. Reuse the same UUID only to retry the exact same statement; retries will not create another phone request."),
-            human_confirmed: z.literal(true)
-                .describe("Confirms the person accepted this exact vibecheck, either by explicitly requesting SomaCheck with this statement in their current message or by accepting after the agent showed it."),
+            consent_basis: z.enum(["user_requested_vibecheck", "user_approved_statement"])
+                .describe("Required one-ask consent basis. Use user_requested_vibecheck when the current message asks for a SomaCheck vibecheck, including when the agent chooses the statement; call immediately without another confirmation. Use user_approved_statement only after the agent proposed exact wording and the person accepted it."),
         },
         outputSchema: liveAskSchema,
         annotations: {
@@ -333,13 +367,14 @@ export function createVibecheckServer(dependencies) {
                     // prevent the exact result from completing this tool call.
                 });
             });
+            startClaudeChannelWatch(result, token, identity);
             const structuredContent = { ...result, error_code: null };
             const text = result.state === "completed"
                 ? `Vibecheck completed: ${Math.round((result.confidence ?? 0) * 100)}% ${result.verdict}. Treat this as a signal, say what it changes in your next action, and defer to any typed response from the person.`
                 : result.state === "pending"
                     ? result.delivery_state === "failed" || result.delivery_state === "skipped"
                         ? `Vibecheck ${result.request_id} was stored, but phone delivery is ${result.delivery_state}. It expires at ${result.expires_at}. Do not repost it or change the idempotency_key; check the phone setup before a later decision.`
-                        : `Vibecheck ${result.request_id} is still pending after a bounded wait. Keep this exact handle and check it once later with get_vibecheck_result. It expires at ${result.expires_at}; do not poll continuously or re-ask for this decision.`
+                        : `Vibecheck ${result.request_id} is still pending after a bounded wait. Keep this exact handle and check it once later with get_vibecheck_result. It expires at ${result.expires_at}; do not poll continuously, re-ask for this decision, or promise an automatic follow-up unless an actual SomaCheck channel event arrives.`
                     : `This vibecheck is ${result.state}. Do not create another ask for the same decision.`;
             return { content: [{ type: "text", text }], structuredContent };
         }
@@ -353,6 +388,76 @@ export function createVibecheckServer(dependencies) {
     });
     return server;
 }
+async function watchForClaudeChannelResult(created, token, identity, dependencies, notify) {
+    const requestId = parseLiveVibecheckHandle(created.request_id);
+    if (requestId === null || identity.kind !== "local" || identity.client_key !== "claude")
+        return;
+    const options = dependencies.claudeChannelWatch || undefined;
+    const now = options?.now ?? Date.now;
+    const sleep = options?.sleep ?? unrefSleep;
+    const interval = options?.pollIntervalMs ?? CLAUDE_CHANNEL_POLL_INTERVAL_MS;
+    const maxWatchMs = options?.maxWatchMs ?? CLAUDE_CHANNEL_MAX_WATCH_MS;
+    const parsedExpiry = created.expires_at === null ? Number.NaN : Date.parse(created.expires_at);
+    const deadline = Math.min(Number.isFinite(parsedExpiry) ? parsedExpiry : now() + maxWatchMs, now() + maxWatchMs);
+    let consecutiveReadFailures = 0;
+    while (now() < deadline) {
+        await sleep(Math.min(interval, Math.max(0, deadline - now())));
+        if (now() >= deadline)
+            return;
+        const readAbort = new AbortController();
+        const readTimeout = setTimeout(() => readAbort.abort(new Error("Claude channel result read timed out.")), CLAUDE_CHANNEL_RESULT_TIMEOUT_MS);
+        readTimeout.unref?.();
+        let lifecycle;
+        try {
+            lifecycle = await dependencies.api.liveVibecheckResult(token, identity, requestId, readAbort.signal);
+            consecutiveReadFailures = 0;
+        }
+        catch {
+            consecutiveReadFailures += 1;
+            if (consecutiveReadFailures >= 3)
+                return;
+            continue;
+        }
+        finally {
+            clearTimeout(readTimeout);
+        }
+        if (lifecycle.status === "pending")
+            continue;
+        const handle = `live:${requestId}`;
+        const content = lifecycle.status === "answered"
+            ? `A SomaCheck vibecheck requested by this Claude connection has completed. The exact result is ${lifecycle.verdict} with confidence ${formatChannelConfidence(lifecycle.confidence)}. Treat it as a signal, not a verdict. Continue the current conversation now: briefly acknowledge the signal and state what it changes in your next action. The exact opaque request handle is ${handle}. Do not request another vibecheck for this decision.`
+            : `A SomaCheck vibecheck requested by this Claude connection is now ${lifecycle.status}. The exact opaque request handle is ${handle}. Do not create a replacement request for the same decision.`;
+        try {
+            await notify({
+                method: "notifications/claude/channel",
+                params: {
+                    content,
+                    meta: {
+                        event: "vibecheck_result",
+                        request_id: handle,
+                        status: lifecycle.status,
+                    },
+                },
+            });
+        }
+        catch {
+            // Channel opt-in is client-controlled and experimental. A host that did
+            // not enable it must not crash the MCP server or cause duplicate events.
+        }
+        return;
+    }
+}
+function unrefSleep(milliseconds) {
+    if (milliseconds <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, milliseconds);
+        timer.unref?.();
+    });
+}
+function formatChannelConfidence(confidence) {
+    return confidence === null ? "unavailable" : confidence.toFixed(2);
+}
 async function waitForLiveVibecheck(created, token, identity, dependencies, signal, deadline, progress) {
     if (created.state !== "pending"
         || created.delivery_state === "failed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somacheck/vibecheck",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Send a consented vibecheck to SomaCheck and use the result as a signal.",
   "repository": {
     "type": "git",
@@ -19,7 +19,8 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
-    "test": "npm run build && node --import tsx --test test/*.test.ts && node --test test/*.test.mjs",
+    "test": "npm run build && node --import tsx --test test/*.test.ts && node --test test/*.test.mjs && npm run test:skill",
+    "test:skill": "python3 test/skill-triggers/verify.py",
     "test:release-artifacts": "bash ./verify-release-artifacts.sh",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build"