@harrylabsj/kiwi 0.6.0

package/dist/agent/kernel.d.ts

@@ -0,0 +1,258 @@
+/**
+ * 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.
+ */
+/**
+ * AgentKernel (design §4.1): lifecycle and concurrency owner of one Kiwi
+ * agent instance.
+ *
+ * v0.3.0-A responsibilities:
+ * - open/recover the persistent main conversation (Pi AgentHarness Session);
+ * - serialize every user message, slash command and (later) event through
+ *   one queue — only the kernel submits state changes;
+ * - retrieve relevant memories per turn (logged, redaction-leveled) and
+ *   inject them into the system prompt as an untamperable briefing;
+ * - expose memory write tools to the model (governance lives in
+ *   MemoryStore) and deterministic slash commands to the operator.
+ */
+import { type ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model, Models } from "@earendil-works/pi-ai";
+import type { AgentProfile } from "../config/profile.js";
+import type { CommerceClient } from "../commerce/types.js";
+import { type AgentPaths } from "./agent-db.js";
+import { type TickBudget, type TickResult } from "./buyer/scheduler.js";
+import { BuyerTaskStore } from "./buyer/task-store.js";
+import type { CommerceConnector } from "./connector/types.js";
+import { type AgentMode } from "./mode.js";
+import { WriteApprovalCandidateStore, type ApprovalExecutionResult } from "./merchant/action-candidate.js";
+import type { CredentialBroker } from "./merchant/credential-broker.js";
+import type { MerchantClient } from "./merchant/types.js";
+import { MemoryStore } from "./memory/store.js";
+import { type Principal } from "./memory/types.js";
+import { PrivateVault } from "./memory/vault.js";
+/** Execution hooks for a pending WriteApprovalCandidate (process-lifetime only). */
+export interface PendingActionHooks {
+    readPreconditions: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export declare const MAIN_SESSION_ID = "main";
+export interface AgentKernelOptions {
+    profile: AgentProfile;
+    /** Injectable paths (tests); defaults to .kiwi/agents/<agent_id>. */
+    paths?: AgentPaths;
+    models: Models;
+    model: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    vault?: PrivateVault;
+    /** Buyer tasks read facts through this connector (v0.3.0-B). */
+    connector?: CommerceConnector;
+    /**
+     * Negotiation CommerceClient (v0.3.0-C): claim/snapshot/submit for linked
+     * consultations. Optional — negotiation tools fail closed when absent.
+     */
+    commerceClient?: CommerceClient;
+    /** Merchant catalog/inventory client (merchant kernels). */
+    merchantClient?: MerchantClient;
+    /** Credential Broker: negotiation/catalog/inventory scopes (§15.4). */
+    broker?: CredentialBroker;
+    /** Runtime write-approval mode (§16); defaults to supervised. */
+    mode?: AgentMode;
+    now?: () => string;
+    /** agent catalog base URL（buyer `negotiate_buyer_task` 的 A2A 商家发现用）。 */
+    catalog?: string;
+}
+/** A2A 磋商结果记忆记录（/negotiate 与 negotiate_buyer_task 共用形状）。 */
+interface NegotiationRecord {
+    negotiationId: string;
+    catalogAgentId: string;
+    sku: string;
+    quantity: number;
+    offerPriceMinor?: number;
+    dealPriceMinor?: number;
+    agreementId?: string;
+}
+export interface KernelReply {
+    /** Public assistant answer or deterministic command output. */
+    text: string;
+    /** True when the command was /quit. */
+    quit: boolean;
+}
+export declare class AgentKernel {
+    readonly profile: AgentProfile;
+    readonly principal: Principal;
+    private readonly paths;
+    private readonly db;
+    private readonly store;
+    private readonly session;
+    private readonly harness;
+    private briefing;
+    /** 统一时钟（构造注入或墙钟；与 open() 的 clock 闭包同源语义）。 */
+    private readonly clock;
+    private chain;
+    private shutdownRequested;
+    private closed;
+    private readonly taskStore?;
+    private readonly scheduler?;
+    private readonly approvals?;
+    /** v0.7.0 KTH：handoff 存储（open() 构造，buyer 角色注入）。 */
+    private readonly handoffRuntime?;
+    private readonly commerceClient?;
+    private readonly merchantClient?;
+    private readonly broker?;
+    /** Shared mutable mode ref (tools read it via a getter before the kernel exists). */
+    private readonly modeRef;
+    /** Live execution hooks for pending candidates (v0.3.0-C /approve). */
+    private readonly pendingHooks;
+    /** Current conversation-turn id, shared with the remember tool (evidence dedup §9.3). */
+    private readonly turnId;
+    private turnSeq;
+    /** Negotiation conversations that reached consensus — the auto-follow must never re-open them. */
+    private readonly settledNegotiations;
+    private constructor();
+    static open(options: AgentKernelOptions): Promise<AgentKernel>;
+    private briefingSetter;
+    /**
+     * v0.7.0 KTH：handoff 运行态摘要（/handoff 命令用）——候选生命周期 +
+     * 交付观察状态，从 Ledger 事件投影（#17 用户可见目标与摘要、#18 可审计）。
+     */
+    get handoffSummary(): {
+        enabled: false;
+    } | {
+        enabled: true;
+        candidates: Array<{
+            candidate_id: string;
+            negotiation_id: string;
+            lifecycle: string;
+            destination_type: string;
+            destination_ref: string;
+            display_summary: {
+                merchant: string;
+                summary: string;
+            };
+        }>;
+        handoffs: Array<{
+            handoff_id: string;
+            delivery: string;
+        }>;
+    };
+    /** 模拟 OS/browser/deep-link handler 启动（LAUNCHED；不证明页面加载）。 */
+    launchHandoff(handoffId: string, negotiationId: string): Promise<string>;
+    /** 本地回调证据：handoff-open 演示（OPENED_CONFIRMED 证据门，KTH §9）。 */
+    confirmHandoffOpened(handoffId: string, negotiationId: string): Promise<string>;
+    get memoryStore(): MemoryStore;
+    /** Buyer task store (undefined for merchant kernels). */
+    get buyerTasks(): BuyerTaskStore | undefined;
+    /** WriteApprovalCandidate approval store (both roles; undefined only if unopened). */
+    get actionCandidates(): WriteApprovalCandidateStore | undefined;
+    /** Current runtime write-approval mode (design §16). */
+    getMode(): AgentMode;
+    /**
+     * Change the runtime mode. Switching INTO autopilot requires an explicit
+     * `confirm` — the same fail-closed rule as the operator control plane
+     * (docs/operator-tui-v0.2.md §8).
+     */
+    setMode(mode: AgentMode, options?: {
+        confirmed?: boolean;
+    }): {
+        ok: boolean;
+        error?: string;
+    };
+    /** Pending WriteApprovalCandidates awaiting /approve (fail closed on expiry). */
+    listPendingApprovals(): ReturnType<WriteApprovalCandidateStore["listPending"]>;
+    /** 释放候选执行钩子闭包（评审项 P3-5；候选生命周期终结后调用）。 */
+    private releasePending;
+    /**
+     * Approve + execute a pending WriteApprovalCandidate. Execution re-reads the
+     * preconditions and re-hashes them (§16): a stale or expired approval is
+     * superseded, never executed. A candidate left over from a previous process
+     * (no live execution hooks) is expired, matching operator-plane recovery.
+     */
+    approveCandidate(candidateId: string): Promise<ApprovalExecutionResult>;
+    /** Approval execution without re-enqueueing (callers must already be serialized). */
+    private approveCandidateInner;
+    /** Reject a pending/advice-only WriteApprovalCandidate. Never executes. */
+    rejectCandidate(candidateId: string): {
+        ok: boolean;
+        error?: string;
+    };
+    /**
+     * Run one scheduler tick (buyer kernels only): due wakeups, tracking-rule
+     * checks and notifications, all derived from the database (restart-safe).
+     * Serialized with everything else the kernel does.
+     */
+    schedulerTick(budget?: TickBudget): Promise<TickResult>;
+    /** 惰性过期清扫入口（/handoff 渲染前调用；幂等，可重复调）。 */
+    sweepHandoffCandidates(): number;
+    /**
+     * Autonomous negotiation follow-up (autopilot only): if this agent has a
+     * pending negotiation message, drive ONE deterministic turn to handle it.
+     * The deterministic decision negotiates within the profile's HardPolicy
+     * (buyer budget / merchant floor+discount) and auto-submits through the
+     * gateway gate — no per-turn human and no LLM tool-loop fragility. Escalated
+     * (out-of-rule) decisions park for a human. Returns a progress line for the
+     * chat, or undefined when there is nothing to do.
+     */
+    negotiationAutoTick(): Promise<string | undefined>;
+    private negotiationAutoTickUnlocked;
+    get isShutdownRequested(): boolean;
+    /** Serialize all kernel work — one message, command or event at a time. */
+    private enqueue;
+    /**
+     * Handle one user input line: slash commands run deterministically;
+     * anything else goes to the model with a per-turn memory briefing.
+     */
+    /**
+     * 把一段上下文注入会话（不触发模型回复）：`/negotiate` 等确定性动作的结果
+     * 写入 session（user 角色、带「系统记录」标记），下一轮用户提问时模型能看到
+     * （消除"两个脑"）。
+     */
+    injectContext(text: string): Promise<void>;
+    /**
+     * 把一轮 A2A 磋商结果写入记忆（episode namespace，active 无需人工确认）：
+     * 持久上下文，`/why` 可查、跨重启可恢复。
+     */
+    recordNegotiation(input: NegotiationRecord): Promise<string>;
+    handleUserText(text: string): Promise<KernelReply>;
+    private handleSlash;
+    private renderMemory;
+    private findMemoryForForget;
+    private handleForget;
+    private handleCorrect;
+    /** Owner-only reveal of Restricted (Vault) values — never echoed to a buyer. */
+    private renderPrivate;
+    /** Human-only promotion of a candidate (design §10.1): constraints and
+     * restricted values require /confirm before they take effect. */
+    private handleConfirm;
+    private renderWhy;
+    private handleMode;
+    private renderPending;
+    private handleApprove;
+    private handleReject;
+    /**
+     * `/register`：把本 merchant 注册进 agent catalog（buyer 据此发现）。
+     * 用法：/register --agent-card-url <url> [--catalog <url>] [--domain <d>]
+     * agent-card-url 可来自 `kiwi agent serve` 的 A2A server（缺省 env KIWI_AGENT_CARD_URL）。
+     * catalog 缺省 env KIWI_CATALOG_URL 或 http://127.0.0.1:8600。
+     */
+    private handleRegister;
+    /**
+     * Resolve a user-facing approval target: a /pending index, an exact id, or a
+     * UNIQUE prefix of a pending candidate (LLM flows truncate long UUIDs).
+     * Ambiguous prefixes and out-of-range indices stay rejected.
+     */
+    private resolveApprovalId;
+    /** Flush the session and close the database. Idempotent. */
+    close(): Promise<void>;
+}
+export {};