@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/session/walletIdentitySessions.js

@@ -0,0 +1,189 @@
+import { hashEventValue } from "../eventlog/sink.js";
+import { cloneLocalSession, createLocalSessionBase, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
+import { SessionStoreError } from "./sessionErrors.js";
+import { isTerminalWalletIdentityStatus, walletIdentityResultInputSchema, walletIdentitySessionSchema } from "./walletIdentity.js";
+const ALLOWED_WALLET_IDENTITY_TRANSITIONS = {
+    pending: ["opened", "expired"],
+    opened: ["connecting", "failed", "expired"],
+    connecting: ["connected", "rejected", "failed", "expired"],
+    connected: [],
+    rejected: [],
+    failed: [],
+    expired: []
+};
+export function transitionWalletIdentity(session, next) {
+    if (session.status === next) {
+        return;
+    }
+    const allowed = ALLOWED_WALLET_IDENTITY_TRANSITIONS[session.status] ?? [];
+    if (!allowed.includes(next)) {
+        throw new SessionStoreError("invalid_session_transition", `Invalid wallet identity transition: ${session.status} -> ${next}`);
+    }
+    session.status = next;
+}
+function parseWalletIdentitySession(session) {
+    const parsed = walletIdentitySessionSchema.safeParse(session);
+    if (!parsed.success) {
+        throw new SessionStoreError("input_invalid", "Invalid wallet identity session shape");
+    }
+}
+export class WalletIdentitySessionManager {
+    options;
+    sessions = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async create(now) {
+        const { base, token } = createLocalSessionBase(now, this.options.ttlMs);
+        const session = {
+            ...base,
+            status: "pending"
+        };
+        this.sessions.set(session.id, session);
+        await this.options.appendEventLog({
+            type: "wallet_identity.created",
+            sessionId: session.id,
+            status: session.status,
+            at: now.toISOString()
+        });
+        return { session: cloneLocalSession(session), token };
+    }
+    async get(id, now) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return undefined;
+        }
+        if (isLocalSessionExpired(session, now) && !isTerminalWalletIdentityStatus(session.status)) {
+            return cloneLocalSession(await this.expire(id, session, now));
+        }
+        return cloneLocalSession(session);
+    }
+    async list(now) {
+        const sessions = [];
+        for (const id of this.sessions.keys()) {
+            const session = await this.get(id, now);
+            if (session) {
+                sessions.push(session);
+            }
+        }
+        return sessions;
+    }
+    async validateToken(id, token) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return false;
+        }
+        // Wallet identity sessions expose terminal lifecycle states through read APIs after token validation.
+        // Mutable methods own expiry transitions and return lifecycle-specific errors.
+        return tokenMatchesHash(session.tokenHash, token);
+    }
+    async recordOpened(id, now) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            throw new SessionStoreError("session_not_found", `Wallet identity session not found: ${id}`);
+        }
+        if (isLocalSessionExpired(session, now) && !isTerminalWalletIdentityStatus(session.status)) {
+            return cloneLocalSession(await this.expire(id, session, now));
+        }
+        if (isTerminalWalletIdentityStatus(session.status)) {
+            return cloneLocalSession(session);
+        }
+        const nextSession = cloneLocalSession(session);
+        if (nextSession.status === "pending") {
+            transitionWalletIdentity(nextSession, "opened");
+        }
+        nextSession.lastActivityAt = now.toISOString();
+        await this.options.appendEventLog({
+            type: "wallet_identity.opened",
+            sessionId: id,
+            status: nextSession.status,
+            at: now.toISOString()
+        });
+        this.sessions.set(id, nextSession);
+        return cloneLocalSession(nextSession);
+    }
+    async recordConnecting(id, now) {
+        const session = await this.requireMutable(id, now);
+        const nextSession = cloneLocalSession(session);
+        if (nextSession.status !== "connecting") {
+            transitionWalletIdentity(nextSession, "connecting");
+        }
+        nextSession.lastActivityAt = now.toISOString();
+        await this.options.appendEventLog({
+            type: "wallet_identity.connecting",
+            sessionId: id,
+            status: nextSession.status,
+            at: now.toISOString()
+        });
+        this.sessions.set(id, nextSession);
+        return cloneLocalSession(nextSession);
+    }
+    async recordResult(id, result, now) {
+        const session = await this.requireMutable(id, now);
+        const parsed = walletIdentityResultInputSchema.safeParse(result);
+        if (!parsed.success) {
+            throw new SessionStoreError("input_invalid", `Invalid wallet identity result: ${id}`);
+        }
+        if (session.status === "opened" &&
+            parsed.data.status === "failed" &&
+            parsed.data.failureReason !== "no_compatible_wallet") {
+            throw new SessionStoreError("invalid_session_transition", "Only no_compatible_wallet may fail before a connection attempt");
+        }
+        const nextSession = cloneLocalSession(session);
+        transitionWalletIdentity(nextSession, parsed.data.status);
+        Object.assign(nextSession, parsed.data);
+        nextSession.lastActivityAt = now.toISOString();
+        parseWalletIdentitySession(nextSession);
+        if (parsed.data.status === "connected") {
+            await this.options.setActiveAccount(parsed.data.account, now, {
+                name: parsed.data.walletName,
+                id: parsed.data.walletId
+            });
+        }
+        this.sessions.set(id, nextSession);
+        const eventType = parsed.data.status === "connected"
+            ? "wallet_identity.connected"
+            : parsed.data.status === "rejected"
+                ? "wallet_identity.rejected"
+                : "wallet_identity.failed";
+        const event = {
+            type: eventType,
+            sessionId: id,
+            status: nextSession.status,
+            at: now.toISOString()
+        };
+        await this.options.appendEventLog(parsed.data.status === "connected"
+            ? { ...event, walletAddressHash: hashEventValue(parsed.data.account) }
+            : event);
+        return cloneLocalSession(nextSession);
+    }
+    clear() {
+        this.sessions.clear();
+    }
+    async requireMutable(id, now) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            throw new SessionStoreError("session_not_found", `Wallet identity session not found: ${id}`);
+        }
+        if (isLocalSessionExpired(session, now) && !isTerminalWalletIdentityStatus(session.status)) {
+            await this.expire(id, session, now);
+            throw new SessionStoreError("session_expired", `Wallet identity session expired: ${id}`);
+        }
+        if (isTerminalWalletIdentityStatus(session.status)) {
+            throw new SessionStoreError("invalid_session_transition", `Wallet identity session already terminal: ${id}`);
+        }
+        return session;
+    }
+    async expire(id, session, now) {
+        const nextSession = cloneLocalSession(session);
+        transitionWalletIdentity(nextSession, "expired");
+        await this.options.appendEventLog({
+            type: "wallet_identity.expired",
+            sessionId: id,
+            status: nextSession.status,
+            at: now.toISOString()
+        });
+        this.sessions.set(id, nextSession);
+        return nextSession;
+    }
+}

