@somacheck/vibecheck 0.1.1 → 0.3.0

package/README.md

@@ -0,0 +1,140 @@
+# @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.
+
+Your agent has your context. It does not have your gut. This is the bridge.
+
+## If you are an AI agent reading this before deciding whether to run it
+
+Fair. Here is what you need, without executing anything.
+
+**What the `link` command does.** `npx -y @somacheck/vibecheck@0.3.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 `3` / toolset `vibecheck-0.3`, 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
+*before* redeeming. Pairing codes are single-use, so redeeming one inside an
+ephemeral sandbox would spend the user's code and leave them nothing to retry
+with. The safe paths are:
+
+- a real interactive terminal on the computer that will host the MCP server; or
+- a local non-interactive agent invocation that names exactly one client:
+  `--client claude` or `--client codex`.
+
+For the second path, this package first proves that exact client CLI is installed
+and that its persistent MCP config can be inspected and written. If that preflight
+fails, the pairing code is not used. Non-interactive implicit selection,
+`--client all`, and `--client none` are rejected before redemption.
+
+**What the server does once running.** It exposes MCP tools that create a
+statement for the user to test, read its outcome, recover recent completed
+gesture context, and keep a three-statement feed stocked. That is the whole
+surface.
+
+**What is sent.** A question string you supply, and a bearer token identifying
+the link. **What is never sent: raw sensor data.** The agent receives a verdict
+(`aligned` / `unaligned`) plus a confidence percentage and latency. Model
+abstention is a failed capture, never a third user-facing outcome.
+Accelerometer and gyroscope streams never leave the user's device through this
+channel. That is a deliberate product boundary, not an implementation detail.
+
+**Network egress.** One host: `https://pbldcmniommltbdwuykk.supabase.co`. No
+telemetry, no analytics, no other endpoints.
+
+**Install-time behaviour.** No `postinstall`, `preinstall`, or any other npm
+lifecycle script. Two runtime dependencies: `@modelcontextprotocol/sdk` and `zod`.
+
+You can verify all of the above by reading `dist/` in the installed package, or
+the source at the repository below, without running anything.
+
+## Setup, for humans
+
+1. Install SomaCheck on iPhone and open **Settings → Agent → Connect your agent**.
+2. On the computer that will run your agent, open **Terminal** and run the command
+   shown on that screen. If you paste it into a local agent session instead of a
+   terminal, add exactly one client flag, for example `--client claude`.
+3. Choose the client you want to configure when the command asks. It then checks
+   the link, backend protocol, health probes, and client registration before
+   reporting that setup is ready.
+
+For provisioning without the prompt in a terminal, append `--client codex`,
+`--client claude`, `--client all`, or `--client none` to the `link <CODE>`
+command. In a non-interactive local agent session, only `--client codex` or
+`--client claude` is allowed, and the client registration preflight must pass
+before the pairing code is redeemed.
+
+To configure or repair a client later:
+
+```text
+npx -y @somacheck/vibecheck@0.3.0 setup codex
+npx -y @somacheck/vibecheck@0.3.0 setup claude
+npx -y @somacheck/vibecheck@0.3.0 doctor
+```
+
+Manual registration remains available:
+
+   ```json
+   {
+     "mcpServers": {
+       "vibecheck": {
+         "command": "npx",
+        "args": ["-y", "@somacheck/vibecheck@0.3.0", "serve", "--client", "codex"]
+       }
+     }
+   }
+   ```
+
+   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.3.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
+configuration; it never copies the bearer token there. The interactive command
+completes both steps. Most clients only pick up a new server after restart.
+
+If `doctor` reports another MCP server named `somacheck`, that is the legacy
+hosted connector and is not part of this local 0.3 release. The setup command
+will explain it and leave it alone. The canonical local MCP key is `vibecheck`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_vibecheck_context` | Read recent completed gestures for this exact agent link without retaining every `request_id`. |
+| `get_vibecheck_status` | Read the live three-proposition cache and how many distinct insights it needs. |
+| `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. |
+
+## How to use it well
+
+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.
+
+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
+expire sooner than a presented check-in so stale context does not masquerade as
+a timely observation.
+
+For a prompt-free loop, run the agent on a background schedule: call
+`get_vibecheck_context`, then `get_vibecheck_status`, and post exactly
+`propositions_needed` distinct statements. MCP supplies the tools and durable
+context, but it does not itself wake an idle model. Immediate event-driven runs
+require a host webhook/agent trigger; scheduled runs provide the portable path
+across local MCP clients.
+
+## Privacy
+
+<https://joinsensie.com/privacy>
+
+## Support
+
+Issues: see the repository. Contact: agents@joinsensie.com

