@tx5dr/plugin-api 1.7.12 → 2.5.0

package/dist/context.d.ts

@@ -1,7 +1,15 @@
-import type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, BandAccess, UIBridge, PluginFileStore, PluginNetworkControl } from './helpers.js';
+import type { KVStore, ReadonlyKVStore, PluginLogger, PluginTimers, OperatorSnapshot, OperatorCommandPort, RadioView, RadioCapabilitiesView, RadioCommandPort, RadioTunerCommandPort, RadioPowerView, RadioPowerCommandPort, LogbookReadAccess, LogbookAccess, PluginLogbookSessions, BandAccess, UIBridge, PluginFileStore, PluginNetworkControl, PluginEventBus } from './helpers.js';
+import type { PluginPermission } from '@tx5dr/contracts';
 import type { LogbookSyncRegistrar } from './sync.js';
 import type { HostSettingsControl } from './settings.js';
 import type { HostDependencies } from './host-dependencies.js';
+/** A cancellable task started by Host after the core server is ready. */
+export type PluginAfterStartupTask = (signal: AbortSignal) => void | Promise<void>;
+/** Host-owned lifecycle services that do not block the initial plugin load. */
+export interface PluginLifecyclePort {
+    /** Schedule idempotent plugin work for the first post-startup turn. */
+    scheduleAfterStartup(id: string, task: PluginAfterStartupTask): () => void;
+}
 /**
  * Runtime services exposed to a plugin instance.
  *
@@ -15,12 +23,15 @@ import type { HostDependencies } from './host-dependencies.js';
  * here, plugin code should treat it as unavailable rather than reaching into
  * TX-5DR internals.
  */