package/dist/core/suiAddress.js

@@ -0,0 +1,18 @@
+import { isValidSuiAddress, isValidTransactionDigest, normalizeSuiAddress } from "@mysten/sui/utils";
+import { z } from "zod";
+// Use the string-only schema at MCP/HTTP output boundaries because zod transforms
+// cannot be represented in MCP JSON Schema. Use the normalized schema for values
+// before storing them as local session state.
+export const suiAddressStringSchema = z
+    .string()
+    .refine(isValidSuiAddress, "Expected a 32-byte Sui address");
+// Shared Sui transaction digest schema (pinned SDK source of truth). Used at
+// MCP/HTTP boundaries and by the signable-adapter commitment fields.
+export const suiTransactionDigestSchema = z
+    .string()
+    .refine(isValidTransactionDigest, "Expected a Sui transaction digest");
+export const normalizedSuiAddressSchema = suiAddressStringSchema.transform((value) => normalizeSuiAddress(value));
+export function parseSuiAddress(value) {
+    const parsed = normalizedSuiAddressSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}

package/dist/core/suiEndpoint.js

@@ -0,0 +1,72 @@
+export class SuiEndpointError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details = {}) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export const MAX_SUI_GRPC_URL_LENGTH = 512;
+export const MAX_SUI_GRAPHQL_URL_LENGTH = 512;
+export function parseGrpcUrl(value) {
+    let parsed;
+    if (value.length > MAX_SUI_GRPC_URL_LENGTH) {
+        throw new SuiEndpointError("invalid_url", `Sui gRPC URL must be ${MAX_SUI_GRPC_URL_LENGTH} characters or fewer`);
+    }
+    const authority = getUrlAuthority(value);
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must be a valid http(s) URL with an explicit port");
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must use http or https");
+    }
+    if (!authority || !hasExplicitPort(authority)) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must include an explicit port, for example :443 or :9000");
+    }
+    if (authority.includes("@")) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must not include credentials");
+    }
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must include only scheme, host, and explicit port");
+    }
+    return `${parsed.protocol}//${authority}`;
+}
+// GraphQL endpoints commonly include a path such as /graphql and may omit an
+// explicit port. gRPC endpoints stay stricter because the pinned gRPC client
+// runtime expects only scheme, host, and explicit port.
+export function parseGraphqlUrl(value) {
+    let parsed;
+    if (value.length > MAX_SUI_GRAPHQL_URL_LENGTH) {
+        throw new SuiEndpointError("invalid_url", `Sui GraphQL URL must be ${MAX_SUI_GRAPHQL_URL_LENGTH} characters or fewer`);
+    }
+    const authority = getUrlAuthority(value);
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must be a valid https URL");
+    }
+    if (parsed.protocol !== "https:") {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must use https");
+    }
+    if (!authority) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must include a host");
+    }
+    if (authority.includes("@")) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must not include credentials");
+    }
+    if (parsed.search || parsed.hash) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must not include a query string or fragment");
+    }
+    return parsed.toString();
+}
+function getUrlAuthority(value) {
+    return value.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]+)/i)?.[1];
+}
+function hasExplicitPort(authority) {
+    return /\]:\d+$/.test(authority) || /^[^[]*:\d+$/.test(authority);
+}

