remoteclaw 0.0.0 → 0.0.1

package/dist/plugin-sdk/line/webhook.d.ts

@@ -0,0 +1,19 @@
+import type { WebhookRequestBody } from "@line/bot-sdk";
+import type { Request, Response, NextFunction } from "express";
+import type { RuntimeEnv } from "../runtime.js";
+export interface LineWebhookOptions {
+    channelSecret: string;
+    onEvents: (body: WebhookRequestBody) => Promise<void>;
+    runtime?: RuntimeEnv;
+}
+export declare function createLineWebhookMiddleware(options: LineWebhookOptions): (req: Request, res: Response, _next: NextFunction) => Promise<void>;
+export interface StartLineWebhookOptions {
+    channelSecret: string;
+    onEvents: (body: WebhookRequestBody) => Promise<void>;
+    runtime?: RuntimeEnv;
+    path?: string;
+}
+export declare function startLineWebhook(options: StartLineWebhookOptions): {
+    path: string;
+    handler: (req: Request, res: Response, _next: NextFunction) => Promise<void>;
+};

package/dist/plugin-sdk/logger.d.ts

@@ -0,0 +1,6 @@
+import { type RuntimeEnv } from "./runtime.js";
+export declare function logInfo(message: string, runtime?: RuntimeEnv): void;
+export declare function logWarn(message: string, runtime?: RuntimeEnv): void;
+export declare function logSuccess(message: string, runtime?: RuntimeEnv): void;
+export declare function logError(message: string, runtime?: RuntimeEnv): void;
+export declare function logDebug(message: string): void;

package/dist/plugin-sdk/logging/config.d.ts

@@ -0,0 +1,4 @@
+import type { RemoteClawConfig } from "../config/types.js";
+type LoggingConfig = RemoteClawConfig["logging"];
+export declare function readLoggingConfig(): LoggingConfig | undefined;
+export {};

package/dist/plugin-sdk/logging/console.d.ts

@@ -0,0 +1,23 @@
+import type { RemoteClawConfig } from "../config/types.js";
+import { type LogLevel } from "./levels.js";
+export type ConsoleStyle = "pretty" | "compact" | "json";
+type ConsoleSettings = {
+    level: LogLevel;
+    style: ConsoleStyle;
+};
+export type ConsoleLoggerSettings = ConsoleSettings;
+type ConsoleConfigLoader = () => RemoteClawConfig["logging"] | undefined;
+export declare function setConsoleConfigLoaderForTests(loader?: ConsoleConfigLoader): void;
+export declare function getConsoleSettings(): ConsoleLoggerSettings;
+export declare function getResolvedConsoleSettings(): ConsoleLoggerSettings;
+export declare function routeLogsToStderr(): void;
+export declare function setConsoleSubsystemFilter(filters?: string[] | null): void;
+export declare function setConsoleTimestampPrefix(enabled: boolean): void;
+export declare function shouldLogSubsystemToConsole(subsystem: string): boolean;
+export declare function formatConsoleTimestamp(style: ConsoleStyle): string;
+/**
+ * Route console.* calls through file logging while still emitting to stdout/stderr.
+ * This keeps user-facing output unchanged but guarantees every console call is captured in log files.
+ */
+export declare function enableConsoleCapture(): void;
+export {};

package/dist/plugin-sdk/logging/diagnostic-session-state.d.ts

@@ -0,0 +1,30 @@
+export type SessionStateValue = "idle" | "processing" | "waiting";
+export type SessionState = {
+    sessionId?: string;
+    sessionKey?: string;
+    lastActivity: number;
+    state: SessionStateValue;
+    queueDepth: number;
+    toolCallHistory?: ToolCallRecord[];
+    toolLoopWarningBuckets?: Map<string, number>;
+    commandPollCounts?: Map<string, {
+        count: number;
+        lastPollAt: number;
+    }>;
+};
+export type ToolCallRecord = {
+    toolName: string;
+    argsHash: string;
+    toolCallId?: string;
+    resultHash?: string;
+    timestamp: number;
+};
+export type SessionRef = {
+    sessionId?: string;
+    sessionKey?: string;
+};
+export declare const diagnosticSessionStates: Map<string, SessionState>;
+export declare function pruneDiagnosticSessionStates(now?: number, force?: boolean): void;
+export declare function getDiagnosticSessionState(ref: SessionRef): SessionState;
+export declare function getDiagnosticSessionStateCountForTest(): number;
+export declare function resetDiagnosticSessionStateForTest(): void;

