Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The coordinator: one plain-language message in, a run of specialist steps out.
//
// start() load remembered preferences, build and freeze the plan, persist
// it, then advance.
// advance() under a short lease, run every queued step whose dependencies are
// settled. A step that would sign, transfer, launch or exceed the
// cap stops at needs_approval with the exact payload, its hash and
// the confirmation table. When nothing else can move, the run waits
// on the owner (awaiting_approval) or finishes with a summary.
// decide() the owner's approve or deny. Approve re-checks the payload hash
// and the plan fingerprint, executes exactly that payload once, and
// resumes the run. A mirrored step decides through the approval
// inbox, so a decision from /approvals, push or Telegram resumes the
// same run through approval-executor.js.
//
// Every state change is an event (persisted, then published to live streams),
// so the chat renders the same story live, after a reload, or from a decision
// taken on another device.
//
// The store, specialists, bridge, squad resolver and preference loader are
// injected, which is how tests/team-chat-escalation.test.js drives this exact
// code against an in-memory store.
import { buildPlan, mintLabel, describeEntryCondition } from './plan.js';
import { planFingerprint, sha256Hex, scanForInjection } from './untrusted.js';
import { memberForRole } from './squad.js';
import { publish } from './bus.js';
export const TERMINAL = Object.freeze(['done', 'failed', 'skipped', 'denied', 'expired']);
const APPROVAL_TTL_MS = 15 * 60 * 1000;
const ORDER_TTL_MS = 24 * 60 * 60 * 1000;
const LEASE_MS = 120_000;
const ROLE_TITLE = { coordinator: 'Coordinator', researcher: 'Researcher', entry: 'Entry', trader: 'Trader', launcher: 'Launcher' };
function shortAddr(a) {
const s = String(a || '');
return s.length > 12 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
}
function fmtSol(v) {
const n = Number(v);
return Number.isFinite(n) ? `${n.toLocaleString('en-US', { maximumFractionDigits: n >= 1 ? 4 : 6 })} SOL` : 'n/a';
}
function chainLabel(network) {
return network === 'devnet' ? 'Solana devnet' : 'Solana mainnet';
}
// Owners paste coin pages into chat. When part of a message reads like orders
// aimed at an AI, say so: the plan holds only the steps listed, and anything
// that moves funds still stops for an approval that names the recipient.
function pastedTextNote(text, steps) {
if (!scanForInjection(text).suspicious) return [];
const moves = steps.some((s) => s.kind === 'transfer' || s.kind === 'trade');
return [`Part of your message reads like instructions aimed at an AI, often pasted from a coin page. I only planned the steps listed below${moves ? ', and anything that moves funds still waits for your approval' : ''}.`];
}
/** The owner-facing view of one step row. */
export function publicStep(row) {
const a = row.approval;
return {
id: row.id,
key: row.step_key,
idx: row.idx,
role: row.role,
role_title: ROLE_TITLE[row.role] || row.role,
kind: row.kind,
title: row.title,
params: row.params,
depends_on: row.depends_on || [],
agent_id: row.agent_id,
status: row.status,
evidence: row.evidence || {},
result: row.result || null,
approval: a
? {
action: a.payload?.action,
payload: a.payload,
payload_hash: a.payload_hash,
summary: a.summary,
table: a.table,
gate_reasons: a.gate_reasons,
risk_notes: a.risk_notes,
expires_at: a.expires_at,
mirrored: Boolean(row.approval_request_id),
inbox_url: a.inbox_url || null,
handoff_url: a.handoff_url || null,
}
: null,
error: row.error,
started_at: row.started_at,
finished_at: row.finished_at,
};
}
/** The deterministic end-of-run report: one line per specialist step. No model writes it. */
export function summarizeRun(steps) {
const lines = steps.map((s) => {
const text = s.status === 'done'
? s.result?.summary || s.evidence?.summary || s.title
: s.status === 'needs_approval'
? `Waiting for your approval: ${s.approval?.summary || s.title}`
: s.status === 'skipped'
? `Skipped: ${s.error || 'its preconditions were not met.'}`
: s.status === 'denied'
? 'You declined this step. Nothing was signed.'
: s.status === 'expired'
? 'The approval window closed. Nothing was signed; ask again for a fresh quote.'
: s.status === 'failed'
? `Failed: ${s.error || 'unknown error'}`
: s.title;
return { step_id: s.id, key: s.step_key, role: s.role, role_title: ROLE_TITLE[s.role] || s.role, title: s.title, status: s.status, text: String(text).slice(0, 400), receipt: s.result?.receipt || null };
});
const count = (st) => steps.filter((s) => s.status === st).length;
const parts = [];
if (count('done')) parts.push(`${count('done')} done`);
if (count('needs_approval')) parts.push(`${count('needs_approval')} waiting for you`);
if (count('skipped')) parts.push(`${count('skipped')} skipped`);
if (count('failed')) parts.push(`${count('failed')} failed`);
if (count('denied')) parts.push(`${count('denied')} declined`);
if (count('expired')) parts.push(`${count('expired')} expired`);
return { headline: `${steps.length} step${steps.length === 1 ? '' : 's'}: ${parts.join(', ') || 'nothing ran'}.`, lines };
}
function tokenLabel(mint) {
const label = mintLabel(mint);
return label.startsWith('$') ? `${label} (${shortAddr(mint)})` : shortAddr(mint);
}
/** Build the approval for a quoted trade. The payload is exactly what executes. */
export function buildTradeApproval({ run, squad, step, quoted, cap, requested, riskNotes = [] }) {
const p = step.params;
const isBuy = p.side === 'buy';
const gate = ['signs'];
if (isBuy && cap != null && requested > cap) gate.push('exceeds_cap');
const payload = {
action: 'trade',
side: p.side,
mint: p.mint,
amount: quoted.amount,
amount_unit: isBuy ? 'SOL' : quoted.amount === 'max' ? 'max' : 'token',
slippage_bps: quoted.slippage_bps,
network: run.network,
mode: run.mode,
agent_id: squad.policy_agent_id,
squad_id: squad.id,
run_id: run.id,
step_id: step.id,
};
const q = quoted.quote;
const wallet = q?.wallet_address || quoted.agent?.meta?.solana_address || null;
const amountText = isBuy ? fmtSol(quoted.amount) : quoted.amount === 'max' ? `All ${mintLabel(p.mint)} held` : `${Number(quoted.amount).toLocaleString('en-US')} ${mintLabel(p.mint)}`;
const table = [
{ label: 'Action', value: `${isBuy ? 'Buy' : 'Sell'} ${mintLabel(p.mint)}` },
{ label: 'Amount', value: amountText + (q?.usd_value ? ` (~$${Number(q.usd_value).toFixed(2)})` : '') },
{ label: 'Token', value: tokenLabel(p.mint), full: p.mint },
{ label: isBuy ? 'Tokens go to' : 'SOL goes to', value: wallet ? `${squad.name} Trader wallet (${shortAddr(wallet)})` : `${squad.name} Trader wallet (created on first trade)`, full: wallet },
{ label: 'Chain', value: chainLabel(run.network) },
{ label: 'Mode', value: run.mode === 'live' ? 'Live: signs from the Trader wallet' : 'Paper: simulated against the live quote, never signs' },
];
if (q?.venue) table.push({ label: 'Venue', value: q.venue });
if (q && isBuy && q.expected_tokens_out != null) table.push({ label: 'Expected out', value: `${Number(q.expected_tokens_out).toLocaleString('en-US', { maximumFractionDigits: 2 })} tokens` });
if (q && !isBuy && q.expected_sol_out != null) table.push({ label: 'Expected out', value: fmtSol(q.expected_sol_out) });
if (q?.price_impact_pct != null) table.push({ label: 'Price impact', value: `${Number(q.price_impact_pct).toFixed(2)}%` });
table.push({ label: 'Max slippage', value: `${(quoted.slippage_bps / 100).toFixed(2)}%` });
if (q?.platform_fee?.amount_sol != null) table.push({ label: 'Platform fee', value: fmtSol(q.platform_fee.amount_sol) });
const notes = [...riskNotes];
if (gate.includes('exceeds_cap')) notes.unshift(`You asked for ${fmtSol(requested)}; the per-trade cap is ${fmtSol(cap)}, so this approval is for the cap.`);
if (quoted.note) notes.push(quoted.note);
const summary = `${isBuy ? 'Buy' : 'Sell'} ${amountText} ${isBuy ? `of ${mintLabel(p.mint)} ` : ''}on ${chainLabel(run.network)} (${run.mode === 'live' ? 'live' : 'paper'})`;
return {
payload,
payload_hash: sha256Hex(payload),
summary,
table,
gate_reasons: gate,
risk_notes: notes.slice(0, 8),
amount_usd: q?.usd_value ?? null,
token_label: mintLabel(p.mint),
wallet,
expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
};
}
/** Build the approval for a standing conditional order (live mode, condition not met yet). */
export function buildOrderApproval({ run, squad, step, condition, amount, slippageBps, cap, requested, wallet }) {
const p = step.params;
const isBuy = p.side === 'buy';
const gate = ['signs'];
if (isBuy && cap != null && requested > cap) gate.push('exceeds_cap');
const orderExpires = new Date(Date.now() + ORDER_TTL_MS).toISOString();
const payload = {
action: 'order',
side: p.side,
mint: p.mint,
amount,
amount_unit: isBuy ? 'SOL' : amount === 'max' ? 'max' : 'token',
slippage_bps: slippageBps,
condition,
order_expires_at: orderExpires,
network: run.network,
mode: 'live',
agent_id: squad.policy_agent_id,
squad_id: squad.id,
run_id: run.id,
step_id: step.id,
};
const amountText = isBuy ? fmtSol(amount) : amount === 'max' ? `All ${mintLabel(p.mint)} held` : `${Number(amount).toLocaleString('en-US')} ${mintLabel(p.mint)}`;
const table = [
{ label: 'Action', value: `Standing order: ${isBuy ? 'buy' : 'sell'} when ${describeEntryCondition(condition)}` },
{ label: 'Amount', value: amountText },
{ label: 'Token', value: tokenLabel(p.mint), full: p.mint },
{ label: isBuy ? 'Tokens go to' : 'SOL goes to', value: wallet ? `${squad.name} Trader wallet (${shortAddr(wallet)})` : `${squad.name} Trader wallet`, full: wallet },
{ label: 'Chain', value: chainLabel(run.network) },
{ label: 'Mode', value: 'Live: the order worker signs from the Trader wallet when the condition holds' },
{ label: 'Expires', value: '24 hours after you approve' },
{ label: 'Max slippage', value: `${(slippageBps / 100).toFixed(2)}%` },
];
const notes = ['The entry condition is not met yet, so the Trader proposes a standing order instead of buying now.'];
if (gate.includes('exceeds_cap')) notes.unshift(`You asked for ${fmtSol(requested)}; the per-trade cap is ${fmtSol(cap)}, so this order is for the cap.`);
return {
payload,
payload_hash: sha256Hex(payload),
summary: `Standing ${isBuy ? 'buy' : 'sell'} of ${amountText}${isBuy ? ` of ${mintLabel(p.mint)}` : ''} when ${describeEntryCondition(condition)}`,
table,
gate_reasons: gate,
risk_notes: notes,
amount_usd: null,
token_label: mintLabel(p.mint),
wallet,
expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
};
}
function buildHandoffApproval({ run, squad, step, action, table, summary, handoffUrl, extra = {} }) {
const payload = { action, ...extra, network: run.network, squad_id: squad.id, run_id: run.id, step_id: step.id, handoff_url: handoffUrl };
return {
payload,
payload_hash: sha256Hex(payload),
summary,
table,
gate_reasons: [action === 'launch' ? 'launches' : 'transfers'],
risk_notes: ['Approving opens the page where you review and sign this yourself. The coordinator never signs it.'],
handoff_url: handoffUrl,
expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
};
}
/**
* @param {object} deps
* @param {object} deps.store createSqlStore() or createMemoryStore()
* @param {object} deps.specialists the specialists.js module (or a test double)
* @param {object|null} deps.bridge createApprovalsBridge(), or null for chat-only approvals
* @param {Function} deps.resolveSquad (id, userId) => squad
* @param {Function} deps.loadPrefs (agentId, squadId) => { values, entries }
* @param {string} deps.userId
* @param {object} [deps.req]
* @param {boolean} [deps.useModel] let the model propose a plan (validated either way)
*/
export function createRunner({ store, specialists, bridge = null, resolveSquad, loadPrefs, userId, req = null, useModel = true }) {
async function emit(runId, stepId, kind, payload) {
const ev = await store.appendEvent(runId, stepId, kind, payload);
publish(runId, ev);
return ev;
}
async function emitStep(row) {
return emit(row.run_id, row.id, 'step', { step: publicStep(row) });
}
function failMessage(e, role) {
if (e?.isStepError) return { code: e.code, message: e.message, detail: e.detail || null };
console.error('[team-chat] step failed', e?.stack || e?.message);
return { code: 'internal_error', message: `The ${ROLE_TITLE[role] || role} hit an unexpected error. Nothing was signed.`, detail: null };
}
// ── start ──────────────────────────────────────────────────────────────────
async function start({ squad, utterance, mode = 'paper', onCreated = null }) {
const text = String(utterance || '').trim().slice(0, 2000);
const prefs = await loadPrefs(squad.policy_agent_id, squad.id);
const built = await buildPlan(text, { prefs: prefs.values, useModel, track: { userId, agentId: squad.policy_agent_id, tool: 'team-chat-plan' } });
const steps = built.steps.map((s) => ({ ...s, agent_id: memberForRole(squad, s.role)?.agent_id || squad.policy_agent_id }));
const plan = {
steps: steps.map(({ key, kind, role, title, params, depends_on }) => ({ key, kind, role, title, params, depends_on })),
notes: [...(built.notes || []), ...pastedTextNote(text, steps)],
clarify: built.clarify || null,
planner: built.planner,
prefs: prefs.values,
};
plan.fingerprint = planFingerprint(plan);
const run = await store.createRun({ userId, squad, utterance: text, mode: mode === 'live' ? 'live' : 'paper', plan, planner: built.planner });
if (onCreated) await onCreated(run);
const rows = await store.insertSteps(run.id, steps);
await emit(run.id, null, 'run', { run_id: run.id, status: run.status, mode: run.mode, network: run.network, utterance: text, created_at: run.created_at });
await emit(run.id, null, 'memory', { entries: prefs.entries });
await emit(run.id, null, 'plan', { steps: rows.map(publicStep), notes: plan.notes, clarify: plan.clarify, planner: plan.planner });
if (!rows.length) {
await store.updateRun(run.id, { status: 'done', summary: { headline: plan.clarify || 'Nothing to do.', lines: [] } });
await emit(run.id, null, 'summary', { status: 'done', headline: plan.clarify || 'Nothing to do.', lines: [], clarify: true });
return { run: await store.getRunById(run.id), squad };
}
await advance(run.id, { squad });
return { run: await store.getRunById(run.id), squad };
}
// ── advance ────────────────────────────────────────────────────────────────
async function expireStale(run, steps) {
const now = Date.now();
let changed = false;
for (const s of steps) {
if (s.status !== 'needs_approval' || !s.approval?.expires_at) continue;
if (new Date(s.approval.expires_at).getTime() > now) continue;
const row = await store.claimStep(s.id, ['needs_approval'], 'expired', { error: 'The approval window closed before a decision. Nothing was signed.' });
if (row) {
changed = true;
await emitStep(row);
}
}
return changed;
}
async function syncInbox(steps) {
if (!bridge) return false;
const mirrored = steps.filter((s) => s.status === 'needs_approval' && s.approval_request_id);
if (!mirrored.length) return false;
const statuses = await bridge.statuses(mirrored.map((s) => s.approval_request_id));
let changed = false;
for (const s of mirrored) {
const st = statuses.get(s.approval_request_id);
if (st !== 'denied' && st !== 'expired') continue;
const row = await store.claimStep(s.id, ['needs_approval'], st, { error: st === 'denied' ? 'Declined from the approval inbox. Nothing was signed.' : 'The approval expired in the inbox. Nothing was signed.' });
if (row) {
changed = true;
await emitStep(row);
}
}
return changed;
}
async function finalize(run, steps) {
const open = steps.filter((s) => !TERMINAL.includes(s.status));
if (!open.length) {
const summary = summarizeRun(steps);
const allFailed = steps.every((s) => s.status === 'failed');
const status = allFailed ? 'failed' : 'done';
if (run.status !== status) {
await store.updateRun(run.id, { status, summary });
await emit(run.id, null, 'summary', { status, ...summary });
}
return status;
}
const waiting = open.every((s) => s.status === 'needs_approval');
if (waiting && run.status !== 'awaiting_approval') {
const summary = summarizeRun(steps);
await store.updateRun(run.id, { status: 'awaiting_approval', summary });
await emit(run.id, null, 'summary', { status: 'awaiting_approval', ...summary });
return 'awaiting_approval';
}
if (!waiting && run.status === 'awaiting_approval') {
await store.updateRun(run.id, { status: 'running' });
await emit(run.id, null, 'run', { run_id: run.id, status: 'running', mode: run.mode, network: run.network });
}
return waiting ? 'awaiting_approval' : 'running';
}
async function advance(runId, { squad = null } = {}) {
if (!(await store.lockRun(runId, LEASE_MS))) return { locked: true };
try {
let run = await store.getRunById(runId);
if (!run || run.user_id !== userId) return { missing: true };
const sq = squad || (await resolveSquad(run.squad_id, userId));
if (!sq) {
await store.updateRun(runId, { status: 'failed' });
await emit(runId, null, 'error', { code: 'squad_missing', message: 'This squad no longer exists or is no longer yours.' });
return { status: 'failed' };
}
for (let guard = 0; guard < 40; guard++) {
run = await store.getRunById(runId);
if (['done', 'failed', 'cancelled'].includes(run.status)) break;
let steps = await store.getSteps(runId);
if ((await expireStale(run, steps)) | (await syncInbox(steps))) steps = await store.getSteps(runId);
const byKey = new Map(steps.map((s) => [s.step_key, s]));
const ready = steps.filter((s) => s.status === 'queued' && (s.depends_on || []).every((k) => TERMINAL.includes(byKey.get(k)?.status)));
if (!ready.length) break;
for (const step of ready) await runStep(run, sq, step, steps);
}
run = await store.getRunById(runId);
const status = await finalize(run, await store.getSteps(runId));
return { status };
} finally {
await store.unlockRun(runId);
}
}
// ── one step ───────────────────────────────────────────────────────────────
async function runStep(run, squad, step, steps) {
const started = await store.claimStep(step.id, ['queued'], 'running');
if (!started) return;
await emitStep(started);
const ctx = { squad, step: started, userId, req, run };
try {
switch (step.kind) {
case 'remember': {
const out = await specialists.remember(ctx);
await finish(started, out);
const prefs = await loadPrefs(squad.policy_agent_id, squad.id);
await emit(run.id, null, 'memory', { entries: prefs.entries, saved: out.evidence?.memory?.key || null });
return;
}
case 'answer':
await finish(started, { verdict: 'answered', summary: String(step.params?.text || '').slice(0, 400), evidence: {} });
return;
case 'research':
await finish(started, await specialists.research(ctx));
return;
case 'entry_check':
await finish(started, await specialists.entryCheck(ctx));
return;
case 'strategy':
await finish(started, await specialists.draftStrategy(ctx));
return;
case 'launch':
await launchGate(run, squad, started, await specialists.prepareLaunch(ctx));
return;
case 'transfer':
await transferGate(run, squad, started, await specialists.prepareTransfer(ctx));
return;
case 'trade':
await tradeGate(run, squad, started, steps);
return;
default:
await settle(started, 'skipped', { error: `Unknown step kind "${step.kind}".` });
}
} catch (e) {
const f = failMessage(e, step.role);
await settle(started, 'failed', { error: f.message, evidence: { ...(started.evidence || {}), error_code: f.code, error_detail: f.detail } });
}
}
async function finish(step, out) {
await settle(step, 'done', { evidence: { ...(out.evidence || {}), verdict: out.verdict, summary: out.summary }, result: { verdict: out.verdict, summary: out.summary } });
}
async function settle(step, status, patch) {
const row = await store.claimStep(step.id, [step.status], status, patch);
if (row) await emitStep(row);
return row;
}
async function pause(run, squad, step, approval, evidence) {
const row = await store.claimStep(step.id, ['running'], 'needs_approval', { approval, evidence });
if (!row) return;
await emitStep(row);
await emit(run.id, row.id, 'approval', { step_id: row.id, approval: publicStep(row).approval });
if (!bridge || !(await bridge.shouldMirror(approval, run))) return;
let mirrored;
try {
mirrored = await bridge.mirror({ userId, squad, run, step: row, approval });
} catch (e) {
console.warn('[team-chat] inbox mirror failed; approval stays in the chat', e?.message);
return;
}
if (!mirrored?.request) return;
await store.setApprovalRequestId(row.id, mirrored.request.id);
const inboxUrl = await bridge.link(mirrored.request);
const linked = await store.claimStep(row.id, ['needs_approval'], 'needs_approval', { approval: { ...approval, inbox_url: inboxUrl } });
if (linked) await emitStep(linked);
if (mirrored.autoApproved) {
await emit(run.id, row.id, 'note', { text: 'Your auto-approve policy covers this trade, so the Trader is executing it now.' });
await bridge.runAuto(mirrored.request, (claim) => executeApprovedStep(row.id, { inboxRow: claim }));
}
}
async function tradeGate(run, squad, step, steps) {
const p = step.params;
const deps = steps.filter((s) => (step.depends_on || []).includes(s.step_key));
const current = new Map((await store.getSteps(run.id)).map((s) => [s.id, s]));
const research = deps.map((d) => current.get(d.id)).find((d) => d?.kind === 'research');
const entry = deps.map((d) => current.get(d.id)).find((d) => d?.kind === 'entry_check');
const riskNotes = [];
if (p.side === 'buy') {
if (!research || research.status !== 'done') {
await settle(step, 'skipped', { error: 'There is no research verdict for this coin to cite, so the Trader will not buy it.' });
return;
}
const verdict = research.evidence?.verdict;
if (research.evidence?.risk_note) riskNotes.push(research.evidence.risk_note);
if (verdict === 'avoid') {
await settle(step, 'skipped', { error: 'Research says avoid this coin, so the Trader will not buy it.' });
return;
}
if (verdict === 'caution') {
const allowed = squad.kind === 'team' ? squad.policy?.allow_caution === true : run.plan?.prefs?.risk !== 'low';
if (!allowed) {
const why = squad.kind === 'team' ? 'the team only trades on a pass' : 'your remembered risk preference is low';
await settle(step, 'skipped', { error: `Research flagged caution and ${why}, so the Trader will not buy it.` });
return;
}
riskNotes.push('Research flagged caution on this coin.');
}
}
const condition = entry?.params?.condition || null;
const agent = await specialists.loadPolicyAgent(squad, userId);
const cap = specialists.tradeCapSol(squad, agent.meta);
const requested = p.side === 'buy' ? Number(p.amount) : null;
const amount = p.side === 'buy' && cap != null && requested > cap ? cap : p.amount;
if (condition && entry?.status !== 'done') {
await settle(step, 'skipped', { error: 'The entry check could not run, so the Trader cannot confirm your condition.' });
return;
}
if (condition && entry.evidence?.verdict !== 'met') {
const why = entry.evidence?.verdict === 'unknown' ? 'could not be confirmed from live data' : 'is not met yet';
if (run.mode !== 'live') {
await settle(step, 'skipped', { error: `Your entry condition ${why}, so there was nothing to simulate. In live mode the Trader proposes a standing order that fires when it holds.` });
return;
}
const sellAmount = p.side === 'sell' ? (p.amount_unit === 'max' || p.amount_unit === 'percent' ? (Number(p.amount) >= 100 || p.amount_unit === 'max' ? 'max' : null) : Number(p.amount)) : null;
if (p.side === 'sell' && sellAmount == null) {
await settle(step, 'skipped', { error: `Your condition ${why}. A standing sell needs an exact token count or "all".` });
return;
}
const approval = buildOrderApproval({ run, squad, step, condition, amount: p.side === 'buy' ? amount : sellAmount, slippageBps: p.slippage_bps, cap, requested, wallet: agent.meta.solana_address || null });
approval.risk_notes.push(...riskNotes);
await pause(run, squad, step, approval, { ...(step.evidence || {}), summary: approval.summary, cap_sol: cap });
return;
}
const quoted = await specialists.quoteTrade({ squad, step, userId, amount, req });
if (quoted.quote && quoted.quote.allowed === false) {
const reason = quoted.quote.blocked_reason?.message || 'the spend guard would block it';
await settle(step, 'failed', { error: `The spend guard stopped this trade before it reached you: ${reason}`, evidence: { quote: quoted.quote, cap_sol: cap } });
return;
}
const approval = buildTradeApproval({ run, squad, step, quoted, cap, requested, riskNotes });
await pause(run, squad, step, approval, { quote: quoted.quote, cap_sol: cap, summary: approval.summary });
}
async function launchGate(run, squad, step, out) {
const ev = { ...(out.evidence || {}), verdict: out.verdict, summary: out.summary };
if (out.verdict !== 'ready' || !out.evidence?.launch_url) {
await settle(step, 'done', { evidence: ev, result: { verdict: out.verdict, summary: out.summary } });
return;
}
const plan = out.evidence.plan;
const table = [
{ label: 'Action', value: `Launch ${plan.name} ($${plan.symbol})` },
{ label: 'Signer', value: 'You, in your own wallet, on the launchpad' },
{ label: 'Initial buy', value: plan.initial_buy_sol ? `${fmtSol(plan.initial_buy_sol)} (you confirm it on the launchpad)` : 'None unless you add one on the launchpad' },
{ label: 'Chain', value: chainLabel(run.network) },
];
const approval = buildHandoffApproval({ run, squad, step, action: 'launch', table, summary: `Launch ${plan.name} ($${plan.symbol}) on ${chainLabel(run.network)}`, handoffUrl: out.evidence.launch_url, extra: { name: plan.name, symbol: plan.symbol } });
await pause(run, squad, step, approval, ev);
}
async function transferGate(run, squad, step, out) {
const e = out.evidence;
const table = [
{ label: 'Recipient', value: e.recipient.endsWith('.sol') ? e.recipient : shortAddr(e.recipient), full: e.recipient },
{ label: 'Amount', value: `${e.amount} ${e.asset}` },
{ label: 'Asset', value: e.asset },
{ label: 'Chain', value: chainLabel(run.network) },
{ label: 'From', value: e.from ? `${squad.name} Trader wallet (${shortAddr(e.from)})` : `${squad.name} Trader wallet` },
];
const approval = buildHandoffApproval({ run, squad, step, action: 'transfer', table, summary: `Send ${e.amount} ${e.asset} to ${e.recipient.endsWith('.sol') ? e.recipient : shortAddr(e.recipient)}`, handoffUrl: e.handoff_url, extra: { amount: e.amount, asset: e.asset, recipient: e.recipient } });
await pause(run, squad, step, approval, { ...e, verdict: out.verdict, summary: out.summary });
}
// ── approval execution ─────────────────────────────────────────────────────
/**
* Execute an approved step exactly once. Called by decide() for a chat-only
* approval and by the inbox executor for a mirrored one. Returns the inbox
* executor contract: { status: 'ok'|'error', signature?, note? }.
*/
async function executeApprovedStep(stepId, { inboxRow = null } = {}) {
const step = await store.getStep(stepId);
if (!step) return { status: 'error', note: 'The chat step for this approval no longer exists. Nothing was executed.' };
const run = await store.getRunById(step.run_id);
if (!run || run.user_id !== userId || (inboxRow && inboxRow.user_id !== run.user_id)) {
return { status: 'error', note: 'This approval does not belong to this account. Nothing was executed.' };
}
const a = step.approval;
const integrity = a && a.payload && a.payload_hash === sha256Hex(a.payload)
&& a.payload.step_id === step.id && a.payload.run_id === run.id
&& (!inboxRow || inboxRow.payload_hash === a.payload_hash)
&& run.plan?.fingerprint === planFingerprint(run.plan);
if (!integrity) {
const row = await store.claimStep(step.id, ['needs_approval'], 'failed', { error: 'The approved action no longer matches the plan you saw. Nothing was executed.' });
if (row) await emitStep(row);
return { status: 'error', note: 'Integrity check failed. Nothing was executed.', integrity: false };
}
if (!inboxRow && new Date(a.expires_at).getTime() <= Date.now()) {
const row = await store.claimStep(step.id, ['needs_approval'], 'expired', { error: 'The approval window closed before a decision. Nothing was signed.' });
if (row) await emitStep(row);
return { status: 'error', note: 'expired' };
}
const claimed = await store.claimStep(step.id, ['needs_approval'], 'executing');
if (!claimed) return { status: 'skipped', note: `This step is already ${step.status}.` };
await emitStep(claimed);
const squad = await resolveSquad(run.squad_id, userId);
if (!squad) {
const row = await store.claimStep(step.id, ['executing'], 'failed', { error: 'This squad no longer exists. Nothing was executed.' });
if (row) await emitStep(row);
return { status: 'error', note: 'squad missing' };
}
const payload = a.payload;
try {
let result;
if (payload.action === 'trade') {
const { receipt } = await specialists.executeTrade({ squad, payload, userId, req });
const verb = payload.side === 'buy' ? 'Bought' : 'Sold';
const summary = receipt.simulated
? `Simulated: ${payload.side} ${payload.side === 'buy' ? fmtSol(payload.amount) : payload.amount === 'max' ? 'the whole position' : `${payload.amount} tokens`} of ${mintLabel(payload.mint)} through the full trade pipeline. Nothing was signed.`
: `${verb} ${payload.side === 'buy' ? fmtSol(payload.amount) : payload.amount === 'max' ? 'the whole position' : `${payload.amount} tokens`} of ${mintLabel(payload.mint)}.`;
result = { verdict: receipt.simulated ? 'simulated' : 'executed', summary, receipt };
} else if (payload.action === 'order') {
const { receipt } = await specialists.placeConditionalOrder({ squad, payload, userId });
result = { verdict: 'order_placed', summary: `Placed a standing order: ${a.summary}. It fires inside your spend guards when the condition holds.`, receipt };
} else {
result = { verdict: 'handed_off', summary: payload.action === 'launch' ? 'Opened the launchpad with your coin plan. You sign the launch there.' : 'Opened the agent wallet with this send. You confirm and sign it there.', receipt: { handoff_url: payload.handoff_url } };
}
const done = await store.claimStep(step.id, ['executing'], 'done', { result, evidence: { ...(step.evidence || {}), verdict: result.verdict, summary: result.summary } });
if (done) await emitStep(done);
return { status: 'ok', signature: result.receipt?.signature || null, note: result.summary.slice(0, 240) };
} catch (e) {
const f = failMessage(e, step.role);
const row = await store.claimStep(step.id, ['executing'], 'failed', { error: f.message, evidence: { ...(step.evidence || {}), error_code: f.code, error_detail: f.detail } });
if (row) await emitStep(row);
return { status: 'error', note: f.message.slice(0, 240) };
}
}
/**
* The owner's decision on a paused step. Returns the refreshed step.
* Throws { status, code, message } on a stale hash or a step that is not paused.
*/
async function decide({ stepId, decision, payloadHash }) {
const step = await store.getStep(stepId);
const run = step ? await store.getRunById(step.run_id) : null;
if (!step || !run || run.user_id !== userId) throw Object.assign(new Error('That step was not found.'), { status: 404, code: 'not_found' });
if (step.status !== 'needs_approval') {
return { step: publicStep(step), idempotent: true };
}
if (decision === 'approve' && payloadHash !== step.approval?.payload_hash) {
throw Object.assign(new Error('The action on file differs from the one you approved, so nothing was executed. Reload and review it again.'), { status: 409, code: 'payload_mismatch' });
}
if (step.approval_request_id && bridge) {
try {
await bridge.decide({ userId, approvalRequestId: step.approval_request_id, decision, payloadHash, req });
} catch (e) {
if (e?.code === 'expired') {
const row = await store.claimStep(step.id, ['needs_approval'], 'expired', { error: e.message });
if (row) await emitStep(row);
} else if (e?.code === 'already_denied' || e?.code === 'already_decided') {
await syncInbox([step]);
} else {
throw e;
}
}
if (decision === 'deny') {
const row = await store.claimStep(step.id, ['needs_approval'], 'denied', { error: 'You declined this step. Nothing was signed.' });
if (row) await emitStep(row);
}
} else if (decision === 'approve') {
await executeApprovedStep(step.id);
} else {
const row = await store.claimStep(step.id, ['needs_approval'], 'denied', { error: 'You declined this step. Nothing was signed.' });
if (row) await emitStep(row);
}
await advance(run.id);
return { step: publicStep(await store.getStep(step.id)), idempotent: false };
}
/** Pick up decisions taken elsewhere and continue whatever can move. */
async function refresh(runId) {
return advance(runId);
}
return { start, advance, refresh, decide, executeApprovedStep, emit };
}