@aomi-labs/client 0.1.16 → 0.1.17

package/README.md

@@ -126,6 +126,7 @@ npx @aomi-labs/client chat "swap 1 ETH" --verbose        # stream tool calls + r
 npx @aomi-labs/client app list                           # list available apps
 npx @aomi-labs/client model list                         # list available models
 npx @aomi-labs/client model set claude-sonnet-4          # switch the current session model
+npx @aomi-labs/client session new                        # create a fresh active session
 npx @aomi-labs/client secret list                        # list configured secret handles
 npx @aomi-labs/client --secret ALCHEMY_API_KEY=...       # ingest a secret for the active session
 npx @aomi-labs/client log                                # show full conversation history
@@ -149,6 +150,31 @@ npx @aomi-labs/client chat "send 0 ETH to myself" \
 The address is persisted in the state file, so subsequent commands in the same
 session don't need it again.
 
+### Chain selection
+
+Use `--chain <id>` for the current command when the task is chain-specific:
+
+```bash
+$ npx @aomi-labs/client chat "swap 1 POL for USDC on Polygon" --chain 137
+```
+
+Use `AOMI_CHAIN_ID` when several consecutive commands should share the same
+chain context.
+
+### Fresh sessions
+
+Use `--new-session` when you want a command to start a fresh backend/local
+session instead of reusing the currently active one:
+
+```bash
+$ npx @aomi-labs/client chat "show my balances" --new-session
+$ npx @aomi-labs/client --secret ALCHEMY_API_KEY=... --new-session
+$ npx @aomi-labs/client session new
+```
+
+This is useful when starting a new operator flow or a new external chat thread
+and you do not want stale session state to bleed into the next run.
+
 ### Model selection
 
 The CLI can discover and switch backend models for the active session:

package/dist/cli.js

@@ -22,7 +22,7 @@ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 // package.json
 var package_default = {
   name: "@aomi-labs/client",
-  version: "0.1.16",
+  version: "0.1.17",
   description: "Platform-agnostic TypeScript client for the Aomi backend API",
   type: "module",
   main: "./dist/index.cjs",
@@ -139,6 +139,12 @@ function parseSecret(value, secrets) {
     secrets[value.slice(0, eqIdx)] = value.slice(eqIdx + 1);
   }
 }
