@zktx.io/sui-mcp 0.5.0

package/dist/core/session/status.js

@@ -0,0 +1,60 @@
+import { isRequestWaiting } from "./transactionRequest.js";
+import { workflowProgress } from "./walletConnection.js";
+export function reviewProgress(preparing, request, availability, observation) {
+    if (preparing)
+        return workflowProgress(true, true, availability);
+    if (request?.requestStatus === "completed")
+        return { status: "idle" };
+    const waiting = !!request && !observation.stopped &&
+        (observation.pending || ["awaiting_signature", "submitting", "awaiting_chain_result"].includes(request.requestStatus));
+    return workflowProgress(waiting, request?.requestStatus === "awaiting_signature", availability);
+}
+export const EXECUTION_POLLING_INTERVAL_SECONDS = 3;
+export const EXECUTION_STATUS_CATEGORIES = ["final", "user_action_required", "awaiting_chain_result", "non_terminal"];
+export function isFinalSessionStatus(status) { return status === "expired"; }
+export function getExecutionPollingStatus(session, request) {
+    return request?.requestStatus ?? session.status;
+}
+export function executionStatusCategory(status) {
+    if (["completed", "request_failed", "stopped", "outcome_unknown", "expired"].includes(status))
+        return "final";
+    if (status === "awaiting_chain_result")
+        return "awaiting_chain_result";
+    if (status === "awaiting_signature" || status === "submitting")
+        return "non_terminal";
+    return "user_action_required";
+}
+export function isWaitStoppingExecutionStatus(status) {
+    const category = executionStatusCategory(status);
+    return category === "final" || category === "user_action_required";
+}
+export function isInteractionPendingReviewStatus(status) {
+    return executionStatusCategory(status) !== "final";
+}
+export function isReviewInteractionPending({ hasReviewInput, request, progress }) {
+    // Historical preparation state is not proof that a live input remains.
+    // Consumed input, in turn, does not end its admitted request or observation.
+    return hasReviewInput || progress.status !== "idle" || !!request && isRequestWaiting(request.requestStatus);
+}
+export function executionPollingHint() {
+    return {
+        nonTerminalStatuses: ["awaiting_signature", "submitting", "awaiting_chain_result"],
+        waitStoppingStatuses: ["proposed", "awaiting_wallet", "wallet_connected", "ready_for_wallet_review", "refresh_required", "blocked", "expired",
+            "stopped", "request_failed", "outcome_unknown", "completed"],
+        finalStatuses: ["stopped", "request_failed", "outcome_unknown", "completed", "expired"],
+        userActionRequiredStatuses: ["proposed", "awaiting_wallet", "wallet_connected", "ready_for_wallet_review", "refresh_required", "blocked"],
+        recommendedIntervalSeconds: EXECUTION_POLLING_INTERVAL_SECONDS
+    };
+}
+export function reviewStatusResponse({ session, request, walletAvailability, walletObservation, progress, connectionConflict }) {
+    const pollingStatus = getExecutionPollingStatus(session, request);
+    return {
+        walletAvailability, walletObservation, progress, connectionConflict,
+        reviewSessionId: session.id, status: session.status, reviewRevision: session.reviewRevision,
+        account: session.account, plans: session.plans, reviewState: session.reviewState,
+        pollingStatus, statusCategory: executionStatusCategory(pollingStatus), pollingHint: executionPollingHint(),
+        expiresAt: session.expiresAt, lastActivityAt: session.lastActivityAt,
+        ...(request ? { attemptId: request.attemptId, requestStatus: request.requestStatus, request,
+            ...(request.execution ? { executionResult: request.execution } : {}) } : {})
+    };
+}

package/dist/core/session/transactionMaterialStore.js

