@somacheck/vibecheck 0.5.0 → 0.6.1

package/README.md

@@ -9,13 +9,13 @@ 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.5.0 link <CODE> --client <CLIENT>`
+**What the `link` command does.** `npx -y @somacheck/vibecheck@0.6.1 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
 connection without printing the token. Setup is not reported ready until the
 selected client has the exact pinned `vibecheck` MCP registration, the backend
-accepts protocol `4` / toolset `vibecheck-0.5`, and both status and context
+accepts protocol `5` / toolset `vibecheck-0.6`, and both status and context
 probes succeed. It contacts exactly one network host: the Supabase project below.
 
 **It will refuse unsafe sandbox linking, on purpose.** `link` checks safety
@@ -35,7 +35,9 @@ fails, the pairing code is not used. Non-interactive implicit selection,
 **What the server does once running.** It exposes MCP tools that share bounded,
 user-authorized context summaries, create a statement for the user to test,
 read its outcome, recover recent completed gesture context, and keep a
-three-statement feed stocked.
+three-statement feed stocked. Version 0.6 adds `request_vibecheck` for a
+person-approved, immediate phone check-in. That path is deliberately separate
+from the reflection feed.
 
 **What is sent.** A statement string, bounded derived context observations the
 agent explicitly shares, and a bearer token identifying the link. Tool
@@ -76,9 +78,9 @@ before the pairing code is redeemed.
 To configure or repair a client later:
 
 ```text
-npx -y @somacheck/vibecheck@0.5.0 setup codex
-npx -y @somacheck/vibecheck@0.5.0 setup claude
-npx -y @somacheck/vibecheck@0.5.0 doctor
+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
 ```
 
 Manual registration remains available:
@@ -88,13 +90,13 @@ Manual registration remains available:
      "mcpServers": {
        "vibecheck": {
          "command": "npx",
-        "args": ["-y", "@somacheck/vibecheck@0.5.0", "serve", "--client", "codex"]
+        "args": ["-y", "@somacheck/vibecheck@0.6.1", "serve", "--client", "codex"]
        }
      }
    }
    ```
 
-   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.5.0 serve --client claude`
+   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.6.1 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
@@ -114,6 +116,7 @@ will explain it and leave it alone. The canonical local MCP key is `vibecheck`.
 | `share_somacheck_context` | Share 1–20 bounded, derived, user-authorized observations; raw conversations and secrets are rejected. |
 | `post_vibecheck_statement` | Add one to three personalized statements without blocking; returns a stable `request_id` for each. |
 | `get_vibecheck_result` | Read that exact proposition once by `request_id`; returns queued, pending, or its terminal result. |
+| `request_vibecheck` | With per-ask consent, send one immediate phone vibecheck, wait boundedly for its exact answer, and retain an opaque `live:<uuid>` fallback handle. |
 
 ## How to use it well
 
@@ -123,6 +126,39 @@ prompt is **a statement for the person to test**, not a question about facts:
 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.
 
