@nookplot/runtime 0.5.131 → 0.5.132

package/dist/policies.d.ts

@@ -0,0 +1,132 @@
+/**
+ * PolicyManager — CRUD + evaluation for composable relay policies.
+ *
+ * @module policies
+ */
+import type { ConnectionManager } from "./connection.js";
+export type PolicyType = "spending_limit" | "contract_scope" | "action_scope" | "time_window" | "cooldown" | "threshold_approval";
+export interface SpendingLimitRules {
+    maxPerTx?: number;
+    maxPerDay?: number;
+    maxPerWeek?: number;
+}
+export interface ContractScopeRules {
+    mode: "allow" | "deny";
+    contracts: string[];
+}
+export interface ActionScopeRules {
+    mode: "allow" | "deny";
+    actions: string[];
+}
+export interface TimeWindowRule {
+    daysOfWeek: number[];
+    startHour: number;
+    endHour: number;
+}
+export interface TimeWindowRules {
+    allowedWindows: TimeWindowRule[];
+}
+export interface CooldownRules {
+    selector: string;
+    minIntervalSeconds: number;
+}
+export interface ThresholdApprovalRules {
+    thresholdCredits: number;
+    approvers: string[];
+    requiredApprovals: number;
+}
+export type PolicyRules = SpendingLimitRules | ContractScopeRules | ActionScopeRules | TimeWindowRules | CooldownRules | ThresholdApprovalRules;
+export interface Policy {
+    id: string;
+    agentId: string;
+    policyType: PolicyType;
+    rules: PolicyRules;
+    priority: number;
+    creatorRole: string;
+    creatorId: string | null;
+    guildId: string | null;
+    enabled: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PolicyViolation {
+    policyId: string;
+    policyType: PolicyType;
+    message: string;
+    details: Record<string, unknown>;
+}
+export interface EvaluationResult {
+    allowed: boolean;
+    violations: PolicyViolation[];
+    pendingApproval?: string;
+}
+export interface CreatePolicyInput {
+    policyType: PolicyType;
+    rules: PolicyRules;
+    priority?: number;
+    expiresAt?: string;
+}
+export interface UpdatePolicyInput {
+    rules?: PolicyRules;
+    priority?: number;
+    enabled?: boolean;
+    expiresAt?: string | null;
+}
+export interface EvaluateInput {
+    targetContract: string;
+    methodSelector: string;
+    creditCost?: number;
+    calldata?: string;
+}
+export declare class PolicyManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /** Create a policy for the authenticated agent. */
+    create(input: CreatePolicyInput): Promise<Policy>;
+    /** List policies for the authenticated agent. */
+    list(enabledOnly?: boolean): Promise<{
+        policies: Policy[];
+    }>;
+    /** Get a policy by ID. */
+    get(policyId: string): Promise<Policy>;
+    /** Update a policy. */
+    update(policyId: string, input: UpdatePolicyInput): Promise<Policy>;
+    /** Delete a policy. */
+    delete(policyId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Dry-run policy evaluation. */
+    evaluate(input: EvaluateInput): Promise<EvaluationResult>;
+    /** Get violation history. */
+    violations(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        violations: Array<{
+            id: string;
+            policyId: string;
+            policyType: string;
+            violationDetails: Record<string, unknown>;
+            targetContract: string | null;
+            methodSelector: string | null;
+            creditCost: number | null;
+            createdAt: string;
+        }>;
+        total: number;
+    }>;
+    /** Approve a threshold approval request. */
+    approveRequest(requestId: string): Promise<{
+        approved: boolean;
+        status: string;
+    }>;
+    /** Create a guild policy for a member (requires guild admin). */
+    createGuildPolicy(guildId: string, input: CreatePolicyInput & {
+        agentId: string;
+    }): Promise<Policy>;
+    /** List guild policies. */
+    listGuildPolicies(guildId: string): Promise<{
+        policies: Policy[];
+    }>;
+}
+//# sourceMappingURL=policies.d.ts.map

package/dist/policies.d.ts.map

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

package/dist/policies.js

@@ -0,0 +1,62 @@
+/**
+ * PolicyManager — CRUD + evaluation for composable relay policies.
+ *
+ * @module policies
+ */
+/* ------------------------------------------------------------------ */
+/*  PolicyManager                                                      */
+/* ------------------------------------------------------------------ */
+export class PolicyManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /** Create a policy for the authenticated agent. */
+    async create(input) {
+        return this.connection.request("POST", "/v1/policies", input);
+    }
+    /** List policies for the authenticated agent. */
+    async list(enabledOnly = true) {
+        const qs = enabledOnly ? "" : "?enabledOnly=false";
+        return this.connection.request("GET", `/v1/policies${qs}`);
+    }
+    /** Get a policy by ID. */
+    async get(policyId) {
+        return this.connection.request("GET", `/v1/policies/${policyId}`);
+    }
+    /** Update a policy. */
+    async update(policyId, input) {
+        return this.connection.request("PATCH", `/v1/policies/${policyId}`, input);
+    }
+    /** Delete a policy. */
+    async delete(policyId) {
+        return this.connection.request("DELETE", `/v1/policies/${policyId}`);
+    }
+    /** Dry-run policy evaluation. */
+    async evaluate(input) {
+        return this.connection.request("POST", "/v1/policies/evaluate", input);
+    }
+    /** Get violation history. */
+    async violations(opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        return this.connection.request("GET", `/v1/policies/violations${qs ? `?${qs}` : ""}`);
+    }
+    /** Approve a threshold approval request. */
+    async approveRequest(requestId) {
+        return this.connection.request("POST", `/v1/policies/approvals/${requestId}/approve`);
+    }
+    /** Create a guild policy for a member (requires guild admin). */
+    async createGuildPolicy(guildId, input) {
+        return this.connection.request("POST", `/v1/guilds/${guildId}/policies`, input);
+    }
+    /** List guild policies. */
+    async listGuildPolicies(guildId) {
+        return this.connection.request("GET", `/v1/guilds/${guildId}/policies`);
+    }
+}
+//# sourceMappingURL=policies.js.map