package/dist/mcp/activeAccountResponse.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const activeAccountResponseSchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("set"),
+        account: z.string(),
+        source: z.literal("wallet_identity"),
+        setAt: z.string(),
+        boundary: z.literal("read_context_only_not_signing_authorization")
+    }),
+    z.object({
+        status: z.literal("none")
+    })
+]);
+export function activeAccountResponse(active) {
+    return active
+        ? {
+            status: "set",
+            account: active.address,
+            source: active.source,
+            setAt: active.setAt,
+            boundary: "read_context_only_not_signing_authorization"
+        }
+        : { status: "none" };
+}

package/dist/mcp/prompts.js

@@ -0,0 +1,146 @@
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { z } from "zod";
+import { actionGroups, promptNameFor } from "../adapters/adapterPromptSurfaces.js";
+export const MCP_PROMPTS = [
+    {
+        name: "inspect-supported-sui-actions",
+        title: "Inspect Supported Sui Actions",
+        description: "Review current supported mainnet surfaces and tool status.",
+        text: [
+            "Inspect the Say Ur Intent MCP server status and supported mainnet Sui protocol surfaces.",
+            "Use read.get_server_status first, then read.list_supported_protocols.",
+            "Report implemented tools separately from unavailable or blocked surfaces."
+        ].join("\n")
+    },
+    {
+        name: "prepare-reviewable-sui-action",
+        title: "Prepare Reviewable Sui Action",
+        description: "Prepare a local review session for a supported action proposal.",
+        text: [
+            "Prepare a reviewable Sui action only through Say Ur Intent's review-session flow.",
+            "Use action.prepare_external_proposal_review when the input is a structured external payment or Sui action proposal.",
+            "External proposals get read-only local review and never become signing material. Use action.prepare_sui_action_review for a natural-language swap intent; after a wallet account is connected, account-bound review can reach ready_for_wallet_review, where the local review page offers digest-gated, user-controlled wallet signing.",
+            "Show the reviewUrl and summarize the review checks. This MCP response never contains signing data, transaction bytes, or signing readiness; signing and execution receipts happen on the local review page."
+        ].join("\n")
+    }
+];
+// Platform-owned boundary language appended to every adapter prompt surface.
+// Adapters contribute copy about their own action only; they cannot weaken
+// or omit these lines.
+const PLATFORM_PROMPT_BOUNDARY_LINES = [
+    "Show the reviewUrl and summarize the review checks.",
+    "This MCP response never contains signing data, transaction bytes, or signing readiness; signing and execution receipts happen on the local review page."
+];
+function surfacePromptText(surface, intent) {
+    return [
+        `Prepare a reviewable Sui mainnet ${surface.action} for this intent: "${intent}".`,
+        `Parse the source amount, source symbol, and target symbol from the intent (any language) and call ${surface.toolName} with them and intent.protocol set to "${surface.protocolSlug}".`,
+        ...PLATFORM_PROMPT_BOUNDARY_LINES
+    ].join("\n");
+}
+function registerSurfacePrompt(server, name, surface, description) {
+    server.registerPrompt(name, {
+        title: surface.title,
+        description,
+        argsSchema: {
+            intent: z.string().describe(surface.intentArgDescription)
+        }
+    }, async ({ intent }) => ({
+        description,
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: surfacePromptText(surface, intent)
+                }
+            }
+        ]
+    }));
+}
+export function registerMcpPrompts(server, surfaces = []) {
+    for (const prompt of MCP_PROMPTS) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description
+        }, async () => ({
+            description: prompt.description,
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: prompt.text
+                    }
+                }
+            ]
+        }));
+    }
+    // Adapter prompt surfaces: action-first names (`swap-deep`) with one
+    // free-text intent argument so clients can pass the whole request in one
+    // line (Claude Code: /mcp__say-ur-intent__swap-deep 10 sui to usdc;
+    // Claude Desktop shows a single input field). The model parses the
+    // intent; this server never does.
+    for (const surface of surfaces) {
+        registerSurfacePrompt(server, promptNameFor(surface), surface, surface.description);
+    }
+    // Bare action prompts are always registered. One protocol: straight to it.
+    // Several protocols: an optional `protocol` argument (completion suggests
+    // the slugs) and explicit instructions to ask the user - the venue is the
+    // user's choice, never the server's.
+    for (const [action, group] of actionGroups(surfaces)) {
+        registerBareActionPrompt(server, action, group);
+    }
+}
+export function bareActionPromptText(action, group, intent, protocol) {
+    const chosen = group.length === 1 ? group[0] : group.find((surface) => surface.protocolSlug === (protocol ?? "").trim());
+    if (chosen) {
+        return surfacePromptText(chosen, intent);
+    }
+    const options = group
+        .map((surface) => `${surface.protocolSlug} (${surface.title}, tool: ${surface.toolName})`)
+        .join("; ");
+    return [
+        `Several protocols support the ${action} action: ${options}.`,
+        `The user's intent: "${intent}".`,
+        "List these protocol options to the user and ask which one to use. Do not pick a protocol on your own.",
+        "Once the user names a protocol, parse the source amount, source symbol, and target symbol from the intent (any language) and call that protocol's tool with them and intent.protocol set to the chosen slug.",
+        ...PLATFORM_PROMPT_BOUNDARY_LINES
+    ].join("\n");
+}
+function registerBareActionPrompt(server, action, group) {
+    const single = group.length === 1 ? group[0] : undefined;
+    const first = group[0];
+    if (!first) {
+        return;
+    }
+    const description = single
+        ? `${single.description} Shorthand for ${promptNameFor(single)}.`
+        : `Prepare a reviewable Sui ${action} - several protocols support it (${group
+            .map((surface) => surface.protocolSlug)
+            .join(", ")}); you pick which.`;
+    const slugs = group.map((surface) => surface.protocolSlug);
+    server.registerPrompt(action, {
+        title: single ? single.title : `${action} (choose protocol)`,
+        description,
+        argsSchema: {
+            intent: completable(z.string().describe(first.intentArgDescription), (value) => value ? [] : group.flatMap((surface) => surface.exampleIntents)),
+            ...(single
+                ? {}
+                : {
+                    protocol: completable(z.string().optional().describe(`Protocol slug (optional): ${slugs.join(" | ")}`), (value) => slugs.filter((slug) => slug.startsWith((value ?? "").toLowerCase())))
+                })
+        }
+    }, async (args) => ({
+        description,
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: bareActionPromptText(action, group, String(args.intent ?? ""), args.protocol)
+                }
+            }
+        ]
+    }));
+}

