@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/session/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Session Component Index
+ *
+ * Session management component for Environment
+ */
+export { SessionComponent } from "./session-component";
+export { SessionMessageConverter } from "./session-message-converter";
+export type { Session, SessionMessage, SessionConfig, SessionCheckpoint, // (new)
+SessionCheckpointsMeta, // (new)
+CreateSessionOptions, UpdateSessionOptions, ListSessionsOptions, AddMessageOptions, CompactOptions, // (new)
+CompactResult, // (new)
+CompactPreview, // (new)
+GetContextOptions, // (new)
+GetContextResult, // (new)
+GetMessagesOptions, } from "./types";
+export type { SessionStore } from "./session-store";
+export { MemorySessionStore } from "./storage/memory";
+export * from "./hooks";
+export { isValidSessionId, MIN_SESSION_ID_LENGTH, MAX_SESSION_ID_LENGTH, } from "./session-id";

package/dist/env/session/index.js

@@ -3,16 +3,16 @@ import {
   MIN_SESSION_ID_LENGTH,
   SessionComponent,
   isValidSessionId
-} from "../../shared/@ai-setting/roy-agent-core-yd21n6c7.js";
+} from "../../shared/@ai-setting/roy-agent-core-zvemdfx5.js";
 import {
   MemorySessionStore
-} from "../../shared/@ai-setting/roy-agent-core-h93v6p6y.js";
+} from "../../shared/@ai-setting/roy-agent-core-7qy3nffr.js";
 import"../../shared/@ai-setting/roy-agent-core-ze068vc9.js";
 import"../../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   SessionMessageConverter
-} from "../../shared/@ai-setting/roy-agent-core-pk1b3kvf.js";
-import"../../shared/@ai-setting/roy-agent-core-zy3hqfwg.js";
+} from "../../shared/@ai-setting/roy-agent-core-2b8jtv7m.js";
+import"../../shared/@ai-setting/roy-agent-core-0hq21px2.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import"../../shared/@ai-setting/roy-agent-core-tdbv7ff4.js";
 import"../../shared/@ai-setting/roy-agent-core-qcspfszy.js";

package/dist/env/session/search-query-parser.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Search Query Parser
+ *
+ * Parses search query strings into structured terms for message matching.
+ *
+ * Supported syntax:
+ * - AND: term1 AND term2 (both required, default behavior)
+ * - OR: term1 OR term2 (either required)
+ * - NOT: term1 NOT term2 (term1 required, term2 excluded)
+ * - Quoted phrases: "exact phrase"
+ * - Default: AND (space-separated terms are ANDed together)
+ *
+ * @example
+ * parseSearchQuery("hello world")        // { required: ["hello", "world"], excluded: [], phrases: [] }
+ * parseSearchQuery("hello OR world")    // { required: ["hello", "world"], orMode: true }
+ * parseSearchQuery("hello NOT world")   // { required: ["hello"], excluded: ["world"] }
+ * parseSearchQuery('"exact phrase"')    // { required: [], excluded: [], phrases: ["exact phrase"] }
+ */
+export interface ParsedQuery {
+    /** Required terms (AND logic by default) */
+    required: string[];
+    /** Terms to exclude */
+    excluded: string[];
+    /** Exact phrases to match */
+    phrases: string[];
+}
+/**
+ * Parse a search query string into structured terms
+ *
+ * @param query - Search query string
+ * @returns Parsed query structure
+ */
+export declare function parseSearchQuery(query: string): ParsedQuery;
+/**
+ * Check if content matches parsed query
+ *
+ * @param content - Content to search
+ * @param query - Parsed query structure
+ * @returns true if content matches query
+ */
+export declare function matchesQuery(content: string, query: ParsedQuery): boolean;

package/dist/env/session/session-component.d.ts