@@ -0,0 +1,221 @@
+import { randomUUID } from "node:crypto";
+import { Transaction } from "@mysten/sui/transactions";
+import { z } from "zod";
+import { normalizedSuiAddressSchema, parseSuiAddress, suiTransactionDigestSchema } from "../suiAddress.js";
+export const LOCAL_TRANSACTION_MATERIAL_KINDS = [
+    "deepbook_swap_transaction_data"
+];
+export const LOCAL_TRANSACTION_MATERIAL_SOURCES = [
+    "sui_mcp_built",
+    "sui_mcp_verified"
+];
+const localTransactionMaterialKindSchema = z.enum(LOCAL_TRANSACTION_MATERIAL_KINDS);
+const localTransactionMaterialSourceSchema = z.enum(LOCAL_TRANSACTION_MATERIAL_SOURCES);
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+export const localTransactionMaterialHandleSchema = z.object({
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: localTransactionMaterialKindSchema,
+    source: localTransactionMaterialSourceSchema,
+    createdAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).superRefine((value, ctx) => {
+    if (Date.parse(value.expiresAt) <= Date.parse(value.createdAt)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "expiresAt must be after createdAt"
+        });
+    }
+});
+export const localTransactionMaterialDigestCommitmentSchema = z.object({
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: localTransactionMaterialKindSchema,
+    source: localTransactionMaterialSourceSchema,
+    digestKind: z.literal("sui_transaction_digest"),
+    transactionDigest: suiTransactionDigestSchema,
+    computedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+});
+export function parseLocalTransactionMaterialHandle(value) {
+    return localTransactionMaterialHandleSchema.parse(value);
+}
+export function parseLocalTransactionMaterialDigestCommitment(value) {
+    return localTransactionMaterialDigestCommitmentSchema.parse(value);
+}
+function parseLocalTransactionMaterialArtifacts(value, now = new Date()) {
+    const transactionMaterial = parseLocalTransactionMaterialHandle(value.transactionMaterial);
+    const transactionMaterialDigest = parseLocalTransactionMaterialDigestCommitment(value.transactionMaterialDigest);
+    const materialCreatedAtMs = Date.parse(transactionMaterial.createdAt);
+    const materialExpiresAtMs = Date.parse(transactionMaterial.expiresAt);
+    const digestComputedAtMs = Date.parse(transactionMaterialDigest.computedAt);
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new LocalTransactionMaterialStoreError("now must be a valid Date");
+    }
+    if (materialCreatedAtMs > nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material createdAt must not be in the future");
+    }
+    if (materialExpiresAtMs <= nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material must not be expired");
+    }
+    if (digestComputedAtMs < materialCreatedAtMs || digestComputedAtMs > nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest computedAt must be between createdAt and now");
+    }
+    if (digestComputedAtMs >= materialExpiresAtMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest must be computed before material expiry");
+    }
+    if (transactionMaterialDigest.materialId !== transactionMaterial.materialId ||
+        transactionMaterialDigest.reviewSessionId !== transactionMaterial.reviewSessionId ||
+        transactionMaterialDigest.planId !== transactionMaterial.planId ||
+        transactionMaterialDigest.account !== transactionMaterial.account ||
+        transactionMaterialDigest.kind !== transactionMaterial.kind ||
+        transactionMaterialDigest.source !== transactionMaterial.source ||
+        transactionMaterialDigest.expiresAt !== transactionMaterial.expiresAt) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest must match the material handle");
+    }
+    return { transactionMaterial, transactionMaterialDigest };
+}
+export async function verifyLocalTransactionMaterialArtifacts(value) {
+    const now = value.now ?? new Date();
+    const parsed = parseLocalTransactionMaterialArtifacts({
+        transactionMaterial: value.transactionMaterial,
+        transactionMaterialDigest: value.transactionMaterialDigest
+    }, now);
+    const material = value.materialStore.getTransactionMaterial(parsed.transactionMaterial, now);
+    if (!material) {
+        throw new LocalTransactionMaterialStoreError("transaction material is unavailable");
+    }
+    let transactionDigest;
+    try {
+        transactionDigest = await Transaction.from(material.transactionBytes).getDigest();
+    }
+    catch {
+        throw new LocalTransactionMaterialStoreError("transaction material bytes cannot produce a Sui transaction digest");
+    }
+    const parsedDigest = suiTransactionDigestSchema.safeParse(transactionDigest);
+    if (!parsedDigest.success) {
+        throw new LocalTransactionMaterialStoreError("computed transaction digest is invalid");
+    }
+    if (parsedDigest.data !== parsed.transactionMaterialDigest.transactionDigest) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest does not match stored transaction bytes");
+    }
+    return { ...parsed, transactionBytes: new Uint8Array(material.transactionBytes) };
+}
+export class LocalTransactionMaterialStoreError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+// Validate the store input and build the stored record (with cloned bytes). Shared
+// by every LocalTransactionMaterialStore implementation so validation never drifts
+// between the in-memory and SQLite backends.
+export function buildTransactionMaterialRecord(input, now = new Date()) {
+    const account = parseSuiAddress(input.account);
+    if (!account) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material account");
+    }
+    if (!input.reviewSessionId) {
+        throw new LocalTransactionMaterialStoreError("reviewSessionId is required");
+    }
+    if (!input.planId) {
+        throw new LocalTransactionMaterialStoreError("planId is required");
+    }
+    if (!LOCAL_TRANSACTION_MATERIAL_KINDS.includes(input.kind)) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material kind");
+    }
+    if (!LOCAL_TRANSACTION_MATERIAL_SOURCES.includes(input.source)) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material source");
+    }
+    if (input.transactionBytes.byteLength === 0) {
+        throw new LocalTransactionMaterialStoreError("transactionBytes must not be empty");
+    }
+    const createdAt = now.toISOString();
+    const expiresAt = input.expiresAt.toISOString();
+    if (Date.parse(expiresAt) <= Date.parse(createdAt)) {
+        throw new LocalTransactionMaterialStoreError("expiresAt must be after createdAt");
+    }
+    return {
+        materialId: `txmat_${randomUUID()}`,
+        reviewSessionId: input.reviewSessionId,
+        planId: input.planId,
+        account,
+        kind: input.kind,
+        source: input.source,
+        createdAt,
+        expiresAt,
+        transactionBytes: cloneBytes(input.transactionBytes),
+        ...(input.redactedDiagnostics === undefined
+            ? {}
+            : { redactedDiagnostics: structuredClone(input.redactedDiagnostics) })
+    };
+}
+// Project the public (redacted) handle out of a stored record.
+export function toMaterialHandle(record) {
+    return {
+        materialId: record.materialId,
+        reviewSessionId: record.reviewSessionId,
+        planId: record.planId,
+        account: record.account,
+        kind: record.kind,
+        source: record.source,
+        createdAt: record.createdAt,
+        expiresAt: record.expiresAt
+    };
+}
+export class InMemoryLocalTransactionMaterialStore {
+    records = new Map();
+    recordTransactionMaterial(input, now = new Date()) {
+        const record = buildTransactionMaterialRecord(input, now);
+        this.records.set(record.materialId, record);
+        return toMaterialHandle(record);
+    }
+    getTransactionMaterial(handle, now = new Date()) {
+        const record = this.records.get(handle.materialId);
+        if (!record) {
+            return undefined;
+        }
+        if (Date.parse(record.expiresAt) <= now.getTime()) {
+            this.records.delete(handle.materialId);
+            return undefined;
+        }
+        if (!sameHandle(record, handle)) {
+            return undefined;
+        }
+        return {
+            ...record,
+            transactionBytes: cloneBytes(record.transactionBytes),
+            ...(record.redactedDiagnostics === undefined
+                ? {}
+                : { redactedDiagnostics: structuredClone(record.redactedDiagnostics) })
+        };
+    }
+    deleteReviewSessionTransactionMaterials(reviewSessionId) {
+        for (const [materialId, record] of this.records) {
+            if (record.reviewSessionId === reviewSessionId) {
+                this.records.delete(materialId);
+            }
+        }
+    }
+}
+export function sameHandle(record, handle) {
+    return record.materialId === handle.materialId &&
+        record.reviewSessionId === handle.reviewSessionId &&
+        record.planId === handle.planId &&
+        record.account === handle.account &&
+        record.kind === handle.kind &&
+        record.source === handle.source &&
+        record.createdAt === handle.createdAt &&
+        record.expiresAt === handle.expiresAt;
+}
+function cloneBytes(bytes) {
+    return new Uint8Array(bytes);
+}

