@noxsoft/anima 2.0.0

package/dist/plugin-sdk/cron/types.d.ts

@@ -0,0 +1,95 @@
+import type { ChannelId } from "../channels/plugins/types.js";
+export type CronSchedule = {
+    kind: "at";
+    at: string;
+} | {
+    kind: "every";
+    everyMs: number;
+    anchorMs?: number;
+} | {
+    kind: "cron";
+    expr: string;
+    tz?: string;
+};
+export type CronSessionTarget = "main" | "isolated";
+export type CronWakeMode = "next-heartbeat" | "now";
+export type CronMessageChannel = ChannelId | "last";
+export type CronDeliveryMode = "none" | "announce";
+export type CronDelivery = {
+    mode: CronDeliveryMode;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffort?: boolean;
+};
+export type CronDeliveryPatch = Partial<CronDelivery>;
+export type CronPayload = {
+    kind: "systemEvent";
+    text: string;
+} | {
+    kind: "agentTurn";
+    message: string;
+    /** Optional model override (provider/model or alias). */
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+    deliver?: boolean;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffortDeliver?: boolean;
+};
+export type CronPayloadPatch = {
+    kind: "systemEvent";
+    text?: string;
+} | {
+    kind: "agentTurn";
+    message?: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+    deliver?: boolean;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffortDeliver?: boolean;
+};
+export type CronJobState = {
+    nextRunAtMs?: number;
+    runningAtMs?: number;
+    lastRunAtMs?: number;
+    lastStatus?: "ok" | "error" | "skipped";
+    lastError?: string;
+    lastDurationMs?: number;
+    /** Number of consecutive execution errors (reset on success). Used for backoff. */
+    consecutiveErrors?: number;
+    /** Number of consecutive schedule computation errors. Auto-disables job after threshold. */
+    scheduleErrorCount?: number;
+};
+export type CronJob = {
+    id: string;
+    agentId?: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    deleteAfterRun?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: CronSchedule;
+    sessionTarget: CronSessionTarget;
+    wakeMode: CronWakeMode;
+    payload: CronPayload;
+    delivery?: CronDelivery;
+    state: CronJobState;
+};
+export type CronStoreFile = {
+    version: 1;
+    jobs: CronJob[];
+};
+export type CronJobCreate = Omit<CronJob, "id" | "createdAtMs" | "updatedAtMs" | "state"> & {
+    state?: Partial<CronJobState>;
+};
+export type CronJobPatch = Partial<Omit<CronJob, "id" | "createdAtMs" | "state" | "payload">> & {
+    payload?: CronPayloadPatch;
+    delivery?: CronDeliveryPatch;
+    state?: Partial<CronJobState>;
+};

package/dist/plugin-sdk/daemon/constants.d.ts

@@ -0,0 +1,30 @@
+export declare const GATEWAY_LAUNCH_AGENT_LABEL = "net.noxsoft.anima.gateway";
+export declare const GATEWAY_SYSTEMD_SERVICE_NAME = "anima-gateway";
+export declare const GATEWAY_WINDOWS_TASK_NAME = "Anima Gateway";
+export declare const GATEWAY_SERVICE_MARKER = "anima";
+export declare const GATEWAY_SERVICE_KIND = "gateway";
+export declare const NODE_LAUNCH_AGENT_LABEL = "net.noxsoft.anima.node";
+export declare const NODE_SYSTEMD_SERVICE_NAME = "anima-node";
+export declare const NODE_WINDOWS_TASK_NAME = "Anima Node";
+export declare const NODE_SERVICE_MARKER = "anima";
+export declare const NODE_SERVICE_KIND = "node";
+export declare const NODE_WINDOWS_TASK_SCRIPT_NAME = "node.cmd";
+export declare const LEGACY_GATEWAY_LAUNCH_AGENT_LABELS: string[];
+export declare const LEGACY_GATEWAY_SYSTEMD_SERVICE_NAMES: string[];
+export declare const LEGACY_GATEWAY_WINDOWS_TASK_NAMES: string[];
+export declare function normalizeGatewayProfile(profile?: string): string | null;
+export declare function resolveGatewayProfileSuffix(profile?: string): string;
+export declare function resolveGatewayLaunchAgentLabel(profile?: string): string;
+export declare function resolveLegacyGatewayLaunchAgentLabels(profile?: string): string[];
+export declare function resolveGatewaySystemdServiceName(profile?: string): string;
+export declare function resolveGatewayWindowsTaskName(profile?: string): string;
+export declare function formatGatewayServiceDescription(params?: {
+    profile?: string;
+    version?: string;
+}): string;
+export declare function resolveNodeLaunchAgentLabel(): string;
+export declare function resolveNodeSystemdServiceName(): string;
+export declare function resolveNodeWindowsTaskName(): string;
+export declare function formatNodeServiceDescription(params?: {
+    version?: string;
+}): string;

