New CLI Action

/**
 * <mcp_command_name> tool
 *
 * <One or two sentences describing what this action does and any important
 * preconditions (e.g. "Wallet must hold USDC in the perps account").>
 */

import { Cli, z } from "incur";
import { createAction } from "../utils/actions.js";
// Import helpers as needed:
//   Session/wallet:  import { WalletIdSchema, DerivationIndexSchema } from "../utils/schemas.js";
//   Solana address:  import { getSolanaAddress } from "../utils/solana.js";
//   EVM address:     import { getEthereumAddress } from "../utils/evm.js";
//   Perps client:    import { createPerpsClient } from "../utils/perps.js";
//   Shared schemas:  import { ActionResponseSchema, PendingConfirmationSchema } from "../utils/output-schemas.js";

const <PascalName>Schema = z.object({
  // Each field needs a .describe() explaining its purpose and any defaults.
  // Always include these at the bottom if the action touches the wallet:
  // walletId: WalletIdSchema.describe("Optional wallet ID (defaults to authenticated wallet)"),
  // derivationIndex: DerivationIndexSchema.describe("Optional derivation index (default: 0)"),
});

const <PascalName>OutputSchema = z.object({
  // Define every field the run() function returns.
  // Use z.string().nullable() when a field can be null.
  // Use .optional() for fields that are sometimes absent.
});

const <camelName>Action = createAction({
  // description: Shown to the LLM agent. Should be detailed enough that the
  // agent knows when and how to use this tool. Include:
  //   - What it does
  //   - Any required preconditions
  //   - What the success response looks like
  //   - Any important defaults or two-step flow notes
  description:
    "Phantom Wallet — <detailed description>.",
  options: <PascalName>Schema,
  output: <PascalName>OutputSchema,
  mcp: {
    // command: The MCP/RPC method name. Use snake_case. Should be more
    // descriptive than the CLI sub-command name because MCP tools are flat
    // (no nesting), e.g. "get_perp_account" not just "account".
    command: "<snake_case_mcp_name>",
    annotations: {
      // readOnlyHint: true  → no side effects (reads only)
      // readOnlyHint: false → has side effects (writes, transactions)
      readOnlyHint: <true|false>,
      // destructiveHint: true → irreversible (sends tx, deletes data)
      destructiveHint: <true|false>,
      // openWorldHint: true → makes network/external calls
      openWorldHint: <true|false>,
    },
  },
  run: async ({ options: params, var: context }) => {
    const { logger } = context;
    const session = context.manager.getSession();

    // context.manager.getClient() → PhantomClient (sign, send, addresses)
    // context.apiClient           → PhantomApiClient (REST endpoints)
    // session.walletId            → currently authenticated wallet ID
    // session.organizationId      → org ID for the current session

    // A session is automatically initialized on first use and persisted
    // across calls — no manual session management required.

    // ... implementation ...

    return { /* must match <PascalName>OutputSchema */ };
  },
});

export const <camelName>Command = Cli.create("<cli-subcommand>", <camelName>Action.command);
export const <camelName>Tool = <camelName>Action.tool;