@te-river/opencode-team-mode 1.7.2 → 1.7.4

package/dist/approval-gate.d.ts

@@ -1,205 +0,0 @@
-/**
- * Unified approval gate — Layer 2 (timeout auto-reject) + Layer 3 (SDK
- * fallback) of the R6 + R2 approval flow.
- *
- * The host only shows its official confirmation dialog for command patterns
- * declared `ask` in an agent's permission config (Layer 1, envprotect.ts).
- * When a dialog opens it SUSPENDS the tool call and waits for a human; on the
- * OpenCode DESKTOP that human is present, but a request can also be left
- * unanswered.  This module owns ONE timer that watches the host permission
- * events and closes abandoned requests on the safe side.
- *
- * REAL host contract (1.18.29, probed live via SSE + the plugin event hook —
- * see gate-test report-p5):
- *   permission.asked   → properties = { id, sessionID, permission: "bash",
- *                        patterns: [<concrete command segment>, …], metadata:
- *                        { command }, always: [<host's "always" generalization
- *                        proposal>], tool: { messageID, callID } } — the props
- *                        carry NO `type` field, and the tool name sits in
- *                        `permission`.  A props matching one of OUR injected
- *                        bash ask sets means the dialog is ours: audit "ask",
- *                        arm the timeout, and — for the R6 env face — mark
- *                        the session deferrable (canDefer, see below).
- *   permission.replied → properties = { sessionID, requestID, reply } on the
- *                        wire, but the plugin-side observer has also seen it
- *                        with ONLY { sessionID }.  The gate therefore cancels
- *                        EVERY pending timer of that session on a reply: an
- *                        already-approved command left on a live timer would
- *                        get a second reject after the timeout, the SDK call
- *                        would hit a dead id (4xx) and flip the gate
- *                        permanently degraded.
- *
- * Older/typed spellings (`permission.updated`, `pattern`, `permissionID`,
- * `response`) keep being accepted — the shipped SDK d.ts still names the
- * events that way, and some builds omit the reply id entirely (a short
- * ghost-suppression window per session then absorbs late/duplicate `asked`
- * replays instead of re-arming a ghost timer).
- *
- * Hard rules (HUMAN-approved):
- *   - the plugin NEVER self-allows: `reply` is fixed to "reject".  The only
- *     way a gated command runs is a human approving the dialog;
- *   - on `TM_ENV_PROTECT=off` the gate is not armed (the caller decides);
- *   - deferral is SESSION-SCOPED (canDefer): only sessions registered as
- *     carrying our injected ask set may have env reads passed through —
- *     registration comes from an exec-role user prompt (the live-proven
- *     `message.updated` UserMessage{role,agent,sessionID} signal, plus the
- *     documented `chat.message` hook) or from an R6-env-classified asked
- *     event.  Stock build/plan sessions never register, so the global R6
- *     hook keeps hard-throwing there — closing the R6 bypass the global
- *     `isArmed()` deferral allowed;
- *   - if the SDK reply FAILS (network/host — including the SDK's
- *     `throwOnError:false` envelope resolving with `{ error }`), we cannot
- *     close the dialog, so the gate flips itself permanently "degraded" —
- *     the R6 hook stops deferring env reads and hard-throws them again
- *     (fail-closed), and the event is audited "degraded".
- *
- * SDK surface (probed live): the host client may carry NO `permission`
- * namespace and NO list/create endpoint; the reply path is the top-level
- * `postSessionIdPermissionsPermissionId({ path: { id: sessionID,
- * permissionID }, body: { response } })`.  `client.permission.reply` /
- * `client.permission.list` are still tried first so a richer host build is
- * supported, but when they are absent the poll fallback is a no-op (events
- * are the sole pending signal).
- */
-import type { PermissionEvent } from "./types.js";
-/** Default timeout, in minutes, before an unanswered dialog is auto-rejected.
- *  1 min (user directive) — an unanswered dialog no longer hangs for 10.
- *  A short timer is safe because a reject that lands on an already-closed
- *  request is benign; see `MIN_ASK_TIMEOUT_MIN` for the full rationale. */
-export declare const DEFAULT_ASK_TIMEOUT_MIN = 1;
-/**
- * Hard floor (minutes) for the auto-reject timeout.  The HISTORIC 3-min
- * floor existed to dodge the measured ~120s `permission.replied` bus lag:
- * a shorter timer would fire before the cancel arrives and auto-reject a
- * just-approved request.  That lag, though, is the HOST DELIVERING the
- * replied event to the plugin over the bus — NOT the host resolving the
- * user's click: an approval takes effect instantly host-side, so the
- * plugin's late reject simply targets an already-closed request id → 404.
- * T2's `classifyReplyFailure` maps that outcome to the benign
- * `already-closed` verdict (it never flips the gate to `degraded`, and the
- * approved command runs either way); `onReplied` records a reply landing
- * after the auto-reject as `late-<verdict>` for observability.  With that
- * classification in place a short timeout no longer disables the gate, so
- * the floor drops to 1 minute (user directive).  Trade-off: an UNANSWERED
- * dialog auto-rejects after 1 min — a user who stepped away re-triggers
- * the command.  In-range values below the floor still clamp UP to it.
- *
- * This is the FALLBACK default of the floor.  The live floor comes from the
- * P0 config knob `TM_ASK_TIMEOUT_FLOOR_MIN`
- * (`resolveTmConfig().askTimeoutFloorMin`, itself defaulted to 1).
- */
-export declare const MIN_ASK_TIMEOUT_MIN = 1;
-/** The verdict vocabulary recorded in the audit trail (privacy: no command
- *  text, path, variable name or value is ever logged).  `already-closed` /
- *  `rejected-shape-bug` split the old blanket `degraded` on a failed reply by
- *  `classifyReplyFailure`; a late reply past the auto-reject is recorded as a
- *  dynamic `late-<verdict>` string (observability only — never re-runs or
- *  revives the command). */
-export type ApprovalVerdict = "ask" | "allowed-once" | "allowed-always" | "rejected" | "timeout-rejected" | "already-closed" | "rejected-shape-bug" | "degraded";
-/**
- * Resolve `TM_ASK_TIMEOUT_MIN`.  Unset / blank / non-numeric / <1 / >1440
- * (24h) fall back to the 1-minute default — a mistyped value can never
- * disable the timeout or make it absurdly long.  Valid values below the
- * floor clamp UP to it — the floor is the P0 config knob
- * `TM_ASK_TIMEOUT_FLOOR_MIN` (`resolveTmConfig().askTimeoutFloorMin`,
- * default 1).  The historic ~120s bus-lag reason for a 3-min floor is
- * obsolete: a late reject on an already-closed id is benign
- * `already-closed`, not a degraded flip (see `MIN_ASK_TIMEOUT_MIN`).
- */
-export declare function resolveAskTimeoutMs(env?: Record<string, string | undefined>): number;
-type TimerHandle = unknown;
-export interface GateTimers {
-    setTimeoutFn: (cb: () => void, ms: number) => TimerHandle;
-    clearTimeoutFn: (handle: TimerHandle) => void;
-}
-export interface ApprovalGateDeps {
-    client: unknown;
-    timeoutMs: number;
-    /** Injectable timers (default: real global timers) for deterministic tests. */
-    timers?: GateTimers;
-    /** Injectable clock (default: Date.now) for deterministic window tests. */
-    now?: () => number;
-    /** Best-effort attention hook — fired on EVERY permission.asked (all
-     *  dialogs: bash R2/R6 asks AND the tm_* ctx.ask web dialogs) so a user
-     *  not staring at the screen learns a confirmation is waiting.  The caller
-     *  wires this to the host's `tui.showToast`.  Never throws into the gate. */
-    notify?: (message: string) => void;
-}
-export interface ApprovalGate {
-    /** Handle one host event (permission.asked/updated / permission.replied). */
-    handleEvent(event: PermissionEvent): void;
-    /** Start the poll fallback (no-op when the host has no list endpoint). */
-    start(): void;
-    /** Stop the poll + every pending timer. */
-    dispose(): void;
-    /** Global gate health: armed, not degraded, and the client can reply. */
-    isArmed(): boolean;
-    /**
-     * The R6 hook's deferral query: TRUE only when this exact session is
-     * registered as carrying our injected ask set AND the gate is healthy.
-     * Replaces the old global `isArmed()` deferral (which let stock build/plan
-     * sessions pass env reads silently with no dialog in front of them).
-     */
-    canDefer(sessionID?: string): boolean;
-    /** True once a session registered (exec-role prompt seen on
-     *  message.updated / chat.message by index.ts, or an R6-env-classified
-     *  asked event).  Introspection for tests/diagnostics. */
-    hasLiveAsk(sessionID?: string): boolean;
-    /** Mark a session as carrying the injected ask set (index.ts calls this
-     *  when a user prompt routes to an agent we injected the escalated bash
-     *  ask object into — proven live: `message.updated` UserMessage carries
-     *  { sessionID, role:"user", agent } and fires BEFORE the session's first
-     *  tool call, while permission.asked fires AFTER tool.execute.before). */
-    registerExecSession(sessionID?: string): void;
-    /**
-     * Drop a session's exec-role registration (index.ts calls this when a user
-     * prompt routes to an agent that does NOT carry our injected ask set).
-     * The verified host passes {tool, sessionID, callID} with NO agent to
-     * tool.execute.before (desktop binary: `plugin.trigger("tool.execute.before",
-     * { tool, sessionID, callID }, { args })`), so the per-turn agent signal
-     * can only come from message.updated/chat.message.  Without revocation a
-     * session that once ran a team prompt stayed deferrable forever — even
-     * after the user switched the picker to a stock agent whose dialogs would
-     * never fire, silently passing env reads (canDefer true + no dialog).
-     * A later env-classified permission.asked re-registers on real dialog
-     * evidence, and the next exec-role prompt re-registers again — both paths
-     * re-arm from fresh evidence, so revocation only ever closes a stale
-     * window (fail-closed direction).
-     */
-    revokeExecSession(sessionID?: string): void;
-    /** True after the user picked "always" on an env-related ask in this session
-     *  — subsequent env reads pass silently (the approval event itself is audited). */
-    isEnvApproved(sessionID?: string): boolean;
-    /** Number of pending requests currently being timed (tests / introspection). */
-    pendingSize(): number;
-}
-/** How a FAILED permission-reply call should be treated by the gate. */
-export type ReplyFailureClass = "benign-closed" | "param-shape" | "transport";
-/**
- * Classify a reply-call failure so the gate no longer flips permanently
- * `degraded` on a harmless close.  `unwrapSdkEnvelope` has already hoisted the
- * HTTP status onto the thrown envelope error; a genuine `Promise.reject`
- * arrives as a plain Error with no status.
- *   - `benign-closed`: 404, or a NotFound/PermissionNotFound name/_tag — the
- *     dialog was ALREADY closed on the host (the D4 late-reply race): our
- *     reject was a no-op, so the popup path stays trustworthy.
- *   - `param-shape`: 400, or a BadRequest/InvalidRequest name/_tag — our
- *     reply body/params are wrong for this host: a real integration bug.
- *   - `transport`: everything else — a genuine Error, a 5xx, or an empty /
- *     status-less body — we could not reach or close the dialog.
- * Reads only the error CLASS + status number (privacy: never message text).
- */
-export declare function classifyReplyFailure(err: unknown): ReplyFailureClass;
-/** True when the client exposes a permission-reply path at all.  index.ts
- *  arms the gate ONLY for such a client — fail-closed otherwise (no armed
- *  auto-reject ⇒ the R6 hook keeps hard-throwing every env read). */
-export declare function hasPermissionReplyCapability(client: unknown): boolean;
-/**
- * Create the approval gate.  It is intentionally pure about timing +
- * replying + session registration; the caller (index.ts) decides whether to
- * arm it (mode != off AND the client is reply-capable), feeds events in, and
- * wires `canDefer(sessionID)` into the R6 hook.
- */
-export declare function createApprovalGate(deps: ApprovalGateDeps): ApprovalGate;
-export {};
-//# sourceMappingURL=approval-gate.d.ts.map

package/dist/approval-gate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"approval-gate.d.ts","sourceRoot":"","sources":["../src/approval-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAIjD;;;2EAG2E;AAC3E,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAkBpC;;;;;4BAK4B;AAC5B,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,cAAc,GACd,gBAAgB,GAChB,UAAU,GACV,kBAAkB,GAClB,gBAAgB,GAChB,oBAAoB,GACpB,UAAU,CAAA;AAEd;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAWjG;AAED,KAAK,WAAW,GAAG,OAAO,CAAA;AAE1B,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAA;IACzD,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;;;iFAG6E;IAC7E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IACzC,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAAA;IACb,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC;;8DAE0D;IAC1D,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvC;;;;8EAI0E;IAC1E,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7C;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C;uFACmF;IACnF,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1C,gFAAgF;IAChF,WAAW,IAAI,MAAM,CAAA;CACtB;AAuED,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,aAAa,GAAG,WAAW,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAgBpE;AA8DD;;qEAEqE;AACrE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAErE;AAyBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAqUvE"}