@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.26

package/dist/tools/approvals.service.d.ts

@@ -6,7 +6,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { LockService } from "../infra/lock/lock.service.js";
-import { DevicePolicyService } from "../local-devices/device-policy.service.js";
+import { DevicePolicyService, type PolicyOpResult } from "../local-devices/device-policy.service.js";
 import { type OrgRole } from "../orgs/roles.js";
 import { RunResume } from "../runtime/run-jobs.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
@@ -47,7 +47,6 @@ export interface NetworkAskDetail {
     };
     /** The hosts the decision allowed (every approved decision writes them; none: nothing). */
     grantedHosts?: string[];
-    /** What took effect: a run grant, the device's policy, or a run grant because the device did not apply it. */
     /**
      * What took effect: a run grant (`once`), the device's policy (`always`), a run grant because
      * the device could not be reached or lacks the feature (`once_fallback`), or nothing because the
@@ -56,6 +55,22 @@ export interface NetworkAskDetail {
     outcome?: "once" | "always" | "once_fallback" | "refused";
     /** Why 「一直允许」 did not reach the device's policy. */
     fallback?: "offline" | "refused" | "unsupported";
+    /**
+     * Set while the ask is still pending: the last 「一直允许」 whose device change was recorded only
+     * after a crash (transactional outbox spec §7.4) and did not take effect: `failed` (the device
+     * refused it, never received it or stopped while applying it) or `unknown` (the device did not
+     * answer; its next connection tells), with the reason. The owner may decide again.
+     */
+    attempt?: NetworkAskAttempt;
+}
+/** Why a pending network ask's last 「一直允许」 did not decide it ({@link NetworkAskDetail.attempt}). */
+export interface NetworkAskAttempt {
+    /**
+     * `applied_undecided`: the device applied the change, but the account that chose it can no
+     * longer decide this ask (someone else must).
+     */
+    outcome: "failed" | "unknown" | "applied_undecided";
+    message: string;
 }
 /** A network ask's detail as the API shows it: without the kept command result. */
 export type NetworkAskView = Omit<NetworkAskDetail, "result">;
@@ -189,7 +204,7 @@ export interface NetworkAskInput {
     callId: string;
     /** The device owner: the only person who may decide. */
     requestedFor: string;
-    detail: Omit<NetworkAskDetail, "grantedHosts" | "outcome" | "fallback">;
+    detail: Omit<NetworkAskDetail, "grantedHosts" | "outcome" | "fallback" | "attempt">;
     /** `["once", "always"]`, or `["once"]` when the device takes no remote grants. */
     scopes: ("once" | "always")[];
 }
