JX-BPOS/api-report/apps/api/src/modules/toolbox/contract.d.ts

/**
 * module: toolbox —— 对外类型(编码规范 §10.1)。
 *
 * 两条缝之二(§7.3):`ToolInvoker` 支持 record | replay | live ——
 * **任何工具执行不经 ToolInvoker,回放审就对它失明**(§12.5#10)。
 */
import type { ActionIntent, TaskId } from '@contracts';
import type { AuditFinding } from './internal/domain/registration-audit.ts';
import type { CallDisposition, EffectLevel, EvolutionViolation, Preauthorization, ToolContract } from './internal/domain/tool-contract.ts';
export type { ActionIntent, AuditFinding, CallDisposition, EffectLevel, EvolutionViolation, Preauthorization, ToolContract };
export declare const INVOKER_MODES: readonly ["live", "record", "replay"];
export type InvokerMode = (typeof INVOKER_MODES)[number];
export declare class ToolNotFoundError extends Error {
    readonly tool: string;
    constructor(tool: string);
}
export declare class ToolNotAllowedError extends Error {
    readonly tool: string;
    readonly activityId: string;
    constructor(tool: string, activityId: string);
}
export declare class ToolDisabledError extends Error {
    readonly tool: string;
    constructor(tool: string);
}
export declare class ToolReplayMissError extends Error {
    readonly key: string;
    constructor(key: string);
}
export declare class RegistrationRejectedError extends Error {
    readonly findings: readonly AuditFinding[];
    constructor(findings: readonly AuditFinding[]);
}
export type ToolCall = {
    readonly tool: string;
    readonly operation?: string;
    readonly input: Record<string, unknown>;
    readonly activityId: string;
    readonly taskId?: TaskId;
    readonly stepNo?: number;
};
export type ToolResult = {
    readonly ok: boolean;
    readonly output?: Record<string, unknown>;
    readonly error?: {
        readonly code: string;
        readonly retryable: boolean;
        readonly message: string;
    };
    readonly latencyMs: number;
    readonly mode: InvokerMode;
};
/** 调用留痕:入参快照、出参、时延与错误自动留痕入任务记忆(OS 7.3) */
export type InvocationTrace = {
    readonly tool: string;
    readonly input: Record<string, unknown>;
    readonly result: ToolResult;
    readonly at: string;
};
/**
 * 工具调用器 —— 活动基座六件里的「工具(调用契约)」。
 * **读类**过程中自由调用;**写类**登记为动作意向,放行后落地(除契约显式预授权者)。
 */
export type ToolInvoker = {
    readonly mode: InvokerMode;
    /** 判定运行时待遇 —— 调用方据此决定是即调还是登记意向 */
    disposition(call: ToolCall, preauthorized: readonly Preauthorization[]): Promise<CallDisposition>;
    invoke(call: ToolCall): Promise<ToolResult>;
    /** 落地预检第四项:工具契约含 validate 能力时调之(ADR-005) */
    validate(call: ToolCall): Promise<ToolResult | undefined>;
    withMode(mode: InvokerMode): ToolInvoker;
};
export type RegisterToolInput = {
    readonly contract: ToolContract;
    /** 契约测试集:样例入参 → 期望出参形状;试运行审的依据 */
    readonly samples: ReadonlyArray<{
        input: Record<string, unknown>;
        expectShape: Record<string, unknown>;
    }>;
    /** 连接配置的值 —— 只存治理台,加密落库(ADR-009) */
    readonly connectionValues?: Readonly<Record<string, string>>;
};
export type RegistrationVerdict = {
    readonly accepted: boolean;
    readonly staticFindings: readonly AuditFinding[];
    readonly evolution: readonly EvolutionViolation[];
    readonly trialRun: {
        readonly ran: number;
        readonly passed: number;
        readonly failures: readonly string[];
    };
};
export type ToolboxService = {
    /** 注册两审:静态审读清单,试运行审验代码 */
    register(input: RegisterToolInput): Promise<RegistrationVerdict>;
    list(): Promise<ToolContract[]>;
    get(name: string): Promise<ToolContract | undefined>;
    /** 有活动声明引用的工具不得删除;可停用 —— 停用后调用返回结构化错误 */
    setEnabled(name: string, enabled: boolean): Promise<void>;
    bindConnection(name: string, values: Readonly<Record<string, string>>): Promise<void>;
    /** 白名单:活动只经调用契约用工具,授权在白名单与契约,不在活动代码 */
    setAllowlist(activityId: string, tools: readonly string[]): Promise<void>;
    allowlistOf(activityId: string): Promise<string[]>;
    /** 安装静态审:活动声明的工具契约齐备?装不齐不上架 */
    assertContractsAvailable(names: readonly string[]): Promise<{
        ok: boolean;
        missing: string[];
    }>;
};