package/dist/plugin-sdk/logging/diagnostic.d.ts

@@ -0,0 +1,65 @@
+import { type SessionRef, type SessionStateValue } from "./diagnostic-session-state.js";
+declare const diag: import("./subsystem.js").SubsystemLogger;
+export declare function logWebhookReceived(params: {
+    channel: string;
+    updateType?: string;
+    chatId?: number | string;
+}): void;
+export declare function logWebhookProcessed(params: {
+    channel: string;
+    updateType?: string;
+    chatId?: number | string;
+    durationMs?: number;
+}): void;
+export declare function logWebhookError(params: {
+    channel: string;
+    updateType?: string;
+    chatId?: number | string;
+    error: string;
+}): void;
+export declare function logMessageQueued(params: {
+    sessionId?: string;
+    sessionKey?: string;
+    channel?: string;
+    source: string;
+}): void;
+export declare function logMessageProcessed(params: {
+    channel: string;
+    messageId?: number | string;
+    chatId?: number | string;
+    sessionId?: string;
+    sessionKey?: string;
+    durationMs?: number;
+    outcome: "completed" | "skipped" | "error";
+    reason?: string;
+    error?: string;
+}): void;
+export declare function logSessionStateChange(params: SessionRef & {
+    state: SessionStateValue;
+    reason?: string;
+}): void;
+export declare function logSessionStuck(params: SessionRef & {
+    state: SessionStateValue;
+    ageMs: number;
+}): void;
+export declare function logLaneEnqueue(lane: string, queueSize: number): void;
+export declare function logLaneDequeue(lane: string, waitMs: number, queueSize: number): void;
+export declare function logRunAttempt(params: SessionRef & {
+    runId: string;
+    attempt: number;
+}): void;
+export declare function logToolLoopAction(params: SessionRef & {
+    toolName: string;
+    level: "warning" | "critical";
+    action: "warn" | "block";
+    detector: "generic_repeat" | "known_poll_no_progress" | "global_circuit_breaker" | "ping_pong";
+    count: number;
+    message: string;
+    pairedToolName?: string;
+}): void;
+export declare function logActiveRuns(): void;
+export declare function startDiagnosticHeartbeat(): void;
+export declare function stopDiagnosticHeartbeat(): void;
+export declare function getDiagnosticSessionStateCountForTest(): number;
+export declare function resetDiagnosticStateForTest(): void;
+export { diag as diagnosticLogger };

package/dist/plugin-sdk/logging/env-log-level.d.ts

@@ -0,0 +1,2 @@
+import { type LogLevel } from "./levels.js";
+export declare function resolveEnvLogLevelOverride(): LogLevel | undefined;

package/dist/plugin-sdk/logging/levels.d.ts

@@ -0,0 +1,5 @@
+export declare const ALLOWED_LOG_LEVELS: readonly ["silent", "fatal", "error", "warn", "info", "debug", "trace"];
+export type LogLevel = (typeof ALLOWED_LOG_LEVELS)[number];
+export declare function tryParseLogLevel(level?: string): LogLevel | undefined;
+export declare function normalizeLogLevel(level?: string, fallback?: LogLevel): "error" | "silent" | "fatal" | "warn" | "info" | "debug" | "trace";
+export declare function levelToMinLevel(level: LogLevel): number;

package/dist/plugin-sdk/logging/logger.d.ts

@@ -0,0 +1,44 @@
+import { Logger as TsLogger } from "tslog";
+import type { ConsoleStyle } from "./console.js";
+import { type LogLevel } from "./levels.js";
+export declare const DEFAULT_LOG_DIR: string;
+export declare const DEFAULT_LOG_FILE: string;
+export type LoggerSettings = {
+    level?: LogLevel;
+    file?: string;
+    maxFileBytes?: number;
+    consoleLevel?: LogLevel;
+    consoleStyle?: ConsoleStyle;
+};
+type LogObj = {
+    date?: Date;
+} & Record<string, unknown>;
+type ResolvedSettings = {
+    level: LogLevel;
+    file: string;
+    maxFileBytes: number;
+};
+export type LoggerResolvedSettings = ResolvedSettings;
+export type LogTransportRecord = Record<string, unknown>;
+export type LogTransport = (logObj: LogTransportRecord) => void;
+export declare function isFileLogLevelEnabled(level: LogLevel): boolean;
+export declare function getLogger(): TsLogger<LogObj>;
+export declare function getChildLogger(bindings?: Record<string, unknown>, opts?: {
+    level?: LogLevel;
+}): TsLogger<LogObj>;
+export declare function toPinoLikeLogger(logger: TsLogger<LogObj>, level: LogLevel): PinoLikeLogger;
+export type PinoLikeLogger = {
+    level: string;
+    child: (bindings?: Record<string, unknown>) => PinoLikeLogger;
+    trace: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    fatal: (...args: unknown[]) => void;
+};
+export declare function getResolvedLoggerSettings(): LoggerResolvedSettings;
+export declare function setLoggerOverride(settings: LoggerSettings | null): void;
+export declare function resetLogger(): void;
+export declare function registerLogTransport(transport: LogTransport): () => void;
+export {};