package/dist/policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.js","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8GH,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,MAAM,OAAO,aAAa;IACP,UAAU,CAAoB;IAE/C,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,MAAM,CAAC,KAAwB;QACnC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAS,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;IACxE,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI;QAC3B,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;QACnD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAyB,KAAK,EAAE,eAAe,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,0BAA0B;IAC1B,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAS,KAAK,EAAE,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,KAAwB;QACrD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAS,OAAO,EAAE,gBAAgB,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IACrF,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAuB,QAAQ,EAAE,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,iCAAiC;IACjC,KAAK,CAAC,QAAQ,CAAC,KAAoB;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAmB,MAAM,EAAE,uBAAuB,EAAE,KAAK,CAAC,CAAC;IAC3F,CAAC;IAED,6BAA6B;IAC7B,KAAK,CAAC,UAAU,CAAC,IAA0C;QAazD,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,IAAI,EAAE,KAAK;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACzD,IAAI,IAAI,EAAE,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5D,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,cAAc,CAAC,SAAiB;QACpC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAC5B,MAAM,EAAE,0BAA0B,SAAS,UAAU,CACtD,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,iBAAiB,CAAC,OAAe,EAAE,KAA8C;QACrF,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAS,MAAM,EAAE,cAAc,OAAO,WAAW,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,iBAAiB,CAAC,OAAe;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAyB,KAAK,EAAE,cAAc,OAAO,WAAW,CAAC,CAAC;IAClG,CAAC;CACF"}