package/dist/plugin-sdk/discord/accounts.d.ts

@@ -0,0 +1,9 @@
+export type ResolvedDiscordAccount = {
+    accountId: string;
+    name?: string;
+    config: Record<string, any>;
+};
+export declare function resolveDiscordAccount(_p: any): ResolvedDiscordAccount;
+export declare function listDiscordAccountIds(_cfg: any): string[];
+export declare function resolveDefaultDiscordAccountId(_cfg: any): string;
+export declare function listEnabledDiscordAccounts(_cfg: any): any[];

package/dist/plugin-sdk/discord/audit.d.ts

@@ -0,0 +1,2 @@
+export declare function auditDiscordChannelPermissions(..._args: any[]): Promise<void>;
+export declare function collectDiscordAuditChannelIds(..._args: any[]): string[];

package/dist/plugin-sdk/discord/directory-live.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveDiscordDirectoryLivePeers(..._args: any[]): Promise<never[]>;
+export declare function resolveDiscordDirectoryLiveGroups(..._args: any[]): Promise<never[]>;
+export declare function listDiscordDirectoryGroupsLive(..._args: any[]): Promise<never[]>;
+export declare function listDiscordDirectoryPeersLive(..._args: any[]): Promise<never[]>;

package/dist/plugin-sdk/discord/monitor/allow-list.d.ts

@@ -0,0 +1 @@
+export declare function normalizeDiscordSlug(slug: string): string;

package/dist/plugin-sdk/discord/monitor/gateway-registry.d.ts

@@ -0,0 +1,3 @@
+export declare function getGateway(..._args: any[]): any;
+export declare function registerGateway(..._args: any[]): void;
+export declare function clearGateways(): void;

package/dist/plugin-sdk/discord/monitor/presence-cache.d.ts

@@ -0,0 +1 @@
+export declare function getPresence(..._args: any[]): any;

package/dist/plugin-sdk/discord/monitor.d.ts

@@ -0,0 +1,3 @@
+export declare function monitorDiscordProvider(..._args: any[]): {
+    stop: () => void;
+};

package/dist/plugin-sdk/discord/pluralkit.d.ts

@@ -0,0 +1 @@
+export type DiscordPluralKitConfig = Record<string, unknown>;

package/dist/plugin-sdk/discord/probe.d.ts

@@ -0,0 +1,3 @@
+export declare function probeDiscord(..._args: any[]): Promise<{
+    ok: boolean;
+}>;

package/dist/plugin-sdk/discord/resolve-channels.d.ts

@@ -0,0 +1 @@
+export declare function resolveDiscordChannelAllowlist(..._args: any[]): any[];

package/dist/plugin-sdk/discord/resolve-users.d.ts

@@ -0,0 +1 @@
+export declare function resolveDiscordUserAllowlist(..._args: any[]): any[];

package/dist/plugin-sdk/discord/send.d.ts

