@stelis/say-ur-intent 0.0.2 → 0.0.4

package/dist/runtime/reviewServerAcquire.js

@@ -1,75 +1,88 @@
+const DEFAULT_REACQUIRE_INTERVAL_MS = 3000;
 function errorCode(error) {
     return typeof error === "object" && error !== null
         ? error.code
         : undefined;
 }
-/**
- * Bind the review server to its fixed port, taking the port over from a previous
- * instance of our own review server if necessary.
- *
- * Safety: the holder is positively identified over loopback before any signal is
- * sent. A process that is not our review server is never signalled; a same-name
- * instance owned by another OS user surfaces a clear error rather than a kill.
- * The port is never silently reassigned, so the wallet autoconnect origin stays
- * stable.
- */
-export async function startReviewServerWithTakeover(start, port, deps) {
+// Bind the port: returns the server on success, undefined when the port is already
+// in use, and rethrows any other (non-EADDRINUSE) startup error.
+async function tryStart(start, port) {
     try {
         return await start(port);
     }
     catch (error) {
-        if (errorCode(error) !== "EADDRINUSE") {
-            throw error;
-        }
-        const holder = await deps.probeIdentity(port);
-        if (!holder || holder.service !== deps.serviceName) {
-            throw new Error(`Review server port ${port} is already in use by a process that is not a ${deps.serviceName} review server. ` +
-                `Set SAY_UR_INTENT_REVIEW_PORT to a free port. The port is not reassigned automatically so the wallet autoconnect origin stays stable.`);
+        if (errorCode(error) === "EADDRINUSE") {
+            return undefined;
         }
-        if (holder.pid === deps.currentPid) {
-            // We appear to hold the port ourselves yet cannot bind it. Never signal
-            // our own process; surface the original bind error.
-            throw error;
-        }
-        deps.logger.info("review port held by a previous say-ur-intent instance; taking it over", {
-            port,
-            previousPid: holder.pid
-        });
-        const terminated = deps.terminate(holder.pid);
-        if (!terminated.ok) {
-            if (terminated.reason === "no_permission") {
-                throw new Error(`Review server port ${port} is held by a ${deps.serviceName} instance owned by another OS user; cannot take it over. ` +
-                    `Set SAY_UR_INTENT_REVIEW_PORT to a free port for this client.`);
+        throw error;
+    }
+}
+/**
+ * Bind the review server to its fixed port, or defer to a healthy peer already
+ * serving it.
+ *
+ * - Port free → bind and own the single review origin.
+ * - Port held by a separate healthy instance of our review server → defer (run no
+ *   local server; the peer serves the shared database for every client) and watch for
+ *   the owner to exit, then take the origin over. No process is ever signalled.
+ * - Port held by anything else (foreign, no identity answer, or our own pid) → clear
+ *   error; the origin is never silently reassigned.
+ */
+export async function startOrDeferReviewServer(start, port, deps) {
+    const owned = await tryStart(start, port);
+    if (owned) {
+        deps.logger.info("review server bound; owning the review origin", { port });
+        return { deferred: false, close: () => owned.close() };
+    }
+    const holder = await deps.probeIdentity(port);
+    if (!holder || holder.service !== deps.serviceName || holder.pid === deps.currentPid) {
+        throw new Error(`Review server port ${port} is already in use by a process that is not a separate ${deps.serviceName} review server. ` +
+            `Set SAY_UR_INTENT_REVIEW_PORT to a free port. The port is not reassigned automatically so the wallet autoconnect origin stays stable.`);
+    }
+    deps.logger.info("review port owned by a healthy peer; deferring and watching for takeover", {
+        port,
+        ownerPid: holder.pid,
+        ...(holder.version ? { ownerVersion: holder.version } : {})
+    });
+    const reacquireIntervalMs = deps.reacquireIntervalMs ?? DEFAULT_REACQUIRE_INTERVAL_MS;
+    let stopped = false;
+    let acquired;
+    const watch = (async () => {
+        while (!stopped && !acquired) {
+            await deps.delay(reacquireIntervalMs);
+            if (stopped || acquired) {
+                break;
             }
-            if (terminated.reason === "error") {
-                throw new Error(`Failed to stop the ${deps.serviceName} instance holding review port ${port}: ${terminated.message ?? "unknown error"}.`);
+            const next = await tryStart(start, port);
+            if (!next) {
+                continue; // a peer still owns the port; keep deferring
             }
-            // not_found: the holder already exited between probe and signal; fall
-            // through and rebind.
-        }
-        const waitForReleaseMs = deps.waitForReleaseMs ?? 3000;
-        const pollIntervalMs = deps.pollIntervalMs ?? 100;
-        const attempts = Math.max(1, Math.ceil(waitForReleaseMs / pollIntervalMs));
-        for (let attempt = 0; attempt < attempts; attempt++) {
-            await deps.delay(pollIntervalMs);
-            try {
-                return await start(port);
+            if (stopped) {
+                await next.close();
+                break;
             }
-            catch (retryError) {
-                if (errorCode(retryError) !== "EADDRINUSE") {
-                    throw retryError;
-                }
+            acquired = next;
+            deps.logger.info("acquired review port after the previous owner exited", { port });
+        }
+    })();
+    watch.catch(() => undefined);
+    return {
+        deferred: true,
+        close: async () => {
+            // Stop watching; the loop's stopped-check closes any bind that lands in-flight,
+            // so we never await the (possibly mid-delay) watch loop here.
+            stopped = true;
+            if (acquired) {
+                await acquired.close();
             }
         }
-        throw new Error(`Review server port ${port} did not become free after stopping the previous ${deps.serviceName} instance (pid ${holder.pid}). ` +
-            `Set SAY_UR_INTENT_REVIEW_PORT to a free port.`);
-    }
+    };
 }
 /**
- * Ask whatever is listening on the loopback review port to identify itself. Only
- * our own review server answers `/__identity`; any other process either returns
- * something else or does not answer, and we report it as "not ours" so the
- * caller never signals it.
+ * Ask whatever is listening on the loopback review port to identify itself. Only our
+ * own review server answers `/__identity`; any other process either returns something
+ * else or does not answer, and we report it as "not ours" so the caller never defers
+ * to it.
  */
 export async function probeReviewServerIdentity(port, host = "127.0.0.1", timeoutMs = 1000) {
     try {
@@ -100,29 +113,3 @@ export async function probeReviewServerIdentity(port, host = "127.0.0.1", timeou
         return null;
     }
 }
-/**
- * Gracefully signal a same-user process. SIGTERM lets the previous instance run
- * its own shutdown handler (close the review server and database, then exit).
- * Killing another OS user's process fails with EPERM, which we report instead of
- * escalating.
- */
-export function terminateProcessByPid(pid) {
-    try {
-        process.kill(pid, "SIGTERM");
-        return { ok: true };
-    }
-    catch (error) {
-        const code = errorCode(error);
-        if (code === "ESRCH") {
-            return { ok: false, reason: "not_found" };
-        }
-        if (code === "EPERM") {
-            return { ok: false, reason: "no_permission" };
-        }
-        return {
-            ok: false,
-            reason: "error",
-            message: error instanceof Error ? error.message : String(error)
-        };
-    }
-}

package/dist/runtime/smokeMainnetRead.js

@@ -9,11 +9,10 @@ import { validateSupportedAdapterLifecycle } from "../adapters/adapterLifecycleV
 import { SqliteActivityStore } from "../core/activity/sqliteActivityStore.js";
 import { TransactionActivityService } from "../core/activity/transactionActivityService.js";
 import { createSuiReadService } from "../core/read/readService.js";
-import { InMemorySessionStore } from "../core/session/sessionStore.js";
+import { LocalSessionStore } from "../core/session/sessionStore.js";
 import { createMcpServer } from "../mcp/server.js";
 import { TOOL_NAMES } from "../mcp/toolNames.js";
 import { createReviewHttpServer } from "../review-server/server.js";
-import { InMemoryLocalTransactionMaterialStore } from "../core/session/transactionMaterialStore.js";
 import { buildSupportedReviewAdapters } from "../adapters/reviewAdapters.js";
 import { createDeepbookSwapTransactionMaterialDigestProducer, createDeepbookSwapTransactionMaterialProducer } from "../adapters/deepbook/deepbookTransactionMaterialProducer.js";
 import { createDeepbookSwapHumanReadableReviewProducer } from "../adapters/deepbook/deepbookHumanReviewProducer.js";
@@ -121,11 +120,15 @@ async function main() {
             chainIdentifier,
             coinMetadataCache: activityStore.createCoinMetadataCache()
         });
-        const transactionMaterialStore = new InMemoryLocalTransactionMaterialStore();
-        const sessions = new InMemorySessionStore({
+        const transactionMaterialStore = activityStore.createTransactionMaterialStore();
+        const sessions = new LocalSessionStore({
             activityStore,
             logger,
-            validateAdapterLifecycle: validateSupportedAdapterLifecycle
+            validateAdapterLifecycle: validateSupportedAdapterLifecycle,
+            sessions: activityStore.createSessionRecordStore(),
+            artifacts: activityStore.createPrivateReviewArtifactStore(),
+            walletIdentityStore: activityStore.createWalletIdentityRecordStore(),
+            settingsStore: activityStore.createSettingsRecordStore()
         });
         reviewServer = await createReviewHttpServer({
             host: config.reviewHost,

package/dist/runtime/start.js

@@ -15,13 +15,12 @@ import { createSuiReadService } from "../core/read/readService.js";
 import { createTransactionObjectOwnershipProducer } from "../core/action/transactionObjectOwnershipProducer.js";
 import { createReviewTimeSimulationProducer } from "../core/action/reviewTimeSimulationEvidence.js";
 import { producePtbVisualizationArtifact } from "../core/action/ptbVisualizationProducer.js";
-import { InMemoryLocalTransactionMaterialStore } from "../core/session/transactionMaterialStore.js";
-import { InMemorySessionStore } from "../core/session/sessionStore.js";
+import { LocalSessionStore } from "../core/session/sessionStore.js";
 import { createMcpServer, startMcp } from "../mcp/server.js";
 import { SERVER_NAME, SERVER_NETWORK, SERVER_VERSION } from "../mcp/serverInfo.js";
 import { createReviewHttpServer } from "../review-server/server.js";
 import { DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_URL, composeRuntimeConfig, loadBootConfig } from "./config.js";
-import { probeReviewServerIdentity, startReviewServerWithTakeover, terminateProcessByPid } from "./reviewServerAcquire.js";
+import { probeReviewServerIdentity, startOrDeferReviewServer } from "./reviewServerAcquire.js";
 import { RuntimeLocalSettingsService } from "./localSettingsService.js";
 import { createStderrLogger } from "./logger.js";
 import { SuiEndpointError, verifyMainnetGraphqlEndpoint, verifyMainnetGrpcEndpoint } from "./suiEndpoint.js";
@@ -81,12 +80,16 @@ async function main() {
                 });
             }
         });
-        const transactionMaterialStore = new InMemoryLocalTransactionMaterialStore();
-        const sessions = new InMemorySessionStore({
+        const transactionMaterialStore = store.createTransactionMaterialStore();
+        const sessions = new LocalSessionStore({
             activityStore: store,
             transactionMaterialStore,
             logger,
-            validateAdapterLifecycle: validateSupportedAdapterLifecycle
+            validateAdapterLifecycle: validateSupportedAdapterLifecycle,
+            sessions: store.createSessionRecordStore(),
+            artifacts: store.createPrivateReviewArtifactStore(),
+            walletIdentityStore: store.createWalletIdentityRecordStore(),
+            settingsStore: store.createSettingsRecordStore()
         });
         const readService = createSuiReadService({
             client: suiClient,
@@ -169,22 +172,19 @@ async function main() {
                 network: SERVER_NETWORK
             }
         });
-        // The review origin is a single-port singleton: the newest instance takes
-        // the fixed port over from a previous instance of our own review server so
-        // the most recently started client owns the one wallet-autoconnect origin.
-        const reviewServer = await startReviewServerWithTakeover((port) => reviewServerFactory.start(port), config.reviewPort, {
+        // The review origin is a single-port singleton shared through the local database:
+        // whichever process owns the fixed port serves every client. A second instance
+        // defers to a healthy peer (no signals, no port war) and takes the origin over
+        // only if that peer exits.
+        const reviewServer = await startOrDeferReviewServer((port) => reviewServerFactory.start(port), config.reviewPort, {
             probeIdentity: (probePort) => probeReviewServerIdentity(probePort, config.reviewHost),
-            terminate: terminateProcessByPid,
             delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
             currentPid: process.pid,
             serviceName: SERVER_NAME,
             logger
         });
         reviewServerForCleanup = reviewServer;
-        logger.info("review server started", {
-            host: reviewServer.host,
-            port: reviewServer.port
-        });
+        logger.info(reviewServer.deferred ? "review server deferring to a healthy peer on the shared origin" : "review server started", { host: config.reviewHost, port: config.reviewPort, deferred: reviewServer.deferred });
         let shuttingDown = false;
         const shutdown = async (signal) => {
             logger.info("shutdown requested", { signal });
@@ -236,7 +236,7 @@ async function main() {
             promptSurfaces: ADAPTER_PROMPT_SURFACES,
             sessions,
             activityStore: store,
-            reviewBaseUrl: `http://${reviewServer.host}:${reviewServer.port}`,
+            reviewBaseUrl: `http://${config.reviewHost}:${config.reviewPort}`,
             readService,
             transactionActivityService: new TransactionActivityService({
                 activityStore: store,

package/docs/FRONTEND_POLICY.md

@@ -139,7 +139,12 @@ wallet review contract, a connected wallet whose account equals the reviewed
 account, and a successful digest-gated handoff. The signing step shows no wallet picker:
 dapp-kit autoconnect restores the wallet recorded for the active account on the
 fixed-port origin, and the sign action stays gated on the connected account
-matching the reviewed account. While a handoff is outstanding the server locks the session
+matching the reviewed account. When autoconnect cannot establish a connection -
+for example after a reload or in a new tab, or for a hardware signer whose
+device session is not restored automatically - the signing step may offer a
+targeted reconnect for the one recorded wallet. That reconnect is not a wallet
+picker: it resumes the recorded wallet's signer session, and the sign action
+stays gated on the connected account matching the reviewed account. While a handoff is outstanding the server locks the session
 (state recomputes are refused) and the page shows a signing-in-progress state
 whose only action is cancel. Other states render:
 
@@ -210,7 +215,7 @@ Wallet and review screens must be keyboard reachable and screen-reader labeled.
 
 Native push notifications are out of scope. A frontend may use low-authority browser affordances such as document title changes for off-tab terminal results, but only after server status changes.
 
-Each session URL represents one independent tab surface. Cross-tab state sharing is out of scope unless a shared local store is explicitly designed.
+Each session URL represents one independent tab surface. Cross-tab state sharing is out of scope unless a shared local store is explicitly designed. That shared local store is now explicitly designed — the shared SQLite database (see docs/LOCAL_DB_ARCHITECTURE.md) — so live review and session state is shared across local clients through it, while the frontend still does not share state directly between browser tabs.
 
 ## Out Of Scope
 

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Local DB Architecture
 
-Say Ur Intent uses a local SQLite database for durable product state that must survive MCP server restarts. The database stores account read context, Say Ur Intent review activity evidence, and user-requested bounded Sui activity facts. It is not a custody store, wallet authorization store, background indexer, complete wallet-history store, or raw transaction archive.
+Say Ur Intent uses a local SQLite database for durable product state that must survive MCP server restarts. The database stores account read context, Say Ur Intent review activity evidence, live review and session state shared across local AI clients, and user-requested bounded Sui activity facts. It is not a custody store, wallet authorization store, background indexer, complete wallet-history store, or raw transaction archive.
 
 This document is for maintainers and contributors who change local state, import/export behavior, activity queries, or review evidence storage. Product users normally need only the README and `docs/MCP_SETUP.md`.
 
@@ -53,6 +53,15 @@ WAL mode can create companion files next to the main database, such as `say-ur-i
 - `local_settings`: allowlisted local settings. The current key set is `suiGrpcUrl` and `suiGraphqlUrl`, stored as JSON-encoded text and applied after restart.
 - `coin_metadata_cache`: account-independent positive cache for Sui coin metadata used only to format wallet balance display amounts. Rows are keyed by normalized coin type and verified mainnet chain identifier, expire after 24 hours, and are excluded from local data export/import. Read or write failures for this cache block affected wallet unit reads with `metadata_cache_unavailable`; they are not reported as unavailable token decimals.
 
+The following live session tables hold runtime session state in the shared database so any one review server can serve a session another client created (see [Shared single-origin review server](#shared-single-origin-review-server)):
+
+- `live_review_sessions`: the live review session record — status, bound account, the pending wallet-handoff lock, the plan / review-state / execution-result JSON, and timestamps — keyed by session id.
+- `live_private_review_artifacts`: per-session private review evidence (the transaction-material handle, its digest commitment, and derived evidence), cascade-deleted with its review session.
+- `live_transaction_materials`: locally built unsigned transaction bytes stored as a BLOB behind a redacted handle, with a TTL; deleted on signing, terminal result, or expiry.
+- `live_wallet_identity_sessions` and `live_settings_sessions`: the short-lived wallet-identity and settings capture sessions, stored as validated JSON keyed by session id.
+
+These live tables are distinct from the append-only review evidence tables above: the evidence tables remain the durable activity/audit record, while the live tables hold the in-flight session state that the review server serves.
+
 Database columns use snake_case. MCP and HTTP JSON fields use camelCase, so the database `review_session_id` column stores the same review-session identity exposed as `reviewSessionId` in API responses.
 
 Table relationships:
@@ -72,6 +81,20 @@ Logical local data reset is the local settings page action that clears stored pr
 
 Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. There is no background expiry worker.
 
+## Shared single-origin review server
+
+All live session state lives in this one shared database, so multiple local AI clients (for example Claude and Codex running at the same time) share it. Exactly one process binds the fixed review port and serves every client's review pages from the shared database. A second client's MCP does not take the port over; it defers to that healthy peer and takes the origin over only if the owner exits. Because whichever process owns the port reads and writes the same session rows, a review created by one client is servable by the review server of another, and the single fixed origin keeps the browser wallet autoconnect stable.
+
+Cross-process writes rely on WAL plus `PRAGMA busy_timeout`. The one write that must be atomic across processes — the wallet handoff lock — is a single conditional `UPDATE` on `live_review_sessions.pending_handoff_digest`, so two processes cannot hand off two different transactions for the same session.
+
+### Unsigned transaction material on disk
+
+`live_transaction_materials` stores locally built unsigned transaction bytes so a review can be signed by whichever process owns the port, not only the process that built it. Because these bytes are now on disk in the shared database rather than only in one process's memory, the data directory is created `0700` and the database file is set `0600` so other operating-system users cannot read them; the bytes carry a short TTL and are deleted on signing, terminal result, or expiry. This store is separate from the review evidence path: the MCP tool layer still does not return transaction bytes, and the activity-store evidence inputs still reject transaction bytes, signatures, and signing material before write.
+
+### Schema versioning across shared clients
+
+The live session tables are added without changing `user_version`. A runtime that does not know a live table simply ignores it, so a newer client can introduce live tables while an older client keeps opening the same shared database. Only a change that an older runtime cannot safely read should raise `user_version`, and such a change requires updating every client that shares the database, because a runtime does not open a database whose `user_version` is newer than it supports.
+
 ## Boundaries
 
 The active account is a read context only. It is not signing authorization, login, authentication for transactions, custody, permission for transactions, or proof of ownership. It stores at most one address per database file; setting a new active account replaces the previous one without revoking anything onchain.

package/docs/SDK_API.md

@@ -8,7 +8,7 @@ This document records the pinned SDK APIs used by the current runtime. The sourc
 - `@mysten/deepbook-v3`: `1.3.6`
 - `@mysten/dapp-kit-core`: `1.3.2`
 - `@flowx-finance/sdk`: `2.1.0`
-- `@stelis/agent-q-provider-sui`: `0.0.5`
+- `@stelis/agent-q-provider-sui`: `0.0.7`
 - `@zktx.io/ptb-model`: `0.5.0`
 - `mermaid`: `11.12.0`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelis/say-ur-intent",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "mcpName": "io.github.stelis-dev/say-ur-intent",
   "description": "Say Ur Intent is a local-first toolkit for helping AI applications and users inspect Sui DeFi actions before execution.",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "@mysten/deepbook-v3": "1.3.6",
     "@mysten/sui": "2.17.0",
     "@scure/bip39": "2.2.0",
-    "@stelis/agent-q-provider-sui": "0.0.5",
+    "@stelis/agent-q-provider-sui": "0.0.7",
     "@zktx.io/ptb-model": "0.5.0",
     "better-sqlite3": "12.9.0",
     "mermaid": "11.12.0",