+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:
+
+> 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
+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>`
+handle; pass that handle to `get_vibecheck_result` once later. Caller
+cancellation stops result reads and preserves the backend request and
+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.
+
+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.
+
+After a completed result, explain what the signal changes in your next action.
+Never treat it as authorization or say that the person's body made the
+decision. A typed response from the person always overrides the signal.
+
+An immediate vibecheck is not proposition caching. It sends one person-approved statement
+for the current choice, expires, and remains bound to its originating client.
+The reflection feed remains asynchronous and keeps its existing three-item
+cache behavior.
+
 The agent maintains three distinct insights. SomaCheck presents one at a time;
 the other two remain cached. After a completed gesture, the next cached insight
 is promoted and the open slot is marked for replenishment automatically. Cached insights

package/dist/api.js

@@ -2,6 +2,10 @@ import { StatementPendingError, } from "./vibecheck.js";
 import { BACKEND_PROTOCOL_VERSION, PACKAGE_VERSION, TOOLSET_VERSION } from "./constants.js";
 const STATEMENT_PENDING_MARKER = "SC_VC_STATEMENT_PENDING";
 const UPGRADE_REQUIRED_MARKER = "SC_VC_UPGRADE_REQUIRED";
+const LIVE_ASK_CONFLICT_MARKER = "SC_VC_VIBECHECK_IDEMPOTENCY_CONFLICT";
+const LIVE_ASK_PENDING_MARKER = "SC_VC_VIBECHECK_PENDING";
+const LIVE_ASK_CLIENT_REQUIRED_MARKER = "SC_VC_VIBECHECK_CLIENT_REQUIRED";
+const LIVE_ASK_CLIENT_NOT_READY_MARKER = "SC_VC_VIBECHECK_CLIENT_NOT_READY";
 const STATUSES = new Set(["queued", "pending", "answered", "expired", "cancelled"]);
 const VERDICTS = new Set(["aligned", "unaligned"]);
 const HANDSHAKE_READINESS_STATUSES = new Set([
@@ -10,6 +14,9 @@ const HANDSHAKE_READINESS_STATUSES = new Set([
     "setup_incomplete",
     "health_check_failed",
 ]);
+const PUSH_STATUSES = new Set([
+    "queued", "processing", "sent", "failed", "skipped",
+]);
 const CONTEXT_CATEGORY = {
     goal: "goals_projects", project: "goals_projects",
     decision: "decisions_commitments", commitment: "decisions_commitments",
@@ -40,6 +47,24 @@ export class SomaCheckCompatibilityError extends Error {
         this.name = "SomaCheckCompatibilityError";
     }
 }
+export class SomaCheckLiveAskConflictError extends Error {
+    constructor() {
+        super("That Live Ask retry key is already bound to a different statement.");
+        this.name = "SomaCheckLiveAskConflictError";
+    }
+}
+export class SomaCheckLiveAskPendingError extends Error {
+    constructor() {
+        super("A vibecheck is already waiting for this connection.");
+        this.name = "SomaCheckLiveAskPendingError";
+    }
+}
+export class SomaCheckLiveAskClientError extends Error {
+    constructor() {
+        super("Live Ask requires an exact ready client connection.");
+        this.name = "SomaCheckLiveAskClientError";
+    }
+}
 function firstRow(value) {
     const row = Array.isArray(value) ? value[0] : value;
     if (row === null || typeof row !== "object" || Array.isArray(row)) {
@@ -155,6 +180,39 @@ export function decodeCreatedRequests(value) {
         };
     });
 }
+/** Strict decoder for agent_vibecheck_create. PostgREST wraps the
+ * set-returning function in an array. The backend intentionally uses its
+ * canonical `answered` lifecycle name; the provider-neutral adapter below
+ * maps that to the tool's clearer `completed` state. */
+export function decodeLiveVibecheckCreation(value) {
+    const row = firstRow(value);
+    const status = requiredString(row, "status");
+    if (status !== "pending" && status !== "answered" && status !== "expired" && status !== "cancelled") {
+        throw new Error("SomaCheck returned an invalid vibecheck status.");
+    }
+    if (requiredString(row, "request_kind") !== "live_ask") {
+        throw new Error("SomaCheck returned an invalid vibecheck request kind.");
+    }
+    const pushStatus = nullableString(row, "push_status");
+    if (pushStatus !== null && !PUSH_STATUSES.has(pushStatus)) {
+        throw new Error("SomaCheck returned an invalid vibecheck delivery state.");
+    }
+    return {
+        request_id: requiredString(row, "request_id"),
+        status,
+        expires_at: requiredTimestamp(row, "expires_at"),
+        idempotent_replay: requiredBoolean(row, "idempotent_replay"),
+        push_status: pushStatus,
+        cooldown_until: nullableTimestamp(row, "cooldown_until"),
+    };
+}
+function nullableTimestamp(row, key) {
+    const value = nullableString(row, key);
+    if (value !== null && !Number.isFinite(Date.parse(value))) {
+        throw new Error("SomaCheck returned an invalid timestamp.");
+    }
+    return value;
+}
 export function decodePollResponse(value) {
     const row = asObject(value);
     const status = row.status;
@@ -188,6 +246,21 @@ export function decodePollResponse(value) {
         latency_s: latency,
     };
 }
+export function decodeLiveVibecheckResult(value, expectedRequestId) {
+    const row = firstRow(value);
+    if (requiredString(row, "request_id") !== expectedRequestId) {
+        throw new Error("SomaCheck returned a mismatched vibecheck result.");
+    }
+    if (requiredString(row, "request_kind") !== "live_ask") {
+        throw new Error("SomaCheck returned an invalid vibecheck request kind.");
+    }
+    const result = decodePollResponse(row);
+    if (result.status === "queued") {
+        throw new Error("SomaCheck returned an invalid vibecheck status.");
+    }
+    requiredTimestamp(row, "expires_at");
+    return result;
+}
 export function decodeVibecheckContext(value) {
     return allRows(value).map((row) => {
         const verdict = requiredString(row, "verdict");
@@ -261,12 +334,45 @@ export class SupabaseAgentApi {
         const row = await this.#rpc("agent_link_redeem", { code });
         return requiredString(row, "token");
     }
+    async requestVibecheck(token, identity, statement, idempotencyKey, signal) {
+        if (identity.kind !== "local")
+            throw new SomaCheckLiveAskClientError();
+        const clientKey = identity.client_key;
+        const created = decodeLiveVibecheckCreation(await this.#rpcJson("agent_vibecheck_create", {
+            token,
+            statement,
+            idempotency_key: idempotencyKey,
+            client_key: clientKey,
+        }, signal));
+        const lifecycle = created.status === "answered"
+            ? await this.liveVibecheckResult(token, identity, created.request_id, signal)
+            : { status: created.status, verdict: null, confidence: null, latency_s: null };
+        return {
+            request_id: `live:${created.request_id}`,
+            state: lifecycle.status === "answered" ? "completed" : lifecycle.status,
+            verdict: lifecycle.verdict,
+            confidence: lifecycle.confidence,
+            expires_at: created.expires_at,
+            idempotent_replay: created.idempotent_replay,
+            delivery_state: created.push_status,
+            cooldown_until: created.cooldown_until,
+        };
+    }
     async createRequests(token, statements) {
         return decodeCreatedRequests(await this.#rpcJson("agent_proposition_batch_create", { token, statements }));
     }
     async pollRequest(token, requestId) {
         return decodePollResponse(await this.#rpc("agent_proposition_result", { token, proposition_id: requestId }));
     }
+    async liveVibecheckResult(token, identity, requestId, signal) {
+        if (identity.kind !== "local")
+            throw new SomaCheckLiveAskClientError();
+        return decodeLiveVibecheckResult(await this.#rpcJson("agent_vibecheck_result", {
+            token,
+            live_ask_id: requestId,
+            client_key: identity.client_key,
+        }, signal), requestId);
+    }
     async statusRequest(token) {
         return decodeVibecheckStatus(await this.#rpc("agent_proposition_cache_status", { token }));
     }
@@ -312,7 +418,7 @@ export class SupabaseAgentApi {
     async #rpc(name, body) {
         return firstRow(await this.#rpcJson(name, body));
     }
-    async #rpcJson(name, body) {
+    async #rpcJson(name, body, signal) {
         const response = await this.#fetch(`${this.#endpoint}/rest/v1/rpc/${name}`, {
             method: "POST",
             headers: {
@@ -323,12 +429,23 @@ export class SupabaseAgentApi {
                 "accept-profile": "somacheck_engine",
             },
             body: JSON.stringify(body),
+            ...(signal === undefined ? {} : { signal }),
         });
         if (!response.ok) {
             const responseBody = await response.text().catch(() => "");
             if (response.status === 426 || responseBody.includes(UPGRADE_REQUIRED_MARKER)) {
                 throw new SomaCheckCompatibilityError(null, null, null);
             }
+            if (response.status === 409 && responseBody.includes(LIVE_ASK_CONFLICT_MARKER)) {
+                throw new SomaCheckLiveAskConflictError();
+            }
+            if (response.status === 409 && responseBody.includes(LIVE_ASK_PENDING_MARKER)) {
+                throw new SomaCheckLiveAskPendingError();
+            }
+            if (responseBody.includes(LIVE_ASK_CLIENT_REQUIRED_MARKER)
+                || responseBody.includes(LIVE_ASK_CLIENT_NOT_READY_MARKER)) {
+                throw new SomaCheckLiveAskClientError();
+            }
             if (response.status === 409 || responseBody.includes(STATEMENT_PENDING_MARKER)) {
                 throw new StatementPendingError();
             }

package/dist/cli.js

@@ -182,6 +182,9 @@ async function startServer(runtimeClient) {
     const server = createVibecheckServer({
         api,
         loadToken: async () => (await readConfig(homedir(), runtimeClient ?? undefined)).token,
+        identity: runtimeClient === null
+            ? { kind: "legacy" }
+            : { kind: "local", client_key: runtimeClient },
     });
     await server.connect(new StdioServerTransport());
     if (runtimeClient !== null) {

package/dist/client-setup.js

@@ -91,6 +91,8 @@ function registrationMatches(client, stdout) {
             return false;
         }
     }
+    if (/^\s*(?:Enabled|Status):\s*(?:false|disabled|off)\s*$/im.test(stdout))
+        return false;
     const command = /^\s*Command:\s*(\S+)\s*$/im.exec(stdout)?.[1];
     const rawArgs = /^\s*Args:\s*(.*?)\s*$/im.exec(stdout)?.[1] ?? "";
     const parsedArgs = rawArgs.split(/\s+/).filter(Boolean);
@@ -117,15 +119,35 @@ function isManagedSomaCheckRegistration(client, stdout) {
         }
     }
     else {
+        if (/^\s*(?:Enabled|Status):\s*(?:false|disabled|off)\s*$/im.test(stdout))
+            return false;
         command = /^\s*Command:\s*(\S+)\s*$/im.exec(stdout)?.[1];
         args = (/^\s*Args:\s*(.*?)\s*$/im.exec(stdout)?.[1] ?? "").split(/\s+/).filter(Boolean);
     }
     if (command !== "npx")
         return false;
     const packageArgs = args.filter((arg) => arg.startsWith("@somacheck/vibecheck@"));
-    return packageArgs.length === 1
-        && /^@somacheck\/vibecheck@0\.[0-3]\.\d+$/.test(packageArgs[0])
-        && args.every((arg) => arg === "-y" || arg === "--yes" || arg === packageArgs[0]);
+    if (packageArgs.length !== 1)
+        return false;
+    const packageArg = packageArgs[0];
+    const legacyWithoutClient = /^@somacheck\/vibecheck@0\.[0-3]\.\d+$/.test(packageArg)
+        && args.every((arg) => arg === "-y" || arg === "--yes" || arg === packageArg);
+    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,
+    // 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")
+        && args.length === 5
+        && args[0] === "-y"
+        && args[1] === packageArg
+        && args[2] === "serve"
+        && args[3] === "--client"
+        && args[4] === client;
+    return previousExactClient;
 }
 export async function isClientRegistered(client, runner) {
     return (await clientRegistrationState(client, runner)) === "current";

package/dist/constants.js

@@ -2,17 +2,18 @@
 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.5.0";
+export const PACKAGE_VERSION = "0.6.1";
 export const PACKAGE_SPEC = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MCP_SERVER_NAME = "vibecheck";
 export const LEGACY_HOSTED_MCP_SERVER_NAME = "somacheck";
-export const BACKEND_PROTOCOL_VERSION = 4;
-export const TOOLSET_VERSION = "vibecheck-0.5";
+export const BACKEND_PROTOCOL_VERSION = 5;
+export const TOOLSET_VERSION = "vibecheck-0.6";
 export const TOOL_NAMES = [
     "get_vibecheck_context",
     "get_vibecheck_status",
     "share_somacheck_context",
     "post_vibecheck_statement",
     "get_vibecheck_result",
+    "request_vibecheck",
 ];
 //# sourceMappingURL=constants.js.map

package/dist/server.js

@@ -1,8 +1,28 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { StatementPendingError } from "./vibecheck.js";
-import { SomaCheckCompatibilityError, SomaCheckHttpError } from "./api.js";
+import { StatementPendingError, } from "./vibecheck.js";
+import { SomaCheckCompatibilityError, SomaCheckHttpError, SomaCheckLiveAskClientError, SomaCheckLiveAskConflictError, SomaCheckLiveAskPendingError, } from "./api.js";
 import { PACKAGE_NAME, PACKAGE_SPEC, PACKAGE_VERSION } from "./constants.js";
+const LIVE_ASK_WAIT_BUDGET_MS = 45_000;
+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,
+];
+function abortAwareSleep(milliseconds, signal) {
+    if (signal.aborted || milliseconds <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let timer;
+        const finish = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        timer = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
 const cadenceSchema = z.object({
     reason: z.string(),
     create_due_at: z.string().nullable(),
@@ -48,6 +68,28 @@ const contextItemSchema = z.object({
     answered_at: z.string().datetime({ offset: true }),
 });
 const contextSchema = { checkins: z.array(contextItemSchema) };
+const liveAskErrorCodeSchema = z.enum([
+    "link_revoked",
+    "upgrade_required",
+    "setup_required",
+    "request_conflict",
+    "vibecheck_pending",
+    "rate_limited",
+    "live_ask_unavailable",
+    "backend_unavailable",
+    "connection_failed",
+]);
+const liveAskSchema = {
+    state: z.enum(["pending", "completed", "expired", "cancelled", "error"]),
+    request_id: z.string().nullable(),
+    verdict: z.enum(["aligned", "unaligned"]).nullable(),
+    confidence: z.number().min(0).max(1).nullable(),
+    expires_at: z.string().datetime({ offset: true }).nullable(),
+    idempotent_replay: z.boolean().nullable(),
+    delivery_state: z.enum(["queued", "processing", "sent", "failed", "skipped"]).nullable(),
+    cooldown_until: z.string().datetime({ offset: true }).nullable(),
+    error_code: liveAskErrorCodeSchema.nullable(),
+};
 const agentContextTypeSchema = z.enum([
     "goal", "project", "decision", "commitment", "tension", "question",
     "blindSpot", "relationship", "situation", "change", "deadline",
@@ -69,6 +111,15 @@ const SERVER_INSTRUCTIONS = [
     "SomaCheck lets you offer the person a statement to test through a quick phone check-in.",
     "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.",
+    "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.",
+    "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.",
     "Maintain three distinct propositions drawn from your own context about this person.",
@@ -189,9 +240,9 @@ export function createVibecheckServer(dependencies) {
     });
     server.registerTool("get_vibecheck_result", {
         title: "Get Vibecheck Result",
-        description: "Read one proposition by request_id. This is a single non-blocking read: queued is cached, and pending is presented but not answered.",
+        description: "Read one exact proposition or immediate vibecheck by request_id. This is a single non-blocking read: queued is cached, and pending is not answered. Immediate vibecheck handles begin with live: and remain bound to the originating client.",
         inputSchema: {
-            request_id: z.string().min(1).describe("The request_id returned by post_vibecheck_statement."),
+            request_id: z.string().min(1).describe("The opaque request_id returned by post_vibecheck_statement or request_vibecheck."),
         },
         outputSchema: resultSchema,
         annotations: {
@@ -203,10 +254,19 @@ export function createVibecheckServer(dependencies) {
     }, async ({ request_id }) => {
         try {
             const token = await dependencies.loadToken();
-            const result = await dependencies.api.pollRequest(token, request_id);
+            const liveRequestId = parseLiveVibecheckHandle(request_id);
+            const identity = dependencies.identity ?? { kind: "legacy" };
+            if (liveRequestId !== null && identity.kind === "legacy") {
+                return failure("Could not read that vibecheck: Live Ask needs the exact ready client connection that created it. Run setup and restart the client.");
+            }
+            const result = liveRequestId === null
+                ? await dependencies.api.pollRequest(token, request_id)
+                : await dependencies.api.liveVibecheckResult(token, identity, liveRequestId);
             const structuredContent = { request_id, ...result };
             const text = result.status === "answered"
-                ? `Answered: ${Math.round((result.confidence ?? 0) * 100)}% ${result.verdict}.`
+                ? liveRequestId === null
+                    ? `Answered: ${Math.round((result.confidence ?? 0) * 100)}% ${result.verdict}.`
+                    : `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.status === "queued"
                     ? "Queued. The proposition is cached until the person advances their feed."
                     : result.status === "pending"
@@ -218,8 +278,141 @@ export function createVibecheckServer(dependencies) {
             return failureMessage("read that SomaCheck result", error);
         }
     });
+    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.",
+        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."),
+            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."),
+        },
+        outputSchema: liveAskSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ statement, idempotency_key }, extra) => {
+        const now = dependencies.liveAskWait?.now ?? (() => performance.now());
+        const budgetMs = dependencies.liveAskWait?.budgetMs ?? LIVE_ASK_WAIT_BUDGET_MS;
+        const deadline = now() + budgetMs;
+        const callAbort = new AbortController();
+        const forwardCallerAbort = () => callAbort.abort(extra.signal.reason);
+        if (extra.signal.aborted) {
+            forwardCallerAbort();
+        }
+        else {
+            extra.signal.addEventListener("abort", forwardCallerAbort, { once: true });
+        }
+        const callDeadline = setTimeout(() => callAbort.abort(new Error("Live Ask tool deadline reached.")), budgetMs);
+        try {
+            const identity = dependencies.identity ?? { kind: "legacy" };
+            if (identity.kind === "legacy") {
+                return liveAskFailure(new SomaCheckLiveAskClientError());
+            }
+            const token = await dependencies.loadToken();
+            const created = await dependencies.api.requestVibecheck(token, identity, statement.trim(), idempotency_key, callAbort.signal);
+            const result = await waitForLiveVibecheck(created, token, identity, dependencies, callAbort.signal, deadline, (attempt) => {
+                const progressToken = extra._meta?.progressToken;
+                if (progressToken === undefined)
+                    return;
+                void extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken,
+                        progress: attempt,
+                        total: LIVE_ASK_POLL_DELAYS_MS.length,
+                        message: "Waiting for the person's vibecheck signal.",
+                    },
+                }).catch(() => {
+                    // Progress is optional. A host that does not accept it must not
+                    // prevent the exact result from completing this tool call.
+                });
+            });
+            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.`
+                    : `This vibecheck is ${result.state}. Do not create another ask for the same decision.`;
+            return { content: [{ type: "text", text }], structuredContent };
+        }
+        catch (error) {
+            return liveAskFailure(error);
+        }
+        finally {
+            clearTimeout(callDeadline);
+            extra.signal.removeEventListener("abort", forwardCallerAbort);
+        }
+    });
     return server;
 }
+async function waitForLiveVibecheck(created, token, identity, dependencies, signal, deadline, progress) {
+    if (created.state !== "pending"
+        || created.delivery_state === "failed"
+        || created.delivery_state === "skipped"
+        || signal.aborted) {
+        return created;
+    }
+    const requestId = parseLiveVibecheckHandle(created.request_id);
+    if (requestId === null)
+        return created;
+    const now = dependencies.liveAskWait?.now ?? (() => performance.now());
+    const sleep = dependencies.liveAskWait?.sleep ?? abortAwareSleep;
+    for (const [index, delay] of LIVE_ASK_POLL_DELAYS_MS.entries()) {
+        const remaining = deadline - now();
+        if (signal.aborted || remaining <= 0)
+            return created;
+        await sleep(Math.min(delay, remaining), signal);
+        if (signal.aborted || now() >= deadline)
+            return created;
+        progress(index + 1);
+        if (signal.aborted)
+            return created;
+        let lifecycle;
+        const resultAbort = new AbortController();
+        const forwardCallerAbort = () => resultAbort.abort(signal.reason);
+        signal.addEventListener("abort", forwardCallerAbort, { once: true });
+        const resultTimeout = setTimeout(() => resultAbort.abort(new Error("Live Ask result deadline reached.")), Math.max(0, deadline - now()));
+        try {
+            lifecycle = await dependencies.api.liveVibecheckResult(token, identity, requestId, resultAbort.signal);
+        }
+        catch {
+            // Creation already succeeded. Keep the exact handle so a transient,
+            // cancelled, revoked, or deadline-aborted read cannot prompt a duplicate.
+            return created;
+        }
+        finally {
+            clearTimeout(resultTimeout);
+            signal.removeEventListener("abort", forwardCallerAbort);
+        }
+        if (signal.aborted)
+            return created;
+        if (lifecycle.status === "answered") {
+            return {
+                ...created,
+                state: "completed",
+                verdict: lifecycle.verdict,
+                confidence: lifecycle.confidence,
+            };
+        }
+        if (lifecycle.status === "expired" || lifecycle.status === "cancelled") {
+            return {
+                ...created,
+                state: lifecycle.status,
+                verdict: null,
+                confidence: null,
+            };
+        }
+    }
+    return created;
+}
 function summarise(status) {
     const cadence = status.cadence;
     if (status.first_run_intro.should_offer_now) {
@@ -237,6 +430,16 @@ function formatDuration(seconds) {
     const hours = seconds / 3600;
     return Number.isInteger(hours) ? `${hours}-hour` : `${Math.round(seconds / 60)}-minute`;
 }
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function parseLiveVibecheckHandle(handle) {
+    if (!handle.startsWith("live:"))
+        return null;
+    const requestId = handle.slice("live:".length);
+    if (!UUID_PATTERN.test(requestId)) {
+        throw new Error("The Live Ask request_id is malformed.");
+    }
+    return requestId;
+}
 function failure(text) {
     return {
         isError: true,
@@ -246,6 +449,62 @@ function failure(text) {
 function failureMessage(operation, error) {
     return failure(operationalFailureText(operation, error));
 }
+function liveAskFailure(error) {
+    const doctor = `Run: npx -y ${PACKAGE_SPEC} doctor`;
+    let errorCode;
+    let text;
+    if (error instanceof SomaCheckCompatibilityError) {
+        errorCode = "upgrade_required";
+        text = `Could not request a vibecheck: this package needs an upgrade before immediate vibechecks can be used. ${doctor}`;
+    }
+    else if (error instanceof SomaCheckLiveAskClientError) {
+        errorCode = "setup_required";
+        text = `Could not request a vibecheck: immediate vibechecks need an exact ready agent connection. Run the pinned serve command through setup, then restart the client. ${doctor}`;
+    }
+    else if (error instanceof SomaCheckLiveAskConflictError) {
+        errorCode = "request_conflict";
+        text = "Could not request a vibecheck: that retry key already belongs to a different statement. Use the original statement, or use a new UUID for a genuinely new ask.";
+    }
+    else if (error instanceof SomaCheckLiveAskPendingError) {
+        errorCode = "vibecheck_pending";
+        text = "Could not request a vibecheck: one is already waiting for this connection. Keep the existing request; do not re-ask or change the retry key.";
+    }
+    else if (error instanceof SomaCheckHttpError && (error.status === 401 || error.status === 403)) {
+        errorCode = "link_revoked";
+        text = `Could not request a vibecheck: this SomaCheck link was rejected or revoked. Reconnect in the app. ${doctor}`;
+    }
+    else if (error instanceof SomaCheckHttpError && error.status === 404) {
+        errorCode = "live_ask_unavailable";
+        text = `Could not request a vibecheck: immediate vibechecks are not available on this SomaCheck backend yet. ${doctor}`;
+    }
+    else if (error instanceof SomaCheckHttpError && error.status === 429) {
+        errorCode = "rate_limited";
+        text = "Could not request a vibecheck: too many vibechecks were requested recently. Wait before making a new ask; do not change the retry key for the same ask.";
+    }
+    else if (error instanceof SomaCheckHttpError && error.status >= 500) {
+        errorCode = "backend_unavailable";
+        text = `Could not request a vibecheck: the SomaCheck backend is temporarily unavailable. Retry later with the same idempotency_key. ${doctor}`;
+    }
+    else {
+        errorCode = "connection_failed";
+        text = `Could not request a vibecheck: the local link or network check failed. Retry later with the same idempotency_key. ${doctor}`;
+    }
+    return {
+        isError: true,
+        content: [{ type: "text", text }],
+        structuredContent: {
+            state: "error",
+            request_id: null,
+            verdict: null,
+            confidence: null,
+            expires_at: null,
+            idempotent_replay: null,
+            delivery_state: null,
+            cooldown_until: null,
+            error_code: errorCode,
+        },
+    };
+}
 function operationalFailureText(operation, error) {
     const doctor = `Run: npx -y ${PACKAGE_SPEC} doctor`;
     if (error instanceof SomaCheckCompatibilityError) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@somacheck/vibecheck",
-  "version": "0.5.0",
-  "description": "Ask your embodied sense for an answer through SomaCheck.",
+  "version": "0.6.1",
+  "description": "Send a consented vibecheck to SomaCheck and use the result as a signal.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sensie-app/Somacheck.git",