@harrylabsj/kiwi 0.6.0

package/dist/operator/controller.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AgentProfile } from "../config/profile.js";
+import type { NegotiationDecision } from "../negotiation/types.js";
+import type { NegotiationRunner } from "./runner.js";
+import type { StrategyEngine } from "./strategy.js";
+import type { OperatorEventStore } from "./store.js";
+import { type Candidate, type CandidateRoute, type OperatorEvent, type OperatorMode, type OperatorState, type StrategyPatch } from "./types.js";
+export declare const DEFAULT_OPERATOR_MODE: OperatorMode;
+/** Route a candidate by mode; autopilot escalates to approval on risk. */
+export declare function routeCandidate(decision: NegotiationDecision, mode: OperatorMode, profile: AgentProfile): CandidateRoute;
+export declare function initialOperatorState(): OperatorState;
+/**
+ * Fold one event into the state (mutates and returns `state`, fold-style).
+ * Pure with respect to its inputs: same events -> same state.
+ */
+export declare function reduceOperatorEvent(state: OperatorState, event: OperatorEvent): OperatorState;
+export type OperatorMessageResult = {
+    kind: "applied";
+    patch: StrategyPatch;
+} | {
+    kind: "needs_confirmation";
+    patch: StrategyPatch;
+} | {
+    kind: "rejected";
+    patch?: StrategyPatch;
+    reason: string;
+};
+export type ModeChangeResult = {
+    kind: "changed";
+    mode: OperatorMode;
+} | {
+    kind: "needs_confirmation";
+    mode: OperatorMode;
+    reason: string;
+} | {
+    kind: "unchanged";
+    mode: OperatorMode;
+} | {
+    kind: "error";
+    error: string;
+};
+export type SimpleResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export type ApprovalResult = {
+    kind: "submitted";
+    candidate_id: string;
+    policy_result: string;
+    settlement: "completed" | "failed";
+    message_id?: number;
+} | {
+    kind: "replayed";
+    candidate_id: string;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+export type PrepareResult = {
+    kind: "no_work";
+} | {
+    kind: "blocked";
+    reason: string;
+} | {
+    kind: "awaiting_approval";
+    candidate: Candidate;
+} | {
+    kind: "advice_ready";
+    candidate: Candidate;
+} | {
+    kind: "auto_submitted";
+    candidate_id: string;
+    policy_result: string;
+    message_id?: number;
+};
+export interface WhyReport {
+    candidate_id?: string;
+    route?: CandidateRoute;
+    analysis: string[];
+    reason_codes: string[];
+    active_directives: string[];
+    note?: string;
+}
+export interface ShutdownResult {
+    abandoned_candidate?: string;
+    events: number;
+}
+export interface OperatorControllerOptions {
+    profile: AgentProfile;
+    store: OperatorEventStore;
+    engine: StrategyEngine;
+    runner: NegotiationRunner;
+    /** Clock injection for deterministic tests. */
+    now?: () => string;
+    /** Operator identity source recorded on events (default "local_tui"). */
+    origin?: string;
+}
+export declare class OperatorController {
+    readonly profile: AgentProfile;
+    private readonly store;
+    private readonly engine;
+    private readonly runner;
+    private readonly now;
+    private readonly origin;
+    private readonly state;
+    private readonly eventsLog;
+    /** Live prepared turns for candidates generated by this process. */
+    private readonly prepared;
+    /** Messages rejected this session; not re-claimed until a later run. */
+    private readonly rejectedMessageIds;
+    /** Candidate ids whose submit is currently in flight (approve idempotency). */
+    private readonly submitting;
+    /** Last counterpart public message seen by prepare (TUI transcript pane). */
+    lastCounterpartMessage?: string;
+    private eventSeq;
+    private candidateSeq;
+    constructor(options: OperatorControllerOptions);
+    getState(): OperatorState;
+    /** Load and fold the persisted event stream (fail closed on corruption). */
+    start(): Promise<void>;
+    private nextBase;
+    private record;
+    /**
+     * Compile context: profile HardPolicy values overridden by the LAST applied
+     * budget/floor directive, so compiling again sees the session-effective
+     * values (e.g. after a confirmed raise, "提高到 500" is no longer a raise).
+     */
+    private strategyContext;
+    sendOperatorMessage(text: string): Promise<OperatorMessageResult>;
+    /** Apply the parked relax patch after the operator's explicit confirmation. */
+    confirmStrategy(): Promise<SimpleResult>;
+    setMode(mode: OperatorMode, options?: {
+        confirmed?: boolean;
+    }): Promise<ModeChangeResult>;
+    /**
+     * Pull the next pending message and generate a candidate. No Commerce
+     * write happens unless the gate routes to auto_submit (autopilot).
+     */
+    prepareNextCandidate(): Promise<PrepareResult>;
+    private submitCandidate;
+    /** Approve the current awaiting candidate (idempotent per candidate_id). */
+    approve(candidateId?: string): Promise<ApprovalResult>;
+    private currentCandidateId;
+    /** Reject the current candidate and abandon its claim. Never submits. */
+    reject(candidateId?: string, reason?: string): Promise<SimpleResult>;
+    /**
+     * Record a turn instruction, abandon the old candidate's claim and
+     * regenerate. The instruction is compiled as a turn-scope directive and
+     * expires when the next candidate settles (design §7.3).
+     */
+    revise(instruction: string, candidateId?: string): Promise<PrepareResult>;
+    pause(): Promise<SimpleResult>;
+    resume(): Promise<SimpleResult>;
+    why(): WhyReport;
+    /** Recent events, newest last. Private to this operator session. */
+    history(limit?: number): OperatorEvent[];
+    usage(): OperatorState["stats"] & {
+        events: number;
+    };
+    /**
+     * Safe shutdown (design §17): a candidate still waiting for approval is
+     * best-effort abandoned (never completed) and kept as an audit record.
+     */
+    shutdown(): Promise<ShutdownResult>;
+}