package/dist/mcp/registerTool.js

@@ -0,0 +1,19 @@
+import { assertValidToolName } from "./toolNames.js";
+const DEFAULT_TOOL_ANNOTATIONS = {
+    openWorldHint: false
+};
+function mergedAnnotations(defaultAnnotations, annotations) {
+    return {
+        ...DEFAULT_TOOL_ANNOTATIONS,
+        ...(defaultAnnotations ?? {}),
+        ...(annotations ?? {})
+    };
+}
+export function registerSayUrIntentTool(server, name, config, callback) {
+    assertValidToolName(name);
+    const { defaultAnnotations, annotations, ...sdkConfig } = config;
+    return server.registerTool(name, {
+        ...sdkConfig,
+        annotations: mergedAnnotations(defaultAnnotations, annotations)
+    }, callback);
+}

package/dist/mcp/resources.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const MCP_RESOURCES = [
+    {
+        name: "readme",
+        uri: "sayurintent://docs/readme",
+        title: "README",
+        description: "Public entry document: product purpose, current release boundary, setup path, and documentation map.",
+        path: "README.md"
+    },
+    {
+        name: "mcp-setup",
+        uri: "sayurintent://docs/mcp-setup",
+        title: "MCP Setup",
+        description: "Setup guide: installation, MCP client connection, first-use flow, settings, and troubleshooting.",
+        path: "docs/MCP_SETUP.md"
+    },
+    {
+        name: "mcp-tools",
+        uri: "sayurintent://docs/mcp-tools",
+        title: "MCP Tools",
+        description: "API reference: tool contracts, response fields, statuses, follow-up fields, and output boundaries.",
+        path: "docs/MCP_TOOLS.md"
+    },
+    {
+        name: "wallet-identity",
+        uri: "sayurintent://docs/wallet-identity",
+        title: "Wallet Identity",
+        description: "Wallet identity reference: active-account read context and same-machine capture boundaries.",
+        path: "docs/WALLET_IDENTITY.md"
+    },
+    {
+        name: "agent-behavior",
+        uri: "sayurintent://docs/agent-behavior",
+        title: "Agent Behavior Reference",
+        description: "Answer playbook: user-question flows, tool selection, and response wording boundaries.",
+        path: "docs/AGENT_BEHAVIOR.md"
+    },
+    {
+        name: "deepbook-v3",
+        uri: "sayurintent://protocols/deepbook-v3",
+        title: "DeepBookV3",
+        description: "Protocol reference only; use MCP tool responses and read.list_supported_protocols for current support.",
+        path: "protocols/deepbook-v3.md"
+    },
+    {
+        name: "deepbook-margin",
+        uri: "sayurintent://protocols/deepbook-margin",
+        title: "DeepBook Margin",
+        description: "Protocol reference only; no margin MCP read tools or signable actions are exposed in this release.",
+        path: "protocols/deepbook-margin.md"
+    }
+];
+export function registerMcpResources(server) {
+    for (const resource of MCP_RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown"
+        }, async () => ({
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: "text/markdown",
+                    text: await readFile(resolve(packageRoot, resource.path), "utf8")
+                }
+            ]
+        }));
+    }
+}