@itpay/cli 2.1.40 → 2.1.41

package/dist/src/state/account_auth.js

@@ -1,347 +0,0 @@
-import { HttpError } from '../client/http.js';
-import { HttpTransportError } from '../client/transport.js';
-import { DeviceAuthorizationError, DeviceStateError, DeviceLockBusyError } from './device_authority.js';
-import { createHash } from 'node:crypto';
-import { dirname, resolve } from 'node:path';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
-import { writeLocalPNG } from '../render/qr.js';
-import { TaskJournal } from './task_journal.js';
-import { taskJournalPath } from './config.js';
-export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
-    return resolve(stateDir(env), `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
-}
-function read(baseURL, env = process.env, purpose = "seller") {
-    const path = sellerAuthPath(baseURL, env, purpose);
-    if (!existsSync(path))
-        return;
-    const state = JSON.parse(readFileSync(path, 'utf8'));
-    if (state.baseURL !== baseURL)
-        throw new Error('Seller session backend mismatch');
-    return state;
-}
-function save(state, env = process.env, purpose = "seller") {
-    const path = sellerAuthPath(state.baseURL, env, purpose);
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
-    renameSync(tmp, path);
-}
-export function sellerSessionToken(baseURL, env = process.env) {
-    const state = read(baseURL, env);
-    return state?.expiresAt && Date.parse(state.expiresAt) > Date.now() ? state.sessionToken : undefined;
-}
-export function sellerAuth(action, baseURL, env = process.env, fetcher = fetch) {
-    return accountAuth(action, baseURL, env, fetcher);
-}
-export function agentAuth(action, baseURL, backend, env = process.env, fetcher = fetch) {
-    return accountAuth(action, baseURL, env, fetcher, backend);
-}
-// AUTH01: dashboard session stages stay distinct — the human must know exactly
-// what the official page still needs instead of a generic "pending".
-const ACTIVE_SESSION_STAGES = ['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'];
-function stageInstruction(stage) {
-    if (stage === 'email_verification_required') {
-        return '官方页返回显式或历史身份验证状态；按页面当前要求完成验证。普通登录只需一种有效身份，不要求补齐邮箱和手机。完成后恢复原执行。';
-    }
-    if (stage === 'merge_confirmation_required') {
-        return '官方页需要用户核对两侧账号证明及主账号，再明确确认或取消合并；这不是付款确认。不要替用户同意，不自动重启原服务或授权请求。';
-    }
-    return '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。';
-}
-// AUTH07: distinct outcomes stay distinct — a technical failure is never
-// reported as a user denial, and a missing session is its own state.
-const TERMINAL_SESSION_STATES = {
-    expired: {
-        status: 'auth_expired',
-        instruction: '授权请求已过期。重新运行 itpay auth login 生成新请求；之前的查询输入在服务端保留，可恢复。',
-    },
-    failed: {
-        status: 'auth_failed',
-        instruction: '官方授权因技术原因未完成（不是用户拒绝）。重新运行 itpay auth login 生成新请求。',
-    },
-    cancelled: {
-        status: 'auth_cancelled',
-        instruction: '用户在官方页取消了授权；停止登录。只有用户明确重新要求授权时才发起新的登录。',
-    },
-    denied: {
-        status: 'auth_denied',
-        instruction: '官方授权被拒绝；停止登录，不自动创建新请求。只有用户明确重新要求授权时才重新登录。',
-    },
-};
-class AuthRequestError extends Error {
-    httpStatus;
-    constructor(httpStatus, message) {
-        super(message);
-        this.httpStatus = httpStatus;
-        this.name = 'AuthRequestError';
-    }
-}
-// AUTH03: transport/read uncertainty never maps to "denied" or a new session —
-// the stored session stays on disk and the caller retries the same poll.
-function authStatusUnknown(sessionID, error) {
-    // These errors have definite compatibility/identity/state facts. Let the
-    // command boundary report them rather than turning them into polling.
-    if ((error instanceof HttpError && error.status < 500)
-        || (error instanceof AuthRequestError && error.httpStatus < 500)
-        || error instanceof DeviceAuthorizationError || error instanceof DeviceStateError
-        || error instanceof DeviceLockBusyError)
-        throw error;
-    const failure = error instanceof HttpTransportError
-        ? { category: error.code, attempts: error.attempts }
-        : { category: 'authorization_status_unavailable' };
-    return {
-        status: 'auth_status_unknown',
-        result: { ...failure, ...(sessionID ? { dashboard_auth_session_id: sessionID } : {}) },
-        instruction: sessionID
-            ? '读取官方授权状态失败；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。'
-            : '本轮账号绑定检查未完成，设备与绑定状态尚未确认；没有保存的授权请求。结束本轮，网络或服务恢复后可重新检查，不发起登录。',
-        next: sessionID ? { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 } : null,
-        recovery: [],
-    };
-}
-function sessionGone(env, purpose, baseURL, sessionID) {
-    rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-    return {
-        status: 'auth_session_missing',
-        result: sessionID ? { dashboard_auth_session_id: sessionID } : {},
-        instruction: '之前的授权请求在服务端已不存在。重新运行 itpay auth login 生成新请求。',
-        next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
-        recovery: [],
-    };
-}
-// AUTH04: a successful bind resumes the SAME task that paused for login —
-// from the local task journal, never a placeholder and never a guess at the
-// latest order.
-function authenticatedEnvelope(env, phoneVerified) {
-    const paused = new TaskJournal(taskJournalPath(env)).pausedTasks()
-        .filter((task) => task.stage === 'login_required' || task.stage === 'quota_paused');
-    const resumable = paused.filter((task) => typeof task.resume_command === 'string');
-    const result = { bound: true, phone_verified: phoneVerified };
-    let instruction = '登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。';
-    let next = null;
-    if (resumable.length === 1) {
-        next = { command: resumable[0].resume_command, reason: '恢复登录前暂停的同一查询' };
-    }
-    else if (resumable.length > 1) {
-        result.paused_executions = resumable.map((task) => ({
-            service_execution_id: task.service_execution_id,
-            ...(task.service_id ? { service_id: task.service_id } : {}),
-            resume_command: task.resume_command,
-        }));
-        instruction += ' 有多个暂停的查询：只恢复与当前用户目标对应的那一个，不要一次恢复全部。';
-    }
-    else {
-        instruction += ' 当前没有待恢复的暂停查询；不构造恢复命令。';
-    }
-    return { status: 'authenticated', result, instruction, next, recovery: [] };
-}
-async function accountAuth(action, baseURL, env, fetcher, backend) {
-    const purpose = backend ? 'agent-login' : 'seller';
-    const command = backend ? 'itpay auth status' : 'itpay sell auth status';
-    if (backend) {
-        try {
-            const current = await backend.agentAccountStatus();
-            if (current.status === 'authenticated')
-                return authenticatedEnvelope(env, current.phone_verified === true);
-        }
-        catch (error) {
-            if (error instanceof AuthRequestError)
-                throw error;
-            // AUTH03: even the binding-status probe can hit transport failure; the
-            // truthful state is "unknown", never an implicit unbound or a fresh login.
-            return authStatusUnknown(read(baseURL, env, purpose)?.sessionID, error);
-        }
-    }
-    async function request(path, init = {}) {
-        const response = await fetcher(baseURL + path, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
-        if (!response.ok)
-            throw new AuthRequestError(response.status, `ItPay authorization failed (${response.status}); retry login if expired`);
-        return response;
-    }
-    function pollOpenSession(state) {
-        return request(`/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}?poll_token=${encodeURIComponent(state.pollToken)}`)
-            .then((response) => response.json());
-    }
-    async function bindSavedSession(state) {
-        const bound = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
-        if (bound.status !== 'authenticated')
-            throw new Error('Agent binding did not complete');
-        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-        return authenticatedEnvelope(env, bound.phone_verified === true);
-    }
-    if (action === 'login') {
-        if (backend) {
-            const open = read(baseURL, env, purpose);
-            if (open?.sessionID && open.pollToken && open.startToken) {
-                try {
-                    const current = await pollOpenSession(open);
-                    // AUTH02: a completed-but-unbound session binds in place; never
-                    // create a second auth session for the same login.
-                    if (current.status === 'completed')
-                        return await bindSavedSession(open);
-                    if (ACTIVE_SESSION_STAGES.includes(current.status)) {
-                        const url = open.authURL ?? '';
-                        const qr = url ? await writeLocalPNG(url).catch(() => undefined) : undefined;
-                        return {
-                            status: 'auth_pending',
-                            result: {
-                                dashboard_auth_session_id: open.sessionID,
-                                stage: current.status,
-                                expires_at: current.expires_at,
-                                methods: ['phone', 'email', 'alipay', 'wechat'],
-                            },
-                            // SEC01: the handoff URL carries one-time credentials — it goes
-                            // to the human only, never into logs, prompts, or PR material.
-                            handoff: {
-                                url,
-                                contains_credentials: true,
-                                ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
-                            },
-                            instruction: `${stageInstruction(current.status)} 沿用同一链接或二维码；不要生成新请求。`,
-                            next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
-                            recovery: [],
-                        };
-                    }
-                    const terminal = TERMINAL_SESSION_STATES[current.status];
-                    if (terminal) {
-                        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-                        // Fall through to a fresh session only after a definitive
-                        // terminal state; anything else keeps the stored session.
-                    }
-                    else {
-                        return authStatusUnknown(open.sessionID);
-                    }
-                }
-                catch (error) {
-                    if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
-                        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-                        // The explicit login call may open one fresh session now. Status
-                        // remains read-only and still reports the missing old session.
-                    }
-                    else {
-                        return authStatusUnknown(open.sessionID, error);
-                    }
-                }
-            }
-        }
-        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ return_to: backend ? '/' : '/seller' }) });
-        const result = await response.json();
-        const url = new URL(result.start_url, baseURL);
-        const sameOrigin = url.origin === new URL(baseURL).origin;
-        const alipay = url.origin === 'https://openauth.alipay.com' && url.pathname === '/oauth2/publicAppAuthorize.htm' && !url.username && !url.password;
-        const local = response.headers.get('X-ItPay-Environment') === 'local_simulation'
-            && new URL(baseURL).protocol === 'http:' && new URL(baseURL).hostname === '127.0.0.1'
-            && url.protocol === 'http:' && url.hostname === '127.0.0.1' && !url.username && !url.password;
-        if (!sameOrigin && !alipay && !local)
-            throw new Error('Unexpected authorization origin');
-        const fragment = new URLSearchParams(url.hash.replace(/^#dashboard-auth\?/, ''));
-        const state = url.searchParams.get('state')?.split('.');
-        const startToken = alipay
-            ? (state?.length === 2 && state[0] === result.dashboard_auth_session_id ? state[1] : undefined)
-            : url.searchParams.get('start_token') || fragment.get('start_token');
-        if (!startToken || !result.poll_token || !result.dashboard_auth_session_id)
-            throw new Error('Incomplete authorization response');
-        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken, authURL: url.href }, env, purpose);
-        if (backend) {
-            const qr = await writeLocalPNG(url.href).catch(() => undefined);
-            return {
-                status: 'auth_pending',
-                result: {
-                    dashboard_auth_session_id: result.dashboard_auth_session_id,
-                    stage: 'created',
-                    expires_at: result.expires_at,
-                    methods: ['phone', 'email', 'alipay', 'wechat'],
-                },
-                handoff: {
-                    url: url.href,
-                    contains_credentials: true,
-                    ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
-                },
-                instruction: '把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码，start_token 不要写入聊天记录或日志。',
-                next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
-                recovery: [],
-            };
-        }
-        return { status: 'authorization_required', authorization_url: url.href, instruction: `Complete ItPay login in the browser, then run ${command}.` };
-    }
-    const state = read(baseURL, env, purpose);
-    if (action === 'logout') {
-        const token = sellerSessionToken(baseURL, env);
-        if (token)
-            await request('/v1/me/logout', { method: 'POST', headers: { Authorization: `Bearer ${token}` } });
-        rmSync(sellerAuthPath(baseURL, env), { force: true });
-        return { status: 'logged_out' };
-    }
-    if (!backend && sellerSessionToken(baseURL, env))
-        return { status: 'authenticated', base_url: baseURL, expires_at: state?.expiresAt };
-    if (!state?.sessionID || !state.pollToken || !state.startToken) {
-        // AUTH07: a bare `status` with no session is its own truthful state, not a
-        // failure and not an implicit login.
-        if (!backend)
-            return { status: 'login_required' };
-        return {
-            status: 'login_required',
-            result: {},
-            instruction: '当前设备尚未绑定账号，也没有进行中的授权请求。需要时运行 itpay auth login 发起官方登录。',
-            next: { command: 'itpay auth login --json', reason: '需要账号绑定时发起官方授权' },
-            recovery: [],
-        };
-    }
-    let progress;
-    try {
-        progress = await pollOpenSession(state);
-    }
-    catch (error) {
-        if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
-            return sessionGone(env, purpose, baseURL, state.sessionID);
-        }
-        return authStatusUnknown(state.sessionID, error);
-    }
-    if (progress.status !== 'completed') {
-        if (backend) {
-            const terminal = TERMINAL_SESSION_STATES[progress.status];
-            if (terminal) {
-                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-                return {
-                    status: terminal.status,
-                    result: { dashboard_auth_session_id: state.sessionID, stage: progress.status },
-                    instruction: terminal.instruction,
-                    next: ['denied', 'cancelled'].includes(progress.status) ? null : { command: 'itpay auth login --json', reason: '需要登录时重新发起官方授权' },
-                    recovery: [],
-                };
-            }
-            return {
-                status: 'auth_pending',
-                result: {
-                    dashboard_auth_session_id: state.sessionID,
-                    stage: progress.status,
-                    ...(progress.expires_at ? { expires_at: progress.expires_at } : {}),
-                },
-                instruction: stageInstruction(progress.status),
-                next: { command: 'itpay auth status --json', reason: '轮询同一授权请求', poll_after_ms: 5000 },
-                recovery: [],
-            };
-        }
-        return { status: progress.status, instruction: 'Finish login and email verification in the browser.' };
-    }
-    if (backend) {
-        try {
-            return await bindSavedSession(state);
-        }
-        catch (error) {
-            if (error instanceof AuthRequestError)
-                throw error;
-            // Binding outcome unknown: keep the session so a retry can still bind
-            // the same completed login instead of creating a new one.
-            return authStatusUnknown(state.sessionID, error);
-        }
-    }
-    const claimed = await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
-    const token = /(?:^|[, ]+)itpay_buyer_session=([^;]+)/.exec(claimed.headers.get('set-cookie') ?? '')?.[1];
-    const session = await claimed.json();
-    if (!token || !session.expires_at || !(Date.parse(session.expires_at) > Date.now()))
-        throw new Error('Incomplete Seller session');
-    save({ baseURL, sessionToken: token, expiresAt: session.expires_at }, env);
-    return { status: 'authenticated', base_url: baseURL, expires_at: session.expires_at };
-}
-import { stateDir } from "./config.js";

package/dist/src/state/task_journal.js

@@ -1,90 +0,0 @@
-// Minimal local task journal: which Service Executions are paused at a human
-// gate (login, rate limit) and how to resume the SAME execution. It stores
-// no chat history, PII, credentials or tokens — only ids, stage and the
-// resume command the owner flow already emitted. Business truth stays
-// server-side; this file only makes "continue" point at the right task.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-export const PAUSED_STAGES = new Set([
-    "login_required",
-    "rate_limited",
-    "quota_paused",
-    "auth_pending",
-    "awaiting_input",
-]);
-const TERMINAL_STAGES = new Set([
-    "completed",
-    "delivered",
-    "issued",
-    "failed",
-    "cancelled",
-    "refunded",
-]);
-export class TaskJournal {
-    path;
-    constructor(path) {
-        this.path = path;
-    }
-    record(task) {
-        const file = this.readFile();
-        file.tasks[task.service_execution_id] = {
-            ...task,
-            updated_at: new Date().toISOString(),
-        };
-        this.writeFile(file);
-    }
-    clear(serviceExecutionID) {
-        const file = this.readFile();
-        if (!file.tasks[serviceExecutionID])
-            return;
-        delete file.tasks[serviceExecutionID];
-        this.writeFile(file);
-    }
-    // Observe the latest stage without deleting history; terminal stages stop
-    // the task from counting as resumable.
-    observe(serviceExecutionID, stage, resumeCommand) {
-        const file = this.readFile();
-        const existing = file.tasks[serviceExecutionID];
-        if (existing && existing.stage === stage && (resumeCommand === undefined || existing.resume_command === resumeCommand))
-            return;
-        file.tasks[serviceExecutionID] = {
-            service_execution_id: serviceExecutionID,
-            ...(existing?.service_id ? { service_id: existing.service_id } : {}),
-            stage,
-            ...(resumeCommand ?? existing?.resume_command ? { resume_command: resumeCommand ?? existing.resume_command } : {}),
-            updated_at: new Date().toISOString(),
-        };
-        this.writeFile(file);
-    }
-    // Tasks paused behind login/quota gates, newest first. Terminal or
-    // completed tasks never count as "still waiting for login".
-    pausedTasks() {
-        const file = this.readFile();
-        return Object.values(file.tasks)
-            .filter((task) => PAUSED_STAGES.has(task.stage) && !TERMINAL_STAGES.has(task.stage))
-            .sort((left, right) => right.updated_at.localeCompare(left.updated_at));
-    }
-    readFile() {
-        if (!existsSync(this.path))
-            return { schema_version: "itpay.task_journal.v1", tasks: {} };
-        try {
-            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
-            if (parsed.schema_version !== "itpay.task_journal.v1" || !parsed.tasks || typeof parsed.tasks !== "object") {
-                return { schema_version: "itpay.task_journal.v1", tasks: {} };
-            }
-            return parsed;
-        }
-        catch {
-            return { schema_version: "itpay.task_journal.v1", tasks: {} };
-        }
-    }
-    writeFile(file) {
-        // Bound the journal: keep only the 50 most recent task records.
-        const entries = Object.entries(file.tasks).sort((left, right) => right[1].updated_at.localeCompare(left[1].updated_at));
-        file.tasks = Object.fromEntries(entries.slice(0, 50));
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
-        const tmp = `${this.path}.${process.pid}.tmp`;
-        writeFileSync(tmp, JSON.stringify(file), { mode: 0o600 });
-        renameSync(tmp, this.path);
-    }
-}

package/docs/agent/buyer/rail-booking.json

@@ -1,176 +0,0 @@
-{
-  "schema_version": "itp.agent_doc.v1",
-  "role": "buyer",
-  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows use the same entry point via itpay sell.",
-  "topic": "rail-booking",
-  "title": "Railway Query, Planning, and Ticket Booking",
-  "purpose": "One railway route from understanding the request to saved results, booking, protected checkout, order status and refunds.",
-  "when_to_use": [
-    "Any railway schedule, planning or ticket request; read this topic once before the first railway action."
-  ],
-  "goal_and_overview": {
-    "route": "Understand endpoints and constraints → 2–4 line route brief → Exact or Smart → read enough saved results for the goal → select under delegation → missing real consent only → official payment entry; show and stop.",
-    "query_vs_booking": "Exact/Smart returns a query execution and saved evidence. Booking creates a separate execution from a server-issued selection; it is not a repeated search.",
-    "comparison": "If the human only asked to compare, answer within the searched scope and stop without a buy-or-not question. Reuse already-read unchanged Skill/docs in this context; do not repeat install/readyz/docs at each step. A clear purchase delegation permits selection under their rules, subject to required human terms.",
-    "public_entry": "One public service itpay-rail declares query_exact, query_smart and prepare_purchase. Query, booking, Checkout and order remain separate identities. Legacy IDs are only for recovering their pinned historical executions.",
-    "price_approval": "Choosing a candidate or confirming seat/whole-journey terms is not approving price. Read the current scoped approve_purchase template after quote; record true only for genuine matching exact-price or capped-budget approval, or an explicitly authorized official-page confirmation. Reuse matching approval; never fabricate it."
-  },
-  "flow_at_a_glance": [
-    {
-      "step": "search Exact",
-      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
-      "returns": "one station-pair query execution, resolved scope and either useful results or a same-execution wait action",
-      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
-    },
-    {
-      "step": "search Smart",
-      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
-      "returns": "one broader planning execution, observed coverage and either useful results or a same-execution wait action",
-      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
-    },
-    {
-      "step": "read Exact result",
-      "command": "itpay services read-result <query_execution_id> --json",
-      "returns": "saved station-pair rows with detail.command; detail returns booking_template",
-      "next": "Read enough candidates for the user objective. Only a purchase delegation permits using the chosen template."
-    },
-    {
-      "step": "read Smart result",
-      "command": "itpay services read-result <query_execution_id> --snapshot <snapshot_id> --json",
-      "returns": "same-snapshot journeys and detail.command. Single-leg detail returns a selection action: use human only for a real user pick, agent for delegated selection; its result supplies booking credentials. Transfer detail returns the complete ordered selections template for one ticket plan; do not turn it into separate purchases.",
-      "next": "If current eligible options and full connections satisfy the request, answer or continue under delegation. Selecting a journey does not lock inventory; preserve whole-journey purchase. No unsupported ground distance/time estimates."
-    },
-    {
-      "step": "book",
-      "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
-      "returns": "a separate booking execution using the returned selection token, seat code and party size",
-      "next": "follow its review or waiting action on that same booking execution"
-    },
-    {
-      "step": "review",
-      "command": "itpay services next <booking_execution_id> --json",
-      "returns": "current review revision, material terms and a non-executable confirm_booking input_template",
-      "next": "submit the returned actor-type agent template only after genuine consent; reuse an unchanged explicit consent for code-only correction"
-    },
-    {
-      "step": "checkout",
-      "command": "use the returned next or handoff for the same booking execution",
-      "returns": "an official protected payment entry",
-      "next": "show the official entry using the current host immediately before optional memory/log writing, then stop; retain necessary safety/permissions, do not infer paid or issued"
-    },
-    {
-      "step": "aftercare",
-      "command": "itpay order <order_id> --json",
-      "returns": "authoritative payment and ticket state",
-      "next": "use orders-refunds for the same order when needed"
-    }
-  ],
-  "understand_before_search": [
-    "Preserve full administrative names, original endpoint meaning, date, party size, deadlines and station locks. Ask only for a missing date or genuine ambiguity changing the destination/constraints; no preference means do not pre-ask station, seat or departure time.",
-    "Before the first railway query, leave one 2–4 line conclusion brief in conversation or existing route-brief.txt (choose one, no Backend upload or private reasoning): Origin: full original meaning; station/area/place; evidence from user/context/reliable knowledge/actual lookup; unknown facts. Destination: the same. Journey: date, given party size/deadlines; credible station pair or transfer direction and evidence; Exact/Smart choice and one-sentence reason. Never replace this with “understood”, or write it after querying as pre-query evidence. Reuse it while waiting, reading, quoting or buying; update only changed endpoints/scope/date. With existing results, serve the facts rather than restart for a missing ceremony; missing prior evidence remains unobserved.",
-    "Only clear reliable route knowledge can directly support a candidate. A merely possible/probable transfer or “a long trip should transfer” is unknown: first make one targeted lookup on 12306 or 同程, with 携程 only if needed. Stop once a credible direct station pair or transfer direction is established; do not collect complete external timetables, prices or inventory. Remembered trains still require ItPay to verify the actual date and stock.",
-    "12306 https://kyfw.12306.cn/ is the official date/station/train reference; claim a date verified only after reading that date result. 同程 https://www.ly.com/mergeTrain/huochepiao helps identify station pairs and transfer directions. 携程 https://trains.ctrip.com/ is an optional supplement for transfer routes. Knowledge, search snippets and historical timetables do not prove current operation, inventory, price or purchase credentials.",
-    "If login, captcha or network blocks the short lookup, stop without repeated troubleshooting or browser installation and state the facts still unknown. Clear double-station endpoints can use Exact to verify direct trains; do not choose Smart merely because a transfer seems probable. A known transfer requirement or supported multi-station/place comparison can use Smart; genuinely unclear place meaning needs human clarification.",
-    "Date verification is required; the ItPay query for the actual date can perform it. A 12306 visit is not a mandatory extra call for every order. Valid Smart journeys and credentials do not require routine Exact rechecks of each leg.",
-    "Each side independently means area, place or station, giving all nine combinations. An area is not a same-name station; a specific station stays locked until the human consents to changing it. Smart also supports two locked stations when transfers are needed.",
-    "Distance alone does not establish a transfer requirement. One observed route through a station does not make it mandatory; a failed short lookup or incomplete search cannot establish that all direct trains are absent.",
-    "Unclear meaning that changes region/scope needs one key question, using known context first. Clear meaning with unknown coordinates can use the complete name and mark location verification pending. Use maps/browser for place identity; 12306/同程 for rail directions, 携程 as needed. Do not require a residential location to be researched on 12306. No fabricated coordinates or passenger/payment data in notes."
-  ],
-  "choose_search": {
-    "exact": "Known or credible resolved station pair, direct trains for one station pair and date only. A zero result does not mean the whole city has no train. An area delegation may permit checking another evidence-based pair within that original area; a human-specified station stays locked until they consent to changing that endpoint.",
-    "smart": "Use Smart for a reliably established transfer direction or explicit transfer need, broad station comparison, or a precise place needing nearby stations and ground evidence. Preserve each endpoint as area/place/station; a probable transfer alone is not a basis for Smart. Fastest does not automatically mean max_transfers=0.",
-    "scope": "Exact cannot claim a citywide or all-transfer optimum. Smart gives its observed scope and missing evidence; its first useful options may be shown before expansion finishes."
-  },
-  "input_and_expected_result": {
-    "exact": {
-      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
-      "example": {
-        "input": {
-          "origin": "<已核实出发站>",
-          "destination": "<已核实到达站>",
-          "travel_date": "<用户出行日期 YYYY-MM-DD>"
-        }
-      },
-      "contract": "Only origin, destination and travel_date are accepted. Use station names, not an undocumented station-code field. Filter time, seat and quantity against returned rows. Date is illustrative; use the actual requested queryable date."
-    },
-    "smart": {
-      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
-      "example": {
-        "input": {
-          "endpoints": {
-            "origin": {
-              "kind": "area",
-              "text": "<用户出发市县镇完整名称>"
-            },
-            "destination": {
-              "kind": "station",
-              "text": "<已核实到达站名>"
-            }
-          },
-          "travel_date": "<用户出行日期 YYYY-MM-DD>"
-        }
-      },
-      "contract": "The current published input_schema is authoritative: use endpoints only when it exposes endpoints. Each side independently accepts kind area/place/station and a full text; fill kind when supported by endpoint understanding; omit it only when the object meaning is clear but its category genuinely awaits verification, explicitly recorded in the brief. An unknown city is not resolved by omitting kind. A complete named place is legal; coordinates are optional. Area centers choose nearby stations without claiming door-to-door ground travel; place uses verified POI/coordinates when available; station locks exactly one verified railway station and does not mean the traveler is already there. All nine origin/destination combinations follow this same rule. Province-only areas need a narrower location. Never mix endpoints with legacy origin/destination or send a station lock/confirmed flag. Adult passengers is an integer 1–5. arrive_before maps to arrive_by; conflicting aliases are rejected. preference_context is unsupported."
-    },
-    "result": "Read the resolved station pair or area scope, observed coverage, complete compact train rows, fare/inventory evidence and stable references. The recommendation card is not the full catalog. Unknown cost and unverified address ground facts remain unknown. Eligible means usable, not equally preferable. Prefer existing default_layer, roles, dominance and tradeoffs; show at most three meaningful representatives. A same-arrival, earlier-departing and more expensive dominated option stays in the saved catalog rather than taking the first screen.",
-    "waiting": "Use the same execution and returned bounded wait command. next is a read; background work may still proceed. Do not resubmit, sleep/get/events repeatedly, or reread the whole guide.",
-    "followup": "Read the saved result for the original execution. Smart: itpay services read-result <execution_id> --snapshot <snapshot_id> --json. Exact: use its returned saved-result reader. Read the relevant same-snapshot pages first; unread does not mean nonexistent. Do not automatically enumerate every theoretical combination. For a new Smart query, restore the original area/place/station intent, passengers, deadlines and preferences; an Exact pair is verified evidence, not proof of user station locks. Only a user-locked station change or scope expansion needs new consent. After a changed endpoint or date, supply the original intent and a same-owner reuse_from reference to an unexpired snapshot; unchanged resolved endpoints and matching fresh station-pair facts may be reused. Date change never reuses old inventory. Preference, party-size or deadline changes within the same scope use refine_preferences on the existing plan. Planning deadline does not erase saved facts; an old selection token is not refreshed by rereading. For expiry, use only the server safe fresh-query template once within the original authorization, preserving all conditions and omitting reuse_from; it may consume query quota. Existing or unknown purchases resume the same booking/order, never new queries. Refresh does not guarantee inventory or original price; confirm materially changed terms. Change to a named station: kind station with matching text/code. Original-station vicinity: kind place with verified station text, remove station_code, resolve normally or use verified POI/coordinates (existing 30 km/5 candidates). Whole city only with explicit consent: kind area with full administrative name, remove POI/location/station_code. Preserve date, passengers, time limits and preferences; refuse cross-owner reuse. The public Smart input does not expose overnight layover. A home or specific address remains the destination; nearby railway stations are candidates, never implicit station locks. Report the rail arrival station separately from any unknown last-mile connection. Preserve the endpoint brief; update only affected facts. A terminal location failure follows its explicit complete new-query template only after new evidence.",
-    "public_envelope": "New public operation files contain input plus, for prepare_purchase, the exact continuation supplied by saved result detail. Do not invent source execution/snapshot IDs. Historical executions use their own pinned schema."
-  },
-  "select_and_book": {
-    "delegation": "Apply existing seat/price/delegation rules. Exact fastest requires enough coverage to compare the station-pair candidates; without ordering/coverage evidence the first page is not proof. Smart can present up to three eligible representatives once full connections meet the goal, or continue under delegation; no routine full-catalog or all-seat paging. If an unapproved seat choice changes the price, combine that decision and missing terms into one question. Do not default to second class or require a three-tier menu. No match does not permit loosening conditions.",
-    "input": "Copy the complete current booking_template.input_example; retain passenger count, every ordered token and the returned seat_type code matched to seat_name. Never use a seat display name as the code, mix selections/selection/legs or guess missing credentials. Technical JSON errors are repaired by the Agent using current input_schema/input_errors/template, preserving original user requirements; ask the human only for a genuinely missing business choice.",
-    "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
-    "identity": "Passenger name, ID and phone are entered on the official protected checkout page, not in query or booking JSON.",
-    "whole_journey": "Use the returned complete ticket plan booking_template: ordered selections (2–3 legs) from one owner/snapshot/revision/plan, or selection for one leg. One booking, one refreshed whole quote, one checkout, one order and one payment; each leg issues separately without connection or joint-seat guarantees. Raw legs are single-leg compatibility only; never hand-compose multi-leg legs when complete selections are missing or expired. Do not combine different plans or choose per-leg payment by default. Historical details without a whole-journey template do not prove whole-journey support."
-  },
-  "review_and_checkout": {
-    "review": "Copy the returned complete interaction.input_template.input, current revision and notice. For a whole journey, each ordered leg has its own seat_type and an object preference per passenger; default auto, never null/string arrays. Use known choices and confirm only missing genuine terms consent or material changes. Set accept_non_guaranteed=true only after real consent; delegation or choosing a train alone is not terms consent. The false default is protection, not a broken template; if consent is missing, ask the returned review.consent_question once. Seat/berth placement requests differ from the whole-journey separate-issuance and partial-outcome terms; use the current notice.",
-    "equivalent_correction": "If only seat code spelling changes while train, actual seat class, party, price and terms are identical, reuse an existing explicit human approval. Material draft changes or missing approval require human confirmation. Reuse accepted original endpoints, no-seat, overnight and incomplete-coverage facts when unchanged; never silently substitute the destination.",
-    "checkout": "Present the complete itinerary, total and single official handoff: one payment, separate issuance. The human enters one passenger set on that page; verified account notification email is reused there and can be changed for this order. Do not ask or guess traveler identity/email in chat. Use the returned checkout payment deadline, not an estimated duration. Handoff is not payment, and payment is not all legs issued."
-  },
-  "continue_and_aftercare": {
-    "same_execution": "Read the same booking/checkout/order. Report issued only when every leg is confirmed issued; partial or unknown outcomes keep the same order and successful tickets, reconcile before retry, and explain the affected leg. No automatic rebuy or full-refund promise.",
-    "saved_vs_live": "A saved snapshot remains historical evidence after expiry. Real-time booking or quote credentials may expire and require the documented fresh validation path; rereading an old token does not renew it.",
-    "refund": "For railway refund/change use itpay aftercare list --order <order_id> --json. Select returned leg/passenger targets from the user’s request, explain scope and manual processing, submit the complete current template. Request acceptance is not supplier success or money returned. Read the same case; concrete change proposals need current-revision consent and actual fee facts. No automatic change payment or replacement purchase."
-  },
-  "exceptional_branches": {
-    "login_required": "Use itpay auth login --json, complete the official handoff, then execute the returned recovery command for the same paused query. Login returning a command does not execute it.",
-    "rate_limited": "Respect returned retry_after and continue the same execution.",
-    "booking_review_invalid": "Read the same booking review and use the returned seat code; reuse real consent only under the strict equivalent-correction rule.",
-    "booking_review_changed": "Read the current revision and compare material terms; confirm new terms only when changed.",
-    "selection_stale": "Saved result stays readable, but follow the current owner action for new live inventory and quote evidence; do not assume reread refreshes the token.",
-    "unknown_paid_outcome": "Read the same checkout/order before any mutation. Never repeat payment or create a new order on an unknown outcome.",
-    "lock": "Use the CLI returned device repair-lock recovery only for a lock proven stale; preserve active owners and identity.",
-    "empty": "Report verified scope, failures and missing evidence separately. Do not guess a new date or station as a generic repair. Explain checked scope first, then propose at most two evidence-backed directions. Ask consent before changing a locked endpoint; after consent copy the complete original input and change only the accepted side in a new query.",
-    "ground_evidence_required": "If trains were found but a precise address deadline cannot be verified without ground or station-exit evidence, report the checked rail scope and missing fact. Ask for a precise location or verifiable connection fact; do not expand rail station pairs by default or call it no trains. Preserve the original place and compare its nearby candidates; only actual user consent may replace the destination with a station.",
-    "dependency_unavailable": "Map faults are external failures, not empty location candidates. Preserve resolved endpoints and original conditions. For a retryable wait, respect dependency.retry_at and execute the returned same-execution run command; never restart or sleep inside the CLI. Daily quota, permission or IP failures need service maintenance, not a different address.",
-    "partial": "Report saved usable routes together with checked scope and the precise gap. Unqueried hubs, geographic evidence gaps and budget limits are not proof of no trains. Use the returned action only; do not expand station pairs by default. A proposal to relax a condition is allowed, but requires real consent before a changed-scope query.",
-    "geographic_notice": "Geographic deviation is a ranking or explanation notice. Current eligibility and booking conditions come from verified dates, connections, inventory, prices, authorization and required ground evidence; do not reject a returned eligible train merely by geometric ratio.",
-    "selection_invalid": "Use only the current finite reason and executable recovery. An input constraint error requires the current complete template; stored_selection_inconsistent is a server problem that extra parameters cannot repair. With no recovery, stop: never append hidden fields, recreate a purchase or blame local simulation without evidence.",
-    "location_evidence_required": "A unique verified place continues directly; real multiple candidates use only the returned choice action and preserve the original place. Area-only or conflicting identity evidence is not proof the place does not exist: read affected_endpoint, original place, limited resolved_scope and finite reason; use maps/browser for missing evidence or ask only necessary human facts. A terminated query cannot resume: only after new evidence, fill the complete non-executable new_query_template and create once, preserving the other side/date/party/preferences/locks. Do not switch place to area, fabricate reuse_from or repeatedly get a terminal execution. Only a real dependency wait resumes the same execution. Correcting a proven classification within unchanged intent needs no repeated consent; changing destination or enlarging scope needs real consent."
-  },
-  "search_terms": [
-    "rail",
-    "railway",
-    "train",
-    "ticket",
-    "火车",
-    "火车票",
-    "高铁",
-    "车票",
-    "车次",
-    "seat",
-    "booking",
-    "rail-booking"
-  ],
-  "reading_and_writing": "Use the formal Skill Follow one envelope rules for direct text/file reading, truncation and small JSON input; no parsing scripts.",
-  "restore_old_execution": "Only when resuming an existing v4 execution, follow its own declared legacy schema; new queries use the current three-endpoint contract.",
-  "saved_followup": "Use returned refine_preferences with expected_query_revision for arrival/departure times, passengers, seat preference or priority; rerank uses existing facts. Only endpoints/date/new scope require a new query. Profiles compare within one journey, not the whole catalog. Fares and service fees are whole-journey totals for the stated people; observed available is not proof of ample inventory. Page limit is 1-20; follow next_offset exactly, never infer full-catalog optimality from the visible page. Byte-limited pages may contain fewer rows than limit. Area station candidates are not guaranteed nearest; transfer wait/minimum are facts, not a low-risk guarantee.",
-  "actor_conventions": {
-    "location_confirmation": "Use the returned human template only for the user's real place choice; no delegated human action.",
-    "journey_terms": "workflow:confirm_booking and booking_review_invalid recovery accept agent-reported genuine consent; default false, never infer from purchase delegation.",
-    "ordinary_human_action": "Use its published actor rule; do not generalize railway permission.",
-    "price_approval": "approve_purchase uses actor-type agent with the unchanged server-scoped approval template and genuine matching approval; candidate choice is not price approval."
-  }
-}