@somacheck/vibecheck 0.5.0 → 0.6.0

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.0 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.0 setup codex
+npx -y @somacheck/vibecheck@0.6.0 setup claude
+npx -y @somacheck/vibecheck@0.6.0 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.0", "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.0 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` | After the person accepts the exact statement, send one immediate phone vibecheck with a retry-safe UUID and return an opaque `live:<uuid>` handle. |
 
 ## How to use it well
 
@@ -123,6 +126,27 @@ 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.
 
+For a Live Ask, 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` only after they accept, with `human_confirmed: true`
+and a new UUID in `idempotency_key`. Reuse that UUID only when retrying the
+same statement. The returned `live:<uuid>` handle can be passed to
+`get_vibecheck_result` later. Each read is non-blocking; do not continuously
+poll, and do not re-ask the same decision to obtain a preferred result.
+
+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) {
+        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,
+        }));
+        const lifecycle = created.status === "answered"
+            ? await this.liveVibecheckResult(token, identity, created.request_id)
+            : { 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) {
+        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,
+        }), requestId);
+    }
     async statusRequest(token) {
         return decodeVibecheckStatus(await this.#rpc("agent_proposition_cache_status", { token }));
     }
@@ -329,6 +435,16 @@ export class SupabaseAgentApi {
             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

@@ -123,9 +123,25 @@ function isManagedSomaCheckRegistration(client, stdout) {
     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 that
+    // release. Custom wrappers, extra arguments, disabled entries, and a
+    // registration naming the other client remain user-owned.
+    const previousExactClient = /^@somacheck\/vibecheck@0\.5\.\d+$/.test(packageArg)
+        && 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.0";
 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,7 +1,7 @@
 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 cadenceSchema = z.object({
     reason: z.string(),
@@ -48,6 +48,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 +91,12 @@ 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.",
+    "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.",
+    "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 +217,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 +231,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,6 +255,46 @@ 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. First show the exact statement and call only after the person accepts. Use this only when their own felt response would help with the current choice, not for routine feed content or to judge another person. Returns a stable request_id immediately; call get_vibecheck_result later once, without continuous polling.",
+        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 agent showed the exact statement and the person accepted this one vibecheck."),
+        },
+        outputSchema: liveAskSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ statement, idempotency_key }) => {
+        try {
+            const identity = dependencies.identity ?? { kind: "legacy" };
+            if (identity.kind === "legacy") {
+                return liveAskFailure(new SomaCheckLiveAskClientError());
+            }
+            const token = await dependencies.loadToken();
+            const result = await dependencies.api.requestVibecheck(token, identity, statement.trim(), idempotency_key);
+            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 requested. Keep request_id ${result.request_id} and check it 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);
+        }
+    });
     return server;
 }
 function summarise(status) {
@@ -237,6 +314,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 +333,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.0",
+  "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",