package/dist/plugin-sdk/logging/node-require.d.ts

@@ -0,0 +1 @@
+export declare function resolveNodeRequireFromMeta(metaUrl: string): ((id: string) => NodeJS.Require) | null;

package/dist/plugin-sdk/logging/redact-identifier.d.ts

@@ -0,0 +1,4 @@
+export declare function sha256HexPrefix(value: string, len?: number): string;
+export declare function redactIdentifier(value: string | undefined, opts?: {
+    len?: number;
+}): string;

package/dist/plugin-sdk/logging/redact.d.ts

@@ -0,0 +1,9 @@
+export type RedactSensitiveMode = "off" | "tools";
+type RedactOptions = {
+    mode?: RedactSensitiveMode;
+    patterns?: string[];
+};
+export declare function redactSensitiveText(text: string, options?: RedactOptions): string;
+export declare function redactToolDetail(detail: string): string;
+export declare function getDefaultRedactPatterns(): string[];
+export {};

package/dist/plugin-sdk/logging/state.d.ts

@@ -0,0 +1,19 @@
+export declare const loggingState: {
+    cachedLogger: unknown;
+    cachedSettings: unknown;
+    cachedConsoleSettings: unknown;
+    overrideSettings: unknown;
+    invalidEnvLogLevelValue: string | null;
+    consolePatched: boolean;
+    forceConsoleToStderr: boolean;
+    consoleTimestampPrefix: boolean;
+    consoleSubsystemFilter: string[] | null;
+    resolvingConsoleSettings: boolean;
+    streamErrorHandlersInstalled: boolean;
+    rawConsole: {
+        log: typeof console.log;
+        info: typeof console.info;
+        warn: typeof console.warn;
+        error: typeof console.error;
+    } | null;
+};

package/dist/plugin-sdk/logging/subsystem.d.ts

@@ -0,0 +1,18 @@
+import { type RuntimeEnv } from "../runtime.js";
+import { type LogLevel } from "./levels.js";
+export type SubsystemLogger = {
+    subsystem: string;
+    isEnabled: (level: LogLevel, target?: "any" | "console" | "file") => boolean;
+    trace: (message: string, meta?: Record<string, unknown>) => void;
+    debug: (message: string, meta?: Record<string, unknown>) => void;
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+    fatal: (message: string, meta?: Record<string, unknown>) => void;
+    raw: (message: string) => void;
+    child: (name: string) => SubsystemLogger;
+};
+export declare function stripRedundantSubsystemPrefixForConsole(message: string, displaySubsystem: string): string;
+export declare function createSubsystemLogger(subsystem: string): SubsystemLogger;
+export declare function runtimeForLogger(logger: SubsystemLogger, exit?: RuntimeEnv["exit"]): RuntimeEnv;
+export declare function createSubsystemRuntime(subsystem: string, exit?: RuntimeEnv["exit"]): RuntimeEnv;

package/dist/plugin-sdk/logging/timestamps.d.ts

@@ -0,0 +1 @@
+export declare function formatLocalIsoWithOffset(now: Date): string;

package/dist/plugin-sdk/logging.d.ts