package/dist/core/session/transactionRequest.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { suiAddressStringSchema, suiTransactionDigestSchema } from "../suiAddress.js";
+import { suiChainReceiptEvidenceSchema } from "../action/suiChainReceiptEvidence.js";
+export const TRANSACTION_REQUEST_STATUSES = [
+    "awaiting_signature", "submitting", "awaiting_chain_result", "stopped",
+    "request_failed", "outcome_unknown", "completed"
+];
+export const transactionRequestStatusSchema = z.enum(TRANSACTION_REQUEST_STATUSES);
+// The submission was admitted durably before external I/O. A failed follow-up
+// write must not remove its initial observation window or replacement guard.
+export const INITIAL_CHAIN_OBSERVATION_STATUSES = ["submitting", "awaiting_chain_result"];
+export function isInitialChainObservation(status) {
+    return INITIAL_CHAIN_OBSERVATION_STATUSES.some((value) => value === status);
+}
+// This is the existing signing surface's local wait, independent of protocol
+// request expiry, card input expiry and the chain observation window.
+export const SIGNATURE_WAIT_MS = 90_000;
+export const CHAIN_RECEIPT_LOOKUP_MAX_AGE_MS = 10 * 60 * 1000;
+export const transactionExecutionSummarySchema = z.object({
+    reviewSessionId: z.string().min(1),
+    attemptId: z.string().min(1),
+    planId: z.string().min(1),
+    status: z.enum(["success", "failure"]),
+    txDigest: suiTransactionDigestSchema,
+    chainReceipt: suiChainReceiptEvidenceSchema,
+    failureReason: z.literal("chain_execution_failed").optional(),
+    recordedAt: z.string().datetime()
+}).strict().superRefine((result, context) => {
+    if (result.txDigest !== result.chainReceipt.txDigest || (result.status === "success") !== result.chainReceipt.effectsStatus.success) {
+        context.addIssue({ code: "custom", message: "Execution must match the observed chain receipt." });
+    }
+    if ((result.status === "failure") !== (result.failureReason !== undefined)) {
+        context.addIssue({ code: "custom", message: "Only a chain failure has a chain execution failure reason." });
+    }
+});
+export const transactionRequestSchema = z.object({
+    attemptId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    reviewRevision: z.number().int().nonnegative(),
+    account: suiAddressStringSchema,
+    transactionDigest: suiTransactionDigestSchema,
+    requestStatus: transactionRequestStatusSchema,
+    revision: z.number().int().nonnegative(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    signatureVerifiedAt: z.string().datetime().optional(),
+    submittedAt: z.string().datetime().optional(),
+    reason: z.string().optional(),
+    execution: transactionExecutionSummarySchema.optional()
+}).strict().superRefine((request, context) => {
+    const execution = request.execution;
+    if ((request.requestStatus === "completed") !== (execution !== undefined)) {
+        context.addIssue({ code: "custom", message: "Completed requests require an observed execution result." });
+    }
+    if (execution && (execution.attemptId !== request.attemptId || execution.reviewSessionId !== request.reviewSessionId ||
+        execution.planId !== request.planId || execution.txDigest !== request.transactionDigest || execution.chainReceipt.sender !== request.account)) {
+        context.addIssue({ code: "custom", message: "Execution identity differs from the admitted request." });
+    }
+});
+export function isRequestWaiting(status) {
+    return status === "awaiting_signature" || isInitialChainObservation(status);
+}
+export const requestTransitions = {
+    awaiting_signature: ["submitting", "stopped", "request_failed", "outcome_unknown"],
+    submitting: ["awaiting_chain_result", "outcome_unknown", "completed"],
+    awaiting_chain_result: ["outcome_unknown", "completed"],
+    stopped: [],
+    request_failed: [],
+    outcome_unknown: ["awaiting_chain_result", "completed"],
+    completed: []
+};

package/dist/core/session/wait.js

@@ -0,0 +1,79 @@
+import { EXECUTION_POLLING_INTERVAL_SECONDS, getExecutionPollingStatus, executionStatusCategory, isWaitStoppingExecutionStatus } from "./status.js";
+import { SessionStoreError } from "./sessionStore.js";
+import { workflowViewSchema } from "./workflowView.js";
+import { WALLET_CONNECTION_POLL_SECONDS } from "./walletConnection.js";
+export const DEFAULT_WAIT_TIMEOUT_MS = 45_000;
+export const MAX_WAIT_TIMEOUT_MS = 55_000;
+export const WAIT_OUTCOMES = ["status_reached", "timed_out", "unavailable"];
+export class WaitRequestAbortedError extends Error {
+    reason;
+    constructor(reason = "host_abort") {
+        super("Wait request aborted");
+        this.reason = reason;
+    }
+}
+export async function waitForWalletConnection(cards, cardId, options = {}) {
+    const timeout = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const started = Date.now(), sleep = options.sleep ?? sleepMs;
+    let snapshot;
+    while (true) {
+        assertNotAborted(options.signal);
+        snapshot = await cards.readSaved(cardId);
+        const view = workflowViewSchema.parse(snapshot.data);
+        if (snapshot.kind !== "connect")
+            throw new SessionStoreError("input_invalid", "A connection card ID is required.");
+        if (view.progress.status === "unavailable")
+            return { waitOutcome: "unavailable", snapshot };
+        if (!view.observe)
+            return { waitOutcome: "status_reached", snapshot };
+        const remaining = timeout - (Date.now() - started);
+        if (remaining <= 0)
+            return { waitOutcome: "timed_out", snapshot };
+        await sleep(Math.min(remaining, WALLET_CONNECTION_POLL_SECONDS * 1000), options.signal);
+    }
+}
+export async function waitForExecutionResult(readState, reviewSessionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const sleep = options.sleep ?? sleepMs, startedAt = Date.now();
+    let reason = "missing";
+    while (true) {
+        assertNotAborted(options.signal);
+        const state = await readState(reviewSessionId, options.now?.());
+        if (!state)
+            throw new SessionStoreError("session_not_found", `Review session not found: ${reviewSessionId}`, { reason });
+        const status = getExecutionPollingStatus(state.session, state.request);
+        if (executionStatusCategory(status) === "final")
+            return { ...state, status, waitOutcome: "status_reached" };
+        if (state.progress.status === "unavailable")
+            return { ...state, status, waitOutcome: "unavailable" };
+        if (isWaitStoppingExecutionStatus(status))
+            return { ...state, status, waitOutcome: "status_reached" };
+        const remaining = timeoutMs - (Date.now() - startedAt);
+        if (remaining <= 0)
+            return { ...state, status, waitOutcome: "timed_out" };
+        await sleep(Math.min(remaining, EXECUTION_POLLING_INTERVAL_SECONDS * 1000), options.signal);
+        reason = "session_removed_during_wait";
+    }
+}
+function sleepMs(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new WaitRequestAbortedError());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new WaitRequestAbortedError());
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted) {
+        throw new WaitRequestAbortedError();
+    }
+}