@@ -0,0 +1,6 @@
+export declare function sendMessageDiscord(..._args: any[]): Promise<any>;
+export declare function sendPollDiscord(..._args: any[]): Promise<any>;
+export declare function fetchChannelPermissionsDiscord(..._args: any[]): Promise<any>;
+export declare function banMemberDiscord(..._args: any[]): Promise<void>;
+export declare function kickMemberDiscord(..._args: any[]): Promise<void>;
+export declare function timeoutMemberDiscord(..._args: any[]): Promise<void>;

package/dist/plugin-sdk/discord/targets.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDiscordTarget(target: string): any;
+export declare function resolveDiscordChannelId(..._args: any[]): string | undefined;

package/dist/plugin-sdk/gateway/auth-rate-limit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * In-memory sliding-window rate limiter for gateway authentication attempts.
+ *
+ * Tracks failed auth attempts by {scope, clientIp}. A scope lets callers keep
+ * independent counters for different credential classes (for example, shared
+ * gateway token/password vs device-token auth) while still sharing one
+ * limiter instance.
+ *
+ * Design decisions:
+ * - Pure in-memory Map – no external dependencies; suitable for a single
+ *   gateway process.  The Map is periodically pruned to avoid unbounded
+ *   growth.
+ * - Loopback addresses (127.0.0.1 / ::1) are exempt by default so that local
+ *   CLI sessions are never locked out.
+ * - The module is side-effect-free: callers create an instance via
+ *   {@link createAuthRateLimiter} and pass it where needed.
+ */
+export interface RateLimitConfig {
+    /** Maximum failed attempts before blocking.  @default 10 */
+    maxAttempts?: number;
+    /** Sliding window duration in milliseconds.     @default 60_000 (1 min) */
+    windowMs?: number;
+    /** Lockout duration in milliseconds after the limit is exceeded.  @default 300_000 (5 min) */
+    lockoutMs?: number;
+    /** Exempt loopback (localhost) addresses from rate limiting.  @default true */
+    exemptLoopback?: boolean;
+}
+export declare const AUTH_RATE_LIMIT_SCOPE_DEFAULT = "default";
+export declare const AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET = "shared-secret";
+export declare const AUTH_RATE_LIMIT_SCOPE_DEVICE_TOKEN = "device-token";
+export interface RateLimitEntry {
+    /** Timestamps (epoch ms) of recent failed attempts inside the window. */
+    attempts: number[];
+    /** If set, requests from this IP are blocked until this epoch-ms instant. */
+    lockedUntil?: number;
+}
+export interface RateLimitCheckResult {
+    /** Whether the request is allowed to proceed. */
+    allowed: boolean;
+    /** Number of remaining attempts before the limit is reached. */
+    remaining: number;
+    /** Milliseconds until the lockout expires (0 when not locked). */
+    retryAfterMs: number;
+}
+export interface AuthRateLimiter {
+    /** Check whether `ip` is currently allowed to attempt authentication. */
+    check(ip: string | undefined, scope?: string): RateLimitCheckResult;
+    /** Record a failed authentication attempt for `ip`. */
+    recordFailure(ip: string | undefined, scope?: string): void;
+    /** Reset the rate-limit state for `ip` (e.g. after a successful login). */
+    reset(ip: string | undefined, scope?: string): void;
+    /** Return the current number of tracked IPs (useful for diagnostics). */
+    size(): number;
+    /** Remove expired entries and release memory. */
+    prune(): void;
+    /** Dispose the limiter and cancel periodic cleanup timers. */
+    dispose(): void;
+}
+export declare function createAuthRateLimiter(config?: RateLimitConfig): AuthRateLimiter;

