crewly 1.20.180 → 1.20.181

package/dist/backend/backend/src/services/browser/browser-approval.service.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Owner approval of held browser actions.
+ *
+ * When `BrowserSessionService.authorize` holds an irreversible click (send,
+ * submit, pay, delete…), this service:
+ *
+ * 1. persists the hold under CREWLY_HOME ({@link HeldActionStore});
+ * 2. asks the owner with a Slack decision card (kind `browser_action`,
+ *    "Let it" / "No", never auto-approved) posted by the agent's own bot in
+ *    the thread of the work item it is on;
+ * 3. applies the answer, whichever place it came from — the card's button,
+ *    a reaction, a thread reply (批准 / 可以 / yes, 不行 / no), the decisions
+ *    dashboard, or the Browser page of the dashboard / portal — to the one
+ *    held action, and tells the agent;
+ * 4. at the deadline ({@link BROWSER_APPROVAL_CONSTANTS.DEADLINE_MS}) the
+ *    answer is No;
+ * 5. after a restart, re-attaches a hold whose tab comes back in the
+ *    extension's tab inventory, and expires the rest (card updated, agent
+ *    told to redo the step).
+ *
+ * Approval works exactly like the dashboard's approve always has: it grants
+ * the agent ONE pass for its next attempt and tells it to go ahead. Crewly
+ * does not replay the click itself — the agent knows what it was in the
+ * middle of, and after a wait the page may have changed.
+ *
+ * Every outcome is applied in one place, {@link BrowserApprovalService.onSettled},
+ * which the decision service calls when a `browser_action` card settles.
+ * Paths without a card (no Slack, card not created yet) apply it directly.
+ *
+ * @module services/browser/browser-approval.service
+ */
+import type { OwnerDecision } from '../../types/decision.types.js';
+import type { DecisionKindHandler, PrebuiltAsk } from '../decisions/decision.service.js';
+import { type ComponentLogger } from '../core/logger.service.js';
+import type { BrowserHoldListener, BrowserSession, BrowserSessionService } from './browser-session.service.js';
+import type { ExtensionTabDescriptor } from './browser-bridge.service.js';
+import { HeldActionStore, type HeldBrowserAction } from './held-action-store.js';
+/** The slice of the decision service used here. */
+export interface BrowserApprovalDecisions {
+    askPrebuilt(ask: PrebuiltAsk): Promise<OwnerDecision>;
+    chooseFromDashboard(id: string, optionKey: string): Promise<OwnerDecision>;
+    expire(id: string): Promise<OwnerDecision | null>;
+    cancelWhere(filter: (d: OwnerDecision) => boolean, note?: string): Promise<number>;
+}
+/** Collaborators. */
+export interface BrowserApprovalDeps {
+    store: HeldActionStore;
+    sessions: Pick<BrowserSessionService, 'getSession' | 'resolvePending' | 'restorePending'>;
+    /** The decision service, once it runs */
+    decisions: () => BrowserApprovalDecisions | null;
+    /** Whether a card can be posted now (decision service up, Slack connected) */
+    canAskInSlack: () => boolean;
+    /** Deliver a line to an agent (paths without a card) */
+    tellAgent: (agentSession: string, text: string) => Promise<unknown>;
+    /** Display name of an agent ("Vera") */
+    agentNameOf?: (agentSession: string) => Promise<string | undefined>;
+    /** The tab an agent is bound to */
+    boundTabOf?: (agentSession: string) => {
+        tabId: number;
+        instanceId?: string;
+    } | undefined;
+    /** Re-bind an agent to an existing tab (after a restart) */
+    adoptTab?: (agentSession: string, tabId: number, instanceId?: string) => boolean;
+    now?: () => number;
+    logger?: ComponentLogger;
+}
+/**
+ * Strip a URL to "host/path" for the card.
+ *
+ * @param url - URL the agent targeted
+ * @returns "visa.careerengine.us/subscribe", or undefined
+ */
+export declare function placeOf(url: string | undefined): string | undefined;
+/**
+ * The visible name of what a click targets, from its params: the text the
+ * agent passed, else a quoted name in the selector (`:has-text("Submit")`,
+ * `[aria-label="Send"]`, `text=Pay`), else the selector itself.
+ *
+ * @param params - Params of the call
+ * @returns Button text / selector, or undefined
+ */
+export declare function controlName(params: Record<string, unknown> | undefined): string | undefined;
+/**
+ * What the agent wants to do, in a few words: `click "Submit"`, `press Enter`.
+ *
+ * @param tool - Tool it called
+ * @param params - Params it called it with
+ * @returns Short phrase (≤ 100 characters)
+ */
+export declare function describeTarget(tool: string, params: Record<string, unknown> | undefined): string;
+/**
+ * The card's question: "Vera wants to click "Submit" on visa.careerengine.us/subscribe — it looks like submitting and can't be undone."
+ *
+ * @param agentName - Agent display name
+ * @param action - Held action
+ * @returns One line (≤ 280 characters)
+ */
+export declare function approvalQuestion(agentName: string, action: Pick<HeldBrowserAction, 'target' | 'where' | 'matched'>): string;
+/** The line a held agent is given about where the owner answers. */
+export declare const CARD_ASKED_LINE: string;
+/**
+ * Asks the owner about held browser actions and applies the answer.
+ */
+export declare class BrowserApprovalService implements BrowserHoldListener, DecisionKindHandler {
+    private static instance;
+    private readonly deps;
+    private readonly logger;
+    private readonly now;
+    /** Holds restored from disk, waiting for their tab to come back: pendingId → since (ms) */
+    private readonly awaitingRebind;
+    /** In-flight async work started from sync hooks (tests wait on it) */
+    private readonly inflight;
+    private timer;
+    private ticking;
+    private restored;
+    /**
+     * @param deps - Collaborators
+     */
+    constructor(deps: BrowserApprovalDeps);
+    /** @returns The process-wide instance, or null before wiring */
+    static getInstance(): BrowserApprovalService | null;
+    /** @param service - Instance to install (null clears) */
+    static setInstance(service: BrowserApprovalService | null): void;
+    /** Start the retry / expiry tick. */
+    start(): void;
+    /** Stop the tick. */
+    stop(): void;
+    /** Wait for work started by the sync hooks (tests). */
+    idle(): Promise<void>;
+    private track;
+    /**
+     * An action was held: persist it and ask the owner with a card.
+     *
+     * @param session - Session holding it (`pending` set)
+     * @param params - Params of the held call (not persisted)
+     * @returns What the agent is told about where the owner answers
+     */
+    onHeld(session: BrowserSession, params: Record<string, unknown> | undefined): string | undefined;
+    /**
+     * Create the card for a held action.
+     *
+     * @param action - The held action
+     */
+    private createCard;
+    /**
+     * A hold was dropped without an answer: withdraw its card.
+     *
+     * @param _agentSession - Agent
+     * @param pendingId - The dropped hold
+     */
+    onDropped(_agentSession: string, pendingId: string): void;
+    /**
+     * A `browser_action` decision settled (button, reaction, reply, decisions
+     * dashboard, Browser page via {@link answerFromBrowserPage}, deadline,
+     * expiry or withdrawal). Applies it to the held action.
+     *
+     * @param decision - The settled decision
+     * @returns Note for the agent, or null
+     */
+    onSettled(decision: OwnerDecision): Promise<string | null>;
+    /**
+     * The owner answered on the Browser page (dashboard or portal). With a
+     * card, the answer goes through the card so it is updated too; without
+     * one it is applied directly.
+     *
+     * @param agentSession - Session holding the action
+     * @param pendingId - The hold being answered
+     * @param answer - What the owner chose
+     * @returns The updated session, or undefined when no such hold is waiting
+     */
+    answerFromBrowserPage(agentSession: string, pendingId: string, answer: 'approve' | 'reject'): Promise<BrowserSession | undefined>;
+    /**
+     * Apply an outcome to a held action (once) and say what the agent is told.
+     */
+    private apply;
+    /**
+     * After a restart: wait for the tab of each pending hold to come back
+     * (tab inventory); holds without a known tab expire right away.
+     *
+     * @returns How many holds are waiting for their tab
+     */
+    restore(): Promise<number>;
+    /**
+     * A tab inventory arrived: re-bind each restored hold whose tab is in it.
+     *
+     * @param tabs - Tabs the extension reports
+     * @param instanceId - Browser instance that sent it (undefined = direct WS)
+     */
+    onTabInventory(tabs: ExtensionTabDescriptor[], instanceId?: string): void;
+    /** Expire a hold: through its card when it has one (the card says so), else directly. */
+    private expire;
+    /**
+     * One pass: expire restored holds whose tab never came back, create cards
+     * that could not be created, time out holds without a card, prune.
+     *
+     * @returns Ids acted on
+     */
+    tick(): Promise<string[]>;
+}
+/** @returns The process-wide approval service, or null before wiring */
+export declare function getBrowserApprovals(): BrowserApprovalService | null;
+//# sourceMappingURL=browser-approval.service.d.ts.map

package/dist/backend/backend/src/services/browser/browser-approval.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-approval.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/browser/browser-approval.service.ts"],"names":[],"mappings":"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"}