package/dist/core/session/walletConnection.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { suiAddressStringSchema } from "../suiAddress.js";
+export const SUI_MAINNET_WALLET_CHAIN = "sui:mainnet";
+export const SUI_SIGN_TRANSACTION_METHOD = "sui_signTransaction";
+export const WALLET_CONNECTION_POLL_SECONDS = 5;
+export const walletRunIdSchema = z.string().uuid();
+export const walletStartStageSchema = z.enum(["process_start", "sdk_start", "session_restore", "state_sync"]);
+export const walletUnavailableReasonSchema = z.enum([
+    "initialization_failed", "restoration_failed", "wallet_state_unavailable"
+]);
+export const walletAvailabilitySchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("available"), walletRunId: walletRunIdSchema }).strict(),
+    z.object({ status: z.literal("initializing"), walletRunId: walletRunIdSchema, stage: walletStartStageSchema, message: z.string() }).strict(),
+    z.object({ status: z.literal("recovering"), walletRunId: walletRunIdSchema, message: z.string() }).strict(),
+    z.object({ status: z.literal("unavailable"), walletRunId: walletRunIdSchema.optional(), reason: walletUnavailableReasonSchema, message: z.string() }).strict()
+]);
+export function walletUnavailable(reason, walletRunId) {
+    const message = reason === "restoration_failed"
+        ? "Wallet connections could not be restored."
+        : reason === "wallet_state_unavailable"
+            ? "The wallet connection status could not be checked. Saved transaction results remain available."
+            : "The wallet connection service could not start.";
+    return { status: "unavailable", reason, message, ...(walletRunId === undefined ? {} : { walletRunId }) };
+}
+export class WalletUnavailableError extends Error {
+    reason;
+    constructor(reason, message = walletUnavailable(reason).message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+export const workflowProgressSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("idle") }).strict(),
+    z.object({ status: z.literal("waiting") }).strict(),
+    z.object({ status: z.literal("unavailable"), reason: z.literal("wallet_unavailable"), message: z.string() }).strict()
+]);
+export function workflowProgress(waiting, requiresWallet, availability) {
+    if (!waiting)
+        return { status: "idle" };
+    if (requiresWallet && availability.status === "unavailable") {
+        return { status: "unavailable", reason: "wallet_unavailable", message: availability.message };
+    }
+    return { status: "waiting" };
+}
+export const walletConnectionStatusSchema = z.enum([
+    "awaiting_approval", "connected", "rejected", "failed", "expired", "stopped", "disconnected"
+]);
+export const walletConnectionSchema = z.object({
+    connectionId: z.string().min(1),
+    status: walletConnectionStatusSchema,
+    revision: z.number().int().nonnegative(),
+    accounts: z.array(suiAddressStringSchema),
+    methods: z.array(z.string()),
+    chain: z.literal(SUI_MAINNET_WALLET_CHAIN),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+    walletName: z.string().optional(),
+    reason: z.string().optional()
+}).strict();
+export const connectionConflictSchema = z.object({
+    reason: z.literal("multiple_connections"),
+    connectionIds: z.array(z.string().min(1)).min(2).refine((ids) => new Set(ids).size === ids.length)
+}).strict();
+export const CONNECTION_CONFLICT_MESSAGE = "More than one wallet connection is saved. Disconnect the connections you no longer need before continuing.";
+export const assetReadAccountSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("available"), account: suiAddressStringSchema }).strict(),
+    z.object({ status: z.literal("address_required") }).strict()
+]);
+// Management may name every recorded target. Account use requires exactly one
+// live connection and no connection operation still awaiting its outcome.
+export function walletConnectionSelection(connections, at, stored) {
+    const connected = connections.filter((item) => item.status === "connected" && Date.parse(item.expiresAt) > at);
+    const pending = connections.some((item) => item.pendingAction || item.status === "awaiting_approval");
+    const connection = connected.length === 1 && !pending ? connected[0] : undefined;
+    return {
+        ...(connected.length > 1 ? { conflict: { reason: "multiple_connections",
+                connectionIds: connected.map((item) => item.connectionId).sort() } } : {}),
+        ...(connection ? { connection } : {}),
+        pairingAllowed: connected.length === 0 && !pending,
+        assetReadAccount: connection && stored?.walletId === connection.connectionId && connection.accounts.includes(stored.address)
+            ? { status: "available", account: stored.address } : { status: "address_required" }
+    };
+}
+export class WalletUserRejectedError extends Error {
+    constructor() { super("The wallet request was rejected by the user."); }
+}
+// Shared recorded connection facts only. Each operation checks its own expiry,
+// account, method and revision requirements at its decision boundary.
+export function isOwnedConnectedWallet(record, ownerId, disconnectPending) {
+    return !!record && record.ownerId === ownerId && record.connection.status === "connected" && !disconnectPending;
+}