+function normalizePrivateKey(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  return trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+}
 function parseArgs(argv) {
   const raw = argv.slice(2);
   const command = raw[0] && !raw[0].startsWith("-") ? raw[0] : void 0;
@@ -200,8 +206,11 @@ function getConfig(parsed) {
     apiKey: (_e = parsed.flags["api-key"]) != null ? _e : process.env.AOMI_API_KEY,
     app: (_g = (_f = parsed.flags["app"]) != null ? _f : process.env.AOMI_APP) != null ? _g : "default",
     model: (_h = parsed.flags["model"]) != null ? _h : process.env.AOMI_MODEL,
+    freshSession: parsed.flags["new-session"] === "true",
     publicKey: (_i = parsed.flags["public-key"]) != null ? _i : process.env.AOMI_PUBLIC_KEY,
-    privateKey: (_j = parsed.flags["private-key"]) != null ? _j : process.env.PRIVATE_KEY,
+    privateKey: normalizePrivateKey(
+      (_j = parsed.flags["private-key"]) != null ? _j : process.env.PRIVATE_KEY
+    ),
     chainRpcUrl: (_k = parsed.flags["rpc-url"]) != null ? _k : process.env.CHAIN_RPC_URL,
     chain: parseChainId((_l = parsed.flags["chain"]) != null ? _l : process.env.AOMI_CHAIN_ID),
     secrets: parsed.secrets,
@@ -1792,20 +1801,29 @@ function buildCliUserState(publicKey, chainId) {
 }
 
 // src/cli/context.ts
-function getOrCreateSession(runtime) {
+function buildSessionState(runtime) {
+  const { config } = runtime;
+  return {
+    sessionId: crypto.randomUUID(),
+    baseUrl: config.baseUrl,
+    app: config.app,
+    model: config.model,
+    apiKey: config.apiKey,
+    publicKey: config.publicKey,
+    chainId: config.chain,
+    clientId: crypto.randomUUID()
+  };
+}
+function createFreshSessionState(runtime) {
+  const state = buildSessionState(runtime);
+  writeState(state);
+  return state;
+}
+function getOrCreateSession(runtime, options = {}) {
   const { config } = runtime;
-  let state = readState();
+  let state = options.fresh || config.freshSession ? createFreshSessionState(runtime) : readState();
   if (!state) {
-    state = {
-      sessionId: crypto.randomUUID(),
-      baseUrl: config.baseUrl,
-      app: config.app,
-      apiKey: config.apiKey,
-      publicKey: config.publicKey,
-      chainId: config.chain,
-      clientId: crypto.randomUUID()
-    };
-    writeState(state);
+    state = createFreshSessionState(runtime);
   } else {
     let changed = false;
     if (config.baseUrl !== state.baseUrl) {
@@ -1987,7 +2005,9 @@ async function chatCommand(runtime) {
     fatal("Usage: aomi chat <message>");
   }
   const verbose = runtime.parsed.flags["verbose"] === "true" || runtime.parsed.flags["v"] === "true";
-  const { session, state } = getOrCreateSession(runtime);
+  const { session, state } = getOrCreateSession(runtime, {
+    fresh: runtime.config.freshSession
+  });
   try {
     await ingestSecretsIfPresent(runtime, state, session.client);
     await applyRequestedModelIfPresent(runtime, session, state);
@@ -2740,7 +2760,9 @@ async function ingestSecretsCommand(runtime) {
   if (secretEntries.length === 0) {
     fatal("Usage: aomi --secret NAME=value [NAME=value ...]");
   }
-  const { session, state } = getOrCreateSession(runtime);
+  const { session, state } = getOrCreateSession(runtime, {
+    fresh: runtime.config.freshSession
+  });
   try {
     const handles = await ingestSecretsIfPresent(
       runtime,
@@ -2873,6 +2895,12 @@ async function sessionsCommand(_runtime) {
 async function sessionCommand(runtime) {
   const subcommand = runtime.parsed.positional[0];
   const selector = runtime.parsed.positional[1];
+  if (subcommand === "new") {
+    const state = createFreshSessionState(runtime);
+    console.log(`Active session set to ${state.sessionId} (new).`);
+    printDataFileLocation();
+    return;
+  }
   if (subcommand === "resume") {
     if (!selector) {
       fatal("Usage: aomi session resume <session-id|session-N|N>");
@@ -2908,7 +2936,7 @@ async function sessionCommand(runtime) {
     return;
   }
   fatal(
-    "Usage: aomi session list\n       aomi session resume <session-id|session-N|N>\n       aomi session delete <session-id|session-N|N>"
+    "Usage: aomi session list\n       aomi session new\n       aomi session resume <session-id|session-N|N>\n       aomi session delete <session-id|session-N|N>"
   );
 }
 
@@ -3840,6 +3868,7 @@ Usage:
   aomi model set <rig>  Set the active model for the current session
   aomi chain list       List supported chains
   aomi session list     List local sessions with metadata
+  aomi session new      Start a fresh local/backend session and make it active
   aomi session resume <id>
                         Resume a local session (session-id or session-N)
   aomi session delete <id>
@@ -3860,6 +3889,8 @@ Options:
   --api-key <key>       API key for non-default apps
   --app <name>          App (default: "default")
   --model <rig>         Set the active model for this session
+  --new-session         Create a fresh active session for this command
+  --chain <id>          Active chain for chat/session context
   --public-key <addr>   Wallet address (so the agent knows your wallet)
   --private-key <key>   Hex private key for signing
   --rpc-url <url>       RPC URL for transaction submission
@@ -3887,6 +3918,7 @@ Environment (overridden by flags):
   AOMI_API_KEY          API key
   AOMI_APP              App
   AOMI_MODEL            Model rig
+  AOMI_CHAIN_ID         Active chain for chat/session context
   AOMI_PUBLIC_KEY       Wallet address
   AOMI_AA_PROVIDER      AA provider: alchemy | pimlico
   AOMI_AA_MODE          AA mode: 4337 | 7702

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aomi-labs/client",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Platform-agnostic TypeScript client for the Aomi backend API",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/README.md

@@ -0,0 +1,46 @@
+# Aomi Skills
+
+Agent skills for interacting with the [Aomi](https://aomi.dev) on-chain AI transaction builder.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| [aomi-app-builder](aomi-app-builder/SKILL.md) | Build Aomi apps and plugins from APIs, specs, SDK docs, runtime interfaces, and product requirements |
+| [aomi-transact](aomi-transact/SKILL.md) | Build and execute EVM transactions through a conversational AI agent via the `aomi` CLI |
+
+## Installation
+
+```bash
+npx skills add aomi-labs/skills
+```
+
+Works with Claude Code, Cursor, Gemini CLI, VS Code Copilot, and any [Agent Skills](https://agentskills.io)-compatible tool.
+
+## Prerequisites
+
+```bash
+npm install -g @aomi-labs/client
+```
+
+For transaction signing, also install [viem](https://viem.sh):
+
+```bash
+npm install -g viem
+```
+
+## Usage
+
+Once installed, ask your agent:
+
+- "What's the price of ETH?"
+- "Swap 1 ETH for USDC on Uniswap"
+- "Send 0.1 ETH to vitalik.eth"
+
+The agent handles the full flow: chat with the backend, review pending transactions, sign and broadcast on-chain.
+
+## Resources
+
+- [@aomi-labs/client on npm](https://www.npmjs.com/package/@aomi-labs/client)
+- [Aomi Widget](https://github.com/aomi-labs/aomi-widget)
+- [Agent Skills Spec](https://agentskills.io)

package/skills/aomi-app-builder/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: aomi-app-builder
+description: >
+  Use when the user wants to build, scaffold, or update an Aomi app/plugin from
+  API docs, OpenAPI or Swagger specs, SDK docs, repository examples, endpoint
+  notes, runtime interfaces, or product requirements. Converts specs into Aomi
+  SDK crates with `lib.rs`, `client.rs`, and `tool.rs`, plus tool schemas,
+  preambles, host-interop flows, and validation steps. Prefer real product
+  integrations over docs-only helpers whenever a callable surface exists.
+compatibility: "Best when a local `aomi-sdk` checkout is available, often at `../aomi-sdk`. Falls back to bundled references when the SDK repo is not present."
+license: MIT
+allowed-tools: Bash
+metadata:
+  author: aomi-labs
+  version: "0.1"
+---
+
+# Aomi App Builder
+
+Use this skill for tasks like:
+
+- "Build an Aomi app from this OpenAPI spec."
+- "Turn these REST endpoints into an Aomi plugin."
+- "Scaffold a new Aomi SDK app for this product/API."
+- "Update an existing Aomi app to support these new endpoints."
+- "Turn these builder docs or SDK repos into an Aomi assistant."
+
+## First Read
+
+If a local `aomi-sdk` checkout exists, inspect these first:
+
+- `sdk/examples/app-template-http/src/lib.rs`
+- `sdk/examples/app-template-http/src/client.rs`
+- `sdk/examples/app-template-http/src/tool.rs`
+- `docs/repo-structure.md`
+- `docs/host-interop.md`
+- 2 or 3 relevant apps under `apps/*/src/{lib,client,tool}.rs`
+
+If the supplied docs mostly point to GitHub repositories, SDKs, or examples instead of listing public endpoints:
+
+- treat those linked repositories as the real source of truth
+- inspect their README, config examples, example commands, and RPC/API surfaces
+- check whether they expose or produce a runnable service interface such as REST, GraphQL, JSON-RPC, gRPC, webhooks, or another stable client contract
+- prefer building against that executable surface instead of wrapping the docs themselves
+- avoid inventing a public transactional API that the docs do not actually publish
+
+If the current repo is `aomi-widget`, also inspect:
+
+- `apps/landing/content/examples/*.mdx`
+- `apps/landing/content/guides/build/**/*.mdx`
+
+If the SDK repo is not available, read:
+
+- [references/aomi-sdk-patterns.md](references/aomi-sdk-patterns.md)
+- [references/spec-to-tools.md](references/spec-to-tools.md)
+
+## Default Workflow
+
+1. Identify the product surface:
+   - What external API, SDK, repo, or spec is the source of truth?
+   - What concrete callable surface exists: REST, GraphQL, JSON-RPC, gRPC, webhook, CLI contract, or something else?
+   - Is there a real target we can point the app at: hosted service, self-hosted node, local example stack, or customer-provided endpoint?
+   - Is this read-only, execution-oriented, or mixed?
+   - What auth/env vars are required?
+   - What user state must come from the host or caller?
+   - Is this actually a public end-user API, a standard client interface exposed by a runtime/example app, or only builder-facing documentation?
+2. Describe the intended user-facing toolset before implementation:
+   - list the proposed tools by name
+   - say what user intent each tool serves
+   - call out which tools are read-only, which prepare actions, and which write or submit
+   - mention any expected target URL, runtime, or host dependency
+   - if the toolset is uncertain, surface the uncertainty before coding
+   - identify the primary user workflow the app should make easy first
+   - keep the first pass to the smallest sufficient toolset for that workflow unless the user asked for broader API coverage
+3. Reduce the spec into semantically meaningful tools.
+4. Scaffold or update the Aomi app using the standard file split:
+   - `lib.rs` for manifest and preamble
+   - `client.rs` for HTTP client, auth, models, and normalization
+   - `tool.rs` for `DynAomiTool` implementations
+5. Write the preamble around actual tool behavior, confirmation rules, and any host handoff.
+6. Validate with the SDK build flow and add focused tests when logic is non-trivial.
+
+## Tool Design Rules
+
+- First decide what kind of app this should be:
+  - product client
+  - execution assistant
+  - builder / SDK / runtime assistant
+- Before implementing, state the proposed toolset in concrete user-facing terms. This is part of the design, not optional polish.
+- Prefer the smallest sufficient toolset that makes the primary user workflow work end to end.
+- If there are multiple plausible integration targets, briefly state which one you are choosing and why before coding.
+- Prefer tools that interact with an actual product surface over tools that merely restate documentation.
+- A hosted API is not required. A self-hosted service, local example stack, standard RPC server, or other runnable interface still counts as a real integration target.
+- If the source material is SDK- or architecture-heavy, first ask whether it produces a service that clients call. If yes, build the client for that service.
+- Only fall back to a builder-oriented or docs-oriented tool surface when no stable executable target is available.
+- Do not mirror every endpoint 1:1 unless that is actually the cleanest model-facing API or the user explicitly asked for broad coverage.
+- Prefer 3 to 8 tools with clear user intent boundaries such as `search_*`, `get_*`, `build_*`, `submit_*`, `list_*`, or `resolve_*`.
+- Prefer intent-shaped tool names over raw protocol or transport names when practical.
+- Aggregate noisy upstream endpoints behind a smaller tool surface when the model does not need the raw distinction.
+- Prefer typed arguments over raw JSON string blobs when the primary workflow can be modeled cleanly that way.
+- Separate core tools from escape hatches. A generic fallback tool such as `*_rpc` or `*_raw` is fine, but it should not replace a clean core workflow.
+- Keep args typed and documented with `JsonSchema`. Field doc comments are model-facing and matter.
+- Return stable JSON with predictable keys. Normalize upstream naming, paging, and inconsistent shapes inside `client.rs` or helper functions.
+- Convert upstream errors into short actionable messages. Do not leak raw HTML, secrets, or giant payload dumps.
+
+## File Responsibilities
+
+### `lib.rs`
+
+- Keep it easy to scan.
+- Define `PREAMBLE` or a small `build_preamble()` hook.
+- Register tools with `dyn_aomi_app!`.
+- Only keep manifest-level wiring here.
+
+### `client.rs`
+
+- Own the app struct, HTTP client, auth headers, env vars, typed models, and response normalization.
+- Prefer `reqwest::blocking::Client` with explicit timeouts for sync tools, matching the current SDK examples.
+- Keep third-party API quirks here instead of spreading them across tool implementations.
+
+### `tool.rs`
+
+- Implement `DynAomiTool`.
+- Use descriptions that tell the model when to call the tool, not just what endpoint it wraps.
+- Map normalized client results into concise JSON results.
+- Use `DynToolCallCtx` when host state such as connected wallet, session state, or caller attributes is needed.
+
+## Preamble Rules
+
+Write the preamble from the app's real contract:
+
+- Define role, capabilities, workflow, and guardrails.
+- Mention tool order for multi-step flows.
+- State explicit confirmation requirements before write actions.
+- If dates matter, include the current date or instruct the app to use exact dates.
+- If the app relies on host wallet/signing tools, say that clearly and do not imply hidden infrastructure.
+
+For deeper patterns and examples, read [references/aomi-sdk-patterns.md](references/aomi-sdk-patterns.md).
+
+## Host Interop And Execution
+
+For execution-oriented apps:
+
+- Follow the public host conventions from `docs/host-interop.md`.
+- Do not invent private namespaces or internal fallback behavior.
+- When the next step belongs to the host wallet or signer, return machine-readable `SYSTEM_NEXT_ACTION` guidance.
+- Preserve exact transaction or signature args when a downstream host tool must execute them.
+- Do not claim a write succeeded until the upstream API submit step has actually completed.
+
+## Validation
+
+When working inside `aomi-sdk`:
+
+- Scaffold with `cargo run -p xtask -- new-app <name>` if starting from scratch, or copy `sdk/examples/app-template-http`.
+- Build the plugin with `cargo run -p xtask -- build-aomi --app <name>`.
+- If `build-aomi` reports zero built plugins for a brand new app, check whether the new `apps/<name>/Cargo.toml` is still untracked. The current xtask prefers `git ls-files` discovery for app manifests.
+- For a direct compile signal on an untracked app, use `cargo build --manifest-path apps/<name>/Cargo.toml`.
+- If the app has meaningful branching or normalization logic, add unit tests with `aomi_sdk::testing::{TestCtxBuilder, run_tool, run_async_tool}`.
+- If a real target is available, validate the app with a short ladder:
+  - compile/build
+  - connectivity check
+  - one representative read flow
+  - one representative write or submit flow when applicable
+  - post-write verification such as status, receipt, or refreshed state
+- Prefer proving one end-to-end user scenario over checking many disconnected endpoints.
+
+When the task also touches docs or demos in `aomi-widget`, update the relevant examples or guides to match the new app behavior.
+
+## Output Expectations
+
+Aim to leave behind:
+
+- a coherent Aomi app crate or patch
+- typed tool args and strong descriptions
+- a preamble that explains the tool contract and rules
+- stable JSON outputs for the host/model
+- an app that can point at a real product surface when one exists
+- a short validation pass or a clear note about what could not be verified

package/skills/aomi-app-builder/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Aomi App Builder"
+  short_description: "Build Aomi apps from APIs and specs"
+  default_prompt: "Use $aomi-app-builder to turn this API, OpenAPI spec, or product brief into an Aomi SDK app/plugin with a clean tool surface, preamble, and validation plan."

package/skills/aomi-app-builder/references/aomi-sdk-patterns.md

@@ -0,0 +1,191 @@
+# Aomi SDK Patterns
+
+These patterns come from the SDK example and the inspected public apps in `aomi-sdk`.
+
+## Canonical Layout
+
+Use this split unless there is a strong reason not to:
+
+```text
+apps/my-app/
+├─ Cargo.toml
+└─ src/
+   ├─ lib.rs
+   ├─ client.rs
+   └─ tool.rs
+```
+
+- `lib.rs`: manifest, preamble, `dyn_aomi_app!`
+- `client.rs`: app struct, HTTP client, auth, models, helpers
+- `tool.rs`: `DynAomiTool` impls and user-facing tool surface
+
+## Minimal Manifest Shape
+
+```rust
+use aomi_sdk::*;
+
+mod client;
+mod tool;
+
+const PREAMBLE: &str = r#"## Role
+You are ...
+"#;
+
+dyn_aomi_app!(
+    app = client::MyApp,
+    name = "my-app",
+    version = "0.1.0",
+    preamble = PREAMBLE,
+    tools = [
+        client::SearchThing,
+        client::GetThing,
+    ]
+);
+```
+
+Keep `lib.rs` small. The manifest should be easy to audit at a glance.
+
+## What The Real Apps Show
+
+### `sdk/examples/app-template-http`
+
+Use as the default baseline for read-only HTTP APIs.
+
+- Simple `reqwest::blocking` client
+- Clean typed args
+- Small tool surface
+- Straightforward JSON normalization
+
+### `apps/x`
+
+Use this pattern when the upstream API:
+
+- needs an env-backed API key
+- has a wrapper response envelope
+- benefits from normalized data models and formatting helpers
+
+Notable conventions:
+
+- auth env vars live in `client.rs`
+- logical API failures are normalized before reaching tools
+- tools return concise, model-friendly JSON
+
+### `apps/polymarket`
+
+Use this pattern when the app needs:
+
+- multiple upstream API surfaces
+- dynamic preamble context such as exact current date
+- intent resolution before execution
+- multi-step flows with explicit user confirmation
+
+Notable conventions:
+
+- preamble explains exact flow order
+- tool surface separates search, details, intent resolution, preview, and submit
+- results include next-step hints without hiding uncertainty
+
+### `apps/khalani`
+
+Use this pattern when execution must hand off to host wallet tools.
+
+Notable conventions:
+
+- app tools never send the wallet request directly
+- build tools return `SYSTEM_NEXT_ACTION`
+- preamble tells the model to preserve exact host args and continue after wallet callbacks
+
+### Executable product integrations
+
+When the source material is mostly SDK docs, example repos, runtime notes, or architecture docs, first check whether it exposes or produces a client-facing interface such as:
+
+- REST or GraphQL
+- JSON-RPC
+- gRPC
+- webhooks
+- a stable CLI request/response contract
+- a local example service or reference node
+
+If such a surface exists:
+
+- build the app against that executable interface
+- treat the SDK, example repo, and docs as implementation references
+- expose user-useful operations against the real service, not just summaries of the docs
+- validate with at least one real call when possible
+
+### Builder-oriented fallbacks
+
+Use a builder-oriented shape only when the source material is mostly:
+
+- SDK documentation
+- example repositories
+- architecture notes
+- runtime / RPC references
+- config files and quickstarts
+
+In that case:
+
+- do not pretend there is a public swap, quote, or portfolio API unless the source really documents one
+- do not hide the absence of a real integration target
+- prefer tools such as `list_*_resources`, `get_*_overview`, `get_*_quickstart`, `get_*_rpc_surface`, or `get_*_network_defaults`
+- make the preamble explicit that the app is a builder assistant, not an end-user trading agent
+- say clearly what would be needed to upgrade the app into a real client later, such as a base URL, running example service, or customer endpoint
+
+## Tool Authoring Checklist
+
+Every tool should answer these:
+
+- What user intent does it serve?
+- What exact name should the model call?
+- What fields does the model need to provide?
+- What result shape will be easiest for the model to reason over?
+- If the upstream API is inconsistent, where will normalization happen?
+
+Prefer names like:
+
+- `search_*`
+- `get_*`
+- `list_*`
+- `resolve_*`
+- `build_*`
+- `submit_*`
+
+## Client Conventions
+
+Keep these in `client.rs` whenever possible:
+
+- base URLs
+- auth headers
+- shared request helpers
+- response envelopes
+- normalization helpers
+- typed upstream models
+
+Prefer short actionable errors such as:
+
+- `X_API_KEY environment variable not set`
+- `Gamma API error 404: ...`
+- `Failed to parse markets: ...`
+
+## Validation Commands
+
+Inside `aomi-sdk`, the repo documents these as the standard loop:
+
+```bash
+cargo run -p xtask -- new-app my-app
+cargo run -p xtask -- build-aomi --app my-app
+```
+
+One caveat from practice:
+
+- `xtask build-aomi` currently prefers tracked `apps/*/Cargo.toml` files via `git ls-files`
+- a brand new untracked app can therefore compile fine but still be skipped by `build-aomi`
+- use `cargo build --manifest-path apps/my-app/Cargo.toml` for an immediate compile check before the new app is tracked
+
+For focused logic tests, use the SDK test helpers:
+
+```rust
+use aomi_sdk::testing::{TestCtxBuilder, run_tool};
+```
+
+Use `run_async_tool` only when the tool is actually async.

package/skills/aomi-app-builder/references/spec-to-tools.md

@@ -0,0 +1,149 @@
+# Spec To Tools
+
+Use this when the input is an OpenAPI document, Swagger spec, Postman collection, endpoint list, or product brief.
+
+It also applies when the "spec" is really one of these:
+
+- SDK docs that link out to source repos
+- runtime / RPC documentation
+- example applications
+- architecture notes with concrete commands, configs, and method names
+
+## Extract First
+
+Before writing code, pull out:
+
+- base URL and authentication scheme
+- the actual integration target the finished app should call
+- main entities and identifiers
+- read operations vs write operations
+- pagination, filters, and search parameters
+- user-specific inputs the host must provide
+- confirmation or safety requirements
+- rate limits, async jobs, and polling behavior
+- common error shapes
+- whether the docs actually publish an end-user API or mainly document a builder workflow
+
+If a detail is missing, do not invent it. Leave a TODO or ask for the smallest missing piece.
+
+## Find The Real Integration Target
+
+Prefer the nearest executable product surface over explanatory documentation.
+
+Ask these questions early:
+
+- What will the finished app actually call?
+- Is there a concrete service contract such as REST, GraphQL, JSON-RPC, gRPC, webhook delivery, or a stable CLI protocol?
+- Is the target hosted, self-hosted, customer-provided, or only available through a local example stack?
+- If the source is an SDK or example project, does it expose a service that clients use after the builder sets it up?
+
+Useful rule of thumb:
+
+- If users can point the app at a running thing, build the client for that thing.
+- If no running thing exists yet, only then consider a builder or reference assistant.
+
+## Decide The App Type Early
+
+Choose one of these before naming tools:
+
+- **Product client**: the source exposes a real callable product surface, even if it is self-hosted or example-backed.
+- **Execution assistant**: the docs expose quote/build/submit flows and host or wallet handoff matters.
+- **Builder assistant**: the docs mostly explain how to build on top of a network, SDK, or runtime.
+
+Builder assistants are valid outcomes, but they are the fallback, not the default. If the docs mostly point to SDK repos and example stacks, first check whether those repos produce a runnable interface that the app can call.
+
+## Map Endpoints To Model-Facing Tools
+
+Do not default to one tool per endpoint. Instead, group endpoints by user intent.
+
+Before implementation, write down the proposed toolset explicitly:
+
+- tool name
+- what the user would ask for that should trigger it
+- key inputs
+- key outputs
+- whether it reads, prepares, or writes
+- whether it depends on a live target, wallet, signer, or host callback
+
+Treat this as a required checkpoint. If the proposed toolset is weak, too docs-oriented, too endpoint-shaped, or not clearly tied to user intent, revise it before writing code.
+
+When choosing the first implementation:
+
+- optimize for the primary user workflow first
+- keep the toolset as small as possible while still making that workflow work end to end
+- prefer app-specific high-value actions over broad protocol coverage when the source makes the important workflow obvious
+- avoid schema or discovery tools unless they are needed to support the chosen workflow
+- only mirror the wider API surface if the user asked for broad coverage
+
+Good mappings:
+
+- several lookup endpoints -> `search_*` or `get_*`
+- multiple list and detail calls -> `resolve_*` then `get_*`
+- quote + build + submit endpoints -> `get_*_quote`, `build_*`, `submit_*`
+- create side effects -> preview/build first, then explicit submit after confirmation
+- standard runtime interfaces -> wrap the standard methods first, then add extension hooks or custom methods
+- SDK + example repo + config + RPC docs -> `list_*_resources`, `get_*_overview`, `get_*_quickstart`, `get_*_rpc_surface`, `get_*_defaults`
+- example-backed transactional app -> one health/connectivity tool, a few read tools for key state, one write tool for the main action, and one verification tool for the outcome
+
+Less useful mappings:
+
+- raw REST verbs as tool names
+- exposing every transport detail directly to the model
+- returning unnormalized upstream payloads when only 20 percent of the fields matter
+- choosing a docs-summary tool surface when a real client could be built instead
+- inventing public user actions that are not actually documented by the source
+- building a large first-pass toolset before proving the primary user workflow
+
+## Preamble Rubric
+
+A strong preamble usually includes:
+
+- `## Role`
+- `## Capabilities`
+- `## Workflow`
+- `## Rules`
+
+For execution apps, spell out:
+
+- when confirmation is required
+- which tool comes first
+- which tool hands off to the wallet or host
+- what must be preserved exactly between steps
+
+## Output Shape Rubric
+
+Return the minimum stable JSON the model needs for the next step.
+
+Good result shapes often include:
+
+- a top-level echo of the key input
+- normalized identifiers
+- concise summaries
+- arrays of candidate objects
+- `requires_selection`, `selection_reason`, or `next_step_hint` when ambiguity remains
+- `SYSTEM_NEXT_ACTION` when the host must take over
+
+Avoid:
+
+- leaking auth credentials
+- giant raw payloads
+- mixed naming conventions from multiple upstream APIs
+- claiming success before the final submit step succeeds
+
+## Suggested Build Loop
+
+1. Read the spec and summarize the app contract.
+2. Identify the concrete service or runtime target.
+3. Propose the tool surface in concrete user-facing terms.
+4. Scaffold or patch `lib.rs`, `client.rs`, and `tool.rs`.
+5. Normalize auth, models, and errors in `client.rs`.
+6. Implement small, strongly typed tools.
+7. Build and test.
+8. If the target is available, verify a short end-to-end scenario:
+   - connectivity
+   - key read
+   - key write when applicable
+   - post-write verification
+9. Update docs or examples if the repo includes them.
+
+If the app is brand new in `aomi-sdk`, remember that `cargo run -p xtask -- build-aomi --app <name>` may skip an untracked app. A direct `cargo build --manifest-path apps/<name>/Cargo.toml` is the fastest compile check until the manifest is tracked.

package/skills/aomi-transact/SKILL.md

@@ -36,6 +36,7 @@ backend. Local session data lives under `AOMI_STATE_DIR` or `~/.aomi`.
 - If the user provides a private key or API key, do not repeat it back unless they explicitly ask for that exact value to be reformatted.
 - Prefer `aomi --secret NAME=value ...` over stuffing provider API keys into normal chat text.
 - Do not sign anything unless the CLI has actually queued a wallet request and you can identify its `tx-N` ID.
+- When starting work from a new Codex or assistant chat thread, default the first Aomi command to `--new-session` unless the user explicitly wants to continue an existing session.
 - If `PRIVATE_KEY` is set in the environment, do not also pass `--private-key` unless you intentionally want to override the environment value.
 - `--public-key` must match the address derived from the signing key. If they differ, `aomi sign` will update the session to the signer address.
 - Private keys must start with `0x`. Add the prefix if missing.
@@ -73,7 +74,7 @@ tx-N`, there is nothing to sign yet.
 Use these when the user does not need signing:
 
 ```bash
-aomi chat "<message>"
+aomi chat "<message>" --new-session
 aomi chat "<message>" --verbose
 aomi tx
 aomi log
@@ -92,8 +93,10 @@ aomi session resume <id>
 Notes:
 
 - Quote the chat message.
+- On the first command in a new Codex or assistant thread, prefer `--new-session` so old local/backend state does not bleed into the new task.
 - Use `--verbose` when debugging tool calls or streaming behavior.
 - Pass `--public-key` on the first wallet-aware chat if the backend needs the user's address.
+- For chain-specific requests, prefer `--chain <id>` on the command itself. Use `AOMI_CHAIN_ID=<id>` only when multiple consecutive commands should stay on the same chain.
 - Use `aomi secret list` to inspect configured secret handles for the active session.
 - `aomi close` wipes the active local session pointer and starts a fresh thread next time.
 
@@ -103,8 +106,8 @@ Use this when the backend or selected app needs API keys, provider tokens, or
 other named secrets for the current session:
 
 ```bash
-aomi --secret ALCHEMY_API_KEY=sk_live_123
-aomi --secret ALCHEMY_API_KEY=sk_live_123 chat "simulate a swap on Base"
+aomi --secret ALCHEMY_API_KEY=sk_live_123 --new-session
+aomi --secret ALCHEMY_API_KEY=sk_live_123 chat "simulate a swap on Base" --new-session
 aomi secret list
 aomi secret clear
 ```
@@ -123,7 +126,7 @@ Use the first chat turn to give the agent the task and, if relevant, the wallet
 address and chain:
 
 ```bash
-aomi chat "swap 1 ETH for USDC" --public-key 0xYourAddress --chain 1
+aomi chat "swap 1 ETH for USDC" --new-session --public-key 0xYourAddress --chain 1
 ```
 
 If the user wants a different backend app or chain, pass them explicitly on the
@@ -210,7 +213,7 @@ aomi close
 ### Chat
 
 ```bash
-aomi chat "<message>"
+aomi chat "<message>" --new-session
 aomi chat "<message>" --verbose
 aomi chat "<message>" --model <rig>
 aomi chat "<message>" --public-key 0xYourAddress --chain 1
@@ -218,9 +221,11 @@ aomi chat "<message>" --app khalani --chain 137
 ```
 
 - Quote the message.
+- On the first command in a new Codex or assistant thread, prefer `--new-session`.
 - Use `--verbose` to stream tool calls and agent output.
 - Use `--public-key` on the first wallet-aware message.
 - Use `--app`, `--model`, and `--chain` to change the active context for the next request.
+- Prefer `--chain <id>` for one-off chain-specific requests. Use `AOMI_CHAIN_ID=<id>` when several consecutive commands should share the same chain context.
 
 ### Transaction Inspection
 
@@ -265,6 +270,7 @@ aomi chain list
 
 ```bash
 aomi session list
+aomi session new
 aomi session resume <id>
 aomi session delete <id>
 aomi close