package/dist/plugin-sdk/gateway/auth.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage } from "node:http";
+import type { GatewayAuthConfig, GatewayTailscaleMode, GatewayTrustedProxyConfig } from "../config/config.js";
+import { type TailscaleWhoisIdentity } from "../infra/tailscale.js";
+import { type AuthRateLimiter } from "./auth-rate-limit.js";
+export type ResolvedGatewayAuthMode = "none" | "token" | "password" | "trusted-proxy";
+export type ResolvedGatewayAuth = {
+    mode: ResolvedGatewayAuthMode;
+    token?: string;
+    password?: string;
+    allowTailscale: boolean;
+    trustedProxy?: GatewayTrustedProxyConfig;
+};
+export type GatewayAuthResult = {
+    ok: boolean;
+    method?: "none" | "token" | "password" | "tailscale" | "device-token" | "trusted-proxy";
+    user?: string;
+    reason?: string;
+    /** Present when the request was blocked by the rate limiter. */
+    rateLimited?: boolean;
+    /** Milliseconds the client should wait before retrying (when rate-limited). */
+    retryAfterMs?: number;
+};
+type ConnectAuth = {
+    token?: string;
+    password?: string;
+};
+type TailscaleWhoisLookup = (ip: string) => Promise<TailscaleWhoisIdentity | null>;
+export declare function isLocalDirectRequest(req?: IncomingMessage, trustedProxies?: string[]): boolean;
+export declare function resolveGatewayAuth(params: {
+    authConfig?: GatewayAuthConfig | null;
+    env?: NodeJS.ProcessEnv;
+    tailscaleMode?: GatewayTailscaleMode;
+}): ResolvedGatewayAuth;
+export declare function assertGatewayAuthConfigured(auth: ResolvedGatewayAuth): void;
+export declare function authorizeGatewayConnect(params: {
+    auth: ResolvedGatewayAuth;
+    connectAuth?: ConnectAuth | null;
+    req?: IncomingMessage;
+    trustedProxies?: string[];
+    tailscaleWhois?: TailscaleWhoisLookup;
+    /** Optional rate limiter instance; when provided, failed attempts are tracked per IP. */
+    rateLimiter?: AuthRateLimiter;
+    /** Client IP used for rate-limit tracking. Falls back to proxy-aware request IP resolution. */
+    clientIp?: string;
+    /** Optional limiter scope; defaults to shared-secret auth scope. */
+    rateLimitScope?: string;
+}): Promise<GatewayAuthResult>;
+export {};

package/dist/plugin-sdk/gateway/call.d.ts

@@ -0,0 +1,51 @@
+import type { AnimaConfig } from "../config/config.js";
+import { type GatewayClientMode, type GatewayClientName } from "../utils/message-channel.js";
+export type CallGatewayOptions = {
+    url?: string;
+    token?: string;
+    password?: string;
+    tlsFingerprint?: string;
+    config?: AnimaConfig;
+    method: string;
+    params?: unknown;
+    expectFinal?: boolean;
+    timeoutMs?: number;
+    clientName?: GatewayClientName;
+    clientDisplayName?: string;
+    clientVersion?: string;
+    platform?: string;
+    mode?: GatewayClientMode;
+    instanceId?: string;
+    minProtocol?: number;
+    maxProtocol?: number;
+    /**
+     * Overrides the config path shown in connection error details.
+     * Does not affect config loading; callers still control auth via opts.token/password/env/config.
+     */
+    configPath?: string;
+};
+export type GatewayConnectionDetails = {
+    url: string;
+    urlSource: string;
+    bindDetail?: string;
+    remoteFallbackNote?: string;
+    message: string;
+};
+export type ExplicitGatewayAuth = {
+    token?: string;
+    password?: string;
+};
+export declare function resolveExplicitGatewayAuth(opts?: ExplicitGatewayAuth): ExplicitGatewayAuth;
+export declare function ensureExplicitGatewayAuth(params: {
+    urlOverride?: string;
+    auth: ExplicitGatewayAuth;
+    errorHint: string;
+    configPath?: string;
+}): void;
+export declare function buildGatewayConnectionDetails(options?: {
+    config?: AnimaConfig;
+    url?: string;
+    configPath?: string;
+}): GatewayConnectionDetails;
+export declare function callGateway<T = Record<string, unknown>>(opts: CallGatewayOptions): Promise<T>;
+export declare function randomIdempotencyKey(): `${string}-${string}-${string}-${string}-${string}`;

package/dist/plugin-sdk/gateway/chat-abort.d.ts