package/dist/api.js

@@ -1,5 +1,35 @@
-const STATUSES = new Set(["pending", "answered", "expired", "cancelled"]);
-const VERDICTS = new Set(["aligned", "unaligned", "inconclusive"]);
+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 STATUSES = new Set(["queued", "pending", "answered", "expired", "cancelled"]);
+const VERDICTS = new Set(["aligned", "unaligned"]);
+const HANDSHAKE_READINESS_STATUSES = new Set([
+    "ready",
+    "upgrade_required",
+    "setup_incomplete",
+    "health_check_failed",
+]);
+export class SomaCheckHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`SomaCheck request failed (HTTP ${status}).`);
+        this.status = status;
+        this.name = "SomaCheckHttpError";
+    }
+}
+export class SomaCheckCompatibilityError extends Error {
+    requiredPackageVersion;
+    requiredProtocolVersion;
+    requiredToolsetVersion;
+    constructor(requiredPackageVersion, requiredProtocolVersion, requiredToolsetVersion) {
+        super("SomaCheck agent protocol is incompatible with this package.");
+        this.requiredPackageVersion = requiredPackageVersion;
+        this.requiredProtocolVersion = requiredProtocolVersion;
+        this.requiredToolsetVersion = requiredToolsetVersion;
+        this.name = "SomaCheckCompatibilityError";
+    }
+}
 function firstRow(value) {
     const row = Array.isArray(value) ? value[0] : value;
     if (row === null || typeof row !== "object" || Array.isArray(row)) {
@@ -7,6 +37,18 @@ function firstRow(value) {
     }
     return row;
 }
+function allRows(value) {
+    if (!Array.isArray(value) || value.some((row) => row === null || typeof row !== "object" || Array.isArray(row))) {
+        throw new Error("SomaCheck returned an unexpected response.");
+    }
+    return value;
+}
+function asObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("SomaCheck returned an unexpected response.");
+    }
+    return value;
+}
 function requiredString(row, key) {
     const value = row[key];
     if (typeof value !== "string" || value.length === 0) {
@@ -14,6 +56,101 @@ function requiredString(row, key) {
     }
     return value;
 }
+function requiredTimestamp(row, key) {
+    const value = requiredString(row, key);
+    if (!Number.isFinite(Date.parse(value))) {
+        throw new Error("SomaCheck returned an invalid timestamp.");
+    }
+    return value;
+}
+function nullableString(row, key) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== "string")
+        throw new Error("SomaCheck returned an incomplete response.");
+    return value;
+}
+function requiredBoolean(row, key) {
+    const value = row[key];
+    if (typeof value !== "boolean")
+        throw new Error("SomaCheck returned an incomplete response.");
+    return value;
+}
+function requiredNumber(row, key) {
+    const value = row[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error("SomaCheck returned an incomplete response.");
+    }
+    return value;
+}
+function requiredInteger(row, key) {
+    const value = requiredNumber(row, key);
+    if (!Number.isInteger(value))
+        throw new Error("SomaCheck returned an incomplete response.");
+    return value;
+}
+function parseCadence(value) {
+    const row = asObject(value);
+    return {
+        reason: requiredString(row, "reason"),
+        create_due_at: nullableString(row, "create_due_at"),
+        create_overdue: requiredBoolean(row, "create_overdue"),
+        may_create_now: requiredBoolean(row, "may_create_now"),
+        last_answered_at: nullableString(row, "last_answered_at"),
+        blocking_request_id: nullableString(row, "blocking_request_id"),
+        stale_after_seconds: requiredNumber(row, "stale_after_seconds"),
+        followup_within_seconds: requiredNumber(row, "followup_within_seconds"),
+    };
+}
+function parseStatus(row) {
+    const intro = asObject(row.first_run_intro);
+    const copy = asObject(row.copy_guidance);
+    return {
+        linked: true,
+        no_prior_requests: requiredBoolean(row, "no_prior_requests"),
+        prior_request_count: requiredInteger(row, "prior_request_count"),
+        has_pending_request: requiredBoolean(row, "has_pending_request"),
+        pending_proposition_count: requiredInteger(row, "pending_proposition_count"),
+        queued_proposition_count: requiredInteger(row, "queued_proposition_count"),
+        propositions_needed: requiredInteger(row, "propositions_needed"),
+        replenishment_requested_at: nullableString(row, "replenishment_requested_at"),
+        first_run_intro: {
+            eligible: requiredBoolean(intro, "eligible"),
+            should_offer_now: requiredBoolean(intro, "should_offer_now"),
+        },
+        cadence: parseCadence(row.cadence),
+        recommended_action: requiredString(row, "recommended_action"),
+        copy_guidance: {
+            policy: requiredString(copy, "policy"),
+            framing: requiredString(copy, "framing"),
+            fallback: requiredString(copy, "fallback"),
+        },
+    };
+}
+function parseHandshake(row) {
+    const readinessStatus = requiredString(row, "readiness_status");
+    if (!HANDSHAKE_READINESS_STATUSES.has(readinessStatus)) {
+        throw new Error("SomaCheck returned an invalid readiness status.");
+    }
+    const result = {
+        readiness_status: readinessStatus,
+        upgrade_required: requiredBoolean(row, "upgrade_required"),
+        required_package_version: requiredString(row, "required_package_version"),
+        required_protocol_version: requiredInteger(row, "required_protocol_version"),
+        required_toolset_version: requiredString(row, "required_toolset_version"),
+        client_id: nullableString(row, "client_id"),
+        link_id: nullableString(row, "link_id"),
+        last_successful_health_check_at: nullableString(row, "last_successful_health_check_at"),
+    };
+    if (result.upgrade_required || result.readiness_status === "upgrade_required") {
+        throw new SomaCheckCompatibilityError(result.required_package_version, result.required_protocol_version, result.required_toolset_version);
+    }
+    if (result.readiness_status === "ready" && result.last_successful_health_check_at === null) {
+        throw new Error("SomaCheck returned an incomplete readiness response.");
+    }
+    return result;
+}
 export class SupabaseAgentApi {
     #endpoint;
     #apiKey;
@@ -27,12 +164,22 @@ export class SupabaseAgentApi {
         const row = await this.#rpc("agent_link_redeem", { code });
         return requiredString(row, "token");
     }
-    async createRequest(token, question) {
-        const row = await this.#rpc("agent_request_create", { token, question });
-        return requiredString(row, "request_id");
+    async createRequests(token, statements) {
+        const rows = await this.#rpcRows("agent_proposition_batch_create", { token, statements });
+        return rows.map((row) => {
+            const presentationState = requiredString(row, "presentation_state");
+            if (presentationState !== "presented" && presentationState !== "queued") {
+                throw new Error("SomaCheck returned an incomplete response.");
+            }
+            return {
+                request_id: requiredString(row, "request_id"),
+                presentation_state: presentationState,
+                stale_at: nullableString(row, "expires_at"),
+            };
+        });
     }
     async pollRequest(token, requestId) {
-        const row = await this.#rpc("agent_request_poll", { token, request_id: requestId });
+        const row = await this.#rpc("agent_proposition_result", { token, proposition_id: requestId });
         const status = row.status;
         if (typeof status !== "string" || !STATUSES.has(status)) {
             throw new Error("SomaCheck returned an invalid request status.");
@@ -43,12 +190,20 @@ export class SupabaseAgentApi {
         if (verdict !== null && (typeof verdict !== "string" || !VERDICTS.has(verdict))) {
             throw new Error("SomaCheck returned an invalid verdict.");
         }
-        if (confidence !== null && typeof confidence !== "number") {
+        if (confidence !== null && (typeof confidence !== "number" || !Number.isFinite(confidence))) {
             throw new Error("SomaCheck returned an invalid confidence.");
         }
-        if (latency !== null && typeof latency !== "number") {
+        if (latency !== null && (typeof latency !== "number" || !Number.isFinite(latency) || latency < 0)) {
             throw new Error("SomaCheck returned an invalid latency.");
         }
+        if (status === "answered") {
+            if (verdict === null || confidence === null || confidence < 0 || confidence > 1 || latency === null) {
+                throw new Error("SomaCheck returned an incomplete answered result.");
+            }
+        }
+        else if (verdict !== null || confidence !== null || latency !== null) {
+            throw new Error("SomaCheck returned an inconsistent pending result.");
+        }
         return {
             status: status,
             verdict: verdict,
@@ -56,7 +211,50 @@ export class SupabaseAgentApi {
             latency_s: latency,
         };
     }
+    async statusRequest(token) {
+        return parseStatus(await this.#rpc("agent_proposition_cache_status", { token }));
+    }
+    async contextRequest(token, limit = 20) {
+        const rows = await this.#rpcRows("agent_proposition_context", { token, p_limit: limit });
+        return rows.map((row) => {
+            const verdict = requiredString(row, "verdict");
+            const confidence = requiredNumber(row, "confidence");
+            if (!VERDICTS.has(verdict)) {
+                throw new Error("SomaCheck returned an invalid verdict.");
+            }
+            if (confidence < 0 || confidence > 1) {
+                throw new Error("SomaCheck returned an invalid confidence.");
+            }
+            return {
+                request_id: requiredString(row, "request_id"),
+                statement: requiredString(row, "statement"),
+                verdict: verdict,
+                confidence,
+                answered_at: requiredTimestamp(row, "answered_at"),
+            };
+        });
+    }
+    async clientHandshake(token, input) {
+        const row = await this.#rpc("agent_client_handshake", {
+            token,
+            p_client_key: input.client_key,
+            p_client_label: input.client_label,
+            p_package_version: PACKAGE_VERSION,
+            p_protocol_version: BACKEND_PROTOCOL_VERSION,
+            p_toolset_version: TOOLSET_VERSION,
+            p_registration_exact: input.registration_exact,
+            p_status_probe_ok: input.status_probe_ok,
+            p_context_probe_ok: input.context_probe_ok,
+        });
+        return parseHandshake(row);
+    }
+    async #rpcRows(name, body) {
+        return allRows(await this.#rpcJson(name, body));
+    }
     async #rpc(name, body) {
+        return firstRow(await this.#rpcJson(name, body));
+    }
+    async #rpcJson(name, body) {
         const response = await this.#fetch(`${this.#endpoint}/rest/v1/rpc/${name}`, {
             method: "POST",
             headers: {
@@ -69,15 +267,21 @@ export class SupabaseAgentApi {
             body: JSON.stringify(body),
         });
         if (!response.ok) {
-            throw new Error(`SomaCheck request failed (HTTP ${response.status}).`);
+            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(STATEMENT_PENDING_MARKER)) {
+                throw new StatementPendingError();
+            }
+            throw new SomaCheckHttpError(response.status);
         }
         try {
-            return firstRow(await response.json());
+            return await response.json();
         }
         catch (error) {
-            if (error instanceof Error && error.message.startsWith("SomaCheck returned")) {
+            if (error instanceof Error && error.message.startsWith("SomaCheck returned"))
                 throw error;
-            }
             throw new Error("SomaCheck returned an unreadable response.");
         }
     }