@@ -0,0 +1,10 @@
+import type { ConsoleLoggerSettings, ConsoleStyle } from "./logging/console.js";
+import { enableConsoleCapture, getConsoleSettings, getResolvedConsoleSettings, routeLogsToStderr, setConsoleSubsystemFilter, setConsoleConfigLoaderForTests, setConsoleTimestampPrefix, shouldLogSubsystemToConsole } from "./logging/console.js";
+import type { LogLevel } from "./logging/levels.js";
+import { ALLOWED_LOG_LEVELS, levelToMinLevel, normalizeLogLevel } from "./logging/levels.js";
+import type { LoggerResolvedSettings, LoggerSettings, PinoLikeLogger } from "./logging/logger.js";
+import { DEFAULT_LOG_DIR, DEFAULT_LOG_FILE, getChildLogger, getLogger, getResolvedLoggerSettings, isFileLogLevelEnabled, resetLogger, setLoggerOverride, toPinoLikeLogger } from "./logging/logger.js";
+import type { SubsystemLogger } from "./logging/subsystem.js";
+import { createSubsystemLogger, createSubsystemRuntime, runtimeForLogger, stripRedundantSubsystemPrefixForConsole } from "./logging/subsystem.js";
+export { enableConsoleCapture, getConsoleSettings, getResolvedConsoleSettings, routeLogsToStderr, setConsoleSubsystemFilter, setConsoleConfigLoaderForTests, setConsoleTimestampPrefix, shouldLogSubsystemToConsole, ALLOWED_LOG_LEVELS, levelToMinLevel, normalizeLogLevel, DEFAULT_LOG_DIR, DEFAULT_LOG_FILE, getChildLogger, getLogger, getResolvedLoggerSettings, isFileLogLevelEnabled, resetLogger, setLoggerOverride, toPinoLikeLogger, createSubsystemLogger, createSubsystemRuntime, runtimeForLogger, stripRedundantSubsystemPrefixForConsole, };
+export type { ConsoleLoggerSettings, ConsoleStyle, LogLevel, LoggerResolvedSettings, LoggerSettings, PinoLikeLogger, SubsystemLogger, };

package/dist/plugin-sdk/markdown/fences.d.ts

@@ -0,0 +1,10 @@
+export type FenceSpan = {
+    start: number;
+    end: number;
+    openLine: string;
+    marker: string;
+    indent: string;
+};
+export declare function parseFenceSpans(buffer: string): FenceSpan[];
+export declare function findFenceSpanAt(spans: FenceSpan[], index: number): FenceSpan | undefined;
+export declare function isSafeFenceBreak(spans: FenceSpan[], index: number): boolean;

package/dist/plugin-sdk/markdown/ir.d.ts

@@ -0,0 +1,32 @@
+import type { MarkdownTableMode } from "../config/types.base.js";
+export type MarkdownStyle = "bold" | "italic" | "strikethrough" | "code" | "code_block" | "spoiler" | "blockquote";
+export type MarkdownStyleSpan = {
+    start: number;
+    end: number;
+    style: MarkdownStyle;
+};
+export type MarkdownLinkSpan = {
+    start: number;
+    end: number;
+    href: string;
+};
+export type MarkdownIR = {
+    text: string;
+    styles: MarkdownStyleSpan[];
+    links: MarkdownLinkSpan[];
+};
+export type MarkdownParseOptions = {
+    linkify?: boolean;
+    enableSpoilers?: boolean;
+    headingStyle?: "none" | "bold";
+    blockquotePrefix?: string;
+    autolink?: boolean;
+    /** How to render tables (off|bullets|code). Default: off. */
+    tableMode?: MarkdownTableMode;
+};
+export declare function markdownToIR(markdown: string, options?: MarkdownParseOptions): MarkdownIR;
+export declare function markdownToIRWithMeta(markdown: string, options?: MarkdownParseOptions): {
+    ir: MarkdownIR;
+    hasTables: boolean;
+};
+export declare function chunkMarkdownIR(ir: MarkdownIR, limit: number): MarkdownIR[];

package/dist/plugin-sdk/markdown/render.d.ts

@@ -0,0 +1,18 @@
+import type { MarkdownIR, MarkdownLinkSpan, MarkdownStyle } from "./ir.js";
+export type RenderStyleMarker = {
+    open: string;
+    close: string;
+};
+export type RenderStyleMap = Partial<Record<MarkdownStyle, RenderStyleMarker>>;
+export type RenderLink = {
+    start: number;
+    end: number;
+    open: string;
+    close: string;
+};
+export type RenderOptions = {
+    styleMarkers: RenderStyleMap;
+    escapeText: (text: string) => string;
+    buildLink?: (link: MarkdownLinkSpan, text: string) => RenderLink | null;
+};
+export declare function renderMarkdownWithMarkers(ir: MarkdownIR, options: RenderOptions): string;