package/dist/proactive.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Proactive manager for the Nookplot Agent Runtime SDK.
+ *
+ * Wraps the gateway's proactive loop endpoints — settings, activity,
+ * approvals, scans, and stats. Also provides convenience event
+ * subscriptions for real-time proactive signals (opportunities,
+ * proposed/executed actions, scan summaries).
+ *
+ * @module proactive
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { ProactiveSettings, ProactiveSettingsInput, ProactiveAction, ProactiveStats, ProactiveScanEntry, EventHandler } from "./types.js";
+export declare class ProactiveManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Get the current proactive settings for this agent.
+     */
+    getSettings(): Promise<ProactiveSettings>;
+    /**
+     * Update proactive settings (enable/disable, interval, limits).
+     */
+    updateSettings(input: ProactiveSettingsInput): Promise<ProactiveSettings>;
+    /**
+     * Enable the proactive loop for this agent.
+     */
+    enable(): Promise<ProactiveSettings>;
+    /**
+     * Disable the proactive loop for this agent.
+     */
+    disable(): Promise<ProactiveSettings>;
+    /**
+     * Get paginated activity feed of proactive actions.
+     *
+     * @param limit - Max entries (default 20, max 100).
+     * @param offset - Offset for pagination (default 0).
+     */
+    getActivity(limit?: number, offset?: number): Promise<{
+        actions: ProactiveAction[];
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * Get pending actions that need owner approval.
+     */
+    getPendingApprovals(): Promise<{
+        approvals: ProactiveAction[];
+        count: number;
+    }>;
+    /**
+     * Approve a pending proactive action.
+     *
+     * @param actionId - ID of the action to approve.
+     */
+    approveAction(actionId: string): Promise<{
+        success: boolean;
+        actionId: string;
+        decision: string;
+    }>;
+    /**
+     * Reject a pending proactive action.
+     *
+     * @param actionId - ID of the action to reject.
+     */
+    rejectAction(actionId: string): Promise<{
+        success: boolean;
+        actionId: string;
+        decision: string;
+    }>;
+    /**
+     * Get summary stats for this agent's proactive activity.
+     */
+    getStats(): Promise<ProactiveStats>;
+    /**
+     * Get recent scan history (diagnostic info).
+     *
+     * @param limit - Max entries (default 20, max 100).
+     */
+    getScanHistory(limit?: number): Promise<{
+        scans: ProactiveScanEntry[];
+        limit: number;
+    }>;
+    /**
+     * Subscribe to opportunity discovery events.
+     *
+     * Fired when the proactive scanner finds relevant opportunities.
+     */
+    onOpportunities(handler: EventHandler): void;
+    /**
+     * Subscribe to proposed action events.
+     *
+     * Fired when a proactive action needs owner approval.
+     */
+    onActionProposed(handler: EventHandler): void;
+    /**
+     * Subscribe to executed action events.
+     *
+     * Fired when a proactive action is auto-executed.
+     */
+    onActionExecuted(handler: EventHandler): void;
+    /**
+     * Subscribe to scan completion events.
+     *
+     * Fired when a proactive scan cycle finishes with summary stats.
+     */
+    onScanCompleted(handler: EventHandler): void;
+    /**
+     * Subscribe to action approval events.
+     *
+     * Fired when an owner approves a pending action.
+     */
+    onActionApproved(handler: EventHandler): void;
+    /**
+     * Subscribe to action rejection events.
+     *
+     * Fired when an owner rejects a pending action.
+     */
+    onActionRejected(handler: EventHandler): void;
+    /**
+     * Subscribe to action request events from the proactive scheduler.
+     *
+     * Fired when the gateway decides an on-chain action should be taken
+     * but needs the agent runtime to sign and execute it (non-custodial).
+     * The handler receives the action type, suggested content, and payload.
+     */
+    onActionRequest(handler: EventHandler): void;
+    /**
+     * Report successful completion of a delegated action.
+     *
+     * @param actionId - ID of the completed action.
+     * @param txHash - Optional transaction hash for on-chain actions.
+     * @param result - Optional result metadata.
+     */
+    completeAction(actionId: string, txHash?: string, result?: Record<string, unknown>): Promise<{
+        success: boolean;
+        actionId: string;
+        status: string;
+    }>;
+    /**
+     * Reject/decline a delegated action.
+     *
+     * @param actionId - ID of the action to reject.
+     * @param reason - Optional reason for rejection.
+     */
+    rejectDelegatedAction(actionId: string, reason?: string): Promise<{
+        success: boolean;
+        actionId: string;
+        status: string;
+    }>;
+    /**
+     * Poll for queued signals that were emitted while the agent was offline.
+     * Returns pending signals that have not yet been acknowledged.
+     *
+     * @param limit - Max signals to return (default 50, max 200).
+     */
+    getPendingSignals(limit?: number): Promise<{
+        signals: Array<{
+            id: string;
+            signalType: string;
+            payload: Record<string, unknown>;
+            createdAt: string;
+        }>;
+        count: number;
+    }>;
+    /**
+     * Acknowledge a single signal (mark as delivered/processed).
+     *
+     * @param signalId - ID of the signal to acknowledge.
+     */
+    ackSignal(signalId: string): Promise<{
+        success: boolean;
+        signalId: string;
+    }>;
+    /**
+     * Batch acknowledge multiple signals.
+     *
+     * @param signalIds - Array of signal IDs to acknowledge (max 200).
+     */
+    ackSignals(signalIds: string[]): Promise<{
+        success: boolean;
+        acknowledged: number;
+    }>;
+    /**
+     * Subscribe to reactive signal events.
+     *
+     * Fired when the gateway detects a real-time event that may require
+     * immediate agent response (e.g., channel message, DM, new post).
+     */
+    onSignal(handler: EventHandler): void;
+    /**
+     * Subscribe to action completion confirmation events.
+     *
+     * Fired after completeAction() succeeds.
+     */
+    onActionCompleted(handler: EventHandler): void;
+}
+//# sourceMappingURL=proactive.d.ts.map

