@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/dist/types/notifications/topic-registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each SKC session owns one active Telegram forum topic in the paired private
+ * DM. The topic is created via `createForumTopic`, reused while the session
+ * remains active, and removed from the registry when the daemon deletes it on
+ * shutdown. The registry also tracks whether the one-time identity header has
+ * already been pinned, so it is sent exactly once per active topic, even across
+ * reconnects.
+ *
+ * State is a plain serialisable map persisted beside the daemon state files;
+ * topic creation is injected so this module is pure and unit-testable without a
+ * live Bot API.
+ */
+/** Persisted record for one session's topic. */
+export interface TopicRecord {
+    /** Telegram forum topic id (message_thread_id). */
+    topicId: string;
+    /** Whether the one-time identity header has been sent/pinned. */
+    identitySent: boolean;
+    /** Creation timestamp (ms epoch). */
+    createdAt: number;
+    /** Last applied topic title (for rename detection). */
+    name?: string;
+}
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+    /** sessionId -> record. */
+    topics: Record<string, TopicRecord>;
+}
+export declare function emptyTopicRegistryState(): TopicRegistryState;
+/**
+ * In-memory registry over a serialisable state. Topic creation is injected via
+ * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
+ * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
+ */
+export declare class TopicRegistry {
+    private readonly topics;
+    /** Maps topicId -> sessionId for fast inbound routing. */
+    private readonly byTopic;
+    /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
+    private readonly inflight;
+    constructor(state?: TopicRegistryState);
+    /** Merge a serialized state into this registry, preserving all persisted fields. */
+    load(state: TopicRegistryState): void;
+    /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+    sessionForTopic(topicId: string): string | undefined;
+    /** All session ids with a persisted topic record. */
+    sessionIds(): string[];
+    /** The existing topic record for a session, if any. */
+    get(sessionId: string): TopicRecord | undefined;
+    /**
+     * Return the existing active topic for `sessionId`, or create one via
+     * `create` (called only on first use).
+     */
+    getOrCreateTopic(sessionId: string, create: () => Promise<string>, now?: () => number, name?: string): Promise<TopicRecord>;
+    /** Mark the identity header as sent for a session. Idempotent. */
+    markIdentitySent(sessionId: string): void;
+    /** Whether the identity header still needs sending for this session. */
+    needsIdentity(sessionId: string): boolean;
+    /**
+     * Record the topic's applied title. Returns `true` when it changed (so the
+     * caller should `editForumTopic`), `false` when already current or unknown.
+     */
+    applyName(sessionId: string, name: string): boolean;
+    /** Remove a session topic record after Telegram deletes the topic. */
+    delete(sessionId: string): boolean;
+    /** Serialise for atomic persistence beside the daemon state. */
+    serialize(): TopicRegistryState;
+}

package/dist/types/plan-mode/approved-plan.d.ts

@@ -0,0 +1,49 @@
+/** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
+ *  approval popup. Populated by the standing handler that the resolve tool
+ *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+export interface PlanApprovalDetails {
+    planFilePath: string;
+    finalPlanFilePath: string;
+    title: string;
+    planExists: boolean;
+}
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
+export declare function normalizePlanTitle(title: string): {
+    title: string;
+    fileName: string;
+};
+/** Best-effort derivation of a plan title from inputs the agent already produced.
+ *  Returns the first non-empty candidate that survives `normalizePlanTitle`:
+ *    1. an explicit `suppliedTitle` (e.g. `extra.title` from the resolve call),
+ *    2. the first level-1 markdown heading inside `planContent`,
+ *    3. the filename stem of `planFilePath` (e.g. `PLAN` from `local://PLAN.md`),
+ *    4. the literal `"plan"` so callers never have to handle `null`.
+ *  The fallback exists because some grammar-constrained models cannot emit a
+ *  string into the open `extra` schema and instead drop in `{}` (issue #1179);
+ *  plan-mode would otherwise loop forever on an unreachable validation. */
+export declare function resolvePlanTitle(input: {
+    suppliedTitle?: unknown;
+    planContent: string;
+    planFilePath: string;
+}): {
+    title: string;
+    fileName: string;
+    source: "supplied" | "heading" | "filename" | "default";
+};
+/** Humanize a normalized plan title for use as a session display name.
+ *  Replaces `-`/`_` separators with spaces and capitalizes the first letter.
+ *  Returns an empty string when the input collapses to whitespace. */
+export declare function humanizePlanTitle(title: string): string;
+interface RenameApprovedPlanFileOptions {
+    planFilePath: string;
+    finalPlanFilePath: string;
+    getArtifactsDir: () => string | null;
+    getSessionId: () => string | null;
+}
+export declare function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void>;
+export {};