@@ -0,0 +1,44 @@
+export type ChatAbortControllerEntry = {
+    controller: AbortController;
+    sessionId: string;
+    sessionKey: string;
+    startedAtMs: number;
+    expiresAtMs: number;
+};
+export declare function isChatStopCommandText(text: string): boolean;
+export declare function resolveChatRunExpiresAtMs(params: {
+    now: number;
+    timeoutMs: number;
+    graceMs?: number;
+    minMs?: number;
+    maxMs?: number;
+}): number;
+export type ChatAbortOps = {
+    chatAbortControllers: Map<string, ChatAbortControllerEntry>;
+    chatRunBuffers: Map<string, string>;
+    chatDeltaSentAt: Map<string, number>;
+    chatAbortedRuns: Map<string, number>;
+    removeChatRun: (sessionId: string, clientRunId: string, sessionKey?: string) => {
+        sessionKey: string;
+        clientRunId: string;
+    } | undefined;
+    agentRunSeq: Map<string, number>;
+    broadcast: (event: string, payload: unknown, opts?: {
+        dropIfSlow?: boolean;
+    }) => void;
+    nodeSendToSession: (sessionKey: string, event: string, payload: unknown) => void;
+};
+export declare function abortChatRunById(ops: ChatAbortOps, params: {
+    runId: string;
+    sessionKey: string;
+    stopReason?: string;
+}): {
+    aborted: boolean;
+};
+export declare function abortChatRunsForSessionKey(ops: ChatAbortOps, params: {
+    sessionKey: string;
+    stopReason?: string;
+}): {
+    aborted: boolean;
+    runIds: string[];
+};

package/dist/plugin-sdk/gateway/chat-sanitize.d.ts

@@ -0,0 +1,4 @@
+import { stripEnvelope } from "../shared/chat-envelope.js";
+export { stripEnvelope };
+export declare function stripEnvelopeFromMessage(message: unknown): unknown;
+export declare function stripEnvelopeFromMessages(messages: unknown[]): unknown[];

package/dist/plugin-sdk/gateway/client.d.ts

@@ -0,0 +1,63 @@
+import type { DeviceIdentity } from "../infra/device-identity.js";
+import { type GatewayClientMode, type GatewayClientName } from "../utils/message-channel.js";
+import { type EventFrame, type HelloOk } from "./protocol/index.js";
+export type GatewayClientOptions = {
+    url?: string;
+    connectDelayMs?: number;
+    tickWatchMinIntervalMs?: number;
+    token?: string;
+    password?: string;
+    instanceId?: string;
+    clientName?: GatewayClientName;
+    clientDisplayName?: string;
+    clientVersion?: string;
+    platform?: string;
+    mode?: GatewayClientMode;
+    role?: string;
+    scopes?: string[];
+    caps?: string[];
+    commands?: string[];
+    permissions?: Record<string, boolean>;
+    pathEnv?: string;
+    deviceIdentity?: DeviceIdentity;
+    minProtocol?: number;
+    maxProtocol?: number;
+    tlsFingerprint?: string;
+    onEvent?: (evt: EventFrame) => void;
+    onHelloOk?: (hello: HelloOk) => void;
+    onConnectError?: (err: Error) => void;
+    onClose?: (code: number, reason: string) => void;
+    onGap?: (info: {
+        expected: number;
+        received: number;
+    }) => void;
+};
+export declare const GATEWAY_CLOSE_CODE_HINTS: Readonly<Record<number, string>>;
+export declare function describeGatewayCloseCode(code: number): string | undefined;
+export declare class GatewayClient {
+    private ws;
+    private opts;
+    private pending;
+    private backoffMs;
+    private closed;
+    private lastSeq;
+    private connectNonce;
+    private connectSent;
+    private connectTimer;
+    private lastTick;
+    private tickIntervalMs;
+    private tickTimer;
+    constructor(opts: GatewayClientOptions);
+    start(): void;
+    stop(): void;
+    private sendConnect;
+    private handleMessage;
+    private queueConnect;
+    private scheduleReconnect;
+    private flushPendingErrors;
+    private startTickWatch;
+    private validateTlsFingerprint;
+    request<T = Record<string, unknown>>(method: string, params?: unknown, opts?: {
+        expectFinal?: boolean;
+    }): Promise<T>;
+}

