@hcmai/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1775 @@
+import { AxiosInstance } from 'axios';
+
+interface ModelQueryDsl {
+    filter?: Record<string, unknown>;
+    sort?: Array<Record<string, unknown>>;
+    fields?: string[];
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+}
+interface QueryResult<T = Record<string, unknown>> {
+    rows: T[];
+    total?: number;
+}
+interface ActionInput {
+    id?: string;
+    ids?: string[];
+    method?: ActionHttpMethod;
+    scope?: ActionScope;
+    params?: Record<string, unknown>;
+}
+type ActionHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type ActionScope = 'class' | 'object';
+interface ActionResult<R = unknown> {
+    result?: R;
+    taskId?: string;
+}
+
+interface FieldMeta {
+    name: string;
+    type: string;
+    required?: boolean;
+    label?: string;
+    description?: string;
+    enum?: string[];
+    relation?: {
+        model: string;
+        field?: string;
+    };
+}
+interface ActionMeta {
+    name: string;
+    label?: string;
+    description?: string;
+    params?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        description?: string;
+    }>;
+}
+interface RelationMeta {
+    key: string;
+    via: string;
+    label?: string;
+}
+interface ModelDescription {
+    model: string;
+    labels: Record<string, string>;
+    fields: FieldMeta[];
+    actions: ActionMeta[];
+    relations: RelationMeta[];
+}
+interface DescribeOpts {
+    verbose?: boolean;
+}
+
+interface CreateResult {
+    id: string;
+    [key: string]: unknown;
+}
+/** 创建一条 Model 记录,走后端 Model 层完整校验。
+ *  注:返回体形态(尤其 id 字段名)见 spec §12.3,实现期对真后端核实。 */
+declare function create(http: AxiosInstance, model: string, data: Record<string, unknown>): Promise<CreateResult>;
+
+declare function update(http: AxiosInstance, model: string, id: string, data: Record<string, unknown>): Promise<CreateResult>;
+
+interface RemoveResult {
+    id: string;
+    status: number;
+    data?: unknown;
+}
+declare function remove(http: AxiosInstance, model: string, id: string): Promise<RemoveResult>;
+
+interface Fixture {
+    model: string;
+    key_field: string;
+    count: number;
+    items: Array<Record<string, unknown>>;
+    /** 来源文件路径,仅用于报错定位 */
+    sourcePath?: string;
+}
+type RowStatus = 'created' | 'updated' | 'skipped' | 'failed';
+interface RowResult {
+    model: string;
+    key: string;
+    status: RowStatus;
+    id?: string;
+    error?: string;
+    traceId?: string;
+}
+interface ImportResult {
+    created: number;
+    updated: number;
+    skipped: number;
+    failed: number;
+    rows: RowResult[];
+    /** Model:key → uuid(已解析引用快照) */
+    refs: Record<string, string>;
+}
+interface ImportOptions {
+    dryRun?: boolean;
+    updateOnly?: boolean;
+    onError?: 'stop' | 'continue';
+}
+
+/** snake_case → camelCase(单个 key)。 */
+declare function snakeToCamel(key: string): string;
+/** 转换 record 的**顶层** key:snake_case → camelCase。
+ *  嵌套对象/数组的值(jsonb / i18n)原样透传,不转内部键名(对齐 schema §4)。 */
+declare function camelizeKeys(obj: Record<string, unknown>): Record<string, unknown>;
+
+declare class RefStore {
+    private map;
+    private k;
+    register(model: string, key: string, id: string): void;
+    get(model: string, key: string): string | undefined;
+    snapshot(): Record<string, string>;
+}
+interface ParsedPlaceholder {
+    model: string;
+    key: string;
+}
+/** 若 value 恰好是一个 ${Model:key} 占位符,返回其 model/key;否则 null。 */
+declare function parsePlaceholder(value: unknown): ParsedPlaceholder | null;
+/** 用 store 替换 record 顶层的 ${Model:key} 占位符。
+ *  返回 { resolved, unresolved };unresolved 是 "字段名=${Model:key}" 列表,原值保留便于报错。 */
+declare function resolveRefs(record: Record<string, unknown>, store: RefStore): {
+    resolved: Record<string, unknown>;
+    unresolved: string[];
+};
+
+/** 解析 + 校验单个 data fixture(对齐 spec §10 校验项 1–4)。 */
+declare function parseFixture(yamlText: string, sourcePath?: string): Fixture;
+
+/** runner 只依赖 client 的这三个方法,便于单测 stub。 */
+interface ImportClient {
+    findIdByKey(model: string, keyField: string, keyValue: string): Promise<string | null>;
+    create(model: string, data: Record<string, unknown>): Promise<{
+        id: string;
+    }>;
+    update(model: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+}
+declare function runImport(client: ImportClient, fixtures: Fixture[], opts?: ImportOptions): Promise<ImportResult>;
+
+interface HcmClientOpts {
+    endpoint: string;
+    tenantId: string;
+    accessToken?: string;
+    scheme?: 'client_credentials' | 'pat';
+    profile?: string;
+    timeoutMs?: number;
+}
+/**
+ * Structural type representing the resolved auth context that
+ * `HcmClient.fromAuthContext` consumes. Kept as a structural interface
+ * (rather than importing `AuthContext` from `@hcmai/cli`) to avoid a circular
+ * package dependency — the CLI's `AuthContext` is assignable to this shape.
+ */
+interface ClientAuthContext {
+    env: string;
+    endpoint: string;
+    tenantId: string;
+    identity: string;
+}
+declare class HcmClient {
+    readonly profile: string;
+    readonly endpoint: string;
+    readonly tenantId: string;
+    private http;
+    private tokenStore;
+    private explicitToken?;
+    constructor(opts: HcmClientOpts);
+    /**
+     * Build a client from a resolved env + identity context (T15).
+     *
+     * Uses `TokenStore.forIdentity(ctx.identity)` so the token is read from
+     * the identity-scoped store (written by `hcm login --env <env> --name <id>`),
+     * not the legacy profile-scoped credentials.json.
+     *
+     * The `profile` field is kept = `ctx.env` for downstream callers that still
+     * read `client.profile` (e.g. workspace context dump). Phase 2 will rename
+     * the field to `env`.
+     *
+     * Refresh path: fromAuthContext binds `this.identity` so handleRefresh
+     * routes refresh through TokenStore.forIdentity — works for
+     * client_credentials sessions (1h TTL) post-T8 migration.
+     */
+    /**
+     * Identity name for refresh path (set by fromAuthContext). When set,
+     * handleRefresh routes through TokenStore.forIdentity rather than the
+     * profile-scoped legacy store — critical for client_credentials sessions
+     * (~1h token TTL) on post-T8-migration installs.
+     */
+    private identity?;
+    static fromAuthContext(ctx: ClientAuthContext): HcmClient;
+    /**
+     * @deprecated Use `HcmClient.fromAuthContext(ctx)` together with the CLI
+     * helper `getActiveAuthContextFromCli(args)`. WILL THROW on post-T8
+     * installs where `~/.config/hcm/<profile>/profile.yml` was migrated to
+     * `envs/<name>/env.yml` (loadProfile reads the legacy path only).
+     * Kept only for dead-code paths (mini.ts) and pre-migration users.
+     */
+    static fromConfig(args: {
+        profile?: string;
+    }): Promise<HcmClient>;
+    query<T = Record<string, unknown>>(model: string, dsl: ModelQueryDsl): Promise<QueryResult<T>>;
+    action<R = unknown>(model: string, name: string, input: ActionInput): Promise<ActionResult<R>>;
+    describe(model: string, opts?: DescribeOpts): Promise<ModelDescription>;
+    create(model: string, data: Record<string, unknown>): Promise<CreateResult>;
+    update(model: string, id: string, data: Record<string, unknown>): Promise<CreateResult>;
+    remove(model: string, id: string): Promise<RemoveResult>;
+    /** 按业务键查已存在记录的 id(幂等用);命中返回 id,否则 null。 */
+    findIdByKey(model: string, keyField: string, keyValue: string): Promise<string | null>;
+    importPackage(fixtures: Fixture[], opts?: ImportOptions): Promise<ImportResult>;
+    raw(): AxiosInstance;
+    close(): Promise<void>;
+    getAccessToken(): Promise<string | null>;
+    handleRefresh(): Promise<void>;
+}
+
+declare const SDK_VERSION: string;
+
+declare enum ExitCode {
+    SUCCESS = 0,
+    USAGE_ERROR = 1,
+    AUTH_ERROR = 2,
+    BUSINESS_ERROR = 3,
+    NETWORK_ERROR = 4,
+    CONFIG_ERROR = 5,
+    SIGINT = 130
+}
+declare enum CliErrorCode {
+    INVALID_ARGUMENT = "INVALID_ARGUMENT",
+    INVALID_JSON = "INVALID_JSON",
+    MISSING_FLAG = "MISSING_FLAG",
+    AUTH_FAILED = "AUTH_FAILED",
+    AUTH_EXPIRED = "AUTH_EXPIRED",
+    AUTH_REFRESH_FAILED = "AUTH_REFRESH_FAILED",
+    WS_AUTH_ERROR = "WS_AUTH_ERROR",
+    SCOPE_FORBIDDEN = "SCOPE_FORBIDDEN",
+    BUSINESS_RULE_VIOLATION = "BUSINESS_RULE_VIOLATION",
+    MODEL_NOT_FOUND = "MODEL_NOT_FOUND",
+    ACTION_NOT_FOUND = "ACTION_NOT_FOUND",
+    AGENT_NOT_FOUND = "AGENT_NOT_FOUND",
+    TOOL_TIMEOUT = "TOOL_TIMEOUT",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    SERVER_ERROR = "SERVER_ERROR",
+    PROTOCOL_UNSUPPORTED = "PROTOCOL_UNSUPPORTED",
+    PROFILE_NOT_FOUND = "PROFILE_NOT_FOUND",
+    CONFIG_PARSE_ERROR = "CONFIG_PARSE_ERROR",
+    KEYCHAIN_UNAVAILABLE = "KEYCHAIN_UNAVAILABLE",
+    ENV_NOT_FOUND = "ENV_NOT_FOUND",
+    ENV_ALREADY_EXISTS = "ENV_ALREADY_EXISTS",
+    ENV_ENDPOINT_REQUIRED = "ENV_ENDPOINT_REQUIRED",
+    IDENTITY_NOT_FOUND = "IDENTITY_NOT_FOUND",
+    IDENTITY_ALREADY_EXISTS = "IDENTITY_ALREADY_EXISTS",
+    IDENTITY_NOT_IN_ENV = "IDENTITY_NOT_IN_ENV",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    NO_ACTIVE_ENV = "NO_ACTIVE_ENV"
+}
+declare function exitCodeFor(code: CliErrorCode): ExitCode;
+
+interface CliErrorInit {
+    code: CliErrorCode;
+    message: string;
+    context?: Record<string, unknown>;
+    traceId?: string;
+    profile?: string;
+    cause?: unknown;
+}
+declare class CliError extends Error {
+    readonly code: CliErrorCode;
+    readonly exitCode: ExitCode;
+    readonly context?: Record<string, unknown>;
+    readonly traceId?: string;
+    readonly profile?: string;
+    readonly cause?: unknown;
+    constructor(init: CliErrorInit);
+    toFormattedString(): string;
+    toJSON(): {
+        code: CliErrorCode;
+        message: string;
+        context: Record<string, unknown> | undefined;
+        traceId: string | undefined;
+    };
+}
+declare function fromAxiosError(err: any, profile?: string): CliError;
+
+/**
+ * 会话附件元数据——与后端 `ConversationWebSocketHandler.parseAttachments` 形态一致
+ * （message.create payload.attachments 元素；#1849 后随 USER_MESSAGE 入 journal 单源）。
+ */
+interface AttachmentMeta {
+    documentId: string;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+}
+declare function guessMimeType(filePath: string): string;
+/**
+ * 上传本地文件到 HCM 文档存储（web ChatInput 同端点同 storageCategory），
+ * 返回 message.create 可直接携带的附件元数据。类型限制跟随服务端校验。
+ */
+declare function uploadDocument(http: AxiosInstance, filePath: string): Promise<AttachmentMeta>;
+/** 默认产物落盘目录（对标 Claude Code 工具产物本地直接访问）。 */
+declare function defaultDownloadDir(): string;
+/**
+ * 把后端相对下载链接（`/api/documents/download/{id}?...sig=`）拼成可点的绝对 URL，
+ * 供终端渲染——签名 URL 自洽免 Bearer，点开即由浏览器打开（ADR-140）。
+ * apiBase 为 CLI 连接的后端地址（`HcmClient.endpoint`）；无 apiBase 或已是绝对 URL 时原样返回。
+ */
+declare function absoluteDownloadUrl(apiBase: string | undefined, url: string): string;
+/**
+ * 认证下载文档到本地（`/api/documents/download` 需 Bearer，浏览器裸 GET 恒 401 的同款教训）。
+ * destPath 为目录或省略时落 defaultDownloadDir，重名自动加序号。返回写入的绝对路径。
+ */
+declare function downloadDocument(http: AxiosInstance, ref: {
+    documentId?: string;
+    downloadUrl?: string;
+    fileName?: string;
+}, destPath?: string): Promise<string>;
+
+declare function toJson(value: unknown): string;
+
+declare function toYaml(value: unknown): string;
+
+/**
+ * 盒式文本表格。列宽**按内容自适应**、以 {@link MAX_COL_WIDTH} 为上限——短列（SEQ/ROUND
+ * 等）不再被强制撑到 40 列（旧 `colWidths.map(()=>40)` 的 BUG：7 列表 ≈ 290 列宽、糊成一片）。
+ * 宽度与截断均按**终端显示宽度**（CJK=2 列）计，避免中文单元格溢出错位。
+ */
+declare function toTable(rows: Record<string, unknown>[]): string;
+
+type OutputFormat = 'table' | 'json' | 'yaml';
+interface FormatOptions {
+    format: OutputFormat;
+}
+declare function formatRows(rows: Record<string, unknown>[], opts: FormatOptions): string;
+declare function formatObject(obj: unknown, opts: FormatOptions): string;
+
+/**
+ * 凭据的来路。
+ *
+ * 🔴 **来路 ≠ 语义**：`password` 与 `pairing` 是两条完全不同的取得方式，但换来的是
+ * **同一种东西**——`TokenManager.createToken` 铸的服务端会话 token（滑动续期、
+ * 可 `/api/auth/refresh`、可 `/api/auth/logout` 单杀）。而 `pat` 与 `client_credentials`
+ * 不是。判「能不能续期 / 该不该请服务端吊销」必须走 {@link isServerSlidingSession}，
+ * 不要拿 `=== 'password'` 去比——见该函数的说明。
+ */
+type AuthScheme = 'client_credentials' | 'pat' | 'password' | 'pairing';
+/**
+ * 这条凭据是不是「服务端会话 token」——即后端在每个请求上滑动续期、且
+ * `/api/auth/logout` 能单条吊销的那一类。
+ *
+ * 🔴 **存在的理由是防一类静默退化**：全仓有三处要问这个问题——`refreshToken` 的
+ * scheme 分支、`ensureSessionFresh` 的早退、`logout` 的 `revokeOnServer`。散着写成三个
+ * 字面量比较，下次加第五轨时必然漏掉其中一处，而漏掉的后果**没有任何报错**：
+ *   - 漏在 refresh 分支 → 落到 default 抛「unknown auth scheme」，会话再也续不上
+ *   - 漏在 ensureSessionFresh → 不再主动续期，退回「每天重登」
+ *   - 漏在 revokeOnServer → **`logout` 静默跳过服务端吊销**，而 ADR-308 把
+ *     「用完跑 hcm logout」写成了顾问在客户主机上那一行**唯一可操作的缓解**
+ *
+ * 所以这里收敛成一个谓词，三处都调它。
+ */
+declare function isServerSlidingSession(scheme: AuthScheme): boolean;
+interface TokenRecord {
+    scheme: AuthScheme;
+    accessTokenRef: string;
+    refreshTokenRef?: string;
+    expiresAt: string;
+    scopes: string[];
+    /**
+     * 签发时服务端告知的 TTL(秒)。**续期后本地 expiresAt 只能靠它重算**：后端
+     * `POST /api/auth/refresh` 的响应体是 `{"message":"token刷新成功"}` —— 不回新的
+     * 过期时间，而它重设的 Redis TTL 用的正是签发时那个全局配置值
+     * (`SecurityProperties.token.expiration`，缺省 24h)。不存这个数，续期成功之后就只能
+     * 猜一个 TTL 写回本地，猜小了照样早退、猜大了会放过一个已死的 token。
+     *
+     * 🔴 缺省(旧记录升级上来)时按 DEFAULT_SESSION_TTL_SECONDS 兜底，见 refresh.ts。
+     */
+    ttlSeconds?: number;
+}
+declare class TokenStore {
+    private profile;
+    constructor(profile: string);
+    /**
+     * Factory: build an identity-scoped TokenStore. Stores meta at
+     * `identities/<name>/credentials.json` and uses keychain account prefix
+     * `identity-<name>` to isolate from legacy profile-scoped stores.
+     *
+     * Used by T13 login when writing identity meta and by T15 business
+     * commands when reading the active identity's token.
+     */
+    static forIdentity(name: string): TokenStore;
+    private get isIdentity();
+    private metaFile;
+    private dataDir;
+    private keychainAccountPrefix;
+    writeMeta(record: TokenRecord): Promise<void>;
+    readMeta(): Promise<TokenRecord | null>;
+    setAccessToken(token: string): Promise<string>;
+    setRefreshToken(token: string): Promise<string>;
+    getAccessToken(): Promise<string | null>;
+    getRefreshToken(): Promise<string | null>;
+    clear(): Promise<void>;
+    private resolveRef;
+    private canUseKeychain;
+    private writeTokenFile;
+}
+
+/**
+ * **服务端认定的 token 归属**——与"调用方以为的归属"是两回事，两者不一致时
+ * 一切看起来都正常，而你在对着另一个租户干活。
+ *
+ * 这正是 fde-kit 那边 Ruling 30 防的同一件事：`hcm login --tenant 1` 传进去的是
+ * 「我要的租户」，服务端回的 `user.tenantId` 才是「token 实际归属的租户」。此前
+ * login 成功那行只回显前者，于是登错租户是静默的。
+ */
+interface Principal {
+    /** 服务端认定的租户。ADR-177 之后新租户是 UUID，别按 int 处理。 */
+    tenantId?: string;
+    username?: string;
+    roles?: string[];
+}
+/** 登录helper 的统一返回：凭据元数据 + 服务端认定的归属(拿不到时 undefined)。 */
+interface LoginOutcome {
+    record: TokenRecord;
+    /**
+     * 🔴 `undefined` = **服务端没在响应里给身份**，与「给了但字段为空」是两个状态。
+     * 前者的下一步是问服务端为什么不给，后者的下一步是看那个账号本身。合并之后
+     * 回显只能给出一句放之四海而皆准的废话。
+     */
+    principal?: Principal;
+}
+/**
+ * 从服务端响应里的 user/userInfo 对象抽出 Principal。
+ *
+ * 两个来源字段名一致但形状不同，所以这里只认键、不认容器：
+ *   - `POST /api/auth/login` → `LoginResponse.user`(Map，含 id/username/tenantId/roles)
+ *   - `GET  /api/auth/info`  → `UserInfoResponse`(含 userId/username/tenantId/roles)
+ *
+ * 全部字段都当可选处理：任何一个缺失都不该让登录失败——登录已经成功了，
+ * 这里只是回显。
+ */
+declare function toPrincipal(raw: unknown): Principal | undefined;
+/** 回显用的一行摘要。`principal` 为空时明说「服务端未回身份」，不静默略过。 */
+declare function describePrincipal(principal: Principal | undefined): string;
+
+interface ClientCredentialsInput {
+    endpoint: string;
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    profile: string;
+    httpClient: AxiosInstance;
+}
+declare function loginClientCredentials(input: ClientCredentialsInput): Promise<LoginOutcome>;
+
+interface PatLoginInput {
+    endpoint: string;
+    tenantId: string;
+    pat: string;
+    profile: string;
+    httpClient: AxiosInstance;
+}
+declare function loginPat(input: PatLoginInput): Promise<LoginOutcome>;
+
+interface PasswordLoginInput {
+    endpoint: string;
+    tenantId: string;
+    username: string;
+    password: string;
+    profile: string;
+    httpClient: AxiosInstance;
+}
+/** 后端 `SecurityProperties.token.expiration` 的缺省值(24h)，仅在服务端没回 expiresIn 时兜底。 */
+declare const DEFAULT_SESSION_TTL_SECONDS: number;
+declare function loginPassword(input: PasswordLoginInput): Promise<LoginOutcome>;
+
+interface PairingLoginInput {
+    endpoint: string;
+    /** 页面上复制来的配对码。大小写与连字符由服务端归一化，这里原样传。 */
+    code: string;
+    profile: string;
+    httpClient: AxiosInstance;
+}
+/**
+ * 配对码登录（ADR-308 第四轨）。
+ *
+ * 解的是「没有任何一方知道后端地址与 tenantId」：CLI 只有磁盘上人手填的值，用户知道的
+ * 是浏览器地址栏那一串，后端全树无 frontend URL 配置。唯一同时知道这两件事的是那个
+ * 已登录的页面——所以地址由命令行位置参数带进来（人从页面复制整行），租户由服务端
+ * 在响应里给出，**不再有 `'1'` 这个猜测**。
+ *
+ * 🔴 `scheme` 记 `'pairing'` 而不是 `'password'`：如实记录来路（审计与回显需要）。
+ * 但它换来的是 `TokenManager.createToken` 铸的**普通会话 token**，续期/吊销语义与口令
+ * 登录完全一致——这一点由 `isServerSlidingSession` 谓词保证，别在别处写
+ * `=== 'password'` 的比较。
+ */
+declare function loginPairing(input: PairingLoginInput): Promise<LoginOutcome>;
+/**
+ * 从用户粘贴的地址里取出 origin。
+ *
+ * 人复制的是**浏览器地址栏那一串**，带路径、带查询参数都正常——那正是他唯一确定知道的
+ * 东西。要求他先手工削成 origin，等于把「知道后端地址」这个门槛又搬了回来。
+ */
+declare function toOrigin(raw: string): string;
+/**
+ * 由 origin 推一个 env 名：`https://hcm.custa.com` → `custa`。
+ *
+ * 取的是主域左边那一段而不是整个 hostname：`hcm.custa.com` 与 `hcm-test.custa.com`
+ * 会推出不同的名字，而 `hcm.custa.com` 与 `www.custa.com` 也不会撞。
+ * 推不出来时落到 `default`，由调用方处理重名。
+ */
+declare function inferEnvName(origin: string): string;
+
+interface RefreshInput {
+    endpoint: string;
+    /**
+     * Identity name (preferred). When set, uses TokenStore.forIdentity(identity).
+     * Required for sessions established via HcmClient.fromAuthContext.
+     */
+    identity?: string;
+    /**
+     * @deprecated Profile name (legacy). Used when identity is not provided —
+     * for backward compat with fromConfig callers and tests pre-T15.
+     */
+    profile?: string;
+    httpClient: AxiosInstance;
+}
+/**
+ * 本地在「还剩这么多」时就主动去续期。
+ *
+ * 🔴 这个值**不需要、也不应该**去对齐服务端的 `SecurityProperties.token.refreshThreshold`
+ * (缺省 2h)：那是服务端**自动**续期的触发线，而我们打的 `/api/auth/refresh` 是
+ * **无条件**续期(只要 Redis key 还在就重设 TTL)，跟阈值无关。抄一份服务端常量到这里
+ * 只会多一个会漂的载体。
+ */
+declare const PROACTIVE_REFRESH_MARGIN_SECONDS: number;
+/**
+ * 续期。**三种 scheme 是三套完全不同的服务端语义，不是一个端点能覆盖的。**
+ *
+ * 🔴 此前这里写成了一条，于是三条全错，而且错得不会被发现——口令会话在
+ * 「取 refresh token」那一步就抛了，请求根本没发出去，后面那段对不上的协议
+ * 因此永远跑不到，测试也只覆盖了这些提前抛出的错误路径。三条的真实形态：
+ *
+ *  - **password**：`POST /api/auth/refresh`，认 **Authorization 头**，服务端把
+ *    同一个 token 的 Redis TTL 重设回 expiration，响应体只有
+ *    `{"message":"token刷新成功"}`——**没有 access_token**。旧实现往 body 塞
+ *    `{refresh_token}` 再读 `resp.data.access_token`，两头都对不上；而口令登录
+ *    压根拿不到 refresh token，连这个请求都发不出去。
+ *  - **client_credentials**：走 `POST /api/oauth/token` + `grant_type=refresh_token`，
+ *    且后端在进 switch 之前就强制校验 `client_id` + `client_secret`。本 CLI
+ *    **不保存 client_secret**(有意为之：那是长期凭据) ⇒ 这条路在当前设计下
+ *    不可能执行成功。所以这里**明说要重登**，而不是发一个注定 400 的请求
+ *    再把它包装成一句看不懂的错误。
+ *  - **pat**：本来就不可续期，由后端管失效。
+ */
+declare function refreshToken(input: RefreshInput): Promise<TokenRecord>;
+declare function needsRefresh(meta: TokenRecord, marginSec?: number): boolean;
+/**
+ * 命令开跑前把会话续上——**这才是"登录一次基本不用再输密码"落地的那一处**。
+ *
+ * 背景：后端 `TokenAuthenticationFilter` 在每个带 token 的请求上都会滑动续期
+ * (剩余 <= refreshThreshold 时把 Redis TTL 重设回 24h)，也就是说**只要你在用，
+ * 服务端的会话就不会死**。而 CLI 这边的 `expiresAt` 是登录那一刻算死的静态值、
+ * 之后再没更新过，`ensureActiveAuth` 拿它一比就抛 TOKEN_EXPIRED —— 结果是
+ * **CLI 在拒绝服务端明明还认的 token**。
+ *
+ * 这里做的事：本地剩余时间进入窗口时主动打一次无条件续期端点，并把服务端那次
+ * 续期的结果**写回本地**，让本地的过期判断重新变成真的。
+ *
+ * 返回是否真的续了。**任何失败都不抛**：续期是尽力而为，失败时后面的请求自己会
+ * 401 并给出该给的引导；为了一次续期失败就让整条命令挂掉是本末倒置。
+ */
+declare function ensureSessionFresh(input: RefreshInput): Promise<boolean>;
+
+/**
+ * 首登强制改密（fresh tenant 的必经一步）。
+ *
+ * <p>后端契约（AuthController）：
+ * <ul>
+ *   <li>用初始口令 `POST /api/auth/login` → **403**，body 是
+ *       `{error:{code:"AUTH_PASSWORD_CHANGE_REQUIRED", details:{changePasswordToken, expiresInSeconds}}}`
+ *       —— 那个临时 token **只活 300 秒**；</li>
+ *   <li>拿它作 Bearer 调 `POST /api/auth/change-password`，body `{oldPassword,newPassword,confirmPassword}`；</li>
+ *   <li>改完用新口令重新 login 才拿到正式 token。</li>
+ * </ul>
+ *
+ * <p>🔴 这是 `hcm tenant bootstrap` 之后的**硬阻塞**：不走这一步，新建的租户登不进去。
+ * 所以 `hcm login` 自动识别并接管，而不是让顾问自己去拼两条 curl。
+ */
+declare const PASSWORD_CHANGE_REQUIRED = "AUTH_PASSWORD_CHANGE_REQUIRED";
+interface PasswordChangeChallenge {
+    changePasswordToken: string;
+    expiresInSeconds?: number;
+}
+/**
+ * 从一个失败的 login 响应里识别「强制改密」挑战。
+ *
+ * 不是该挑战（网络错、口令错、账号锁定…）一律返回 null，由调用方按原错误处理——
+ * 判据只认后端的错误码，不靠 HTTP 状态猜（423 账号锁定同样是 4xx，不能混）。
+ */
+declare function detectPasswordChangeChallenge(err: any): PasswordChangeChallenge | null;
+interface ChangePasswordInput {
+    endpoint: string;
+    /** 登录挑战里拿到的临时 token（300 秒有效） */
+    changePasswordToken: string;
+    oldPassword: string;
+    newPassword: string;
+    httpClient: AxiosInstance;
+}
+declare function changePassword(input: ChangePasswordInput): Promise<void>;
+
+declare function hcmConfigDir(): string;
+declare function profileDir(profile: string): string;
+declare function profileFile(profile: string): string;
+declare function credentialsFile(profile: string): string;
+declare function globalConfigFile(): string;
+declare function conversationStateFile(profile: string): string;
+declare function replHistoryFile(profile: string): string;
+declare function envsDir(): string;
+declare function envDir(name: string): string;
+declare function envFile(name: string): string;
+declare function identitiesDir(): string;
+declare function identityDir(name: string): string;
+declare function identityMetaFile(name: string): string;
+declare function archiveDir(): string;
+
+interface ProfileConfig {
+    endpoint: string;
+    tenantId: string;
+    defaultAgent?: string;
+    displayName?: string;
+}
+declare function loadProfile(profile: string): Promise<ProfileConfig>;
+declare function saveProfile(profile: string, cfg: ProfileConfig): Promise<void>;
+declare function listProfiles(): Promise<string[]>;
+
+interface GlobalConfig {
+    /** Canonical: name of the active environment. */
+    activeEnv: string;
+    /**
+     * @deprecated Use `activeEnv`. Kept in sync with `activeEnv` for backward compat
+     *   while in-tree callers migrate. Will be removed at end of Phase 2.
+     */
+    activeProfile?: string;
+    defaults?: {
+        output?: 'table' | 'json' | 'yaml';
+        timeout?: string;
+    };
+}
+declare function loadGlobalConfig(): Promise<GlobalConfig>;
+declare function saveGlobalConfig(cfg: GlobalConfig): Promise<void>;
+/**
+ * Resolve active env name. Priority: --env flag > HCM_ENV > HCM_PROFILE (legacy) > global.activeEnv
+ */
+declare function resolveActiveEnv(args: {
+    envFlag?: string;
+}, env: NodeJS.ProcessEnv, global: GlobalConfig): string;
+/**
+ * @deprecated Use `resolveActiveEnv`. Keeps old signature `(args: {flag})` for backward compat.
+ *   Will be removed at end of Phase 2.
+ */
+declare function resolveActiveProfile(args: {
+    flag?: string;
+}, env: NodeJS.ProcessEnv, global: GlobalConfig): string;
+
+interface EnvConfig {
+    endpoint: string;
+    tenantId?: string;
+    defaultIdentity?: string;
+    defaultAgent?: string;
+}
+declare function saveEnv(name: string, cfg: EnvConfig): Promise<void>;
+declare function loadEnv(name: string): Promise<EnvConfig>;
+declare function listEnvs(): Promise<string[]>;
+declare function deleteEnv(name: string): Promise<void>;
+
+interface IdentityMeta {
+    env: string;
+    scheme: AuthScheme;
+    scopes: string[];
+    expiresAt?: string;
+    username?: string;
+    /**
+     * keychain ref same as TokenRecord.accessTokenRef. Populated by TokenStore.forIdentity.
+     * Optional here because saveIdentity may be called before token is written.
+     */
+    accessTokenRef?: string;
+    refreshTokenRef?: string;
+    /**
+     * **服务端认定的租户**(登录响应里的 `user.tenantId` / `/api/auth/info` 的 tenantId)，
+     * 不是命令行上传进去的那个。两者不一致 = 你在对着另一个租户干活，而一切看起来都正常。
+     *
+     * 命令执行时优先用它，`EnvConfig.tenantId` 只是登录前的入参与兜底 —— 后者缺省是
+     * 写死的 `'1'`，而 ADR-177 之后新租户是 UUID，那个缺省几乎必然是错的。
+     */
+    tenantId?: string;
+    /**
+     * 见 `TokenRecord.ttlSeconds`。
+     *
+     * 🔴 必须在这里也留一份：`identities/<name>/credentials.json` 这**一个文件**有两个
+     * 写入方——`TokenStore.forIdentity().writeMeta()` 写 TokenRecord 形状，`saveIdentity()`
+     * 写 IdentityMeta 形状，后者最后写、且只写自己声明的字段。不在这里声明，
+     * 登录流程末尾这一次 saveIdentity 就会把 ttlSeconds 抹掉，续期时只能去猜 TTL。
+     */
+    ttlSeconds?: number;
+}
+declare function saveIdentity(name: string, meta: IdentityMeta): Promise<void>;
+declare function loadIdentity(name: string): Promise<IdentityMeta>;
+declare function listIdentities(env?: string): Promise<string[]>;
+declare function deleteIdentity(name: string): Promise<void>;
+
+interface MigrationSummary {
+    migrated: string[];
+    failed: string[];
+    skipped: string[];
+}
+/**
+ * One-shot lazy migration from legacy `<hcm>/<profile>/profile.yml + credentials.json`
+ * to canonical `<hcm>/envs/<name>/env.yml + identities/<name>/credentials.json`.
+ *
+ * Semantics:
+ * - Idempotent: profiles already migrated (env.yml exists) are skipped.
+ * - Per-profile atomicity: any failure inside migrateOne rolls back the partial env.
+ * - Legacy files for failed profiles stay in place so the user can inspect / retry.
+ * - On any migration success, the global config.yml is rewritten so activeEnv is
+ *   the canonical key (loadGlobalConfig already provides fallback read of
+ *   legacy activeProfile).
+ * - Structured stderr log: `[hcm] event=migration_done count=N archive=PATH/`
+ *   and `[hcm] event=migration_failed profile=NAME reason="..."`.
+ */
+declare function migrateLegacyProfiles(): Promise<MigrationSummary>;
+
+/**
+ * Resolve active identity name.
+ * Priority: --as flag > HCM_IDENTITY env var > env.defaultIdentity > first identity in env > throw.
+ */
+declare function resolveActiveIdentity(args: {
+    asFlag?: string;
+}, env: NodeJS.ProcessEnv, activeEnv: string): Promise<string>;
+
+interface StreamCommandEnvelope<P = unknown> {
+    protocolVersion: '3.0' | '3.2' | '4.0';
+    commandId: string;
+    conversationId: string;
+    type: StreamCommandType;
+    timestamp: number;
+    payload: P;
+}
+interface StreamEventEnvelope<P = unknown> {
+    protocolVersion: '3.0' | '4.0';
+    streamId: string;
+    conversationId: string;
+    requestId: string;
+    traceId: string | null;
+    eventId: string;
+    seq: number;
+    type: string;
+    timestamp: number;
+    payload: P;
+}
+type ConnectionMessage = {
+    type: 'auth_success';
+    sessionId: string;
+} | {
+    type: 'auth_error';
+    code: string;
+    message: string;
+} | {
+    type: 'pong';
+} | {
+    type: 'token_expiring';
+    expiresAt: number;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
+type StreamCommandType = 'message.create' | 'stream.cancel' | 'approval.confirm' | 'approval.reject' | 'interaction.answer' | 'response.interrupt' | 'response.steer' | 'response.regenerate';
+type StreamEventType = 'response.started' | 'response.part.delta' | 'response.part.upserted' | 'response.completed' | 'response.failed' | 'response.interrupted' | 'response.tool.started' | 'response.tool.completed' | 'response.tool.failed' | 'task_progress' | 'task_done' | 'task_failed';
+
+interface ResponseStartedPayload {
+    assistantMessageId: string;
+    resumeSupported: boolean;
+}
+interface ResponsePartDeltaPayload {
+    delta: string;
+    partId?: string;
+    partType?: 'text' | 'reasoning';
+    index?: number;
+}
+interface ResponseCompletedPayload {
+    assistantMessageId: string;
+    finalContent: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface ResponseFailedPayload {
+    code: string;
+    message: string;
+}
+interface ToolCallStartedPayload {
+    callId: string;
+    toolName: string;
+    category?: string;
+    input?: Record<string, unknown>;
+}
+interface ToolCallResultPayload {
+    callId: string;
+    output?: unknown;
+    elapsedMs?: number;
+}
+interface ToolCallFailedPayload {
+    callId: string;
+    code: string;
+    message: string;
+}
+interface TaskProgressPayload {
+    taskId: string;
+    progress: number;
+    message?: string;
+}
+type AnyStreamEvent = StreamEventEnvelope<ResponseStartedPayload> | StreamEventEnvelope<ResponsePartDeltaPayload> | StreamEventEnvelope<ResponseCompletedPayload> | StreamEventEnvelope<ResponseFailedPayload> | StreamEventEnvelope<ToolCallStartedPayload> | StreamEventEnvelope<ToolCallResultPayload> | StreamEventEnvelope<ToolCallFailedPayload> | StreamEventEnvelope<TaskProgressPayload>;
+/** v4 展示流事件 wire type（ADR-118）。终态三事件沿用 v3 命名作兼容边界。 */
+type V4StreamEventType = 'message.start' | 'block.start' | 'block.delta' | 'block.stop' | 'tool.result' | 'message.stop' | 'response.completed' | 'response.failed' | 'response.interrupted';
+/** 控制通道信封：channel='control'，不带 stream 的 streamId/seq 语义。 */
+interface ControlChannelEnvelope {
+    channel: 'control';
+    protocolVersion: string;
+    conversationId: string;
+    type: string;
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+
+interface MessageCreatePayload {
+    content: string;
+    agentKey?: string;
+    directOpsAgentId?: string;
+    parentMessageId?: string;
+    pageContext?: Record<string, unknown>;
+    /** issue #64：附件元数据（后端 parseAttachments 形态，documentId/fileName/mimeType/fileSize）。 */
+    attachments?: Array<{
+        documentId: string;
+        fileName: string;
+        mimeType: string;
+        fileSize: number;
+    }>;
+}
+interface StreamCancelPayload {
+    streamId: string;
+}
+interface ApprovalConfirmPayload {
+    confirmationId: string;
+}
+interface ApprovalRejectPayload {
+    confirmationId: string;
+    reason?: string;
+}
+interface InteractionAnswerPayload {
+    interactionId: string;
+    answer: string;
+    choiceIndex?: number | null;
+}
+
+type MessageClass = 'control' | 'event' | 'connection';
+/** WS 入站消息三分：控制通道（channel='control'）优先于流事件（streamId+seq），其余为连接层。 */
+declare function classifyMessage(parsed: any): MessageClass;
+interface WsClientOpts {
+    endpoint: string;
+    getAccessToken: () => Promise<string | null>;
+    onTokenExpiring?: () => Promise<void>;
+    heartbeatMs?: number;
+}
+declare class WsClient {
+    private opts;
+    private ws?;
+    private handlers;
+    private heartbeatTimer?;
+    private ready;
+    private sessionId?;
+    /** 流进行中断连的持久订阅者（iterator 等终态收口者）。RISK-1：auth 后无持久
+     *  close handler，断连时上层 await 永久挂死。这里让消费方能感知 socket 死。 */
+    private disconnectHandlers;
+    /** 由 close()/ensureConnected 主动关闭 → 不广播 disconnect（非异常断连）。 */
+    private intentionalClose;
+    constructor(opts: WsClientOpts);
+    /**
+     * 订阅「流进行中 socket 异常断连」（后端重启 / 网络闪断）。主动 close() 不触发。
+     * iterator 订阅它 → 断连时 finish()（incomplete 终态），杜绝 await consume 永久挂死。
+     */
+    onDisconnect(fn: () => void): () => void;
+    private notifyDisconnect;
+    connect(): Promise<void>;
+    send<P>(cmd: StreamCommandEnvelope<P>): void;
+    onEvent(fn: (ev: StreamEventEnvelope) => void): () => void;
+    onConnection(fn: (msg: ConnectionMessage) => void): () => void;
+    onControl(fn: (ev: ControlChannelEnvelope) => void): () => void;
+    isReady(): boolean;
+    /**
+     * 连接已断（后端重启 / 网络闪断 / 心跳静默失败后 socket 已死）时重建连接。
+     * REPL 长开场景每轮发消息前调用——旧连接死掉不应让用户重启 CLI（2026-06-12 用户
+     * 实测：后端重启后 REPL 下一条消息报错）。已连接且 socket OPEN 时为 no-op。
+     */
+    ensureConnected(): Promise<void>;
+    getSessionId(): string | undefined;
+    close(): Promise<void>;
+    /** 流进行中 socket 异常断连（非主动 close）→ 广播 disconnect 让消费方收口。 */
+    private persistentOnClose;
+    private persistentOnMessage;
+    private startHeartbeat;
+    private dispatchEvent;
+    private dispatchConnection;
+    private dispatchControl;
+}
+
+interface InteractionRequest {
+    kind: 'CONFIRM' | 'ASK';
+    interactionId: string;
+    summary: string;
+    originAgentPath: string;
+    ttlSeconds: number;
+    riskLevel?: string;
+    toolName?: string;
+    argsPreview?: Record<string, unknown>;
+    question?: string;
+    choices?: string[];
+}
+interface InteractionResolved {
+    interactionId: string;
+    phase: 'RESUMED' | 'TERMINAL' | string;
+}
+interface StreamCommand {
+    protocolVersion: '3.0';
+    commandId: string;
+    conversationId: string;
+    type: 'approval.confirm' | 'approval.reject' | 'interaction.answer' | 'response.interrupt' | 'response.steer';
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+declare function parseInteractionRequest(payload: Record<string, unknown>): InteractionRequest;
+declare function parseInteractionResolved(payload: Record<string, unknown>): InteractionResolved;
+declare function buildConfirm(confirmationId: string, conversationId: string): StreamCommand;
+declare function buildReject(confirmationId: string, conversationId: string, reason?: string): StreamCommand;
+declare function buildAnswer(interactionId: string, conversationId: string, answer: string, choiceIndex?: number): StreamCommand;
+/**
+ * 流中途打断（cooperative cancel）。后端收到后停止当前 round，流以 ROOT message.stop
+ * （payload.stopReason=="interrupted"）终结。payload 为空对象 {}（后端契约已核实）。
+ */
+declare function buildInterrupt(conversationId: string): StreamCommand;
+/**
+ * 流中途引导（steer）。后端入队 content，下一 round 注入 SystemMessage；无任何 ack 事件
+ * （v3 ack 已退役），流正常完成。payload 为 {content}（后端契约已核实）。
+ */
+declare function buildSteer(content: string, conversationId: string): StreamCommand;
+
+interface SendMessageOpts {
+    conversationId?: string;
+    agentKey?: string;
+    agentId?: string;
+    pageContext?: Record<string, unknown>;
+    /**
+     * confirm/ask 决策回发后继续消费 resume 流到真终态（Task B3）。
+     *
+     * v4 协议：confirm 触发时原流以 ROOT message.stop 终态（HALT 语义）；决策回发后后端
+     * resume 续推事件。开启本开关后终态规则变为：
+     *  - ROOT message.stop 且无未决交互 → 终态（含全程无交互的普通流）
+     *  - ROOT message.stop 且有未决交互 → hold（HALT / 串联 confirm 的中间 stop）
+     *  - `control.interaction.resolved(phase=TERMINAL)` 清空未决集且曾 hold 过 ROOT stop
+     *    → 终态兜底（TERMINAL 是 InteractionSession 生命周期事件，必达；防 resume 段缺
+     *    ROOT message.stop 的后端回归挂死 CLI）
+     * 仅在调用方会回发决策（--on-confirm / --on-ask / 交互式确认）时开启；默认关闭，
+     * 行为与历史完全一致。
+     */
+    holdUntilInteractionTerminal?: boolean;
+    /**
+     * 重新生成模式（ADR-089）：不发 message.create，改发 `response.regenerate`
+     * （payload {fromSeq}）。fromSeq = 被重生成 assistant 段起点的 journal seq
+     * （LLM_DONE；timeline chat-text item 的 seq 即它）。后端 append SEGMENT_SUPERSEDED
+     * marker 后用原 user message 重跑 loop，新流事件 requestId 回显本命令 commandId
+     * ——iterator 过滤与终态规则完全复用。必须配合已存在的 conversationId。
+     */
+    regenerateFromSeq?: number;
+    /** 附件元数据（issue #64）：已上传文档随消息发送，后端 parseAttachments 同形态。 */
+    attachments?: AttachmentMeta[];
+}
+interface MessageStreamHandle {
+    conversationId: string;
+    commandId: string;
+    events: AsyncIterable<StreamEventEnvelope>;
+    /**
+     * 客户端中断当前流（ADR-085）。
+     * 发送 `stream.cancel` command 到后端；后端会回 `response.interrupted` 作 iterator 终态。
+     * 调用方仍需等 iterator 走完才能确认终止。
+     */
+    cancel(reason?: string): void;
+    /**
+     * 订阅本 conversation 的带外控制通道事件（control.interaction.request / resolved）。
+     * 仅转发 `ev.conversationId === conversationId` 的事件；返回取消订阅函数。
+     */
+    onControl(fn: (ev: ControlChannelEnvelope) => void): () => void;
+    /**
+     * 回发 client→server 控制命令（approval.confirm / approval.reject / interaction.answer）。
+     * 由 control-channel 的 build* 构造，透传到 ws。
+     */
+    sendCommand(cmd: StreamCommand): void;
+}
+declare function sendMessageAndStream(ws: WsClient, prompt: string, opts?: SendMessageOpts): Promise<MessageStreamHandle>;
+
+interface OneShotToolCall {
+    /** 工具名；委派为 'hcm_delegate'。无法解析时 '?'。 */
+    name: string;
+    /** 参数预览（reducer 已按显示宽度截断）；委派时为目标 agentKey。 */
+    argsPreview: string;
+    success: boolean;
+    elapsedMs: number;
+    /** 委派调用标记。 */
+    isDelegation?: boolean;
+    /** 归属父 tool_use（顶层直接工具为 null）。 */
+    parentToolUseId: string | null;
+}
+interface OneShotResult {
+    conversationId: string;
+    streamId: string;
+    traceId: string | null;
+    /** 最终助手回答正文（ROOT 段文本；委派 specialist 的中间文本不计入）。 */
+    content: string;
+    toolCalls: OneShotToolCall[];
+    elapsedMs: number;
+    events: StreamEventEnvelope[];
+    /** 终态原因（v4 message.stop.stopReason）；未见终态时 undefined。 */
+    stopReason?: string;
+    /** 本轮总 token（v4 message.stop.totalTokens）。 */
+    tokens?: number;
+}
+interface OneShotOpts extends SendMessageOpts {
+    collectEvents?: boolean;
+}
+/**
+ * 非流式单发：消费 v4 事件流并聚合出最终结果。
+ *
+ * 🔴 与流式路径同源：把事件喂进 {@link createV4Reducer}（与 CLI streaming、Web 端 fold
+ * 状态机一致的 v4 语义层），用一个 headless sink 累加 ROOT 文本 + 收集工具调用——而非
+ * 手搓第二套聚合。历史 bug：旧实现监听已废弃的 v3 事件名（response.part.delta /
+ * response.completed / response.tool.*），后端早改发 v4（block.delta:text_delta /
+ * message.stop）→ switch 全不命中 → content 恒空（--no-stream / --output json 拿到空答案）。
+ * 语义层复用见 ADR-129 D2：只换「画」的层，聚合逻辑不重复实现。
+ *
+ * 终态由 stream-iterator 在 ROOT message.stop（或断连）关闭 async iterator 驱动，本函数
+ * 无需自判终止。v3 残余 `response.failed`（仅老路径出现）仍显式抛 CliError 保留旧语义。
+ */
+declare function oneShot(ws: WsClient, prompt: string, opts?: OneShotOpts): Promise<OneShotResult>;
+
+interface ConversationState {
+    lastConversationId?: string;
+    lastStreamId?: string;
+    lastTraceId?: string;
+    lastAgentKey?: string;
+    updatedAt: string;
+}
+declare function loadConversationState(profile: string): Promise<ConversationState | null>;
+declare function saveConversationState(profile: string, state: ConversationState): Promise<void>;
+
+/** Default analyst agent id (seeded in HCM at tenant=__SYSTEM__). */
+declare const DEFAULT_AGENT_ID = "019cca00-0000-7000-0000-000000000001";
+interface CreatedConversation {
+    id: string;
+    agentId: string;
+    title?: string;
+}
+/**
+ * Create a new conversation in HCM. Required before sending any /ws/conversation
+ * message — the WS handler looks up conversation→agentId in DB.
+ */
+declare function createConversation(http: AxiosInstance, agentId?: string): Promise<CreatedConversation>;
+
+interface V4RenderSink {
+    onText(text: string, parentToolUseId: string | null): void;
+    onThinkingDelta(text: string, parentToolUseId: string | null): void;
+    onThinkingDone(parentToolUseId: string | null): void;
+    onToolStarted(callId: string, toolName: string, argsPreview: string, parentToolUseId: string | null): void;
+    /**
+     * @param nextSteps G5 · 工具失败时从 result envelope 解析出的 ADR-058 路标（`error.nextSteps`
+     *   数组 / 顶层 `next_step`）。成功或无路标时 undefined。供 host 在失败行下透出下一步指引。
+     * @param toolName  #1930 · 工具名。优先取 block.start 注册值；缓存短路 no-op 等无 block.start
+     *   的事件由 reducer 从 result 文本兜底解析（如「hcm_describe_tool (缓存命中)」），避免 host
+     *   裸显示 `?`。仍解析不出时 undefined，host 自行兜底。
+     */
+    onToolResult(callId: string, success: boolean, durMs: number, childConversationId: string | null, parentToolUseId: string | null, nextSteps?: string[], toolName?: string): void;
+    onContentPart(part: Record<string, unknown>, parentToolUseId: string | null): void;
+    /**
+     * 用户中途纠偏在轮界被真正注入（v4 `steering.applied` 顶层事件，W1a-2）。
+     * 仅注入时到达——客户端禁止在发 response.steer 时乐观本地显示「已纠偏」。
+     */
+    onSteeringApplied(contents: string[], round: number): void;
+    onDelegationStart(agentKey: string, parentToolUseId: string): void;
+    /**
+     * 委派收口。由 hcm_delegate 自身的 tool.result 驱动（后端时序保证：子流 message.stop
+     * 先到、父 tool.result 紧随其后，见 WebSocketRuntimeEventProjector.finishChildStreamIfAny）
+     * ——因此能携带委派整体 success / 耗时 / 失败路标（2026-06-11 review C1/I1：旧版由子
+     * message.stop 驱动拿不到 success，失败委派被静默渲染成功）。
+     *
+     * @param nextSteps 委派失败时的 ADR-058 路标；成功为 undefined。
+     */
+    onDelegationEnd(parentToolUseId: string, success: boolean, durMs: number, nextSteps?: string[]): void;
+    /**
+     * 委派「暂停待应答」（非失败）：specialist 在子流内调 hcm_ask_user / 触发风险确认时，
+     * 后端按 HALT 语义给 hcm_delegate 的 tool.result 发 transport `success=false`，但其
+     * envelope 实为 `ok:true` + `INTERACTION_REQUIRED`/`CONFIRMATION_REQUIRED` 标记
+     * （后端 InteractionSuspendMiddleware / RiskConfirmationMiddleware）。这不是失败——
+     * 用户应答后委派会 RESUME（同 parentToolUseId 再来一段 message.start）续跑到真终态。
+     *
+     * 消费端据此：保留委派块不收口、累计本段耗时，等 RESUME 续同一块——避免把暂停
+     * 渲染成红色「委派失败」、并避免暂停→续跑被计为两次委派（CLI append-only 无法回填）。
+     * @param durMs 暂停前本段执行耗时（累计进委派块总耗时）。
+     */
+    onDelegationPaused(parentToolUseId: string, durMs: number): void;
+    onTerminal(stopReason: string, tokens: number): void;
+}
+/**
+ * 判定一条 hcm_delegate 的 tool.result（transport `success=false`）实为「暂停待应答」而非失败。
+ *
+ * 后端 wire 接缝不一致：HALT 时 executor 结果 `success=true`+`haltConversation`，但投影到
+ * delegate 的 tool.result `success` 字段为 false；其 resultData envelope 仍诚实保留 `ok:true`
+ * + summary/data 带 `INTERACTION_REQUIRED`（ASK）/`CONFIRMATION_REQUIRED`（CONFIRM）标记。
+ * 以「envelope ok===true 且含交互标记」为准绳——纯结构信号，不误伤真失败（真失败 ok:false）。
+ */
+declare function detectDelegationPause(resultData: unknown): boolean;
+/**
+ * #1930 Bug B · 判定一条**直接工具**（非委派）的 tool.result 实为「待确认 / 待应答」控制信号，
+ * 而非工具执行结果。
+ *
+ * 后端写动作命中确认门 / 交互门时，会先发一条 transport `success=false` 的 TOOL_COMPLETED，其
+ * result 是纯文本前缀 {@code "CONFIRMATION_REQUIRED: ..."} / {@code "INTERACTION_REQUIRED: ..."}
+ * （非 JSON envelope），同时另发一条 {@code control.interaction.request} 让 host 弹确认卡。该 tool.result
+ * 对展示流是冗余的——若按普通工具渲染会变成红色 `⚙ ? ✗ 0ms` 假失败并计入失败统计（实测用户困惑）。
+ *
+ * 以「结果文本以这两个标记**起始**」为准绳（强协议信号，正常工具结果不会以此开头），故 host 可安全
+ * 抑制该行，把待确认态交给 confirm 卡承载。委派场景的同类暂停由 {@link detectDelegationPause} 处理，
+ * 二者互不重叠（委派结果是 envelope，直接工具是纯文本前缀）。
+ */
+declare function detectDirectInteractionPending(resultData: unknown): boolean;
+/**
+ * #1930 Bug A · 为无 block.start 注册名的 tool.result 从结果文本兜底解析有意义的展示名。
+ *
+ * 当前唯一已知来源：ADR-095 catalog 缓存短路 no-op——后端直接发 TOOL_COMPLETED（无 TOOL_STARTED），
+ * result 为 {@code "[ADR-095 catalog cache hit] 工具 <toolName> 已在本 sub-session ..."}。解析出工具名
+ * 时返回 {@code "<toolName> (缓存命中)"}，解析不出则返回 {@code "缓存命中"}。其他结果返回 undefined
+ * （host 保留原 `?` 兜底给真未知事件，不强行编造名字）。
+ */
+declare function deriveNamelessToolLabel(resultData: unknown): string | undefined;
+/**
+ * #1949 · 从确认门 / 交互门占位结果文本解析被挂起的工具名。
+ *
+ * 后端 {@code RiskConfirmationMiddleware} 挂起时发的占位 TOOL_COMPLETED，其 result 为纯文本
+ * {@code "CONFIRMATION_REQUIRED: 等待用户确认 tool=<name>, confirmationId=..., scopeKey=..."}
+ * （INTERACTION_REQUIRED 亦可能带 {@code tool=}）。用户确认后被 resume 的工具，其真结果
+ * {@code tool.result} 可能先于（或缺失）resume 段 {@code block.start} 抵达消费端 → {@code toolNameByCallId}
+ * 无注册名 → 裸显示 `?`（#1949）。这里在抑制占位结果时解析出工具名，供 resume 真结果按 callId 兜底取名。
+ * 解析不出返回 undefined。
+ */
+declare function parseConfirmToolName(resultData: unknown): string | undefined;
+/**
+ * G5 · 从 tool.result 的 resultData 防御性提取 ADR-058 `next_step` 路标。
+ *
+ * 后端 wire：`resultData = { result: "<envelope JSON 字符串>" }`，失败 envelope 形如
+ * `{ ok:false, error:{ code, message, nextSteps:[...] } }`；部分执行器平铺顶层 `next_step`
+ * （可为 string / string[] / {message,...} map）。这里兼容多形态，任一解析失败都静默返回
+ * undefined（非 JSON 纯文本 result 不炸）。
+ */
+declare function extractNextSteps(resultData: unknown): string[] | undefined;
+declare function createV4Reducer(sink: V4RenderSink): {
+    handle: (type: string, payload: Record<string, unknown>) => boolean;
+};
+
+declare function isDelegationToolName(name: string): boolean;
+
+/** 字符串的终端显示宽度（列数）。 */
+declare function displayWidth(s: string): number;
+/** 按显示宽度截断，超宽时截到 maxWidth-1 列并补「…」；未超宽原样返回。 */
+declare function truncateDisplay(s: string, maxWidth: number): string;
+
+/**
+ * 续会话回放（CLI 做透轮刀⑤，对标 Claude Code resume 的上下文可见性）。
+ *
+ * hcm chat 只有显式 --resume 续接 conversation 时才回放历史；否则默认开新会话。
+ * 本模块拉
+ * timeline（GET /api/models/ConversationModel/{id}/action/timeline，与 Web 回放
+ * 同源）折出轻量摘要：最近 N 轮 user/assistant 文本 + 更早轮次计数。
+ */
+/** timeline 条目（后端 TimelineItemDto 的 CLI 侧投影，只取回放需要的字段）。 */
+interface TimelineItemLite {
+    kind: string;
+    seq: number;
+    /** user-msg / steering 的原文。 */
+    text?: string | null;
+    /** chat-text 的正文。 */
+    content?: string | null;
+    /** user-msg 附件元数据（#1849 journal 单源透传；issue #64 回放 📎）。 */
+    attachments?: Array<{
+        fileName?: string;
+    }> | null;
+}
+interface ResumeTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+interface ResumeSummary {
+    conversationId: string;
+    /** 会话总轮数（user-msg 条目数）。 */
+    totalRounds: number;
+    /** 最近 maxRounds 轮的 user/assistant 文本（已按显示宽度截断为单行摘要）。 */
+    recent: ResumeTurn[];
+}
+/**
+ * 拉取 conversation timeline。任何失败（网络/404/结构异常）返回 null——
+ * 回放是体验增强，绝不阻断聊天主流程。
+ */
+declare function fetchConversationTimeline(http: AxiosInstance, conversationId: string): Promise<TimelineItemLite[] | null>;
+/**
+ * 严格拉取 conversation timeline。用于 CLI 显式 inspect 场景：网络/404/结构异常都应暴露，
+ * 不能像 resume 体验增强那样静默吞掉。
+ */
+declare function fetchConversationTimelineStrict(http: AxiosInstance, conversationId: string): Promise<TimelineItemLite[]>;
+/**
+ * timeline → 续会话摘要。取最近 maxRounds 轮：每轮 = user-msg 原文 + 该轮最后一条
+ * chat-text 正文（中间 tools/delegation/steering 等过程条目不进摘要——回顾要的是
+ * 「聊到哪了」不是过程重放）。文本截为单行（换行折叠 + 显示宽度截断）。
+ */
+declare function buildResumeSummary(conversationId: string, items: TimelineItemLite[], maxRounds?: number, maxWidth?: number): ResumeSummary | null;
+declare function findLastAssistantSeq(items: TimelineItemLite[] | null | undefined): number | null;
+
+interface ConversationListItem {
+    id?: string;
+    title?: string | null;
+    summary?: string | null;
+    agentId?: string | null;
+    messageCount?: number | null;
+    totalTokens?: number | null;
+    lastActiveAt?: string | null;
+    lastMessagePreview?: string | null;
+    createTime?: string | null;
+    updateTime?: string | null;
+}
+interface ConversationListResult {
+    rows: ConversationListItem[];
+    total?: number;
+}
+declare function fetchRecentConversations(http: AxiosInstance, limit?: number): Promise<ConversationListResult>;
+
+declare const MINI_CONTEXT_FILE = "hcm.context.json";
+declare const MINI_STATE_DIR = ".hcm";
+declare const MINI_PULL_MANIFEST_FILE = "mini-manifest.json";
+declare const MINI_REMOTE_ROOT = "mini_apps";
+declare const MINI_CONTEXT_KIND = "hcm-mini-app";
+declare const MINI_CONTEXT_VERSION = 1;
+type MiniSurface = 'embedded' | 'standalone';
+type MiniTemplateKind = 'dashboard' | 'multi-page' | 'writable-workbench';
+interface WorkspaceFileItem {
+    id: string;
+    workspaceKey: string;
+    relativePath: string;
+    fileType?: string;
+    fileSize?: number;
+    lastModified?: number | string | null;
+}
+interface WorkspaceFileContent {
+    workspaceKey: string;
+    relativePath: string;
+    content: string;
+    fileType?: string;
+}
+interface WorkspaceFileListResult {
+    data: WorkspaceFileItem[];
+    total: number;
+}
+interface MiniProjectContext {
+    kind: typeof MINI_CONTEXT_KIND;
+    version: typeof MINI_CONTEXT_VERSION;
+    appCode: string;
+    workspaceKey: string;
+    remotePrefix: string;
+    tenantId?: string;
+    endpoint?: string;
+    profile?: string;
+    updatedAt: string;
+}
+interface MiniFileSnapshot {
+    localPath: string;
+    remotePath: string;
+    fileId?: string;
+    sha256: string;
+    size: number;
+    lastModified?: number | string | null;
+}
+interface MiniPullManifest {
+    version: typeof MINI_CONTEXT_VERSION;
+    appCode: string;
+    workspaceKey: string;
+    remotePrefix: string;
+    profile?: string;
+    pulledAt: string;
+    files: MiniFileSnapshot[];
+}
+interface MiniLocalFile {
+    localPath: string;
+    absolutePath: string;
+    content: string;
+    sha256: string;
+    size: number;
+}
+type MiniLocalStatus = 'added' | 'modified' | 'deleted' | 'unchanged';
+interface MiniStatusEntry {
+    localPath: string;
+    remotePath: string;
+    status: MiniLocalStatus;
+    fileId?: string;
+    sha256?: string;
+    baseSha256?: string;
+}
+interface MiniValidationResult {
+    valid: boolean;
+    appCode?: string;
+    workspaceKey?: string;
+    errors: string[];
+    warnings: string[];
+}
+interface MiniPullResult {
+    appCode: string;
+    workspaceKey: string;
+    targetDir: string;
+    files: MiniFileSnapshot[];
+}
+type MiniPushOperation = 'create' | 'update' | 'delete' | 'skip';
+interface MiniPushPlanItem {
+    operation: MiniPushOperation;
+    localPath: string;
+    remotePath: string;
+    fileId?: string;
+    reason?: string;
+}
+interface MiniPushConflict {
+    localPath: string;
+    remotePath: string;
+    reason: string;
+}
+interface MiniPushResult {
+    appCode: string;
+    workspaceKey: string;
+    dryRun: boolean;
+    operations: MiniPushPlanItem[];
+    conflicts: MiniPushConflict[];
+}
+interface MiniPreviewTarget {
+    key: 'bare' | 'standalone' | 'embedded';
+    name: string;
+    url: string;
+}
+type MiniSmokeTargetKind = 'preview' | 'manifest' | 'asset';
+interface MiniSmokeTargetResult {
+    kind: MiniSmokeTargetKind;
+    surface?: MiniPreviewTarget['key'];
+    url: string;
+    status: number | null;
+    ok: boolean;
+    error?: string;
+}
+interface MiniSmokeResult {
+    ok: boolean;
+    checked: number;
+    passed: number;
+    failed: number;
+    targets: MiniSmokeTargetResult[];
+}
+type MiniVerifyNextAction = 'push' | 'fix-validation' | 'resolve-conflict' | 'inspect-status' | 'inspect-preview';
+interface MiniVerifyPlan {
+    operations: MiniPushPlanItem[];
+    conflicts: MiniPushConflict[];
+}
+interface MiniVerifyReport {
+    ok: boolean;
+    validate: MiniValidationResult;
+    status: MiniStatusEntry[];
+    plan: MiniVerifyPlan | null;
+    planSkipped?: string;
+    preview: MiniPreviewTarget[];
+    smoke?: MiniSmokeResult | null;
+}
+interface MiniVerifySummary {
+    validate: {
+        ok: boolean;
+        errors: number;
+        warnings: number;
+        appCode?: string;
+        workspaceKey?: string;
+    };
+    status: {
+        total: number;
+        changed: number;
+        added: number;
+        modified: number;
+        deleted: number;
+        unchanged: number;
+    };
+    dryRun: {
+        ok: boolean;
+        skipped: boolean;
+        skippedReason?: string;
+        operations: number;
+        creates: number;
+        updates: number;
+        deletes: number;
+        skips: number;
+        conflicts: number;
+    };
+    preview: {
+        ok: boolean;
+        count: number;
+        surfaces: MiniPreviewTarget['key'][];
+    };
+}
+interface MiniVerifyChangedFile {
+    path: string;
+    status: MiniLocalStatus;
+    remotePath: string;
+}
+interface MiniVerifyPreviewUrl {
+    surface: MiniPreviewTarget['key'];
+    name: string;
+    url: string;
+}
+interface MiniVerifyBrowserAcceptance {
+    recommendedUrl?: string;
+    expectedTexts: string[];
+    expectedNetwork: string[];
+    console: {
+        failOn: Array<'error' | 'warn'>;
+    };
+}
+interface MiniVerifyAgentReport {
+    ok: boolean;
+    safeToPush: boolean;
+    nextAction: MiniVerifyNextAction;
+    summary: MiniVerifySummary;
+    changedFiles: MiniVerifyChangedFile[];
+    conflicts: MiniPushConflict[];
+    previewUrls: MiniVerifyPreviewUrl[];
+    browserAcceptance: MiniVerifyBrowserAcceptance;
+    smoke: MiniSmokeResult | null;
+}
+
+declare function listWorkspaceFiles(http: AxiosInstance, workspaceKey: string, options?: {
+    pageSize?: number;
+}): Promise<WorkspaceFileListResult>;
+declare function loadWorkspaceFileContent(http: AxiosInstance, fileId: string): Promise<WorkspaceFileContent>;
+declare function saveWorkspaceFileContent(http: AxiosInstance, fileId: string, content: string): Promise<WorkspaceFileItem>;
+declare function createWorkspaceFile(http: AxiosInstance, workspaceKey: string, relativePath: string, content: string): Promise<WorkspaceFileItem>;
+declare function deleteWorkspaceFile(http: AxiosInstance, fileId: string): Promise<void>;
+
+interface MiniInitArgs {
+    appCode: string;
+    workspaceKey: string;
+    targetDir: string;
+    name?: string;
+    defaultSurface?: MiniSurface;
+    templateKind?: MiniTemplateKind;
+    writableModel?: string;
+    writableFields?: string[] | null;
+    writableDefaults?: Record<string, unknown>;
+    writableTodayDefaultFields?: string[];
+    requiredScopes?: string[];
+    tenantId?: string;
+    endpoint?: string;
+    profile?: string;
+    force?: boolean;
+}
+interface MiniPullArgs {
+    http: AxiosInstance;
+    appCode: string;
+    workspaceKey: string;
+    targetDir: string;
+    tenantId?: string;
+    endpoint?: string;
+    profile?: string;
+    force?: boolean;
+}
+interface MiniPushArgs {
+    http: AxiosInstance;
+    rootDir: string;
+    dryRun?: boolean;
+}
+declare function initMiniAppProject(args: MiniInitArgs): Promise<MiniPullResult>;
+declare function pullMiniAppProject(args: MiniPullArgs): Promise<MiniPullResult>;
+declare function getMiniStatus(rootDir: string): Promise<MiniStatusEntry[]>;
+declare function validateMiniProject(rootDir: string): Promise<MiniValidationResult>;
+declare function pushMiniAppProject(args: MiniPushArgs): Promise<MiniPushResult>;
+declare function buildMiniPreviewTargets(rootDir: string, frontendBaseUrl: string): Promise<MiniPreviewTarget[]>;
+interface MiniSmokeFetchResponse {
+    status: number;
+}
+type MiniSmokeFetch = (url: string, init?: {
+    headers?: Record<string, string>;
+    method: 'GET';
+    signal?: AbortSignal;
+}) => Promise<MiniSmokeFetchResponse>;
+interface MiniSmokeCheckArgs {
+    rootDir: string;
+    frontendBaseUrl: string;
+    previewTargets: MiniPreviewTarget[];
+    fetcher?: MiniSmokeFetch;
+    accessToken?: string | null;
+    timeoutMs?: number;
+}
+declare function runMiniSmokeChecks(args: MiniSmokeCheckArgs): Promise<MiniSmokeResult>;
+declare function buildMiniVerifyAgentReport(report: MiniVerifyReport): MiniVerifyAgentReport;
+declare function formatMiniVerifyReport(report: MiniVerifyReport): string;
+declare function readMiniContext(rootDir: string): Promise<MiniProjectContext>;
+declare function readPullManifest(rootDir: string): Promise<MiniPullManifest>;
+
+interface MiniTemplateArgs {
+    appCode: string;
+    name?: string;
+    defaultSurface: MiniSurface;
+    requiredScopes: string[];
+    tenantId: string;
+    templateKind?: MiniTemplateKind;
+    writableModel?: string;
+    writableFields?: string[] | null;
+    writableDefaults?: Record<string, unknown>;
+    writableTodayDefaultFields?: string[];
+}
+interface MiniWritableTemplateConfig {
+    model?: string;
+    fields?: string[] | null;
+    defaults?: Record<string, unknown>;
+    todayDefaultFields?: string[];
+}
+declare function defaultMiniRequiredScopes(templateKind?: MiniTemplateKind, writableConfig?: MiniWritableTemplateConfig): string[];
+declare function buildMiniAppTemplateFiles(args: MiniTemplateArgs): Array<{
+    localPath: string;
+    content: string;
+}>;
+declare function inferMiniWritableTemplateOptionsFromModel(description: ModelDescription): {
+    fields: string[];
+    defaults: Record<string, unknown>;
+    todayDefaultFields: string[];
+};
+
+/**
+ * 模型缓存运维（两级缓存：Caffeine 本地 + Redis 远程）。
+ *
+ * 后端契约（CommonModelQueryCacheController）：
+ * - `GET    /api/models/{model}/cache`       统计
+ * - `DELETE /api/models/{model}/cache`       清全部实体缓存
+ * - `DELETE /api/models/{model}/cache/{id}`  清单条
+ * - `DELETE /api/models/{model}/meta/cache`  清元数据缓存（Code 级 YAML + Action 定义）
+ *
+ * 🔴 缓存必须走 API 管理，不直接操作 Redis —— 保证一致性、审计与业务规则生效。
+ */
+interface CacheStats {
+    modelKey: string;
+    [k: string]: unknown;
+}
+interface CacheClearResult {
+    modelKey: string;
+    clearedCount?: number;
+    message?: string;
+    [k: string]: unknown;
+}
+declare function getCacheStats(http: AxiosInstance, model: string): Promise<CacheStats>;
+declare function clearModelCache(http: AxiosInstance, model: string, id?: string): Promise<CacheClearResult>;
+interface ClearMetaCacheOpts {
+    /** 元数据类型（list / info / view / filter / page…），省略 = 全清 */
+    type?: string;
+    /** 状态变体（如 self），配合 type 使用 */
+    state?: string;
+}
+declare function clearMetaCache(http: AxiosInstance, model: string, opts?: ClearMetaCacheOpts): Promise<CacheClearResult>;
+
+/**
+ * 租户开通（bootstrap）—— 交付旅程第一步。
+ *
+ * 后端契约（TenantBootstrapController）：
+ * - `POST /api/bootstrap/tenant`，header `X-Bootstrap-Key: <secret>`
+ * - body `{ tenantId, adminUsername, adminPassword, tenantName? }`
+ *
+ * 🔴 该端点不走普通 Bearer 认证，用独立的 bootstrap key —— 它要在「还没有任何
+ * 租户和用户」的时刻可用。key 由部署方持有，绝不写进 skill 正文或提交进仓库。
+ */
+interface BootstrapTenantRequest {
+    tenantId: string;
+    adminUsername: string;
+    adminPassword: string;
+    tenantName?: string;
+}
+interface BootstrapReconcileResult {
+    component?: string;
+    version?: number;
+    status?: string;
+    [k: string]: unknown;
+}
+interface BootstrapTenantResult {
+    success: boolean;
+    tenantId: string;
+    adminUserId?: string;
+    message?: string;
+    results?: BootstrapReconcileResult[];
+}
+declare function bootstrapTenant(http: AxiosInstance, bootstrapKey: string, req: BootstrapTenantRequest): Promise<BootstrapTenantResult>;
+
+/**
+ * 租户元数据读写（TenantMetaController，`/api/tenant-meta`）。
+ *
+ * 统一走 query-param 形态（`?path=`）而非路径通配 `/meta/**`：meta 路径含斜杠与点，
+ * query param 避免 URL 段解析歧义与路径穿越面。
+ *
+ * 后端契约：
+ * - `GET    /api/tenant-meta/list?keyword=&type=&page=&pageSize=`
+ * - `GET    /api/tenant-meta/meta?path=<metaName>`
+ * - `PUT    /api/tenant-meta/meta?path=<metaName>`  body `{ content: "<原文>" }`
+ * - `DELETE /api/tenant-meta/meta?path=<metaName>`
+ *
+ * 🔴 写入需 config-admin 身份，且 source 必须可写（租户开发空间绑定态）——
+ * 后端 `assertConfigAdmin` / `assertWritableSource` 会拒绝越权与只读源。
+ */
+interface TenantMetaEntry {
+    metaName?: string;
+    name?: string;
+    type?: string;
+    lastModified?: string;
+    size?: number;
+    [k: string]: unknown;
+}
+interface ListTenantMetaOpts {
+    keyword?: string;
+    /** yml / properties / all（默认 all） */
+    type?: string;
+    page?: number;
+    pageSize?: number;
+}
+declare function listTenantMeta(http: AxiosInstance, opts?: ListTenantMetaOpts): Promise<{
+    items: TenantMetaEntry[];
+    total?: number;
+    raw: unknown;
+}>;
+/** 读单份 meta 原文。返回 `content` 字符串（后端包在信封里时自动解包）。 */
+declare function getTenantMeta(http: AxiosInstance, path: string): Promise<string>;
+interface SaveMetaResult {
+    success?: boolean;
+    message?: string;
+    [k: string]: unknown;
+}
+declare function saveTenantMeta(http: AxiosInstance, path: string, content: string): Promise<SaveMetaResult>;
+declare function deleteTenantMeta(http: AxiosInstance, path: string): Promise<SaveMetaResult>;
+
+interface HttpClientOptions {
+    endpoint: string;
+    getAccessToken: () => Promise<string | null>;
+    onRefresh: () => Promise<void>;
+    timeoutMs?: number;
+    userAgent?: string;
+}
+declare function createHttpClient(opts: HttpClientOptions): AxiosInstance;
+
+/**
+ * 睿戎 Chiron 交付技能库客户端。
+ *
+ * <p>🔴 这些端点**免认证**——交付顾问接手的是「还没有租户、还没有账号」的空环境，
+ * 必须先装技能才能建租户。所以本模块只需要 endpoint，不碰 identity/token。
+ *
+ * 后端契约（ChironController）：
+ * - `GET /skills.json`      目录 manifest
+ * - `GET /skills/{id}.md`   技能原文
+ */
+interface ChironSkill {
+    id: string;
+    title: string;
+    category: string;
+    /** cli = 动作面已全改写为 hcm 命令；curl = 仍为原始 HTTP 形态 */
+    actionSurface: 'cli' | 'curl';
+    description: string;
+    /** 交付生命周期阶段（多值）——一个技能天然跨阶段 */
+    stages: string[];
+    bytes: number;
+    markdownUrl: string;
+}
+interface ChironStage {
+    key: string;
+    name: string;
+    description: string;
+    /** 该阶段下的技能数。0 = 交付路径上的覆盖缺口 */
+    skillCount: number;
+}
+interface ChironCategory {
+    key: string;
+    name: string;
+    description: string;
+    skills: ChironSkill[];
+}
+interface ChironManifest {
+    name: string;
+    title: string;
+    tagline: string;
+    skillCount: number;
+    stages: ChironStage[];
+    categories: ChironCategory[];
+}
+declare function fetchSkillCatalog(http: AxiosInstance): Promise<ChironManifest>;
+declare function fetchSkillMarkdown(http: AxiosInstance, id: string): Promise<string>;
+declare function flattenSkills(manifest: ChironManifest): ChironSkill[];
+/** 按交付生命周期阶段筛选。 */
+declare function filterByStage(skills: ChironSkill[], stage?: string): ChironSkill[];
+/** 关键词匹配 id / 标题 / 描述 / 分类，全部小写包含。 */
+declare function matchSkills(skills: ChironSkill[], keyword?: string): ChironSkill[];
+
+/**
+ * 租户系统参数（配置中心）。
+ *
+ * <p>后端契约（TenantSettingDomainController）：
+ * <ul>
+ *   <li>`GET    /api/tenant-settings/domains/{domain}` 读某域（定义 + 租户覆盖值合并，缺失回退默认值）</li>
+ *   <li>`PATCH  /api/tenant-settings/domains/{domain}` 写，body `{items:[{namespace,settingKey,value}]}`</li>
+ *   <li>`DELETE /api/tenant-settings/domains/{domain}/items/{ns}/{key}?revision=N` 清除租户覆盖</li>
+ * </ul>
+ *
+ * <p>🔴 **不要走标准 Model 的 PUT 改这些值**：那条路直接写库，绕过定义校验、
+ * 乐观锁与历史留痕——改坏 namespace/valueType 会让记录不再匹配任何定义。
+ * 后端已从该 Model 的权限里移除 update action，这里也只暴露上面三条受控路径。
+ */
+interface SettingItem {
+    namespace: string;
+    settingKey: string;
+    value?: unknown;
+    valueType?: string;
+    defaultValue?: unknown;
+    revision?: number;
+    label?: string;
+    [k: string]: unknown;
+}
+declare function getSettingDomain(http: AxiosInstance, domain: string): Promise<{
+    items: SettingItem[];
+    raw: unknown;
+}>;
+interface SettingWrite {
+    namespace: string;
+    settingKey: string;
+    value: unknown;
+}
+declare function patchSettingDomain(http: AxiosInstance, domain: string, items: SettingWrite[]): Promise<unknown>;
+declare function resetSettingItem(http: AxiosInstance, domain: string, namespace: string, settingKey: string, revision?: number): Promise<unknown>;
+/**
+ * 解析 `namespace.settingKey=value` 形态的 --set 参数。
+ *
+ * settingKey 取最后一段，其余是 namespace —— namespace 本身含点
+ * （如 `security.password`），所以从右边切，不能 split('.') 取前两段。
+ */
+declare function parseSettingAssignment(raw: string): SettingWrite;
+
+export { type ActionHttpMethod, type ActionInput, type ActionMeta, type ActionResult, type ActionScope, type AnyStreamEvent, type ApprovalConfirmPayload, type ApprovalRejectPayload, type AttachmentMeta, type AuthScheme, type BootstrapReconcileResult, type BootstrapTenantRequest, type BootstrapTenantResult, type CacheClearResult, type CacheStats, type ChangePasswordInput, type ChironCategory, type ChironManifest, type ChironSkill, type ChironStage, type ClearMetaCacheOpts, CliError, CliErrorCode, type CliErrorInit, type ClientAuthContext, type ClientCredentialsInput, type ConnectionMessage, type ControlChannelEnvelope, type ConversationListItem, type ConversationListResult, type ConversationState, type CreateResult, type CreatedConversation, DEFAULT_AGENT_ID, DEFAULT_SESSION_TTL_SECONDS, type DescribeOpts, type EnvConfig, ExitCode, type FieldMeta, type Fixture, type FormatOptions, type GlobalConfig, HcmClient, type HcmClientOpts, type HttpClientOptions, type IdentityMeta, type ImportClient, type ImportOptions, type ImportResult, type InteractionAnswerPayload, type InteractionRequest, type InteractionResolved, type ListTenantMetaOpts, type LoginOutcome, MINI_CONTEXT_FILE, MINI_CONTEXT_KIND, MINI_CONTEXT_VERSION, MINI_PULL_MANIFEST_FILE, MINI_REMOTE_ROOT, MINI_STATE_DIR, type MessageClass, type MessageCreatePayload, type MessageStreamHandle, type MigrationSummary, type MiniFileSnapshot, type MiniInitArgs, type MiniLocalFile, type MiniLocalStatus, type MiniPreviewTarget, type MiniProjectContext, type MiniPullArgs, type MiniPullManifest, type MiniPullResult, type MiniPushArgs, type MiniPushConflict, type MiniPushOperation, type MiniPushPlanItem, type MiniPushResult, type MiniSmokeCheckArgs, type MiniSmokeFetch, type MiniSmokeFetchResponse, type MiniSmokeResult, type MiniSmokeTargetKind, type MiniSmokeTargetResult, type MiniStatusEntry, type MiniSurface, type MiniTemplateArgs, type MiniTemplateKind, type MiniValidationResult, type MiniVerifyAgentReport, type MiniVerifyBrowserAcceptance, type MiniVerifyChangedFile, type MiniVerifyNextAction, type MiniVerifyPlan, type MiniVerifyPreviewUrl, type MiniVerifyReport, type MiniVerifySummary, type MiniWritableTemplateConfig, type ModelDescription, type ModelQueryDsl, type OneShotOpts, type OneShotResult, type OneShotToolCall, type OutputFormat, PASSWORD_CHANGE_REQUIRED, PROACTIVE_REFRESH_MARGIN_SECONDS, type PairingLoginInput, type ParsedPlaceholder, type PasswordChangeChallenge, type PasswordLoginInput, type PatLoginInput, type Principal, type ProfileConfig, type QueryResult, RefStore, type RefreshInput, type RelationMeta, type RemoveResult, type ResponseCompletedPayload, type ResponseFailedPayload, type ResponsePartDeltaPayload, type ResponseStartedPayload, type ResumeSummary, type ResumeTurn, type RowResult, type RowStatus, SDK_VERSION, type SaveMetaResult, type SendMessageOpts, type SettingItem, type SettingWrite, type StreamCancelPayload, type StreamCommand, type StreamCommandEnvelope, type StreamCommandType, type StreamEventEnvelope, type StreamEventType, type TaskProgressPayload, type TenantMetaEntry, type TimelineItemLite, type TokenRecord, TokenStore, type ToolCallFailedPayload, type ToolCallResultPayload, type ToolCallStartedPayload, type V4RenderSink, type V4StreamEventType, type WorkspaceFileContent, type WorkspaceFileItem, type WorkspaceFileListResult, WsClient, type WsClientOpts, absoluteDownloadUrl, archiveDir, bootstrapTenant, buildAnswer, buildConfirm, buildInterrupt, buildMiniAppTemplateFiles, buildMiniPreviewTargets, buildMiniVerifyAgentReport, buildReject, buildResumeSummary, buildSteer, camelizeKeys, changePassword, classifyMessage, clearMetaCache, clearModelCache, conversationStateFile, create, createConversation, createHttpClient, createV4Reducer, createWorkspaceFile, credentialsFile, defaultDownloadDir, defaultMiniRequiredScopes, deleteEnv, deleteIdentity, deleteTenantMeta, deleteWorkspaceFile, deriveNamelessToolLabel, describePrincipal, detectDelegationPause, detectDirectInteractionPending, detectPasswordChangeChallenge, displayWidth, downloadDocument, ensureSessionFresh, envDir, envFile, envsDir, exitCodeFor, extractNextSteps, fetchConversationTimeline, fetchConversationTimelineStrict, fetchRecentConversations, fetchSkillCatalog, fetchSkillMarkdown, filterByStage, findLastAssistantSeq, flattenSkills, formatMiniVerifyReport, formatObject, formatRows, fromAxiosError, getCacheStats, getMiniStatus, getSettingDomain, getTenantMeta, globalConfigFile, guessMimeType, hcmConfigDir, identitiesDir, identityDir, identityMetaFile, inferEnvName, inferMiniWritableTemplateOptionsFromModel, initMiniAppProject, isDelegationToolName, isServerSlidingSession, listEnvs, listIdentities, listProfiles, listTenantMeta, listWorkspaceFiles, loadConversationState, loadEnv, loadGlobalConfig, loadIdentity, loadProfile, loadWorkspaceFileContent, loginClientCredentials, loginPairing, loginPassword, loginPat, matchSkills, migrateLegacyProfiles, needsRefresh, oneShot, parseConfirmToolName, parseFixture, parseInteractionRequest, parseInteractionResolved, parsePlaceholder, parseSettingAssignment, patchSettingDomain, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readMiniContext, readPullManifest, refreshToken, remove, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveRefs, runImport, runMiniSmokeChecks, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, sendMessageAndStream, snakeToCamel, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, update, uploadDocument, validateMiniProject };