@@ -0,0 +1,464 @@
+/**
+ * @fileoverview Session Component
+ *
+ * Component for managing session lifecycle
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import { type SessionConfig, type Session, type CreateSessionOptions, type UpdateSessionOptions, type ListSessionsOptions, type SessionMessage, type AddMessageOptions, type SessionCheckpoint, // (new)
+type CompactOptions, // (new)
+type CompactResult, // (new)
+type CompactPreview, // (new)
+type GetContextOptions, // (new)
+type GetContextResult, // (new)
+type SearchMessagesOptions, // (new)
+type SearchResult, // (new)
+type ChatTaskBinding, // Task #4023
+type UpsertChatTaskBindingOptions } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+import type { SummaryAgentResult } from "../agent/types";
+export type { SessionConfig, Session, SessionMessage, CreateSessionOptions, UpdateSessionOptions, ListSessionsOptions, AddMessageOptions, SessionCheckpoint, // (new)
+CompactOptions, // (new)
+CompactResult, // (new)
+CompactPreview, // (new)
+GetContextOptions, // (new)
+GetContextResult, // (new)
+SearchMessagesOptions, // (new) Search
+SearchResult, // (new) Search
+MessageMatch, // (new) Search
+ChatTaskBinding, // Task #4023
+UpsertChatTaskBindingOptions, } from "./types";
+/**
+ * 把 compact agent 通过 `workflow_submit_output` 提交的数据归一化。
+ */
+export declare function normalizeAgentCheckpoint(data: Record<string, unknown>): SummaryAgentResult;
+/**
+ * 判断一段文本是否可作为 checkpoint 正文（拒绝空白与降级哨兵）。
+ */
+export declare function isUsableCheckpointText(text?: string | null): boolean;
+/**
+ * 降级路径：compact agent 没有调用 `workflow_submit_output` 时，用它输出的
+ * 纯文本 `finalText` 兜底构造 checkpoint。
+ *
+ * 为什么需要（2026-10-16 生产事故 traceId=83eadac2316d5be7529ca42ce7057d63）：
+ *   compact 是子 agent。首轮若没调提交工具，`checkpointData` 就是 undefined，
+ *   旧代码会写出全空 checkpoint（`"Untitled Checkpoint"`）**然后照样归档几百条消息**
+ *   （实测生产 9 次 / 累计吞掉 4731 条 / 单次最多 2710 条）→ 上下文永久丢失且用户无感知。
+ *
+ *   而实际上模型往往已经产出了可用的 checkpoint 内容，只是以纯文本形式落在
+ *   `finalText` 里（例：`"## 📌 Checkpoint: lark-cli profile 配置 ..."`），
+ *   或者包在 ```json 代码块里。这些内容全部可以救回来。
+ *
+ * 策略：
+ *   1. 先从文本里抠 JSON（```json 代码块 / 裸 JSON / 第一个 {...}）→ 结构化解析；
+ *   2. 否则把整段文本作为 `currentState`，title 取首个 markdown 标题行（或首行）；
+ *   3. 文本为空 / 是降级哨兵 → 返回 undefined（调用方继续降级或抛错）
+ *
+ * @returns 归一化后的 checkpoint，或 undefined（无可用文本）
+ */
+export declare function buildCheckpointFromFinalText(finalText?: string): SummaryAgentResult | undefined;
+/**
+ * Marker error class so callers can distinguish "lock exhausted after
+ * retries" from "validation rejected on first attempt". Previously both
+ * returned `undefined`, hiding the difference from `recordSessionMessages`
+ * and any future operator.
+ */
+export declare class AddMessageLockExhaustedError extends Error {
+    readonly kind: "lock_exhausted";
+    readonly attempts: number;
+    readonly cause: unknown;
+    constructor(attempts: number, cause: unknown);
+}
+/**
+ * SessionComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface SessionComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "SESSION"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<SessionConfig>;
+}
+/**
+ * SessionComponent
+ *
+ * Manages session lifecycle including:
+ * - Session CRUD operations
+ * - Message management
+ * - Active session tracking
+ */
+export declare class SessionComponent extends BaseComponent {
+    /**
+     * Exponential backoff schedule for SQLITE_BUSY retry. Indexed by
+     * attempt number (0-based). Worst-case total wait across 3 attempts:
+     * 50 + 100 + 200 = 350 ms, which is well under the 5 s busy_timeout
+     * so the next retry always starts before the lock has had time to
+     * expire and re-arm.
+     */
+    private static readonly BACKOFFS_MS;
+    readonly name = "session";
+    readonly version = "1.1.0";
+    private config?;
+    private store?;
+    private activeSessionId?;
+    private hooksConfig;
+    /** ConfigComponent 用于配置管理 */
+    private configComponent?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    constructor();
+    /**
+     * Initialize the component
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 获取默认 session 数据库路径
+     */
+    private getDefaultSessionDbPath;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    private registerConfig;
+    /**
+     * 构建最终配置对象
+     */
+    private buildConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * Start the component
+     */
+    onStart(): Promise<void>;
+    /**
+     * Stop the component
+     */
+    onStop(): Promise<void>;
+    /**
+     * Create a new session
+     */
+    create(options?: CreateSessionOptions): Promise<Session>;
+    /**
+     * Get a session by ID
+     */
+    get(id: string): Promise<Session | undefined>;
+    /**
+     * Get a session with full context (for Memory Agent)
+     */
+    getSession(id: string): Promise<{
+        sessionId: string;
+        title: string;
+        messages: any[];
+    } | null>;
+    /**
+     * Search sessions by query (for Memory Agent)
+     *
+     * Simple implementation: list all sessions and return them for the agent to filter
+     */
+    searchSessions(query: string, options?: {
+        session_id?: string;
+        limit?: number;
+    }): Promise<Array<{
+        sessionId: string;
+        title: string;
+        preview: string;
+        timestamp: number;
+    }>>;
+    /**
+     * List all sessions
+     */
+    list(options?: ListSessionsOptions): Promise<Session[]>;
+    /**
+     * Get total session count
+     */
+    getCount(): Promise<number>;
+    /**
+     * Update a session
+     */
+    update(id: string, updates: UpdateSessionOptions): Promise<boolean>;
+    /**
+     * Delete a session
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * 飞书 chat_id → task_id 反向绑定缓存（LRU + TTL）
+     *
+     * 为什么不放 store 缓存里？
+     * - 群消息事件频率高（每条消息都会查一次），避免每条消息都打 DB。
+     * - binding 信息只关心 taskId，不关心整个 session 对象。
+     * - TTL 60s 容忍 task 端被外部归档后残留的 stale 数据。
+     */
+    private chatBindingCache;
+    private static readonly CHAT_BINDING_CACHE_TTL_MS;
+    private static readonly CHAT_BINDING_CACHE_MAX;
+    /**
+     * 同 chatId 的 upsert 串行化锁（Task #4023）。
+     *
+     * upsertChatTaskBinding 是"读-改-写"（先 getChatTaskBinding 再 create/update），
+     * 同一 chatId 并发调用时两个请求都可能读到 null → 各自 create → 后写覆盖前写
+     * （丢失 taskId / rebindCount）。这里用 per-chatId promise 链把同一 chatId 的
+     * upsert 串行化，保证读到的 existing 是最新的。
+     */
+    private chatBindingLocks;
+    /**
+     * 在 chatId 维度串行执行 fn；不同 chatId 互不阻塞。
+     */
+    private runChatBindingExclusive;
+    /**
+     * Upsert 飞书 chat_id → task_id 绑定
+     *
+     * - 首次：新建 session（id=chatId）并写入 larkChat 元数据
+     * - 重复绑定同一 taskId：更新 status / boundAt
+     * - 绑定不同 taskId：rebindCount++ 但不覆盖 taskId（防误覆盖丢失数据）
+     * - rebind 路径会发 warn 日志，便于诊断
+     *
+     * @returns 最终写入的 ChatTaskBinding（包含 rebindCount）
+     */
+    upsertChatTaskBinding(opts: UpsertChatTaskBindingOptions): Promise<ChatTaskBinding>;
+    /**
+     * upsertChatTaskBinding 的实际实现（调用方已持有 chatId 锁）。
+     */
+    private upsertChatTaskBindingLocked;
+    /**
+     * 查询 chat_id → task_id 绑定
+     *
+     * @returns binding 对象；若不存在或 session 元数据不含 larkChat → 返回 null
+     */
+    getChatTaskBinding(chatId: string): Promise<ChatTaskBinding | null>;
+    /**
+     * 清理过期/超容的 chat binding 缓存
+     */
+    private evictStaleChatBindingCache;
+    /**
+     * Get the current active session
+     */
+    getActiveSession(): Session | undefined;
+    /**
+     * Get the active session ID
+     */
+    getActiveSessionId(): string | undefined;
+    /**
+     * Set the active session
+     */
+    setActiveSession(id: string): Promise<boolean>;
+    /**
+     * Add a message to a session.
+     *
+     * Layer 2 of sessions.db fix: wrap the store call in a 3-attempt retry
+     * loop with exponential backoff (50ms, 100ms, 200ms). ONLY retries
+     * `SQLITE_BUSY` / `database is locked` errors — any other failure
+     * (validation, FK violation, etc.) bubbles up immediately on the
+     * first attempt.
+     *
+     * Why 3 attempts × 50/100/200ms (~350ms total worst case):
+     *  - The 2026-07-07 incident had 102 consecutive `database is locked`
+     *    errors over 8 minutes (≈ 4.7s average spacing). A 5s busy_timeout
+     *    (Layer 1) + 350ms retry window absorbs typical contention.
+     *  - Going much higher would risk blocking the React event loop on
+     *    a real deadlock (which retry can't fix anyway).
+     */
+    addMessage(sessionId: string, message: AddMessageOptions): Promise<string | undefined>;
+    /**
+     * Retry-wrapped addMessage. Exposed via the public `addMessage` entry
+     * point; tests assert behavior through that public method.
+     *
+     * Behavior contract:
+     *  - Success → returns the new message id
+     *  - Non-busy error → logs and returns `undefined` (preserves the
+     *    pre-retry behavior so callers that already handle `undefined`
+     *    keep working)
+     *  - Busy error, retries exhausted → throws
+     *    `AddMessageLockExhaustedError` so the caller can distinguish
+     *    "lock could not be obtained" from "validation failed" and log
+     *    at the appropriate severity. (Pre-retry this distinction was
+     *    hidden behind a uniform `undefined` return.)
+     */
+    private addMessageWithRetry;
+    /**
+     * Layer 3 wiring: expose `addMessages` so agent-component (recordSessionMessages)
+     * can write a batch in one transaction instead of N individual calls.
+     *
+     * Forwards to the store; if the store throws (e.g. FK violation), the
+     * error propagates and the caller's existing try/catch handles it.
+     * Retries at the batch level would mask real schema errors, so we
+     * deliberately don't add retry here — the per-call `addMessage` retry
+     * already covers the contention case.
+     */
+    addMessages(sessionId: string, messages: AddMessageOptions[]): Promise<string[]>;
+    /**
+     * Get messages from a session
+     */
+    getMessages(sessionId: string, options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<SessionMessage[]>;
+    /**
+     * Update an existing message in a session
+     */
+    updateMessage(sessionId: string, messageId: string, updates: {
+        metadata?: Record<string, unknown>;
+        parts?: unknown[];
+        content?: string;
+    }): Promise<boolean>;
+    /**
+     * Get message count for a session
+     */
+    getMessageCount(sessionId: string, includeArchived?: boolean): Promise<number>;
+    /**
+     * Get indexes of all messages with the specified role
+     * @param sessionId - Session ID
+     * @param role - Role to filter by (e.g., "user", "assistant")
+     * @returns Array of message indexes (0-indexed, in chronological order)
+     */
+    getMessageIndexes(sessionId: string, role: string): Promise<number[]>;
+    private executeBeforeHooks;
+    private executeAfterHooks;
+    private generateTitle;
+    /**
+     * 生成场景化压缩提示 (Compact Hint)
+     *
+     * 两阶段自动压缩的第一阶段：使用内置 compact-hint agent 分析
+     * 父 session 历史，生成场景化的压缩提示。
+     *
+     * compact-hint agent 通过 filterHistory=false 自动读取父 session 的
+     * 对话历史，LLM 服务端可缓存 system prompt。
+     *
+     * @param sessionId 会话 ID
+     * @returns 生成的场景化提示
+     */
+    generateCompactHint(sessionId: string): Promise<string>;
+    /**
+     * Compact a session
+     *
+     * 1. Get messages from latest checkpoint to current
+     * 2. Call Summary Agent to generate checkpoint
+     * 3. Save checkpoint and archive messages
+     *
+     * 支持 scenarioHint 参数，用于指导不同场景下的压缩重点提取
+     */
+    compact(sessionId: string, options?: CompactOptions): Promise<CompactResult>;
+    /**
+     * Extract recent messages from the conversation for checkpoint context
+     *
+     * Extracts the last N turns of user query + assistant text response,
+     * excluding tool calls and tool results.
+     *
+     * @param messages - All messages in the conversation
+     * @param turnCount - Number of turns to extract (default: 2)
+     * @returns Array of recent messages formatted as { role, content }
+     */
+    /**
+     * 提取最近的若干「用户 → 助手纯文本」轮次，写入 `checkpoint.recentMessages`。
+     *
+     * ⚠️ 用途澄清（2026-10-16 独立 review P2-2 更正）：
+     *   `recentMessages` **不会进入 LLM 上下文**。全仓非测试引用只有
+     *   `packages/cli/src/commands/sessions/compact.ts`（CLI 展示 checkpoint），
+     *   `createCheckpointMessage()` 也不渲染它。所以它**不是**「压缩后保住最近上下文」
+     *   的安全网 —— 此前 commit 里那种说法是过度声称，已更正。
+     *   它的价值限于 CLI `sessions compact` 预览 / 审计可读性。
+     *
+     * ★ 仍然值得修的部分（2026-10-16）：
+     *   原实现只接受「assistant 消息**没有任何 tool-call/tool-result part** 且 content 非空」。
+     *   但真实 agentic 会话里 assistant 几乎总带 tool part（最后一条正文往往为空），
+     *   于是它在生产里**几乎永远返回 []** —— 三条事故 trace 的
+     *   `checkpoint.recentMessages` 全是空数组，CLI 里这个字段等于没有。
+     *
+     *   现在：优先取干净的纯文本轮次（信息密度最高），一轮都没取到时兜底保留最近
+     *   若干条原始消息（含 tool 轮次），至少让 CLI 能看到「刚才在干什么」。
+     */
+    private extractRecentMessages;
+    /**
+     * Preview compact operation
+     */
+    previewCompact(sessionId: string): Promise<CompactPreview>;
+    /**
+     * Get all checkpoints for a session
+     */
+    getCheckpoints(sessionId: string): Promise<SessionCheckpoint[]>;
+    /**
+     * Get a specific checkpoint
+     */
+    getCheckpoint(sessionId: string, checkpointId: string): Promise<SessionCheckpoint | undefined>;
+    /**
+     * Delete a checkpoint and restore archived messages
+     */
+    deleteCheckpoint(sessionId: string, checkpointId: string): Promise<boolean>;
+    /**
+     * Task #2539 — 终态联动释放 sub session 的内存占用（OOM 修复）。
+     *
+     * 触发场景：BackgroundTaskManager 检测到 sub session 终态（success / error /
+     * cancel / timeout）后调用本方法。
+     *
+     * 行为：
+     * - MemorySessionStore：按 checkpoint 对齐裁剪 messages + 保留最新 1 checkpoint（激进模式）
+     *   或仅裁旧 checkpoint（保守模式 keepAllMessagesUntilCompaction=true）
+     * - SQLiteSessionStore：no-op（SQLite 不受内存压力影响；保留完整历史便于审计）
+     *
+     * 幂等：重复调用结果稳定。
+     * 不存在的 sessionId：no-op。
+     */
+    endSessionCleanup(sessionId: string, opts?: {
+        keepAllMessagesUntilCompaction?: boolean;
+        keepLatestCheckpoints?: number;
+    }): Promise<void>;
+    /**
+     * Get session context
+     *
+     * Returns messages starting from the latest checkpoint by default
+     */
+    getContext(sessionId: string, options?: GetContextOptions): Promise<GetContextResult>;
+    /**
+     * Check if session needs compaction
+     */
+    shouldCompact(sessionId: string): Promise<boolean>;
+    /**
+     * Search messages across sessions
+     *
+     * Searches all messages matching the query, aggregated by session.
+     * Supports SQLite FTS5 for fast full-text search.
+     */
+    searchMessages(options: SearchMessagesOptions): Promise<SearchResult[]>;
+    /**
+     * Get latest checkpoint from session
+     */
+    private getLatestCheckpoint;
+    /**
+     * Create checkpoint message (user role)
+     *
+     * Generates a markdown-formatted checkpoint summary as a user message,
+     * allowing it to appear in the message list and provide context for
+     * subsequent LLM calls.
+     */
+    private createCheckpointMessage;
+}

package/dist/env/session/session-config-registration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Session Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * Session Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "session." 前缀），在 registerConfig 中手动设置
+ */
+export declare const SESSION_DEFAULTS: Record<string, unknown>;
+/**
+ * Session Component 配置注册常量
+ *
+ * 定义了所有 Session 相关的配置项和来源
+ */
+export declare const SESSION_CONFIG_REGISTRATION: ComponentRegistration;

package/dist/env/session/session-id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Session-id validation helper (Issue #8)
+ *
+ * `ROY_PARENT_SESSION_ID` is a cross-process propagation channel (set by an
+ * outer parent process and consumed by the spawned child CLI). Because the
+ * value crosses a trust boundary, callers must validate it before using it
+ * to write into the session tree — otherwise a malicious or buggy parent
+ * can inject arbitrary strings into the database or cause log noise.
+ *
+ * The policy:
+ *  - Length: 8..128 characters (covers session_/run_/agent_ UUIDs + a bit of
+ *    headroom; rejects empty, single-char, and absurdly long strings).
+ *  - Character set: `[A-Za-z0-9_-]` (alphanumerics plus `_` and `-`).
+ *    This covers all known session-id formats and rejects any control chars,
+ *    spaces, slashes, dots, or shell metacharacters.
+ */
+export declare const MIN_SESSION_ID_LENGTH = 8;
+export declare const MAX_SESSION_ID_LENGTH = 128;
+/**
+ * Returns true if the given string is a well-formed session id we are willing
+ * to propagate cross-process (e.g. via `ROY_PARENT_SESSION_ID`).
+ *
+ * Pass `null` / `undefined` / empty string → false (defensive: callers often
+ * pull from env where missing values are common).
+ */
+export declare function isValidSessionId(value: unknown): value is string;