package/dist/plugin-sdk/markdown/tables.d.ts

@@ -0,0 +1,2 @@
+import type { MarkdownTableMode } from "../config/types.base.js";
+export declare function convertMarkdownTables(markdown: string, mode: MarkdownTableMode): string;

package/dist/plugin-sdk/markdown/whatsapp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert standard Markdown bold/italic/strikethrough to WhatsApp formatting.
+ *
+ * Order of operations matters:
+ * 1. Protect fenced code blocks (```...```) — already WhatsApp-compatible
+ * 2. Protect inline code (`...`) — leave as-is
+ * 3. Convert **bold** → *bold* and __bold__ → *bold*
+ * 4. Convert ~~strike~~ → ~strike~
+ * 5. Restore protected spans
+ *
+ * Italic *text* and _text_ are left alone since WhatsApp uses _text_ for italic
+ * and single * is already WhatsApp bold — no conversion needed for single markers.
+ */
+export declare function markdownToWhatsApp(text: string): string;

package/dist/plugin-sdk/media/audio-tags.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract audio mode tag from text.
+ * Supports [[audio_as_voice]] to send audio as voice bubble instead of file.
+ * Default is file (preserves backward compatibility).
+ */
+export declare function parseAudioTag(text?: string): {
+    text: string;
+    audioAsVoice: boolean;
+    hadTag: boolean;
+};

package/dist/plugin-sdk/media/audio.d.ts