package/dist/plugin-sdk/gateway/control-ui-shared.d.ts

@@ -0,0 +1,9 @@
+declare const CONTROL_UI_AVATAR_PREFIX = "/avatar";
+export declare function normalizeControlUiBasePath(basePath?: string): string;
+export declare function buildControlUiAvatarUrl(basePath: string, agentId: string): string;
+export declare function resolveAssistantAvatarUrl(params: {
+    avatar?: string | null;
+    agentId?: string | null;
+    basePath?: string;
+}): string | undefined;
+export { CONTROL_UI_AVATAR_PREFIX };

package/dist/plugin-sdk/gateway/device-auth.d.ts

@@ -0,0 +1,12 @@
+export type DeviceAuthPayloadParams = {
+    deviceId: string;
+    clientId: string;
+    clientMode: string;
+    role: string;
+    scopes: string[];
+    signedAtMs: number;
+    token?: string | null;
+    nonce?: string | null;
+    version?: "v1" | "v2";
+};
+export declare function buildDeviceAuthPayload(params: DeviceAuthPayloadParams): string;

package/dist/plugin-sdk/gateway/exec-approval-manager.d.ts

@@ -0,0 +1,44 @@
+import type { ExecApprovalDecision } from "../infra/exec-approvals.js";
+export type ExecApprovalRequestPayload = {
+    command: string;
+    cwd?: string | null;
+    host?: string | null;
+    security?: string | null;
+    ask?: string | null;
+    agentId?: string | null;
+    resolvedPath?: string | null;
+    sessionKey?: string | null;
+};
+export type ExecApprovalRecord = {
+    id: string;
+    request: ExecApprovalRequestPayload;
+    createdAtMs: number;
+    expiresAtMs: number;
+    requestedByConnId?: string | null;
+    requestedByDeviceId?: string | null;
+    requestedByClientId?: string | null;
+    resolvedAtMs?: number;
+    decision?: ExecApprovalDecision;
+    resolvedBy?: string | null;
+};
+export declare class ExecApprovalManager {
+    private pending;
+    create(request: ExecApprovalRequestPayload, timeoutMs: number, id?: string | null): ExecApprovalRecord;
+    /**
+     * Register an approval record and return a promise that resolves when the decision is made.
+     * This separates registration (synchronous) from waiting (async), allowing callers to
+     * confirm registration before the decision is made.
+     */
+    register(record: ExecApprovalRecord, timeoutMs: number): Promise<ExecApprovalDecision | null>;
+    /**
+     * @deprecated Use register() instead for explicit separation of registration and waiting.
+     */
+    waitForDecision(record: ExecApprovalRecord, timeoutMs: number): Promise<ExecApprovalDecision | null>;
+    resolve(recordId: string, decision: ExecApprovalDecision, resolvedBy?: string | null): boolean;
+    getSnapshot(recordId: string): ExecApprovalRecord | null;
+    /**
+     * Wait for decision on an already-registered approval.
+     * Returns the decision promise if the ID is pending, null otherwise.
+     */
+    awaitDecision(recordId: string): Promise<ExecApprovalDecision | null> | null;
+}