-export interface PluginContext {
+export interface PluginContextBase {
+    /** Bundled Plugin API version. Use plugin declarations for compatibility checks. */
+    readonly pluginApiVersion: string;
     /**
      * Resolved plugin configuration values.
      *
-     * The host validates and persists settings, then injects the final values into
-     * this readonly map before invoking hooks or lifecycle methods. Use
+     * The host validates and persists settings, then supplies a detached snapshot
+     * before invoking hooks or lifecycle methods. Mutating nested values does not
+     * update persistence; call {@link PluginContextBase.updateConfig} instead. Use
      * {@link PluginHooks.onConfigChange} to react to updates.
      */
     readonly config: Readonly<Record<string, unknown>>;
@@ -50,6 +61,8 @@ export interface PluginContext {
          */
         readonly operator: KVStore;
     };
+    /** Read-only validation for exact FT8/FT4 message encoding. */
+    readonly digitalMessagePreflight: import('./helpers.js').DigitalMessagePreflight;
     /**
      * Structured logger scoped to the plugin.
      *
@@ -64,24 +77,12 @@ export interface PluginContext {
      * prefer this over raw `setInterval` calls inside plugin code.
      */
     readonly timers: PluginTimers;
+    /** Read-only snapshot and query surface for the current operator. */
+    readonly operator: OperatorSnapshot;
     /**
-     * Control surface for the current operator.
-     */
-    readonly operator: OperatorControl;
-    /**
-     * Access to the physical radio state and tuning controls.
+     * Read-only projection of the physical radio state.
      */
-    readonly radio: RadioControl;
-    /**
-     * Full logbook access — read-only queries, record writes and UI notifications.
-     *
-     * Provides the original read-only helpers (`hasWorked`, `hasWorkedDXCC`,
-     * `hasWorkedGrid`) plus advanced query (`queryQSOs`, `countQSOs`), write
-     * (`addQSO`, `updateQSO`) and notification (`notifyUpdated`) capabilities.
-     * Sync providers and other data-oriented plugins use the write methods to
-     * self-orchestrate their flow without host-side special handling.
-     */
-    readonly logbook: LogbookAccess;
+    readonly radio: RadioView;
     /**
      * Read-only access to current-band and slot decode data.
      */
@@ -100,41 +101,111 @@ export interface PluginContext {
      */
     readonly files: PluginFileStore;
     /**
-     * Logbook sync registration entry point.
-     *
-     * Utility plugins that implement logbook synchronization call
-     * `ctx.logbookSync.register(provider)` during `onLoad` to register their
-     * sync provider. The host manages the provider lifecycle and UI integration.
+     * Schedules optional initialization after the core server is ready.
+     * Registration is synchronous; the task is cancelled automatically when the
+     * plugin instance is unloaded.
      */
+    readonly lifecycle: PluginLifecyclePort;
+}
+type CapabilityProperty<Permissions extends readonly PluginPermission[], Permission extends PluginPermission, Property extends object> = number extends Permissions['length'] ? object : Permission extends Permissions[number] ? Property : object;
+type SettingsCapability<Permissions extends readonly PluginPermission[]> = number extends Permissions['length'] ? object : Extract<Permissions[number], `settings:${string}`> extends never ? object : {
+    readonly settings: CapabilityProperty<Permissions, 'settings:ft8', Pick<HostSettingsControl, 'ft8'>> & CapabilityProperty<Permissions, 'settings:decode-windows', Pick<HostSettingsControl, 'decodeWindows'>> & CapabilityProperty<Permissions, 'settings:realtime', Pick<HostSettingsControl, 'realtime'>> & CapabilityProperty<Permissions, 'settings:frequency-presets', Pick<HostSettingsControl, 'frequencyPresets'>> & CapabilityProperty<Permissions, 'settings:station', Pick<HostSettingsControl, 'station'>> & CapabilityProperty<Permissions, 'settings:psk-reporter', Pick<HostSettingsControl, 'pskReporter'>> & CapabilityProperty<Permissions, 'settings:ntp', Pick<HostSettingsControl, 'ntp'>>;
+};
+type MainLogbookCapability<Permissions extends readonly PluginPermission[]> = 'logbook:write' extends Permissions[number] ? LogbookAccess : 'logbook:read' extends Permissions[number] ? LogbookReadAccess : object;
+type SessionLogbookCapability<Permissions extends readonly PluginPermission[]> = 'logbook:session' extends Permissions[number] ? {
+    readonly sessions: PluginLogbookSessions;
+} : object;
+type LogbookCapability<Permissions extends readonly PluginPermission[]> = number extends Permissions['length'] ? object : Extract<Permissions[number], 'logbook:read' | 'logbook:write' | 'logbook:session'> extends never ? object : {
+    readonly logbook: MainLogbookCapability<Permissions> & SessionLogbookCapability<Permissions>;
+};
+/**
+ * Plugin context whose privileged ports are derived from literal manifest
+ * permissions. Capabilities that were not declared do not exist in the type.
+ *
+ * Host handles are invocation-scoped. In particular, a `Response` returned by
+ * `ctx.fetch` and its Headers/body reader must be consumed before the current
+ * Host callback settles; retaining the native handle for later use results in
+ * `PLUGIN_INVOCATION_EXPIRED`.
+ */
+export type PluginContextFor<Permissions extends readonly PluginPermission[]> = PluginContextBase & CapabilityProperty<Permissions, 'operator:transmit-control', {
+    readonly operatorCommands: OperatorCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:read', {
+    readonly radioCapabilities: RadioCapabilitiesView;
+    readonly radioPower: RadioPowerView;
+}> & CapabilityProperty<Permissions, 'radio:control', {
+    readonly radioCommands: RadioCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:tuner-control', {
+    readonly radioTunerCommands: RadioTunerCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:power', {
+    readonly radioPowerCommands: RadioPowerCommandPort;
+}> & LogbookCapability<Permissions> & CapabilityProperty<Permissions, 'logbook:sync', {
     readonly logbookSync: LogbookSyncRegistrar;
-    /**
-     * Permission-gated host settings control surface.
-     *
-     * Each namespace requires the matching `settings:*` manifest permission.
-     */
-    readonly settings: HostSettingsControl;
-    /**
-     * Permission-gated network capabilities.
-     *
-     * UDP sockets are host-managed and automatically closed when the plugin
-     * instance unloads. This is intentionally protocol-agnostic; protocol codecs
-     * such as WSJT-X UDP belong inside plugins.
-     */
-    readonly network?: PluginNetworkControl;
-    /**
-     * Host-owned runtime dependencies exposed to plugins.
-     *
-     * Native dependencies such as Hamlib are loaded by the host process. Each
-     * dependency is optional and requires its own manifest permission; feature
-     * detect before use.
-     */
-    readonly hostDependencies: HostDependencies;
-    /**
-     * Permission-gated HTTP client.
-     *
-     * This method is only available when the plugin declares the corresponding
-     * network permission. Treat it as optional and feature-detect before calling.
-     */
-    readonly fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+}> & SettingsCapability<Permissions> & CapabilityProperty<Permissions, 'network', {
+    readonly network: PluginNetworkControl;
+    readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}> & CapabilityProperty<Permissions, 'plugin:event-bus', {
+    readonly eventBus: PluginEventBus;
+}> & CapabilityProperty<Permissions, 'host:hamlib', {
+    readonly hostDependencies: HostDependencies & Required<Pick<HostDependencies, 'hamlib'>>;
+}>;
+/** Safe default context for code that has not declared literal permissions. */
+export type PluginContext = PluginContextFor<readonly []>;
+/**
+ * Teardown-only context passed to `onUnload`.
+ *
+ * Cleanup may inspect the read-only operator state, flush plugin-owned state
+ * and release plugin-owned files. The Host also permits previously acquired
+ * native-resource and UI handles to finish cleanup, but does not reopen radio,
+ * network, event-bus, logbook or command capabilities while the instance is
+ * being revoked.
+ */
+export type PluginCleanupContext = Pick<PluginContextBase, 'store' | 'log' | 'timers' | 'files' | 'operator' | 'lifecycle'>;
+/** Host-side erased runtime shape. Public plugin definitions should use `definePlugin()`. */
+export type RuntimePluginContext = PluginContextBase & Partial<{
+    operatorCommands: OperatorCommandPort;
+    radioCapabilities: RadioCapabilitiesView;
+    radioCommands: RadioCommandPort;
+    radioTunerCommands: RadioTunerCommandPort;
+    radioPower: RadioPowerView;
+    radioPowerCommands: RadioPowerCommandPort;
+    logbook: LogbookReadAccess | LogbookAccess | {
+        readonly sessions: PluginLogbookSessions;
+    };
+    logbookSync: LogbookSyncRegistrar;
+    settings: Partial<HostSettingsControl>;
+    network: PluginNetworkControl;
+    eventBus: PluginEventBus;
+    hostDependencies: HostDependencies;
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}>;
+/**
+ * Deliberately narrow context captured by a speculative strategy runtime.
+ * Decisions can inspect operator state and emit a result, but cannot retain a
+ * command, radio, logbook-write, network, timer or UI capability.
+ */
+export interface StrategyPluginContext {
+    /** Bundled Plugin API version available before the strategy runtime is created. */
+    readonly pluginApiVersion: string;
+    /** Detached snapshot of the strategy plugin's resolved configuration. */
+    readonly config: Readonly<Record<string, unknown>>;
+    /** Logger scoped to this strategy instance. */
+    readonly log: PluginLogger;
+    /** Read-only operator snapshot; mutation ports are deliberately absent. */
+    readonly operator: OperatorSnapshot;
+    /** Read-only projection of the current radio band and operating mode. */
+    readonly radio: RadioView;
+    /** Live, read-only views of the storage scopes declared by this plugin. */
+    readonly store: {
+        readonly global: ReadonlyKVStore;
+        readonly operator: ReadonlyKVStore;
+    };
+    /** Read-only exact-message encoding validation. */
+    readonly digitalMessagePreflight: import('./helpers.js').DigitalMessagePreflight;
+}
+/** Minimal context used to evaluate a transmit-control eligibility predicate. */
+export interface PluginEligibilityContext {
+    /** Current detached configuration snapshot used by the synchronous gate. */
+    readonly config: Readonly<Record<string, unknown>>;
 }
+export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnD;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;WAEG;QACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAE3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAEvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAExC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/definition.d.ts

@@ -1,7 +1,8 @@
 import type { PluginSettingDescriptor, PluginQuickAction, PluginQuickSetting, PluginPanelDescriptor, PluginPermission, PluginType, PluginInstanceScope, PluginUIPageDescriptor } from '@tx5dr/contracts';
-import type { PluginContext } from './context.js';
+import type { PluginCleanupContext, PluginContextFor, PluginEligibilityContext, StrategyPluginContext } from './context.js';
 import type { PluginHooks } from './hooks.js';
 import type { StrategyRuntime } from './runtime.js';
+import type { SimulationScenarioDescriptor } from './simulation.js';
 /**
  * Describes a TX-5DR plugin module.
  *
@@ -21,32 +22,43 @@ import type { StrategyRuntime } from './runtime.js';
  *
  * @example
  * ```js
- * /** @type {import('@tx5dr/plugin-api').PluginDefinition} *\/
- * export default {
+ * import { definePlugin } from '@tx5dr/plugin-api';
+ *
+ * export default definePlugin({
+ *   apiVersion: 2,
  *   name: 'my-plugin',
  *   version: '1.0.0',
  *   type: 'utility',
  *   description: 'Annotates interesting decoded stations.',
+ *   permissions: [],
  *   hooks: {
  *     onDecode(messages, ctx) {
  *       ctx.log.info('decoded', { count: messages.length });
  *     },
  *   },
- * };
+ * });
  * ```
  *
  * @example
  * ```ts
- * import type { PluginDefinition } from '@tx5dr/plugin-api';
+ * import { definePlugin } from '@tx5dr/plugin-api';
  *
- * const plugin: PluginDefinition = {
+ * export default definePlugin({
+ *   apiVersion: 2,
  *   name: 'my-strategy',
  *   version: '1.0.0',
  *   type: 'strategy',
- *   createStrategyRuntime(ctx) {
+ *   createStrategyRuntime() {
  *     return {
+ *       checkpoint() {
+ *         return {};
+ *       },
+ *       restore() {},
  *       decide() {
- *         return { stop: false };
+ *         return {
+ *           transmission: null,
+ *           snapshot: this.getSnapshot(),
+ *         };
  *       },
  *       getTransmitText() {
  *         return null;
@@ -61,12 +73,18 @@ import type { StrategyRuntime } from './runtime.js';
  *       reset() {},
  *     };
  *   },
- * };
- *
- * export default plugin;
+ * });
  * ```
  */
-export interface PluginDefinition {
+export interface PluginDefinition<Permissions extends readonly PluginPermission[] = readonly []> {
+    /**
+     * Public API contract version. All new plugins should use `2`.
+     *
+     * API v2 is required for strategy plugins and for utility plugins that request
+     * any mutation capability: `operator:transmit-control`, `radio:control`,
+     * `radio:tuner-control`, `radio:power`, `logbook:write` or `logbook:sync`.
+     */
+    apiVersion?: 2;
     /**
      * Stable machine-readable plugin identifier.
      *
@@ -82,6 +100,13 @@ export interface PluginDefinition {
      * valid semver string makes diagnostics and upgrades much easier.
      */
     version: string;
+    /**
+     * Oldest bundled `@tx5dr/plugin-api` version that can safely load this plugin.
+     *
+     * This is independent from the TX-5DR product/nightly version. Marketplace
+     * artifacts must declare it and match their catalog entry.
+     */
+    minPluginApiVersion?: string;
     /**
      * Declares how the host should schedule and combine this plugin.
      *
@@ -91,11 +116,31 @@ export interface PluginDefinition {
      *   do not own the core automation state machine.
      */
     type: PluginType;
+    /** Optional strategy capabilities advertised to Host UI and routing. */
+    strategyFeatures?: {
+        /** Declares the `QueuedStrategyRuntime` assisted-target queue contract. */
+        targetQueue?: 1;
+        /** Declares support for more than one active target lane. */
+        parallelTargetQueue?: 1;
+        /** Controls whether enqueueing may start a stopped operator. */
+        queueActivation?: 'immediate' | 'operator-toggle';
+        /** Blocks unscoped plugin commands; the strategy may consume its own audited operator authorization. */
+        manualInitiation?: 1;
+        /** Strategy-specific cap applied in addition to the operator cap. */
+        maxConcurrentStreams?: number;
+        /** Maximum signals that may be emitted in one physical frame. */
+        maxSimultaneousSignals?: number;
+    };
+    /** Development-only virtual-radio peer scenarios. The Host owns execution and RF safety. */
+    simulationScenarios?: SimulationScenarioDescriptor[];
     /**
      * Controls whether the host creates one instance per operator or a single
      * shared instance for the whole station.
      *
      * Defaults to `operator` when omitted.
+     * Global scope is utility-only. It cannot use operator-scoped settings or
+     * quick settings, and only global-compatible hooks/panels are accepted by the
+     * loader. Use it for station-wide sync, network services and radio policy.
      */
     instanceScope?: PluginInstanceScope;
     /**
@@ -111,7 +156,7 @@ export interface PluginDefinition {
      * Permissions allow the host to gate sensitive features such as network
      * access. Always declare the smallest set that the plugin truly needs.
      */
-    permissions?: PluginPermission[];
+    permissions?: Permissions;
     /**
      * Declarative settings schema for generated configuration forms.
      *
@@ -149,12 +194,16 @@ export interface PluginDefinition {
      *
      * Each panel has a `slot` that controls where it renders: `'operator'` (the
      * default, shown in the operator card), `'automation'` (shown in the
-     * top-right automation popover), `'main-right'` (the optional far-right main
+     * top-right automation popover), `'operator-action'` (an icon-and-text page
+     * action beside the operator logbook button), `'main-right'` (the optional far-right main
      * pane), `'voice-left-top'` (above the voice frequency card),
      * `'voice-right-top'` (the tabbed top area of the voice right panel),
      * `'cw-left-top'` (above the CW frequency card),
      * `'cw-right-top'` (the tabbed top area of the CW right panel), or
      * `'radio-control-toolbar'` (a global utility iframe button in RadioControl).
+     * An `operator-action` panel must use `component: 'iframe'` and
+     * `openMode: 'page'`; the Host binds it to that operator and opens the
+     * referenced custom UI as a standalone page.
      * Panels may also declare a preferred `width`, such as `'full'`, so hosts can
      * promote more important live panels.
      */
@@ -195,15 +244,15 @@ export interface PluginDefinition {
      * should be omitted for utility plugins. The returned runtime becomes the
      * operator's active automation controller.
      */
-    createStrategyRuntime?(ctx: PluginContext): StrategyRuntime;
+    createStrategyRuntime?(ctx: StrategyPluginContext): StrategyRuntime;
     /**
      * Runs after the plugin instance has been loaded and the context is ready.
      *
-     * Use this for startup work such as warming caches, scheduling timers or
-     * sending initial panel data. Keep it fast; long-running work should be
-     * deferred or done asynchronously.
+     * Use this for startup work such as warming caches, scheduling Host timers or
+     * sending initial panel data. Await required asynchronous work before returning;
+     * do not detach continuations that retain Host capabilities after the callback.
      */
-    onLoad?(ctx: PluginContext): void | Promise<void>;
+    onLoad?(ctx: PluginContextFor<Permissions>): void | Promise<void>;
     /**
      * Runs before the plugin instance is unloaded.
      *
@@ -211,13 +260,41 @@ export interface PluginDefinition {
      * handled through the host abstractions. Any timers created via
      * {@link PluginContext.timers} are cleared automatically by the host.
      */
-    onUnload?(ctx: PluginContext): void | Promise<void>;
+    onUnload?(ctx: PluginCleanupContext): void | Promise<void>;
     /**
      * Event and pipeline hooks implemented by the plugin.
      *
      * Hooks let utility plugins observe or transform the message flow, and let the
      * active strategy participate in decision making.
      */
-    hooks?: PluginHooks;
+    hooks?: PluginHooks<Permissions>;
+    /**
+     * Safety gate for the operator command port.
+     *
+     * Plugins that declare `operator:transmit-control` must implement this or
+     * {@link isAutoCallEnabled}. The host evaluates it immediately before each
+     * command so disabled remote-control or integration features cannot retain
+     * command authority.
+     */
+    isTransmitControlEnabled?(ctx: PluginEligibilityContext): boolean;
+    /**
+     * Marks an operator-scoped plugin as an automatic calling controller and
+     * reports whether that behavior is currently enabled.
+     *
+     * The host uses this declaration for the auto-call indicator and pause UI.
+     * It also acts as the command-port safety gate when
+     * {@link isTransmitControlEnabled} is omitted. Integrations that can submit
+     * occasional external commands but are not auto-call controllers should
+     * implement only {@link isTransmitControlEnabled}.
+     */
+    isAutoCallEnabled?(ctx: PluginEligibilityContext): boolean;
 }
+/** Type-erased plugin definition used by the host after module loading. */
+export type AnyPluginDefinition = PluginDefinition<any>;
+/**
+ * Defines a plugin while preserving literal permissions for capability-aware
+ * callback context inference. New plugins should use this helper instead of
+ * widening their definition to `PluginDefinition`.
+ */
+export declare function definePlugin<const Permissions extends readonly PluginPermission[] = readonly []>(definition: PluginDefinition<Permissions>): PluginDefinition<Permissions>;
 //# sourceMappingURL=definition.d.ts.map

package/dist/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAA;KAAE,CAAC;IAEhD;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,EAAE;QACH,yEAAyE;QACzE,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,kCAAkC;QAClC,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;KAClC,CAAC;IAEF;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAAC;IAE5D;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"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"}

package/dist/definition.js

@@ -1,2 +1,9 @@
-export {};
+/**
+ * Defines a plugin while preserving literal permissions for capability-aware
+ * callback context inference. New plugins should use this helper instead of
+ * widening their definition to `PluginDefinition`.
+ */
+export function definePlugin(definition) {
+    return definition;
+}
 //# sourceMappingURL=definition.js.map

package/dist/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":""}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AA8UA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAE1B,UAAyC;IACzC,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/ft8/StandardQSOPluginRuntime.d.ts

@@ -0,0 +1,142 @@
+import type { PluginLogger } from '../helpers.js';
+import type { QSOContext, ParsedFT8Message, QSORecord, FrameMessage, SlotInfo, OperatorSlots, OperatorConfig } from '@tx5dr/contracts';
+import type { StrategyRuntime, StrategyRuntimeCheckpoint, StrategyRuntimeContext, StrategyRuntimeSlot, StrategyRuntimeSnapshot, StrategyRuntimeSlotContentUpdate } from '../runtime.js';
+import type { StrategyDecision, QSOFailureInfo } from '../hooks.js';
+import type { StrategyDecisionMetaV2, StrategyDecisionResult } from '../runtime.js';
+export declare const STANDARD_QSO_TX6_MESSAGE_OVERRIDE_SETTING = "tx6MessageOverride";
+export type StandardQSOOperatorConfig = OperatorConfig & {
+    autoReplyToDirectCallWhenStopped?: boolean;
+    skipTx1?: boolean;
+    distinguishWorkedStationsByBand?: boolean;
+    tx6MessageOverride?: string;
+};
+export declare function normalizeStandardQSOTx6MessageOverride(content: unknown, defaultMessage: string): string;
+export declare function buildStandardQSODefaultTx6Message(config: Pick<OperatorConfig, 'myCallsign' | 'myGrid'>): string;
+type SlotsIndex = 'TX1' | 'TX2' | 'TX3' | 'TX4' | 'TX5' | 'TX6';
+type Slots = {
+    [key in SlotsIndex]: string;
+};
+export interface StandardQSOPluginOperator {
+    readonly config: StandardQSOOperatorConfig;
+    hasWorkedCallsign(callsign: string, options?: {
+        anyBand?: boolean;
+    }): Promise<boolean>;
+    isTargetBeingWorkedByOthers(targetCallsign: string): boolean;
+    notifySlotsUpdated?(slots: OperatorSlots): void;
+    notifyStateChanged?(state: string): void;
+}
+export interface StandardQSOActivationRequest {
+    callsign: string;
+    lastMessage?: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    };
+}
+export interface StandardQSOActivationResult {
+    accepted: boolean;
+    lifecycleEpoch: number;
+    initialSlot?: StrategyRuntimeSlot;
+}
+interface Post73RetryContext {
+    targetCallsign: string;
+    targetGrid?: string;
+    reportSent?: number;
+    reportReceived?: number;
+    actualFrequency?: number;
+    completedQSO?: QSORecord;
+    expiresAt: number;
+}
+export declare class StandardQSOPluginRuntime implements StrategyRuntime {
+    readonly operator: StandardQSOPluginOperator;
+    private state;
+    private slots;
+    private _context;
+    private tx6MessageOverride;
+    private lastConfigTx6MessageOverride;
+    private timeoutCycles;
+    callAttempts: number;
+    qsoStartTime?: number;
+    tx5TransmissionQueued: boolean;
+    private completedQSORecord?;
+    private pendingQSOCompletion?;
+    private qsoLifecycleEpoch;
+    private speculativeDecisionDepth;
+    post73RetryContext?: Post73RetryContext;
+    private qsoContextHistory;
+    private readonly MAX_CONTEXT_CACHE;
+    foxHash?: string;
+    readonly logger: PluginLogger;
+    constructor(operator: StandardQSOPluginOperator, logger?: PluginLogger);
+    private syncOperatorConfig;
+    get context(): QSOContext;
+    buildNoReplyFailure(reason: string, unansweredTransmissions: number, targetCallsign?: string | undefined): QSOFailureInfo | undefined;
+    buildProtocolTimeoutFailure(stage: 'TX2' | 'TX3' | 'TX4'): QSOFailureInfo | undefined;
+    changeState(state: SlotsIndex): Promise<void>;
+    prepareCompletedQSOEffect(): void;
+    private beginQsoLifecycle;
+    hasUnsettledQSOCompletion(): boolean;
+    beginQsoWithTarget(callsign: string, reason: string): void;
+    settleQSOCompletion(settlement: import('@tx5dr/plugin-api').StrategyQSOCompletionSettlement): void;
+    handleReceivedAndDicideNext(messages: ParsedFT8Message[], options?: {
+        isReDecision?: boolean;
+    }): Promise<StrategyDecision>;
+    handleTransmitSlot(): string | null;
+    onTransmissionQueued(transmission: string): void;
+    getInitialOutboundCallState(): SlotsIndex;
+    activateTarget(request: StandardQSOActivationRequest): StandardQSOActivationResult;
+    requestCall(callsign: string, lastMessage: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    } | undefined): boolean;
+    private requestCallInternal;
+    checkpoint(): StrategyRuntimeCheckpoint;
+    restore(checkpoint: StrategyRuntimeCheckpoint): void;
+    decide(messages: ParsedFT8Message[], meta: StrategyDecisionMetaV2): Promise<StrategyDecisionResult>;
+    getTransmitText(): string | null;
+    getIdleCQText(): string | null;
+    getSnapshot(): StrategyRuntimeSnapshot;
+    patchContext(patch: Partial<StrategyRuntimeContext>): void;
+    private canAcceptTargetCallsign;
+    setState(state: SlotsIndex): void;
+    setSlotContent(update: StrategyRuntimeSlotContentUpdate): void;
+    reset(reason?: string): void;
+    /**
+     * 获取当前所有时隙的内容
+     */
+    getSlots(): Slots;
+    /**
+     * 获取当前状态
+     */
+    getCurrentState(): SlotsIndex;
+    private updateTargetSlotsForSpecialCallsign;
+    updateSlots(): void;
+    /**
+     * 保存当前QSO上下文到历史缓存
+     */
+    private saveCurrentContext;
+    /**
+     * 从历史缓存恢复QSO上下文
+     */
+    restoreContext(targetCallsign: string): boolean;
+    armPost73RetryContext(): void;
+    clearPost73RetryContext(reason: string): void;
+    getActivePost73RetryContext(): Post73RetryContext | undefined;
+    restorePost73RetryContext(context: Post73RetryContext): void;
+    /**
+     * 清空QSO上下文
+     * 在QSO结束时调用，确保干净的下一次通联
+     */
+    clearQSOContext(): void;
+    resetRuntime(reason?: string): void;
+    private changeStateSafely;
+    /**
+     * 通知slots更新
+     */
+    private notifySlotsUpdated;
+    /**
+     * 通知状态变化
+     */
+    private notifyStateChanged;
+}
+export {};
+//# sourceMappingURL=StandardQSOPluginRuntime.d.ts.map

package/dist/ft8/StandardQSOPluginRuntime.d.ts.map

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