package/dist/types/plan-mode/state.d.ts

@@ -0,0 +1,6 @@
+export interface PlanModeState {
+    enabled: boolean;
+    planFilePath: string;
+    workflow?: "parallel" | "iterative";
+    reentry?: boolean;
+}

package/dist/types/registry/agent-registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * AgentRegistry - Process-global registry of live AgentSession instances.
+ *
+ * Tracks every alive agent (the main session plus every subagent) so the
+ * `irc` tool can address peers by id. Sessions are registered explicitly at
+ * creation and removed when the owner releases them.
+ */
+import type { AgentSession } from "../session/agent-session";
+export declare const MAIN_AGENT_ID = "0-Main";
+export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+export type AgentKind = "main" | "sub";
+export interface AgentRef {
+    id: string;
+    displayName: string;
+    kind: AgentKind;
+    parentId?: string;
+    status: AgentStatus;
+    session: AgentSession | null;
+    sessionFile: string | null;
+    createdAt: number;
+    lastActivity: number;
+}
+export type RegistryEvent = {
+    type: "registered";
+    ref: AgentRef;
+} | {
+    type: "status_changed";
+    ref: AgentRef;
+} | {
+    type: "removed";
+    ref: AgentRef;
+};
+type RegistryListener = (event: RegistryEvent) => void;
+export interface RegisterInput {
+    id: string;
+    displayName: string;
+    kind: AgentKind;
+    parentId?: string;
+    session: AgentSession | null;
+    sessionFile?: string | null;
+    status?: AgentStatus;
+}
+export declare class AgentRegistry {
+    #private;
+    static global(): AgentRegistry;
+    /** Reset the global registry. Test-only. */
+    static resetGlobalForTests(): void;
+    register(input: RegisterInput): AgentRef;
+    setStatus(id: string, status: AgentStatus): void;
+    attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
+    detachSession(id: string): void;
+    unregister(id: string): void;
+    get(id: string): AgentRef | undefined;
+    list(): AgentRef[];
+    /**
+     * Returns every alive agent (running | idle) except the caller.
+     * Flat namespace: every agent can see every other agent.
+     */
+    listVisibleTo(id: string): AgentRef[];
+    onChange(listener: RegistryListener): () => void;
+}
+export {};

package/dist/types/reminders/star-reminder.d.ts

