JX-BPOS/api-report/apps/api/src/modules/loop-engine/port.d.ts

/**
 * module: loop-engine —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
 */
import type { LoopModel, StaffId, TaskId } from '@contracts';
import type { CaseModel } from './internal/domain/cmmn-parse.ts';
import type { CaseRuntime, EnabledSet } from './internal/domain/lifecycle.ts';
import type { AgentAction } from './contract.ts';
export type Clock = {
    now(): Date;
};
/** 运行时实例状态 —— loop 的模型定位与就绪集(OS 09 三份持久状态之一) */
export type LoopStateStore = {
    save(taskId: TaskId, model: LoopModel, parsed: CaseModel, runtime: CaseRuntime, pending?: PendingAcceptance | null): Promise<void>;
    load(taskId: TaskId): Promise<{
        model: LoopModel;
        parsed: CaseModel;
        runtime: CaseRuntime;
        pending?: PendingAcceptance;
    } | undefined>;
};
/** S-FEEL —— app 注入 `@sfeel`;引擎零 LLM */
export type Sfeel = {
    condition(expression: string, scope: Readonly<Record<string, unknown>>): boolean;
    expression(expression: string, scope: Readonly<Record<string, unknown>>): unknown;
    unaryTest(cell: string, value: unknown, scope: Readonly<Record<string, unknown>>): boolean;
};
/** 任务数据 —— app 注入 `ledger`(L1):引擎对**任务视图**求值,不依赖事件 */
export type TaskDataGateway = {
    view(taskId: TaskId): Promise<Record<string, unknown>>;
    draftWrite(input: {
        taskId: TaskId;
        domain: string;
        object: string;
        key: Record<string, string | number>;
        patch: Record<string, unknown>;
    }): Promise<void>;
};
/**
 * Agent 回路 —— app 注入(Mastra Agent 在 adapter,§6.1)。
 * **回合由 usecase 驱动,不放开自由 maxSteps,预算在环外由 Harness 强制。**
 */
export type AgentPort = {
    decide(input: {
        taskId: TaskId;
        /** 叙事面:说明书 + 活动记忆选摘 + 任务记忆窗口 */
        narrative: string;
        enabled: EnabledSet;
        scope: Record<string, unknown>;
    }): Promise<AgentAction>;
};
/** 工具 / 人类工具 / 监听 —— 三型行动的落点 */
export type ToolGateway = {
    invoke(input: {
        tool: string;
        input: Record<string, unknown>;
        activityId: string;
        taskId: TaskId;
    }): Promise<{
        ok: boolean;
        output?: Record<string, unknown>;
        error?: {
            message: string;
        };
    }>;
    isWriteEffect(tool: string): Promise<boolean>;
    registerIntent(input: {
        taskId: TaskId;
        tool: string;
        input: Record<string, unknown>;
        label: string;
    }): Promise<void>;
};
/**
 * 在途验收(提交放行的持久痕):卡发出即记,裁决到达再记 verdict ——
 * 判齐重入不再发第二张卡;恢复的那一拍据 verdict 定终局(released 与否)。
 */
export type PendingAcceptance = {
    readonly acceptanceCardId: string;
    readonly verdict?: 'pass' | 'reject';
    readonly selectedPorts?: Record<string, string>;
};
export type CardGateway = {
    issue(input: {
        taskId: TaskId;
        ownerId: StaffId;
        humanCallCap: number;
        workOrder: 'execution' | 'acceptance';
        card: Record<string, unknown>;
    }): Promise<{
        id: string;
    }>;
};
export type ListenerRegistrar = {
    register(input: {
        taskId: TaskId;
        eventType: 'data' | 'time' | 'human';
        keyFilter: Record<string, string>;
        deadline: string;
    }): Promise<{
        id: string;
    }>;
};
/**
 * 视图流控 —— app 注入 `interaction`(L3)。
 * 「loop:AI 按定位与局面临场组织视图流」(AM 07)。MVP 每回合推一次**案例全景**:
 * 阶段与计划项的生命周期态、当下可为、目标缺口 —— 这些是语义引擎算出来的确定事实,
 * 零 LLM 即可成屏;模型只决定「下一步做什么」,不负责画面。
 */
export type ViewGateway = {
    push(input: {
        taskId: TaskId;
        activityId: string;
        template: string;
        scope: Record<string, unknown>;
    }): Promise<void>;
};
/**
 * 技能 —— app 注入 `skill-engine`(L4)。
 * 「渐进披露:常驻上下文**仅有技能目录**,按事加载正文、按需下钻引用」(AM 08)。
 */
export type SkillGateway = {
    /** 目录:id + 何时适用 —— 只给这些,正文等 AI 说要才加载 */
    index(activityId: string): Promise<ReadonlyArray<{
        id: string;
        label: string;
        applicability: string;
    }>>;
    /** 装配入信封:这一回合装配了哪些技能及其版本,记入任务记忆 */
    stamp(activityId: string, skillIds: readonly string[]): Promise<ReadonlyArray<{
        id: string;
        version: string;
    }>>;
};
export type MemoryRecorder = {
    append(input: {
        taskId: TaskId;
        kind: 'engine-transition' | 'evaluation' | 'thought' | 'action' | 'result' | 'observation';
        title: string;
        detail?: Record<string, unknown>;
    }): Promise<void>;
    /** 装载:按定位选摘活动记忆入 Agent 上下文(渐进披露) */
    loadActivityMemory(activityId: string, limit: number): Promise<Array<{
        layer: string;
        statement: string;
    }>>;
    /** 本任务自己的最近轨迹(窗口大小由活动声明的 memoryWindow 定)—— 喂回叙事面,Agent 每拍不失忆 */
    window(taskId: TaskId): Promise<Array<{
        kind: string;
        title: string;
    }>>;
};
export type TaskContext = {
    of(taskId: TaskId): Promise<{
        activityId: string;
        ownerId: StaffId;
        humanCallCap: number;
    }>;
};