@@ -0,0 +1,19 @@
+export declare const TELEGRAM_VOICE_AUDIO_EXTENSIONS: Set<string>;
+/**
+ * MIME types compatible with voice messages.
+ * Telegram sendVoice supports OGG/Opus, MP3, and M4A.
+ * https://core.telegram.org/bots/api#sendvoice
+ */
+export declare const TELEGRAM_VOICE_MIME_TYPES: Set<string>;
+export declare function isTelegramVoiceCompatibleAudio(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;
+/**
+ * Backward-compatible alias used across plugin/runtime call sites.
+ * Keeps existing behavior while making Telegram-specific policy explicit.
+ */
+export declare function isVoiceCompatibleAudio(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;

package/dist/plugin-sdk/media/base64.d.ts

@@ -0,0 +1,6 @@
+export declare function estimateBase64DecodedBytes(base64: string): number;
+/**
+ * Normalize and validate a base64 string.
+ * Returns canonical base64 (no whitespace) or undefined when invalid.
+ */
+export declare function canonicalizeBase64(base64: string): string | undefined;

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

@@ -0,0 +1,7 @@
+export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_AUDIO_BYTES: number;
+export declare const MAX_VIDEO_BYTES: number;
+export declare const MAX_DOCUMENT_BYTES: number;
+export type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+export declare function mediaKindFromMime(mime?: string | null): MediaKind;
+export declare function maxBytesForKind(kind: MediaKind): number;

package/dist/plugin-sdk/media/fetch.d.ts

@@ -0,0 +1,23 @@
+import type { LookupFn, SsrFPolicy } from "../infra/net/ssrf.js";
+type FetchMediaResult = {
+    buffer: Buffer;
+    contentType?: string;
+    fileName?: string;
+};
+export type MediaFetchErrorCode = "max_bytes" | "http_error" | "fetch_failed";
+export declare class MediaFetchError extends Error {
+    readonly code: MediaFetchErrorCode;
+    constructor(code: MediaFetchErrorCode, message: string);
+}
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type FetchMediaOptions = {
+    url: string;
+    fetchImpl?: FetchLike;
+    filePathHint?: string;
+    maxBytes?: number;
+    maxRedirects?: number;
+    ssrfPolicy?: SsrFPolicy;
+    lookupFn?: LookupFn;
+};
+export declare function fetchRemoteMedia(options: FetchMediaOptions): Promise<FetchMediaResult>;
+export {};

package/dist/plugin-sdk/media/image-ops.d.ts

@@ -0,0 +1,41 @@
+export type ImageMetadata = {
+    width: number;
+    height: number;
+};
+export declare const IMAGE_REDUCE_QUALITY_STEPS: readonly [85, 75, 65, 55, 45, 35];
+export declare function buildImageResizeSideGrid(maxSide: number, sideStart: number): number[];
+export declare function getImageMetadata(buffer: Buffer): Promise<ImageMetadata | null>;
+/**
+ * Normalizes EXIF orientation in an image buffer.
+ * Returns the buffer with correct pixel orientation (rotated if needed).
+ * Falls back to original buffer if normalization fails.
+ */
+export declare function normalizeExifOrientation(buffer: Buffer): Promise<Buffer>;
+export declare function resizeToJpeg(params: {
+    buffer: Buffer;
+    maxSide: number;
+    quality: number;
+    withoutEnlargement?: boolean;
+}): Promise<Buffer>;
+export declare function convertHeicToJpeg(buffer: Buffer): Promise<Buffer>;
+/**
+ * Checks if an image has an alpha channel (transparency).
+ * Returns true if the image has alpha, false otherwise.
+ */
+export declare function hasAlphaChannel(buffer: Buffer): Promise<boolean>;
+/**
+ * Resizes an image to PNG format, preserving alpha channel (transparency).
+ * Falls back to sharp only (no sips fallback for PNG with alpha).
+ */
+export declare function resizeToPng(params: {
+    buffer: Buffer;
+    maxSide: number;
+    compressionLevel?: number;
+    withoutEnlargement?: boolean;
+}): Promise<Buffer>;
+export declare function optimizeImageToPng(buffer: Buffer, maxBytes: number): Promise<{
+    buffer: Buffer;
+    optimizedSize: number;
+    resizeSide: number;
+    compressionLevel: number;
+}>;

package/dist/plugin-sdk/media/inbound-path-policy.d.ts

@@ -0,0 +1,18 @@
+import type { RemoteClawConfig } from "../config/config.js";
+export declare const DEFAULT_IMESSAGE_ATTACHMENT_ROOTS: readonly ["/Users/*/Library/Messages/Attachments"];
+export declare function isValidInboundPathRootPattern(value: string): boolean;
+export declare function normalizeInboundPathRoots(roots?: readonly string[]): string[];
+export declare function mergeInboundPathRoots(...rootsLists: Array<readonly string[] | undefined>): string[];
+export declare function isInboundPathAllowed(params: {
+    filePath: string;
+    roots: readonly string[];
+    fallbackRoots?: readonly string[];
+}): boolean;
+export declare function resolveIMessageAttachmentRoots(params: {
+    cfg: RemoteClawConfig;
+    accountId?: string | null;
+}): string[];
+export declare function resolveIMessageRemoteAttachmentRoots(params: {
+    cfg: RemoteClawConfig;
+    accountId?: string | null;
+}): string[];

package/dist/plugin-sdk/media/local-roots.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteClawConfig } from "../config/config.js";
+export declare function getDefaultMediaLocalRoots(): readonly string[];
+export declare function getAgentScopedMediaLocalRoots(cfg: RemoteClawConfig, agentId?: string): readonly string[];

package/dist/plugin-sdk/media/mime.d.ts

@@ -0,0 +1,16 @@
+import { type MediaKind } from "./constants.js";
+export declare function normalizeMimeType(mime?: string | null): string | undefined;
+export declare function getFileExtension(filePath?: string | null): string | undefined;
+export declare function isAudioFileName(fileName?: string | null): boolean;
+export declare function detectMime(opts: {
+    buffer?: Buffer;
+    headerMime?: string | null;
+    filePath?: string;
+}): Promise<string | undefined>;
+export declare function extensionForMime(mime?: string | null): string | undefined;
+export declare function isGifMedia(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;
+export declare function imageMimeFromFormat(format?: string | null): string | undefined;
+export declare function kindFromMime(mime?: string | null): MediaKind;

package/dist/plugin-sdk/media/outbound-attachment.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveOutboundAttachmentFromUrl(mediaUrl: string, maxBytes: number, options?: {
+    localRoots?: readonly string[];
+}): Promise<{
+    path: string;
+    contentType?: string;
+}>;

package/dist/plugin-sdk/media/parse.d.ts

@@ -0,0 +1,8 @@
+export declare const MEDIA_TOKEN_RE: RegExp;
+export declare function normalizeMediaSource(src: string): string;
+export declare function splitMediaFromOutput(raw: string): {
+    text: string;
+    mediaUrls?: string[];
+    mediaUrl?: string;
+    audioAsVoice?: boolean;
+};

package/dist/plugin-sdk/media/png-encode.d.ts

@@ -0,0 +1,8 @@
+/** Compute CRC32 checksum for a buffer (used in PNG chunk encoding). */
+export declare function crc32(buf: Buffer): number;
+/** Create a PNG chunk with type, data, and CRC. */
+export declare function pngChunk(type: string, data: Buffer): Buffer;
+/** Write a pixel to an RGBA buffer. Ignores out-of-bounds writes. */
+export declare function fillPixel(buf: Buffer, x: number, y: number, width: number, r: number, g: number, b: number, a?: number): void;
+/** Encode an RGBA buffer as a PNG image. */
+export declare function encodePngRgba(buffer: Buffer, width: number, height: number): Buffer;

package/dist/plugin-sdk/media/read-response-with-limit.d.ts

@@ -0,0 +1,7 @@
+export declare function readResponseWithLimit(res: Response, maxBytes: number, opts?: {
+    onOverflow?: (params: {
+        size: number;
+        maxBytes: number;
+        res: Response;
+    }) => Error;
+}): Promise<Buffer>;

package/dist/plugin-sdk/media/store.d.ts

@@ -0,0 +1,33 @@
+import { request as httpRequest } from "node:http";
+import { resolvePinnedHostname } from "../infra/net/ssrf.js";
+export declare const MEDIA_MAX_BYTES: number;
+type RequestImpl = typeof httpRequest;
+type ResolvePinnedHostnameImpl = typeof resolvePinnedHostname;
+export declare function setMediaStoreNetworkDepsForTest(deps?: {
+    httpRequest?: RequestImpl;
+    httpsRequest?: RequestImpl;
+    resolvePinnedHostname?: ResolvePinnedHostnameImpl;
+}): void;
+/**
+ * Extract original filename from path if it matches the embedded format.
+ * Pattern: {original}---{uuid}.{ext} → returns "{original}.{ext}"
+ * Falls back to basename if no pattern match, or "file.bin" if empty.
+ */
+export declare function extractOriginalFilename(filePath: string): string;
+export declare function getMediaDir(): string;
+export declare function ensureMediaDir(): Promise<string>;
+export declare function cleanOldMedia(ttlMs?: number): Promise<void>;
+export type SavedMedia = {
+    id: string;
+    path: string;
+    size: number;
+    contentType?: string;
+};
+export type SaveMediaSourceErrorCode = "invalid-path" | "not-found" | "not-file" | "path-mismatch" | "too-large";
+export declare class SaveMediaSourceError extends Error {
+    code: SaveMediaSourceErrorCode;
+    constructor(code: SaveMediaSourceErrorCode, message: string, options?: ErrorOptions);
+}
+export declare function saveMediaSource(source: string, headers?: Record<string, string>, subdir?: string): Promise<SavedMedia>;
+export declare function saveMediaBuffer(buffer: Buffer, contentType?: string, subdir?: string, maxBytes?: number, originalFilename?: string): Promise<SavedMedia>;
+export {};

package/dist/plugin-sdk/middleware/auth-key-retry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Auth key retry — rotates to the next auth profile on rate-limit / auth errors.
+ *
+ * When an agent has multiple auth profiles configured (`auth: ["k1", "k2"]`),
+ * a rate-limit or auth failure triggers a retry with the next key in the
+ * rotation. Each key is tried at most once per invocation.
+ */
+import type { AuthProfileStore } from "../auth/types.js";
+import type { RemoteClawConfig } from "../config/config.js";
+export type AuthKeyRetryOptions = {
+    cfg: RemoteClawConfig;
+    agentId: string;
+    baseEnv?: Record<string, string>;
+    store?: AuthProfileStore;
+};
+/**
+ * Execute a callback with automatic auth key retry on rate-limit / auth errors.
+ *
+ * - `auth: false` / `undefined` / single key → one attempt, no retry.
+ * - `auth: ["k1", "k2", ...]` → up to `N` attempts (one per key).
+ *
+ * The `execute` callback receives a merged env (base + auth). On a rate-limit
+ * or auth error (thrown or returned in the result), the next profile is
+ * selected via round-robin and the callback is retried.
+ *
+ * @param options  Auth config and base env.
+ * @param execute  Callback that runs the agent with the given env.
+ * @param getErrorMessage  Extracts an error string from a non-thrown result
+ *                         (e.g. `result.error`). Return `undefined` if no error.
+ */
+export declare function withAuthKeyRetry<T>(options: AuthKeyRetryOptions, execute: (env: Record<string, string>) => Promise<T>, getErrorMessage: (result: T) => string | undefined): Promise<T>;