@@ -0,0 +1,115 @@
+import type { ImageContent } from "@sayknow-cli/ai";
+import type { CustomMessage } from "../session/messages";
+export declare const STAR_REMINDER_REPO = "jaybeyond/Sayknow_CLI";
+export declare const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
+export declare const STARRED_CACHE_TTL_MS: number;
+export interface StarReminderState {
+    declined: boolean;
+    starred: boolean;
+    /** ISO-8601 timestamp of the last authoritative star check, or "" if never. */
+    starredCheckedAt: string;
+}
+export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
+export interface GhResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type RunGh = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<GhResult>;
+export interface StarReminderDeps {
+    statePath?: string;
+    now?: () => Date;
+    runGh?: RunGh;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function getStarReminderStatePath(): string;
+export declare function defaultStarReminderState(): StarReminderState;
+/** Read state without locking. Missing or malformed files return the default. */
+export declare function readStarReminderStateUnlocked(statePath?: string): Promise<StarReminderState>;
+/** Whether a stored `starred:true` is still within the 24h cache window. */
+export declare function isStarredCacheFresh(state: StarReminderState, now?: Date): boolean;
+/**
+ * Lock-protected read-modify-write. The mutator receives the freshly re-read
+ * state under the lock; callers MUST base monotonic decisions on that value,
+ * not on any snapshot captured before the lock was held.
+ */
+export declare function updateStarReminderStateLocked(mutator: (current: StarReminderState) => StarReminderState | Promise<StarReminderState>, deps?: StarReminderDeps): Promise<StarReminderState>;
+/** A successful PUT is authoritative: always record starred and clear declined. */
+export declare function recordStarredFromPut(deps?: StarReminderDeps): Promise<StarReminderState>;
+/**
+ * Record the result of a fresh `gh` star check performed by this operation.
+ * - "starred": authoritative, clears declined so all reminders stop.
+ * - "unstarred": may downgrade, but only when the current state is not a
+ *   still-fresh confirmed star (which a concurrent process may have just
+ *   written); in that case the fresher confirmation wins.
+ */
+export declare function recordFreshStarCheck(status: "starred" | "unstarred", deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Record a launch-nudge decline. Never downgrades a confirmed star. */
+export declare function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
+export declare function runGhDefault(args: string[], options?: {
+    timeoutMs?: number;
+}): Promise<GhResult>;
+/** Classify the star state of the repo via `gh api`. */
+export declare function checkGhStarred(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+/** Star the repo via `gh api -X PUT`. Returns whether the PUT succeeded. */
+export declare function autoStarRepo(deps?: StarReminderDeps): Promise<boolean>;
+/**
+ * Determine the star state for this session, hitting `gh` only when needed.
+ * A fresh cached star skips `gh`; unstarred and declined states are rechecked.
+ * Authoritative results are persisted via the monotonic helpers.
+ */
+export declare function refreshStarStateForSession(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+export interface StarReminderPromptUI {
+    /** Show a yes/no confirmation. Resolves true when the user accepts. */
+    confirm(title: string, message: string): Promise<boolean>;
+    /** Optional guard; when it returns false the nudge is skipped silently. */
+    isIdle?: () => boolean;
+}
+/**
+ * Run the launch nudge once. Caller is responsible for the `startup.quiet`,
+ * `starReminder.enabled`, and true-interactive gates. All errors are swallowed
+ * so the launch path can never be broken by the reminder.
+ */
+export declare function maybeShowLaunchStarReminder(ui: StarReminderPromptUI, deps?: StarReminderDeps): Promise<void>;
+/**
+ * Schedule the launch nudge to run after the first render so the networked
+ * `gh` check never blocks startup. Returns immediately.
+ */
+export declare function scheduleLaunchStarReminderAfterFirstRender(ui: StarReminderPromptUI, deps?: StarReminderDeps): void;
+export interface StarReminderLaunchGateInput {
+    /** The `starReminder.enabled` setting. */
+    enabled: boolean;
+    /** The `startup.quiet` setting. */
+    quiet: boolean;
+}
+export interface StarReminderLaunchGate {
+    /** Whether to register the decline-driven injection contributor. */
+    register: boolean;
+    /** Whether to schedule the launch nudge after first render. */
+    schedule: boolean;
+}
+/**
+ * Pure decision for interactive wiring. The injection contributor is registered
+ * whenever the feature is enabled; the launch nudge is additionally suppressed
+ * by quiet startup. Centralizing this keeps the interactive gate testable.
+ */
+export declare function starReminderLaunchGate(input: StarReminderLaunchGateInput): StarReminderLaunchGate;
+export interface StarReminderSessionRef {
+    getSessionId(): string | undefined;
+}
+export type StarReminderCustomMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+export type InternalBeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<StarReminderCustomMessage | undefined>;
+export declare function createStarReminderMessage(): StarReminderCustomMessage;
+/**
+ * Build a before-agent-start contributor that injects the persuasion message
+ * once per logical session id, for declined-and-still-unstarred users only.
+ */
+export declare function createStarReminderBeforeAgentStartContributor(session: StarReminderSessionRef, deps?: StarReminderDeps): InternalBeforeAgentStartContributor;

package/dist/types/research-plan/index.d.ts

@@ -0,0 +1 @@
+export * from "./ledger";

package/dist/types/research-plan/ledger.d.ts

@@ -0,0 +1,33 @@
+export type ResearchPlanConfidence = "low" | "medium" | "high";
+export type ResearchEvidenceVerdict = "support" | "contradict" | "uncertain";
+export interface ResearchPlanItem {
+    claim: string;
+    confidence: ResearchPlanConfidence;
+    unknowns: string[];
+    evidenceNeeded: string[];
+    counterexampleQueries: string[];
+    sourceConflictPolicy: string;
+    dropCondition: string;
+    verifierChecks: string[];
+}
+export interface ResearchEvidenceEntry {
+    claim: string;
+    source: string;
+    confidence: ResearchPlanConfidence;
+    verdict: ResearchEvidenceVerdict;
+    notes?: string;
+}
+export interface ResearchLedgerVerdict {
+    claim: string;
+    finalVerdict: "accepted" | "rejected" | "uncertain";
+    survivingSources: ResearchEvidenceEntry[];
+    rejectReason?: string;
+    unresolvedUnknowns: string[];
+}
+export interface ResearchPlanValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateResearchPlanItem(item: Partial<ResearchPlanItem>): ResearchPlanValidationResult;
+export declare function validateResearchEvidenceEntry(entry: Partial<ResearchEvidenceEntry>): ResearchPlanValidationResult;
+export declare function evaluateResearchLedger(item: ResearchPlanItem, evidence: readonly ResearchEvidenceEntry[]): ResearchLedgerVerdict;

package/dist/types/rlm/artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { RlmArtifactPaths } from "./types";
+export declare const RLM_DIR_SEGMENT = "rlm";
+export declare function isValidRlmSessionId(sessionId: string): boolean;
+/** Generate a filesystem-safe, sortable session id (timestamp + random suffix). */
+export declare function generateRlmSessionId(now?: Date): string;
+export declare function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArtifactPaths;
+export declare function ensureRlmSessionDir(paths: RlmArtifactPaths): Promise<void>;
+export declare function rlmSessionExists(cwd: string, sessionId: string): Promise<boolean>;
+export declare function readRlmNotebookIfPresent(cwd: string, sessionId: string): Promise<import("../edit/notebook").NotebookDocument | undefined>;

package/dist/types/rlm/complete-research-tool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * RLM completion/report tool.
+ *
+ * This is the model-facing stop/report seam for autonomous research mode. It
+ * writes the deterministic report from the live notebook and, for final
+ * completion, marks the RLM controller complete so the existing agent loop can
+ * pause through CreateAgentSessionOptions.shouldPause.
+ */
+import * as z from "zod/v4";
+import type { NotebookDocument } from "../edit/notebook";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import type { RlmNotebookWriter } from "./notebook";
+import type { RlmArtifactPaths } from "./types";
+export declare const RLM_COMPLETE_RESEARCH_TOOL_NAME = "complete_research";
+declare const paramsSchema: z.ZodObject<{
+    summary: z.ZodString;
+    final: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export interface RlmReportWriteInput {
+    paths: RlmArtifactPaths;
+    notebook: RlmNotebookWriter;
+    title: string;
+    summary?: string;
+    dataPath?: string | null;
+}
+export interface RlmCompleteResearchContext extends RlmReportWriteInput {
+    minSuccessfulRuns?: number;
+    getGoalStatus?: () => string | undefined;
+    markCompleted?: (summary: string) => void;
+}
+export declare function countSuccessfulNotebookRuns(notebook: NotebookDocument): number;
+export declare function summarizeNotebookForReplay(notebook: NotebookDocument, maxChars?: number): string;
+export declare function writeRlmReport(input: RlmReportWriteInput): Promise<string>;
+export declare function createRlmCompleteResearchTool(context: RlmCompleteResearchContext): CustomTool<typeof paramsSchema>;
+export {};

package/dist/types/rlm/data-context.d.ts

@@ -0,0 +1,6 @@
+export interface RlmDataContext {
+    /** Absolute path the content was loaded from. */
+    path: string;
+    content: string;
+}
+export declare function loadRlmDataContext(cwd: string, dataFlag: string | undefined): Promise<RlmDataContext | null>;

package/dist/types/rlm/index.d.ts

@@ -0,0 +1,47 @@
+import { type Args } from "../cli/args";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { type RlmPreset } from "../main";
+import type { AgentSession } from "../session/agent-session";
+import { type RlmDataContext } from "./data-context";
+interface ExtractedRlmFlags {
+    dataPath: string | undefined;
+    resumeSessionId: string | undefined;
+    minSuccessfulRuns: number;
+    rest: string[];
+}
+export interface RlmPresetOptions {
+    dataContext: RlmDataContext | null;
+    pythonTool: CustomTool;
+    completeResearchTool?: CustomTool;
+    objective?: string;
+    resumeContext?: string;
+    onSessionReady?: (session: AgentSession) => void;
+}
+/** Pull RLM-owned flags out of argv; the remainder is forwarded to the root command. */
+export declare function extractRlmFlags(argv: string[]): ExtractedRlmFlags;
+/** @deprecated use extractRlmFlags; retained for tests and compatibility. */
+export declare function extractDataFlag(argv: string[]): {
+    dataPath: string | undefined;
+    rest: string[];
+};
+export declare function createRlmPreset({ dataContext, pythonTool, completeResearchTool, objective, resumeContext, onSessionReady }: RlmPresetOptions): RlmPreset;
+export declare function buildRlmGoalObjective(input: {
+    messages: readonly string[];
+    dataContext: RlmDataContext | null;
+}): string;
+export declare function isRlmAutonomousRun(parsed: Pick<Args, "print" | "mode" | "messages">, pipedStdin: boolean): boolean;
+export declare function prepareRlmLaunchMode(parsed: Args, pipedStdin: boolean): boolean;
+/**
+ * RLM artifacts are scoped under a SKC session directory and resolving their
+ * paths is a *write* (it must pick a concrete session). When `skc rlm` runs
+ * standalone — no parent agent, no `SKC_SESSION_ID` in the environment — there is
+ * no session to resolve and `resolveSkcSessionForWrite` throws
+ * `missing_for_write`. Establish a dedicated SKC session id in that case and pin
+ * it into the environment so artifact-path resolution, the per-session activity
+ * marker, and the child agent's workflow state all share one writable session.
+ *
+ * Returns the resolved (existing or freshly generated) SKC session id.
+ */
+export declare function ensureRlmSkcSessionId(): string;
+export declare function runRlmCommand(argv: string[]): Promise<void>;
+export {};

package/dist/types/rlm/notebook.d.ts

@@ -0,0 +1,12 @@
+import { type NotebookDocument } from "../edit/notebook";
+import type { RlmCellResult } from "./types";
+export declare class RlmNotebookWriter {
+    #private;
+    constructor(notebookPath: string, initial?: NotebookDocument);
+    get document(): NotebookDocument;
+    get cellCount(): number;
+    appendMarkdown(source: string): Promise<void>;
+    appendCode(code: string, result: RlmCellResult): Promise<void>;
+    /** Resolve once all queued writes have flushed. */
+    flush(): Promise<void>;
+}

package/dist/types/rlm/preset.d.ts

@@ -0,0 +1,23 @@
+import type { RlmDataContext } from "./data-context";
+/**
+ * tool; `read` and `web_search` are the existing built-ins. `bash` is exposed
+ * through the read-only restriction profile below for inspection commands only,
+ * and `goal` is required so RLM sessions cannot finish without explicit goal
+ * completion. Everything else (edit, write, task, skill, browser, eval-js, ...) is excluded.
+ */
+export declare const RLM_READ_ONLY_BASH_PREFIXES: readonly string[];
+export declare const RLM_TOOL_ALLOWLIST: readonly string[];
+export declare function isRlmToolAllowed(name: string): boolean;
+/**
+ * Hard boundary: throws if any active tool is outside the allowlist. Call this
+ * after the session's tool registry is fully assembled and before running, so a
+ * tool leaked in by defaults/discovery/extensions fails the launch loudly.
+ */
+export declare function assertRlmToolAllowlist(activeToolNames: readonly string[]): void;
+/** The research prompt text (exported for testing / prompt assembly). */
+export declare const RLM_RESEARCH_PROMPT: string;
+/**
+ * Build the systemPrompt transform for createAgentSession: appends the research
+ * prompt, data context, and prior-notebook replay context to the default blocks.
+ */
+export declare function buildRlmSystemPrompt(dataContext: RlmDataContext | null, resumeContext?: string): (defaultPrompt: string[]) => string[];

package/dist/types/rlm/python-tool.d.ts

@@ -0,0 +1,16 @@
+import { z } from "@sayknow-cli/ai";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import type { RlmNotebookWriter } from "./notebook";
+export declare const RLM_PYTHON_TOOL_NAME = "python";
+export interface RlmPythonToolContext {
+    cwd: string;
+    sessionId: string;
+    artifactsDir: string;
+    notebook: RlmNotebookWriter;
+    managedWorkspaceVenv?: boolean;
+}
+declare const paramsSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+export declare function createRlmPythonTool(rlm: RlmPythonToolContext): CustomTool<typeof paramsSchema>;
+export {};

package/dist/types/rlm/report.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic RLM report synthesis: turns the accumulated notebook (plus an
+ * optional model-provided summary) into a Markdown research report.
+ */
+import type { NotebookDocument } from "../edit/notebook";
+export interface RlmReportInput {
+    title: string;
+    summary?: string;
+    notebook: NotebookDocument;
+    dataPath?: string | null;
+    generatedAt?: string;
+    maxOutputChars?: number;
+}
+export declare function synthesizeRlmReport(input: RlmReportInput): string;

package/dist/types/rlm/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared types for RLM (research) mode.
+ */
+import type { KernelDisplayOutput } from "../eval/py/kernel";
+export interface RlmArtifactPaths {
+    /** Absolute session directory: <cwd>/.skc/rlm/<sessionId>/ */
+    dir: string;
+    /** Absolute path to the live notebook.ipynb */
+    notebookPath: string;
+    /** Absolute path to the synthesized report.md */
+    reportPath: string;
+    /** Absolute path to the session metadata.json */
+    metadataPath: string;
+    /** Directory for the underlying SKC conversation session files. */
+    agentSessionDir: string;
+}
+/** Outcome of a single RLM python cell execution. */
+export interface RlmCellResult {
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    displayOutputs: KernelDisplayOutput[];
+}
+export interface RlmSessionMetadata {
+    sessionId: string;
+    createdAt: string;
+    cwd: string;
+    dataPath: string | null;
+    cellCount: number;
+    mode?: "interactive" | "autonomous";
+    resumedFrom?: string | null;
+    completedAt?: string | null;
+    finalSummary?: string | null;
+    minSuccessfulRuns?: number;
+    successfulRuns?: number;
+}

package/dist/types/runtime/process-lifecycle.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared runtime lifecycle foundation.
+ *
+ * Two minimal, deliberately small primitives that subsystem runtimes
+ * (DAP/LSP/MCP stdio, eval workers, etc.) adopt so spawned children and
+ * non-process resources cannot outlive their owner:
+ *
+ *   F1(a) `spawnOwnedProcess` — wraps `ptree.spawn` with explicit
+ *         process-group ownership, escalating (SIGTERM -> grace -> SIGKILL)
+ *         tree termination, bounded `awaitExit`, abort-listener cleanup on
+ *         settle, idempotent `dispose`, and a single postmortem hook that
+ *         reaps every still-live owned process group on fatal/normal shutdown.
+ *
+ *   F1(b) `registerResourceOwner` — a generic, idempotent postmortem adapter
+ *         for non-process resources (Bun Workers, VM contexts, timers,
+ *         sockets) built on the existing `postmortem.register` facility.
+ *
+ * Ownership is keyed to the *process group*, not the root process. A root that
+ * exits after backgrounding descendants (`sh -c "worker & exit 0"`) keeps the
+ * owner registered until the group is actually gone, so the descendant tree is
+ * still reaped by `dispose()`/postmortem.
+ *
+ * This module intentionally owns only these primitives. It does not migrate
+ * existing call sites; subsystem PRs adopt it incrementally.
+ *
+ * Note: `ptree.spawn` always pipes stdout/stderr. Adopters that expect output
+ * (DAP/LSP/MCP protocol servers) must consume `owner.child.stdout`; F1 does not
+ * drain it, so a chatty child whose stdout is never read can still block on a
+ * full pipe. That draining is the adopter's responsibility.
+ */
+import { ptree } from "@sayknow-cli/utils";
+/** Options for {@link spawnOwnedProcess}. */
+export interface SpawnOwnedOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** stdin mode passed through to the child. Defaults to `"ignore"`. */
+    stdin?: "pipe" | "ignore";
+    /** When aborted, the owned process tree is disposed (escalating kill). */
+    signal?: AbortSignal;
+    /** Grace period (ms) between SIGTERM and SIGKILL on dispose. Default 2000. */
+    gracefulMs?: number;
+    /**
+     * Spawn the child as its own process-group leader so the whole descendant
+     * tree can be signalled on dispose. Defaults to `true` on POSIX. Has no
+     * effect on Windows, where teardown falls back to single-process kill.
+     */
+    processGroup?: boolean;
+    /** Label used in diagnostics. */
+    name?: string;
+}
+/** Result of a bounded {@link OwnedProcess.awaitExit}. */
+export interface AwaitExitResult {
+    /** `true` when the process has exited; `false` when the timeout fired first. */
+    exited: boolean;
+    /** Exit code if known, else `null`. */
+    code: number | null;
+}
+/** A spawned child process owned by the runtime with guaranteed teardown. */
+export interface OwnedProcess {
+    readonly child: ptree.ChildProcess;
+    readonly pid: number | undefined;
+    /** Resolves/rejects when the root child exits (mirrors ptree's `exited`). */
+    readonly exited: Promise<number>;
+    /** `true` once `dispose()` has started. */
+    readonly disposed: boolean;
+    /**
+     * Wait for the root child to exit, optionally bounded by `timeoutMs`. With no
+     * timeout it resolves only when the child exits. Never rejects.
+     */
+    awaitExit(opts?: {
+        timeoutMs?: number;
+    }): Promise<AwaitExitResult>;
+    /**
+     * Idempotently terminate the owned process *group*: SIGTERM the group, wait
+     * `gracefulMs`, then SIGKILL, polling group liveness throughout. Removes the
+     * abort listener and deregisters from the live-owner set only after teardown
+     * has completed. Repeated/concurrent calls return the same in-flight promise.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Spawn a child process owned by the runtime. The returned {@link OwnedProcess}
+ * is registered for postmortem cleanup and tears down its whole process group
+ * on dispose/abort.
+ */
+export declare function spawnOwnedProcess(cmd: string[], opts?: SpawnOwnedOptions): OwnedProcess;
+/** Number of currently live owned processes. Exposed for leak assertions/tests. */
+export declare function liveOwnedProcessCount(): number;
+/** Dispose every live owned process. For owner-scoped teardown and tests. */
+export declare function disposeAllOwnedProcesses(): Promise<void>;
+type ResourceDisposer = () => void | Promise<void>;
+/**
+ * Register a non-process resource for postmortem/fatal-exit cleanup.
+ *
+ * Idempotent by `name`: re-registering the same name replaces the prior
+ * disposer (last wins). Returns an unregister function that removes the owner
+ * only while it is still the active registration for that name.
+ */
+export declare function registerResourceOwner(name: string, disposer: ResourceDisposer): () => void;
+/** Number of registered resource owners. Exposed for leak assertions/tests. */
+export declare function resourceOwnerCount(): number;
+/**
+ * Run and clear every registered resource disposer. Attempts all disposers even
+ * if some throw, then surfaces the failures as an `AggregateError` so callers
+ * can distinguish "all closed" from "a resource may still be alive".
+ */
+export declare function disposeAllResourceOwners(): Promise<void>;
+export {};