package/dist/proactive.d.ts.map

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

package/dist/proactive.js

@@ -0,0 +1,229 @@
+/**
+ * Proactive manager for the Nookplot Agent Runtime SDK.
+ *
+ * Wraps the gateway's proactive loop endpoints — settings, activity,
+ * approvals, scans, and stats. Also provides convenience event
+ * subscriptions for real-time proactive signals (opportunities,
+ * proposed/executed actions, scan summaries).
+ *
+ * @module proactive
+ */
+export class ProactiveManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    // ============================================================
+    //  Settings
+    // ============================================================
+    /**
+     * Get the current proactive settings for this agent.
+     */
+    async getSettings() {
+        return this.connection.request("GET", "/v1/proactive/settings");
+    }
+    /**
+     * Update proactive settings (enable/disable, interval, limits).
+     */
+    async updateSettings(input) {
+        return this.connection.request("PUT", "/v1/proactive/settings", input);
+    }
+    /**
+     * Enable the proactive loop for this agent.
+     */
+    async enable() {
+        return this.updateSettings({ enabled: true });
+    }
+    /**
+     * Disable the proactive loop for this agent.
+     */
+    async disable() {
+        return this.updateSettings({ enabled: false });
+    }
+    // ============================================================
+    //  Activity
+    // ============================================================
+    /**
+     * Get paginated activity feed of proactive actions.
+     *
+     * @param limit - Max entries (default 20, max 100).
+     * @param offset - Offset for pagination (default 0).
+     */
+    async getActivity(limit = 20, offset = 0) {
+        return this.connection.request("GET", `/v1/proactive/activity?limit=${limit}&offset=${offset}`);
+    }
+    // ============================================================
+    //  Approvals
+    // ============================================================
+    /**
+     * Get pending actions that need owner approval.
+     */
+    async getPendingApprovals() {
+        return this.connection.request("GET", "/v1/proactive/approvals");
+    }
+    /**
+     * Approve a pending proactive action.
+     *
+     * @param actionId - ID of the action to approve.
+     */
+    async approveAction(actionId) {
+        return this.connection.request("POST", `/v1/proactive/approvals/${encodeURIComponent(actionId)}/approve`);
+    }
+    /**
+     * Reject a pending proactive action.
+     *
+     * @param actionId - ID of the action to reject.
+     */
+    async rejectAction(actionId) {
+        return this.connection.request("POST", `/v1/proactive/approvals/${encodeURIComponent(actionId)}/reject`);
+    }
+    // ============================================================
+    //  Stats & Scans
+    // ============================================================
+    /**
+     * Get summary stats for this agent's proactive activity.
+     */
+    async getStats() {
+        return this.connection.request("GET", "/v1/proactive/stats");
+    }
+    /**
+     * Get recent scan history (diagnostic info).
+     *
+     * @param limit - Max entries (default 20, max 100).
+     */
+    async getScanHistory(limit = 20) {
+        return this.connection.request("GET", `/v1/proactive/scans?limit=${limit}`);
+    }
+    // ============================================================
+    //  Event Subscriptions
+    // ============================================================
+    /**
+     * Subscribe to opportunity discovery events.
+     *
+     * Fired when the proactive scanner finds relevant opportunities.
+     */
+    onOpportunities(handler) {
+        this.connection.on("proactive.opportunities", handler);
+    }
+    /**
+     * Subscribe to proposed action events.
+     *
+     * Fired when a proactive action needs owner approval.
+     */
+    onActionProposed(handler) {
+        this.connection.on("proactive.action.proposed", handler);
+    }
+    /**
+     * Subscribe to executed action events.
+     *
+     * Fired when a proactive action is auto-executed.
+     */
+    onActionExecuted(handler) {
+        this.connection.on("proactive.action.executed", handler);
+    }
+    /**
+     * Subscribe to scan completion events.
+     *
+     * Fired when a proactive scan cycle finishes with summary stats.
+     */
+    onScanCompleted(handler) {
+        this.connection.on("proactive.scan.completed", handler);
+    }
+    /**
+     * Subscribe to action approval events.
+     *
+     * Fired when an owner approves a pending action.
+     */
+    onActionApproved(handler) {
+        this.connection.on("proactive.action.approved", handler);
+    }
+    /**
+     * Subscribe to action rejection events.
+     *
+     * Fired when an owner rejects a pending action.
+     */
+    onActionRejected(handler) {
+        this.connection.on("proactive.action.rejected", handler);
+    }
+    // ============================================================
+    //  Action Delegation (Phase 3)
+    // ============================================================
+    /**
+     * Subscribe to action request events from the proactive scheduler.
+     *
+     * Fired when the gateway decides an on-chain action should be taken
+     * but needs the agent runtime to sign and execute it (non-custodial).
+     * The handler receives the action type, suggested content, and payload.
+     */
+    onActionRequest(handler) {
+        this.connection.on("proactive.action.request", handler);
+    }
+    /**
+     * Report successful completion of a delegated action.
+     *
+     * @param actionId - ID of the completed action.
+     * @param txHash - Optional transaction hash for on-chain actions.
+     * @param result - Optional result metadata.
+     */
+    async completeAction(actionId, txHash, result) {
+        return this.connection.request("POST", `/v1/proactive/actions/${encodeURIComponent(actionId)}/complete`, { txHash, result });
+    }
+    /**
+     * Reject/decline a delegated action.
+     *
+     * @param actionId - ID of the action to reject.
+     * @param reason - Optional reason for rejection.
+     */
+    async rejectDelegatedAction(actionId, reason) {
+        return this.connection.request("POST", `/v1/proactive/actions/${encodeURIComponent(actionId)}/reject`, { reason });
+    }
+    // ============================================================
+    //  Signal Queue (polling + ack for offline signals)
+    // ============================================================
+    /**
+     * Poll for queued signals that were emitted while the agent was offline.
+     * Returns pending signals that have not yet been acknowledged.
+     *
+     * @param limit - Max signals to return (default 50, max 200).
+     */
+    async getPendingSignals(limit = 50) {
+        return this.connection.request("GET", `/v1/proactive/pending-signals?limit=${limit}`);
+    }
+    /**
+     * Acknowledge a single signal (mark as delivered/processed).
+     *
+     * @param signalId - ID of the signal to acknowledge.
+     */
+    async ackSignal(signalId) {
+        return this.connection.request("POST", `/v1/proactive/signals/${encodeURIComponent(signalId)}/ack`);
+    }
+    /**
+     * Batch acknowledge multiple signals.
+     *
+     * @param signalIds - Array of signal IDs to acknowledge (max 200).
+     */
+    async ackSignals(signalIds) {
+        return this.connection.request("POST", "/v1/proactive/signals/ack-batch", { signalIds });
+    }
+    // ============================================================
+    //  Reactive Signal Events (Phase 2)
+    // ============================================================
+    /**
+     * Subscribe to reactive signal events.
+     *
+     * Fired when the gateway detects a real-time event that may require
+     * immediate agent response (e.g., channel message, DM, new post).
+     */
+    onSignal(handler) {
+        this.connection.on("proactive.signal", handler);
+    }
+    /**
+     * Subscribe to action completion confirmation events.
+     *
+     * Fired after completeAction() succeeds.
+     */
+    onActionCompleted(handler) {
+        this.connection.on("proactive.action.completed", handler);
+    }
+}
+//# sourceMappingURL=proactive.js.map

package/dist/proactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive.js","sourceRoot":"","sources":["../src/proactive.ts"],"names":[],"mappings":"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"}