package/dist/core/session/walletRuntime.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { suiAddressStringSchema } from "../suiAddress.js";
+import { SUI_MAINNET_WALLET_CHAIN, walletRunIdSchema } from "./walletConnection.js";
+export { walletRunIdSchema, walletStartStageSchema } from "./walletConnection.js";
+export const walletSessionSchema = z.object({
+    topic: z.string().min(1), accounts: z.array(suiAddressStringSchema).min(1), methods: z.array(z.string()),
+    chain: z.literal(SUI_MAINNET_WALLET_CHAIN), expiresAt: z.string().datetime(), walletName: z.string().optional()
+}).strict();
+export const walletSessionObservationSchema = z.discriminatedUnion("status", [
+    z.object({ topic: z.string().min(1), version: z.number().int().positive(), status: z.literal("present"), session: walletSessionSchema }).strict(),
+    z.object({ topic: z.string().min(1), version: z.number().int().positive(), status: z.enum(["absent", "unusable"]) }).strict()
+]);
+export const walletObservationSchema = z.object({
+    runId: walletRunIdSchema, sequence: z.number().int().positive(), observedAt: z.string().datetime()
+}).strict();
+export const walletSnapshotSchema = walletObservationSchema.extend({ sessions: z.array(walletSessionObservationSchema) }).strict();
+const recoveryBase = z.object({ kind: z.literal("wallet_service_recovery"), priorRunId: walletRunIdSchema,
+    admittedAt: z.string().datetime(), updatedAt: z.string().datetime() });
+export const walletRecoverySchema = z.union([
+    recoveryBase.extend({ phase: z.literal("stopping") }).strict(),
+    recoveryBase.extend({ phase: z.literal("starting"), nextRunId: walletRunIdSchema }).strict(),
+    recoveryBase.extend({ outcome: z.enum(["available", "failed", "superseded", "server_restarted"]),
+        nextRunId: walletRunIdSchema.optional(), message: z.string().optional() }).strict()
+]);
+export class WalletRunInterruptedError extends Error {
+    runId;
+    constructor(runId) {
+        super("The wallet service run ended. This operation will not be repeated.");
+        this.runId = runId;
+    }
+}
+export class WalletReplacementFailedError extends Error {
+    runId;
+    constructor(runId) {
+        super("The wallet service restart could not be confirmed.");
+        this.runId = runId;
+    }
+}