@@ -223,7 +238,10 @@ export declare class ApprovalsService {
     private readonly schedules;
     /** A trial approval is kept only for a tool the task may hold as a grant (its agent's tools). */
     private readonly registry;
-    /** 「这台设备一直允许」 sends the `policy` op to the device before the decision is recorded. */
+    /**
+     * 「这台设备一直允许」 records the device change's intent, sends the `policy` op, then records
+     * its outcome with the decision.
+     */
     private readonly policies;
     /** One decision of a network ask at a time, across replicas (the op is sent before the transaction). */
     readonly lockService: LockService;
@@ -234,8 +252,11 @@ export declare class ApprovalsService {
     constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, eventLog: Pick<EventLog, "appendIn" | "notify">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost, schedules: Pick<ScheduledTaskStore, "addGrant">, 
     /** A trial approval is kept only for a tool the task may hold as a grant (its agent's tools). */
     registry: Pick<ToolRegistry, "forAgent">, 
-    /** 「这台设备一直允许」 sends the `policy` op to the device before the decision is recorded. */
-    policies: Pick<DevicePolicyService, "apply" | "summary">, 
+    /**
+     * 「这台设备一直允许」 records the device change's intent, sends the `policy` op, then records
+     * its outcome with the decision.
+     */
+    policies: Pick<DevicePolicyService, "begin" | "send" | "settleIn" | "summary">, 
     /** One decision of a network ask at a time, across replicas (the op is sent before the transaction). */
     lockService: LockService, 
     /** A trial run's 「这次允许」 becomes a task grant only within the org's egress. */
@@ -272,28 +293,84 @@ export declare class ApprovalsService {
      * A network ask's decision (network ask-to-allow spec §5.2), one at a time per ask across
      * replicas: only the device owner (`requested_for`) decides, in a signed-in session (a personal
      * access token is refused; the route already refuses service and embed tokens); the allowed
-     * hosts are a subset of those asked. 「这台设备一直允许」 sends the `policy` op first, outside any
-     * transaction; when the device cannot be reached or lacks the feature the decision is recorded
-     * as a run grant with the reason, and when the device refuses (its owner takes no remote grants)
-     * as `always` with outcome `refused` and nothing granted. Then {@link decideIn} records what took
-     * effect and the run resumes after the commit; a change the device applied after the ask closed
-     * is audited (`late`) and answered with a 409 that says so.
+     * hosts are a subset of those asked. 「这台设备一直允许」 goes through the device change's intent
+     * ({@link decideAlways}): when the device cannot be reached or lacks the feature the decision is
+     * recorded as a run grant with the reason, and when the device refuses (its owner takes no
+     * remote grants) as `always` with outcome `refused` and nothing granted; the decision and the
+     * op's outcome are one transaction. Every decision resumes the run in its transaction and is
+     * announced after the commit; a change the device applied after the ask closed is audited
+     * (`late`) and answered with a 409 that says so.
      */
     private decideNetwork;
-    /** `device.network_allowed` of a policy change that reached the device after the ask closed. */
-    private auditLateAllow;
-    /** The owner of a live device of the org (null: none, deleted, or of another org). */
-    private deviceOwnerOf;
     /**
-     * Adds the hosts to the device's local policy (the `policy` op; never inside a transaction).
-     * Null when it was applied, else why not: the decision falls back to a run grant.
+     * 「这台设备一直允许」 (transactional outbox spec §7): the intent of the device change (naming the
+     * ask) is recorded, the `policy` op sent (no transaction open), then {@link settleNetworkOp}
+     * decides the ask and records the op's outcome in one transaction. When nothing could be sent
+     * (the device is offline, deleted, or its program lacks the feature) the decision is a run
+     * grant with the reason. The device's answer decides: applied → `always`; refused → `always`
+     * with outcome `refused`, nothing granted; no answer → a run grant (`once_fallback`, `offline`)
+     * while the op stays `unknown` for the machine's next hello or the resolver. A device that
+     * reconnects during the call and reports the op applied lets the resolver approve the ask as
+     * this owner first: that decision is returned (`toSeq` null: already announced), never a 409;
+     * when it granted other hosts than this call's (another of the owner's changes) and this call's
+     * change was not confirmed, `approval.already_decided` says so. A device deleted during the
+     * call is `device.not_found` (the op recorded unknown).
+     */
+    private decideAlways;
+    /** Records only the op's outcome, in its own transaction (the ask is left as it is). */
+    private settleOpOnly;
+    /**
+     * The resolve transaction of a network ask's device change: the ask decided as `network` says
+     * ({@link decideTx}: lock order conversation → approval → run), then the op's outcome recorded
+     * (`DevicePolicyService.settleIn`: the machine's row). When the ask closed meanwhile (a reply,
+     * the expiry, a stop) only the op's outcome is recorded, and a change the device applied is
+     * audited `device.network_allowed` with `late: true` in the same transaction.
      */
-    private applyAlways;
+    private settleNetworkOp;
+    /**
+     * The op's outcome for an ask that is no longer pending (in the caller's transaction): recorded,
+     * and a change the device applied audited `device.network_allowed` `late` (the change stands:
+     * the owner chose it; no inverse change is sent). True when it was audited late. `undecided`:
+     * the ask is still pending but the op's account can no longer decide it; the allow is audited
+     * without `late` (it is not after the ask) and the caller gives the ask the reason.
+     */
+    private settleClosedIn;
+    /** The live intent `opId` on machine `machineId` (null: settled already, or expired). */
+    private pendingOpOf;
+    /**
+     * The `device-op-resolve` job's outcome of an op that answers network ask `op.source.approvalId`
+     * (transactional outbox spec §7.4), in the resolver's transaction: under the ask's locks
+     * (conversation, then the approval) the op is read again (settled meanwhile: nothing to do).
+     * Applied, and the ask still pending → approved `always` by the op's account (`via` as it
+     * asked), the run resumed in this transaction as every decision does; the ask closed → audited
+     * `late`; still pending but the op's account can no longer decide it → the allow audited (not
+     * late) and the ask left pending with `applied_undecided`. Not applied (refused, never received,
+     * interrupted) or still unknown → the op's outcome recorded and the ask left pending with the
+     * reason (`detail.attempt`) and an `approval_updated` event so the card shows it: no person is
+     * there to fall back to a run grant (D2).
+     */
+    settleFromResolver(ref: {
+        machineId: string;
+        opId: string;
+        approvalId: string;
+    }, result: PolicyOpResult): Promise<void>;
+    /**
+     * A pending network ask's reason (`detail.attempt`) and its `approval_updated` event (one per
+     * op and outcome), in the caller's transaction with the ask locked; notified after the commit.
+     */
+    private attemptIn;
+    /** The owner of a live device of the org (null: none, deleted, or of another org). */
+    private deviceOwnerOf;
     /** After the commit: the decision's events reach the page, the run's waits and IM delivery. */
     private announceDecided;
     /** An account's display name (null when unknown). */
     private displayNameOf;
     private decideIn;
+    /**
+     * A decision in the caller's transaction: lock order conversation → approval → run (the resume).
+     * Refuses (`approval.already_decided`, `approval.not_found`, …) before any write.
+     */
+    private decideTx;
     /**
      * A trial run of a scheduled task (scheduled tasks spec §7): an approval its creator granted, in
      * any scope, is also added to the task's grants with the approved definition's hash, so its
@@ -338,11 +415,22 @@ export declare class ApprovalsService {
      */
     cancelPendingIn(runId: string): Promise<ApprovalRecord[]>;
     /**
-     * 在调用方的事务内（`mandatory`）取消某组织里指定由 `accountId` 处理（`requested_for`）的全部 pending 审批（成员离职），
-     * 走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、写 `approval_decided{cancelled}`（处理人为 null）。
-     * 返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件（并可续跑对应运行）。
+     * The conversations of `orgId` holding a pending approval `accountId` is asked to decide
+     * (`requested_for`), read without locks: offboarding locks them, by tree root first
+     * (`lockConversationTrees`), before {@link cancelPendingFor}.
+     */
+    pendingConversationsFor(orgId: string, accountId: string): Promise<string[]>;
+    /**
+     * In the caller's transaction (`mandatory`; offboarding): cancels every pending approval of
+     * `orgId` that `accountId` is asked to decide (`requested_for`) in `conversationIds`, the
+     * conversations the caller already locked (by tree root first, `lockConversationTrees`; lock
+     * order: conversations, then approval rows), along the same path as {@link cancelPendingIn}:
+     * `cancelled`, `approval_decided{cancelled}` with no decider. An approval asked meanwhile in
+     * another conversation is left to its run's stop, so no conversation is locked after a row.
+     * Returns the cancelled records and the highest seq written per conversation; the caller
+     * publishes after the commit.
      */
-    cancelPendingFor(orgId: string, accountId: string): Promise<{
+    cancelPendingFor(orgId: string, accountId: string, conversationIds: readonly string[]): Promise<{
         records: ApprovalRecord[];
         seqs: Map<string, number>;
     }>;