package/dist/plugin-sdk/gateway/net.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pick the primary non-internal IPv4 address (LAN IP).
+ * Prefers common interface names (en0, eth0) then falls back to any external IPv4.
+ */
+export declare function pickPrimaryLanIPv4(): string | undefined;
+export declare function isLoopbackAddress(ip: string | undefined): boolean;
+/**
+ * Returns true if the IP belongs to a private or loopback network range.
+ * Private ranges: RFC1918, link-local, ULA IPv6, and CGNAT (100.64/10), plus loopback.
+ */
+export declare function isPrivateOrLoopbackAddress(ip: string | undefined): boolean;
+export declare function parseForwardedForClientIp(forwardedFor?: string): string | undefined;
+export declare function isTrustedProxyAddress(ip: string | undefined, trustedProxies?: string[]): boolean;
+export declare function resolveGatewayClientIp(params: {
+    remoteAddr?: string;
+    forwardedFor?: string;
+    realIp?: string;
+    trustedProxies?: string[];
+}): string | undefined;
+export declare function isLocalGatewayAddress(ip: string | undefined): boolean;
+/**
+ * Resolves gateway bind host with fallback strategy.
+ *
+ * Modes:
+ * - loopback: 127.0.0.1 (rarely fails, but handled gracefully)
+ * - lan: always 0.0.0.0 (no fallback)
+ * - tailnet: Tailnet IPv4 if available, else loopback
+ * - auto: Loopback if available, else 0.0.0.0
+ * - custom: User-specified IP, fallback to 0.0.0.0 if unavailable
+ *
+ * @returns The bind address to use (never null)
+ */
+export declare function resolveGatewayBindHost(bind: import("../config/config.js").GatewayBindMode | undefined, customHost?: string): Promise<string>;
+/**
+ * Test if we can bind to a specific host address.
+ * Creates a temporary server, attempts to bind, then closes it.
+ *
+ * @param host - The host address to test
+ * @returns True if we can successfully bind to this address
+ */
+export declare function canBindToHost(host: string): Promise<boolean>;
+export declare function resolveGatewayListenHosts(bindHost: string, opts?: {
+    canBindToHost?: (host: string) => Promise<boolean>;
+}): Promise<string[]>;
+/**
+ * Validate if a string is a valid IPv4 address.
+ *
+ * @param host - The string to validate
+ * @returns True if valid IPv4 format
+ */
+export declare function isValidIPv4(host: string): boolean;
+/**
+ * Check if a hostname or IP refers to the local machine.
+ * Handles: localhost, 127.x.x.x, ::1, [::1], ::ffff:127.x.x.x
+ * Note: 0.0.0.0 and :: are NOT loopback - they bind to all interfaces.
+ */
+export declare function isLoopbackHost(host: string): boolean;

package/dist/plugin-sdk/gateway/node-registry.d.ts

@@ -0,0 +1,60 @@
+import type { GatewayWsClient } from "./server/ws-types.js";
+export type NodeSession = {
+    nodeId: string;
+    connId: string;
+    client: GatewayWsClient;
+    displayName?: string;
+    platform?: string;
+    version?: string;
+    coreVersion?: string;
+    uiVersion?: string;
+    deviceFamily?: string;
+    modelIdentifier?: string;
+    remoteIp?: string;
+    caps: string[];
+    commands: string[];
+    permissions?: Record<string, boolean>;
+    pathEnv?: string;
+    connectedAtMs: number;
+};
+export type NodeInvokeResult = {
+    ok: boolean;
+    payload?: unknown;
+    payloadJSON?: string | null;
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+};
+export declare class NodeRegistry {
+    private nodesById;
+    private nodesByConn;
+    private pendingInvokes;
+    register(client: GatewayWsClient, opts: {
+        remoteIp?: string | undefined;
+    }): NodeSession;
+    unregister(connId: string): string | null;
+    listConnected(): NodeSession[];
+    get(nodeId: string): NodeSession | undefined;
+    invoke(params: {
+        nodeId: string;
+        command: string;
+        params?: unknown;
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<NodeInvokeResult>;
+    handleInvokeResult(params: {
+        id: string;
+        nodeId: string;
+        ok: boolean;
+        payload?: unknown;
+        payloadJSON?: string | null;
+        error?: {
+            code?: string;
+            message?: string;
+        } | null;
+    }): boolean;
+    sendEvent(nodeId: string, event: string, payload?: unknown): boolean;
+    private sendEventInternal;
+    private sendEventToSession;
+}