@ponythewhite/base-context 1.0.15 → 1.0.16

package/dist/core/kernel/shared.d.ts

@@ -177,10 +177,22 @@ export interface CapturedKernelLifecycle {
     /** Checks the original observation; it never probes or substitutes a newer snapshot. */
     isCurrent(): boolean;
 }
+export interface JobWatchProbeRequest {
+    watchId: string;
+    generation: string;
+    resourceId: string;
+    jobId: string;
+    completionSource?: "handle" | "probe";
+    command: string | null;
+    timeoutMs: number;
+}
 /** Public surface every kernel client exposes to the provisioner and session layer. */
 export interface KernelClient {
     readonly ownerSessionId: string | undefined;
     readonly isRunning: boolean;
+    /** Optional job_watch_probe_v1 capability. Never evaluates a notebook cell. */
+    jobWatchProbe?(request: JobWatchProbeRequest): Promise<Record<string, unknown>>;
+    cancelJobWatchProbe?(watchId: string): void;
     start(options?: KernelStartOptions): Promise<void>;
     execute(code: string, opts?: ExecuteOptions): Promise<ExecuteResult>;
     shutdown(opts?: KernelShutdownOptions): Promise<boolean>;

package/dist/core/kernel/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/core/kernel/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { registerSessionResourceCleanup } from \"@ponythewhite/base-context-ai\";\nimport type { NativeRecoveryResponse } from \"../selective-recovery.js\";\nimport type { KernelBootstrapProgressHandler, KernelPythonSkill } from \"./bootstrap.js\";\nimport type { RestoreResult, SnapshotResult } from \"./state-snapshot.js\";\n\nexport const DEFAULT_MAX_OUTPUT_CHARS = 65536;\nexport const HOST_REQUEST_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const KERNEL_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;\nexport const SNAPSHOT_EXECUTION_TIMEOUT_MS = 5000;\nexport const KERNEL_ABORT_GRACE_MS = 1000;\nexport const KERNEL_BUSY_REUSE_WAIT_MS = 5000;\nexport const KERNEL_BUSY_INTERRUPT_INTERVAL_MS = 500;\nexport const MAX_LATE_SENT_AGENT_MESSAGE_HANDLERS = 256;\nconst KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE =\n\t\"The Python kernel is still running the previously interrupted cell. Wait and try again, or kill the kernel to start fresh.\";\n\nexport class KernelBusyAfterInterruptError extends Error {\n\tconstructor() {\n\t\tsuper(KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE);\n\t\tthis.name = \"KernelBusyAfterInterruptError\";\n\t}\n}\n\n/**\n * Handles one typed request from Python code running in the kernel.\n * The returned record is delivered verbatim to the Python caller.\n */\nexport interface HostRequestContext {\n\t/** Actual active tool/cell cancellation; never read from the Python payload. */\n\tsignal?: AbortSignal;\n\t/** A host-reserved share of this cell's aggregate recovery response budget. */\n\tnativeRecovery?: { maxBytes: number };\n}\n\nexport type HostRequestHandler = (\n\tpayload: Record<string, unknown>,\n\tcontext?: HostRequestContext,\n) => Promise<Record<string, unknown>>;\n\n/** Host request handlers keyed by request type (e.g. \"rlm.run\", \"goal.complete\"). */\nexport type HostRequestHandlers = Record<string, HostRequestHandler>;\n\n/** Where and how to persist the kernel's user namespace so it survives resume. */\nexport interface KernelSnapshotConfig {\n\t/** Absolute path for the dill payload. */\n\tpath: string;\n\t/** Absolute path for the JSON manifest written alongside the payload. */\n\tmanifestPath: string;\n\t/** Maximum aggregate snapshot size. Default 256 MiB. */\n\tmaxBytes?: number;\n\t/** Maximum serialized size of one variable. Default 16 MiB. */\n\tmaxVariableBytes?: number;\n\t/** Debounce window for the auto-snapshot after a successful execution. Default 1500 ms. */\n\tdebounceMs?: number;\n}\n\nexport interface KernelManagerOptions {\n\t/** Python interpreter with the kernel runtime available. Defaults to the auto-bootstrapped kernel. */\n\tpython?: string;\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tsessionId?: string;\n\thostHandlers?: HostRequestHandlers;\n\tpythonSkills?: readonly KernelPythonSkill[];\n\t/** Persist/revive the user namespace across kernel restarts and session resume. */\n\tsnapshot?: KernelSnapshotConfig;\n\t/** Runtime bootstrap re-run on a protocol-repaired kernel so live handles (rlm, bash, skills) exist again. */\n\tbootstrapCode?: string;\n\t/** File receiving the kernel process's stderr, rotated once at each spawn. */\n\tstderrLogPath?: string;\n}\n\nexport interface KernelStartOptions {\n\tonBootstrapProgress?: KernelBootstrapProgressHandler;\n\tsignal?: AbortSignal;\n}\n\nexport interface ExecuteOptions {\n\t/** Only a finalized ipython tool call can retain recovery output; not bootstrap/state cells. */\n\tnativeRecovery?: boolean;\n\t/** @internal Host-only closure captured by the admitted owned executor; never sent to Python. */\n\trunNativeRecovery?: <T>(read: () => Promise<T>) => Promise<T>;\n\t/** Aborting interrupts the kernel out-of-band. */\n\tsignal?: AbortSignal;\n\tonStream?: (chunk: string, name: \"stdout\" | \"stderr\") => void;\n\tonLateSentAgentMessage?: (message: KernelSentAgentMessage) => void;\n\t/** Cap stdout / stderr / result at this many characters. Default 65536. */\n\tmaxOutputChars?: number;\n\t/** Synthetic host cell (snapshot/restore/list); excluded from lastCellCode attribution. */\n\tinternal?: boolean;\n\t/** The protocol repair's own restore; exempt from waiting on the repair it belongs to. */\n\tprotocolRepair?: boolean;\n}\n\n/** MIME tag the `edit` skill emits diff payloads under. */\nexport const DIFF_DISPLAY_MIME = \"application/vnd.prime-agent.diff+json\";\n\n/** MIME tag the `attach-image` skill emits media payloads under. */\nexport const ATTACHMENT_DISPLAY_MIME = \"application/vnd.prime-agent.attachment+json\";\n\n/** MIME tag the `agent-message` skill emits after sending a message. */\nexport const AGENT_MESSAGE_DISPLAY_MIME = \"application/vnd.prime-agent.agent-message+json\";\n\n/**\n * Hard ceiling on a single attachment's base64 payload, a defensive guard\n * against a runaway direct display emit. The `attach-image` skill caps\n * its own images well under this (see `_MAX_IMAGE_BYTES`), so a skill-produced\n * attachment is never dropped here — only a non-skill emit can hit this.\n */\nexport const MAX_ATTACHMENT_DATA_CHARS = 10_000_000;\n\n/** One file edit, captured from a {@link DIFF_DISPLAY_MIME} display payload. */\nexport interface KernelDiffDisplay {\n\tpath: string;\n\toldStr: string;\n\tnewStr: string;\n\t/** 1-based line where `oldStr` begins in the file, for absolute line numbers. */\n\tstartLine?: number;\n}\n\n/** One media attachment, captured from an {@link ATTACHMENT_DISPLAY_MIME} display payload. */\nexport interface KernelAttachment {\n\tmimeType: string;\n\t/** base64-encoded bytes. */\n\tdata: string;\n\t/** Source path, surfaced to the TUI renderer. */\n\tpath?: string;\n}\n\nexport interface KernelSentAgentMessage {\n\tid: string;\n\tmessage: string;\n\tdeliveryStatus: \"delivered\" | \"queued\";\n\treceiverRole?: \"parent\" | \"sibling\" | \"child\";\n\ttarget: {\n\t\tactiveSessionId: string;\n\t\tsessionId: string;\n\t\tsessionName?: string;\n\t};\n}\n\nexport interface ExecuteResult {\n\t/** Whether the finalized textual output was captured without host truncation or interruption. */\n\toutputComplete?: boolean;\n\t/** Host-selected public data transferred once to the normal finalized ipython result. */\n\tnativeRecoveries?: NativeRecoveryResponse[];\n\tstdout: string;\n\tstderr: string;\n\t/** Text of the cell's trailing expression value, if the cell produced one. */\n\tresult?: string;\n\t/** Diffs emitted via display events, in order. */\n\tdiffs?: KernelDiffDisplay[];\n\t/** Media attachments emitted via display events, in order. */\n\tattachments?: KernelAttachment[];\n\t/** Agent messages sent from this cell, in order. */\n\tsentAgentMessages?: KernelSentAgentMessage[];\n\t/** Output that arrived without this cell's id (user threads, other cells' leftovers, raw fd writes). */\n\tbackgroundOutput?: string;\n\tstatus: \"ok\" | \"error\" | \"aborted\";\n\terror?: { ename: string; evalue: string; traceback: string[] };\n\tdurationMs: number;\n}\n\n/** Parse a {@link DIFF_DISPLAY_MIME} payload, tolerating malformed input. */\nexport function parseDiffDisplay(payload: unknown): KernelDiffDisplay | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { path, old_str: oldStr, new_str: newStr, start_line: startLine } = payload;\n\tif (typeof path !== \"string\" || typeof oldStr !== \"string\" || typeof newStr !== \"string\") {\n\t\treturn undefined;\n\t}\n\treturn { path, oldStr, newStr, startLine: typeof startLine === \"number\" ? startLine : undefined };\n}\n\n/**\n * Parse an {@link ATTACHMENT_DISPLAY_MIME} payload. Malformed payloads are\n * tolerantly ignored (`undefined`); a well-formed payload exceeding\n * {@link MAX_ATTACHMENT_DATA_CHARS} is reported as `\"oversized\"` so the caller\n * can fail the cell loudly rather than silently dropping the image.\n */\nexport function parseAttachmentDisplay(payload: unknown): KernelAttachment | \"oversized\" | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { mime_type: mimeType, data, path } = payload;\n\tif (typeof mimeType !== \"string\" || typeof data !== \"string\") {\n\t\treturn undefined;\n\t}\n\tif (data.length > MAX_ATTACHMENT_DATA_CHARS) {\n\t\treturn \"oversized\";\n\t}\n\treturn { mimeType, data, path: typeof path === \"string\" ? path : undefined };\n}\n\nexport function parseSentAgentMessage(payload: unknown): KernelSentAgentMessage | undefined {\n\tif (!isRecord(payload) || !isRecord(payload.target)) {\n\t\treturn undefined;\n\t}\n\tconst { id, message, deliveryStatus, receiverRole, target } = payload;\n\tconst { activeSessionId, sessionId, sessionName } = target;\n\tif (\n\t\ttypeof id !== \"string\" ||\n\t\ttypeof message !== \"string\" ||\n\t\t(deliveryStatus !== \"delivered\" && deliveryStatus !== \"queued\") ||\n\t\ttypeof activeSessionId !== \"string\" ||\n\t\ttypeof sessionId !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tid,\n\t\tmessage,\n\t\tdeliveryStatus,\n\t\t...(receiverRole === \"parent\" || receiverRole === \"sibling\" || receiverRole === \"child\" ? { receiverRole } : {}),\n\t\ttarget: {\n\t\t\tactiveSessionId,\n\t\t\tsessionId,\n\t\t\t...(typeof sessionName === \"string\" ? { sessionName } : {}),\n\t\t},\n\t};\n}\n\nexport function createKernelStartupAbortError(): Error {\n\treturn new Error(\"Kernel startup aborted\");\n}\n\nexport function raceStartupWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n\tif (!signal) {\n\t\treturn promise;\n\t}\n\tif (signal.aborted) {\n\t\treturn Promise.reject(createKernelStartupAbortError());\n\t}\n\treturn new Promise<T>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst cleanup = () => signal.removeEventListener(\"abort\", abort);\n\t\tconst abort = () => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(createKernelStartupAbortError());\n\t\t};\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tpromise.then(\n\t\t\t(value) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nexport interface Deferred<T> {\n\tpromise: Promise<T>;\n\tresolve: (value: T) => void;\n\treject: (error: Error) => void;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nexport function createDeferred<T>(): Deferred<T> {\n\tlet resolve!: (value: T) => void;\n\tlet reject!: (error: Error) => void;\n\tconst promise = new Promise<T>((promiseResolve, promiseReject) => {\n\t\tresolve = promiseResolve;\n\t\treject = promiseReject;\n\t});\n\treturn { promise, resolve, reject };\n}\n\nexport interface KernelShutdownOptions {\n\tsnapshot?: boolean;\n\tdrainHostRequests?: boolean;\n}\n\n/** A bounded owned lifecycle observation, not a namespace, restore, or live-health assertion. */\nexport interface KernelLifecycleState {\n\treadonly source: \"repl-manager\" | \"ipython-provisioner\" | \"unobserved\";\n\treadonly owner: string | null;\n\treadonly generation: number | null;\n\treadonly state: \"idle\" | \"starting\" | \"running\" | \"shutdown\" | \"provisioning\" | \"disposed\" | \"unobserved\";\n}\n\nexport interface CapturedKernelLifecycle {\n\treadonly snapshot: Readonly<KernelLifecycleState>;\n\t/** Checks the original observation; it never probes or substitutes a newer snapshot. */\n\tisCurrent(): boolean;\n}\n\n/** Public surface every kernel client exposes to the provisioner and session layer. */\nexport interface KernelClient {\n\treadonly ownerSessionId: string | undefined;\n\treadonly isRunning: boolean;\n\tstart(options?: KernelStartOptions): Promise<void>;\n\texecute(code: string, opts?: ExecuteOptions): Promise<ExecuteResult>;\n\tshutdown(opts?: KernelShutdownOptions): Promise<boolean>;\n\trestart(): Promise<void>;\n\tkill(): Promise<void>;\n\tdisposeSync(): void;\n\tsnapshotState(): Promise<SnapshotResult | null>;\n\tpruneOversizedVariables(): Promise<SnapshotResult | null>;\n\trestoreState(): Promise<RestoreResult | null>;\n\tlistNamespaceNames(signal?: AbortSignal): Promise<string[] | null>;\n}\n\n// One registry serves every client kind; two parallel registries would\n// double-install process signal handlers.\nexport const liveKernels = new Set<KernelClient>();\nlet signalHandlersInstalled = false;\n\nregisterSessionResourceCleanup((sessionId) => {\n\tfor (const k of liveKernels) {\n\t\tif (!sessionId || k.ownerSessionId === sessionId) {\n\t\t\tvoid k.shutdown({ snapshot: true, drainHostRequests: true });\n\t\t}\n\t}\n});\n\nexport function installSignalHandlersOnce(): void {\n\tif (signalHandlersInstalled) return;\n\tsignalHandlersInstalled = true;\n\n\tconst asyncShutdown = async (): Promise<void> => {\n\t\t// These paths can await, so flush the namespace snapshot before tearing down.\n\t\tawait Promise.allSettled([...liveKernels].map((k) => k.shutdown({ snapshot: true })));\n\t};\n\n\t// `beforeExit` and signal handlers can await async cleanup. `exit`\n\t// can only do sync work (Node won't run pending microtasks past it),\n\t// so it falls back to `disposeSync()` which kills the child synchronously.\n\tprocess.on(\"beforeExit\", () => {\n\t\tvoid asyncShutdown();\n\t});\n\tprocess.on(\"SIGINT\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(130));\n\t});\n\tprocess.on(\"SIGTERM\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(143));\n\t});\n\tprocess.on(\"exit\", () => {\n\t\tfor (const k of liveKernels) k.disposeSync();\n\t});\n}\n"]}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/core/kernel/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { registerSessionResourceCleanup } from \"@ponythewhite/base-context-ai\";\nimport type { NativeRecoveryResponse } from \"../selective-recovery.js\";\nimport type { KernelBootstrapProgressHandler, KernelPythonSkill } from \"./bootstrap.js\";\nimport type { RestoreResult, SnapshotResult } from \"./state-snapshot.js\";\n\nexport const DEFAULT_MAX_OUTPUT_CHARS = 65536;\nexport const HOST_REQUEST_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const KERNEL_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;\nexport const SNAPSHOT_EXECUTION_TIMEOUT_MS = 5000;\nexport const KERNEL_ABORT_GRACE_MS = 1000;\nexport const KERNEL_BUSY_REUSE_WAIT_MS = 5000;\nexport const KERNEL_BUSY_INTERRUPT_INTERVAL_MS = 500;\nexport const MAX_LATE_SENT_AGENT_MESSAGE_HANDLERS = 256;\nconst KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE =\n\t\"The Python kernel is still running the previously interrupted cell. Wait and try again, or kill the kernel to start fresh.\";\n\nexport class KernelBusyAfterInterruptError extends Error {\n\tconstructor() {\n\t\tsuper(KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE);\n\t\tthis.name = \"KernelBusyAfterInterruptError\";\n\t}\n}\n\n/**\n * Handles one typed request from Python code running in the kernel.\n * The returned record is delivered verbatim to the Python caller.\n */\nexport interface HostRequestContext {\n\t/** Actual active tool/cell cancellation; never read from the Python payload. */\n\tsignal?: AbortSignal;\n\t/** A host-reserved share of this cell's aggregate recovery response budget. */\n\tnativeRecovery?: { maxBytes: number };\n}\n\nexport type HostRequestHandler = (\n\tpayload: Record<string, unknown>,\n\tcontext?: HostRequestContext,\n) => Promise<Record<string, unknown>>;\n\n/** Host request handlers keyed by request type (e.g. \"rlm.run\", \"goal.complete\"). */\nexport type HostRequestHandlers = Record<string, HostRequestHandler>;\n\n/** Where and how to persist the kernel's user namespace so it survives resume. */\nexport interface KernelSnapshotConfig {\n\t/** Absolute path for the dill payload. */\n\tpath: string;\n\t/** Absolute path for the JSON manifest written alongside the payload. */\n\tmanifestPath: string;\n\t/** Maximum aggregate snapshot size. Default 256 MiB. */\n\tmaxBytes?: number;\n\t/** Maximum serialized size of one variable. Default 16 MiB. */\n\tmaxVariableBytes?: number;\n\t/** Debounce window for the auto-snapshot after a successful execution. Default 1500 ms. */\n\tdebounceMs?: number;\n}\n\nexport interface KernelManagerOptions {\n\t/** Python interpreter with the kernel runtime available. Defaults to the auto-bootstrapped kernel. */\n\tpython?: string;\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tsessionId?: string;\n\thostHandlers?: HostRequestHandlers;\n\tpythonSkills?: readonly KernelPythonSkill[];\n\t/** Persist/revive the user namespace across kernel restarts and session resume. */\n\tsnapshot?: KernelSnapshotConfig;\n\t/** Runtime bootstrap re-run on a protocol-repaired kernel so live handles (rlm, bash, skills) exist again. */\n\tbootstrapCode?: string;\n\t/** File receiving the kernel process's stderr, rotated once at each spawn. */\n\tstderrLogPath?: string;\n}\n\nexport interface KernelStartOptions {\n\tonBootstrapProgress?: KernelBootstrapProgressHandler;\n\tsignal?: AbortSignal;\n}\n\nexport interface ExecuteOptions {\n\t/** Only a finalized ipython tool call can retain recovery output; not bootstrap/state cells. */\n\tnativeRecovery?: boolean;\n\t/** @internal Host-only closure captured by the admitted owned executor; never sent to Python. */\n\trunNativeRecovery?: <T>(read: () => Promise<T>) => Promise<T>;\n\t/** Aborting interrupts the kernel out-of-band. */\n\tsignal?: AbortSignal;\n\tonStream?: (chunk: string, name: \"stdout\" | \"stderr\") => void;\n\tonLateSentAgentMessage?: (message: KernelSentAgentMessage) => void;\n\t/** Cap stdout / stderr / result at this many characters. Default 65536. */\n\tmaxOutputChars?: number;\n\t/** Synthetic host cell (snapshot/restore/list); excluded from lastCellCode attribution. */\n\tinternal?: boolean;\n\t/** The protocol repair's own restore; exempt from waiting on the repair it belongs to. */\n\tprotocolRepair?: boolean;\n}\n\n/** MIME tag the `edit` skill emits diff payloads under. */\nexport const DIFF_DISPLAY_MIME = \"application/vnd.prime-agent.diff+json\";\n\n/** MIME tag the `attach-image` skill emits media payloads under. */\nexport const ATTACHMENT_DISPLAY_MIME = \"application/vnd.prime-agent.attachment+json\";\n\n/** MIME tag the `agent-message` skill emits after sending a message. */\nexport const AGENT_MESSAGE_DISPLAY_MIME = \"application/vnd.prime-agent.agent-message+json\";\n\n/**\n * Hard ceiling on a single attachment's base64 payload, a defensive guard\n * against a runaway direct display emit. The `attach-image` skill caps\n * its own images well under this (see `_MAX_IMAGE_BYTES`), so a skill-produced\n * attachment is never dropped here — only a non-skill emit can hit this.\n */\nexport const MAX_ATTACHMENT_DATA_CHARS = 10_000_000;\n\n/** One file edit, captured from a {@link DIFF_DISPLAY_MIME} display payload. */\nexport interface KernelDiffDisplay {\n\tpath: string;\n\toldStr: string;\n\tnewStr: string;\n\t/** 1-based line where `oldStr` begins in the file, for absolute line numbers. */\n\tstartLine?: number;\n}\n\n/** One media attachment, captured from an {@link ATTACHMENT_DISPLAY_MIME} display payload. */\nexport interface KernelAttachment {\n\tmimeType: string;\n\t/** base64-encoded bytes. */\n\tdata: string;\n\t/** Source path, surfaced to the TUI renderer. */\n\tpath?: string;\n}\n\nexport interface KernelSentAgentMessage {\n\tid: string;\n\tmessage: string;\n\tdeliveryStatus: \"delivered\" | \"queued\";\n\treceiverRole?: \"parent\" | \"sibling\" | \"child\";\n\ttarget: {\n\t\tactiveSessionId: string;\n\t\tsessionId: string;\n\t\tsessionName?: string;\n\t};\n}\n\nexport interface ExecuteResult {\n\t/** Whether the finalized textual output was captured without host truncation or interruption. */\n\toutputComplete?: boolean;\n\t/** Host-selected public data transferred once to the normal finalized ipython result. */\n\tnativeRecoveries?: NativeRecoveryResponse[];\n\tstdout: string;\n\tstderr: string;\n\t/** Text of the cell's trailing expression value, if the cell produced one. */\n\tresult?: string;\n\t/** Diffs emitted via display events, in order. */\n\tdiffs?: KernelDiffDisplay[];\n\t/** Media attachments emitted via display events, in order. */\n\tattachments?: KernelAttachment[];\n\t/** Agent messages sent from this cell, in order. */\n\tsentAgentMessages?: KernelSentAgentMessage[];\n\t/** Output that arrived without this cell's id (user threads, other cells' leftovers, raw fd writes). */\n\tbackgroundOutput?: string;\n\tstatus: \"ok\" | \"error\" | \"aborted\";\n\terror?: { ename: string; evalue: string; traceback: string[] };\n\tdurationMs: number;\n}\n\n/** Parse a {@link DIFF_DISPLAY_MIME} payload, tolerating malformed input. */\nexport function parseDiffDisplay(payload: unknown): KernelDiffDisplay | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { path, old_str: oldStr, new_str: newStr, start_line: startLine } = payload;\n\tif (typeof path !== \"string\" || typeof oldStr !== \"string\" || typeof newStr !== \"string\") {\n\t\treturn undefined;\n\t}\n\treturn { path, oldStr, newStr, startLine: typeof startLine === \"number\" ? startLine : undefined };\n}\n\n/**\n * Parse an {@link ATTACHMENT_DISPLAY_MIME} payload. Malformed payloads are\n * tolerantly ignored (`undefined`); a well-formed payload exceeding\n * {@link MAX_ATTACHMENT_DATA_CHARS} is reported as `\"oversized\"` so the caller\n * can fail the cell loudly rather than silently dropping the image.\n */\nexport function parseAttachmentDisplay(payload: unknown): KernelAttachment | \"oversized\" | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { mime_type: mimeType, data, path } = payload;\n\tif (typeof mimeType !== \"string\" || typeof data !== \"string\") {\n\t\treturn undefined;\n\t}\n\tif (data.length > MAX_ATTACHMENT_DATA_CHARS) {\n\t\treturn \"oversized\";\n\t}\n\treturn { mimeType, data, path: typeof path === \"string\" ? path : undefined };\n}\n\nexport function parseSentAgentMessage(payload: unknown): KernelSentAgentMessage | undefined {\n\tif (!isRecord(payload) || !isRecord(payload.target)) {\n\t\treturn undefined;\n\t}\n\tconst { id, message, deliveryStatus, receiverRole, target } = payload;\n\tconst { activeSessionId, sessionId, sessionName } = target;\n\tif (\n\t\ttypeof id !== \"string\" ||\n\t\ttypeof message !== \"string\" ||\n\t\t(deliveryStatus !== \"delivered\" && deliveryStatus !== \"queued\") ||\n\t\ttypeof activeSessionId !== \"string\" ||\n\t\ttypeof sessionId !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tid,\n\t\tmessage,\n\t\tdeliveryStatus,\n\t\t...(receiverRole === \"parent\" || receiverRole === \"sibling\" || receiverRole === \"child\" ? { receiverRole } : {}),\n\t\ttarget: {\n\t\t\tactiveSessionId,\n\t\t\tsessionId,\n\t\t\t...(typeof sessionName === \"string\" ? { sessionName } : {}),\n\t\t},\n\t};\n}\n\nexport function createKernelStartupAbortError(): Error {\n\treturn new Error(\"Kernel startup aborted\");\n}\n\nexport function raceStartupWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n\tif (!signal) {\n\t\treturn promise;\n\t}\n\tif (signal.aborted) {\n\t\treturn Promise.reject(createKernelStartupAbortError());\n\t}\n\treturn new Promise<T>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst cleanup = () => signal.removeEventListener(\"abort\", abort);\n\t\tconst abort = () => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(createKernelStartupAbortError());\n\t\t};\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tpromise.then(\n\t\t\t(value) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nexport interface Deferred<T> {\n\tpromise: Promise<T>;\n\tresolve: (value: T) => void;\n\treject: (error: Error) => void;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nexport function createDeferred<T>(): Deferred<T> {\n\tlet resolve!: (value: T) => void;\n\tlet reject!: (error: Error) => void;\n\tconst promise = new Promise<T>((promiseResolve, promiseReject) => {\n\t\tresolve = promiseResolve;\n\t\treject = promiseReject;\n\t});\n\treturn { promise, resolve, reject };\n}\n\nexport interface KernelShutdownOptions {\n\tsnapshot?: boolean;\n\tdrainHostRequests?: boolean;\n}\n\n/** A bounded owned lifecycle observation, not a namespace, restore, or live-health assertion. */\nexport interface KernelLifecycleState {\n\treadonly source: \"repl-manager\" | \"ipython-provisioner\" | \"unobserved\";\n\treadonly owner: string | null;\n\treadonly generation: number | null;\n\treadonly state: \"idle\" | \"starting\" | \"running\" | \"shutdown\" | \"provisioning\" | \"disposed\" | \"unobserved\";\n}\n\nexport interface CapturedKernelLifecycle {\n\treadonly snapshot: Readonly<KernelLifecycleState>;\n\t/** Checks the original observation; it never probes or substitutes a newer snapshot. */\n\tisCurrent(): boolean;\n}\n\nexport interface JobWatchProbeRequest {\n\twatchId: string;\n\tgeneration: string;\n\tresourceId: string;\n\tjobId: string;\n\tcompletionSource?: \"handle\" | \"probe\";\n\tcommand: string | null;\n\ttimeoutMs: number;\n}\n\n/** Public surface every kernel client exposes to the provisioner and session layer. */\nexport interface KernelClient {\n\treadonly ownerSessionId: string | undefined;\n\treadonly isRunning: boolean;\n\t/** Optional job_watch_probe_v1 capability. Never evaluates a notebook cell. */\n\tjobWatchProbe?(request: JobWatchProbeRequest): Promise<Record<string, unknown>>;\n\tcancelJobWatchProbe?(watchId: string): void;\n\tstart(options?: KernelStartOptions): Promise<void>;\n\texecute(code: string, opts?: ExecuteOptions): Promise<ExecuteResult>;\n\tshutdown(opts?: KernelShutdownOptions): Promise<boolean>;\n\trestart(): Promise<void>;\n\tkill(): Promise<void>;\n\tdisposeSync(): void;\n\tsnapshotState(): Promise<SnapshotResult | null>;\n\tpruneOversizedVariables(): Promise<SnapshotResult | null>;\n\trestoreState(): Promise<RestoreResult | null>;\n\tlistNamespaceNames(signal?: AbortSignal): Promise<string[] | null>;\n}\n\n// One registry serves every client kind; two parallel registries would\n// double-install process signal handlers.\nexport const liveKernels = new Set<KernelClient>();\nlet signalHandlersInstalled = false;\n\nregisterSessionResourceCleanup((sessionId) => {\n\tfor (const k of liveKernels) {\n\t\tif (!sessionId || k.ownerSessionId === sessionId) {\n\t\t\tvoid k.shutdown({ snapshot: true, drainHostRequests: true });\n\t\t}\n\t}\n});\n\nexport function installSignalHandlersOnce(): void {\n\tif (signalHandlersInstalled) return;\n\tsignalHandlersInstalled = true;\n\n\tconst asyncShutdown = async (): Promise<void> => {\n\t\t// These paths can await, so flush the namespace snapshot before tearing down.\n\t\tawait Promise.allSettled([...liveKernels].map((k) => k.shutdown({ snapshot: true })));\n\t};\n\n\t// `beforeExit` and signal handlers can await async cleanup. `exit`\n\t// can only do sync work (Node won't run pending microtasks past it),\n\t// so it falls back to `disposeSync()` which kills the child synchronously.\n\tprocess.on(\"beforeExit\", () => {\n\t\tvoid asyncShutdown();\n\t});\n\tprocess.on(\"SIGINT\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(130));\n\t});\n\tprocess.on(\"SIGTERM\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(143));\n\t});\n\tprocess.on(\"exit\", () => {\n\t\tfor (const k of liveKernels) k.disposeSync();\n\t});\n}\n"]}

package/dist/core/kernel/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/core/kernel/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { registerSessionResourceCleanup } from \"@ponythewhite/base-context-ai\";\nimport type { NativeRecoveryResponse } from \"../selective-recovery.js\";\nimport type { KernelBootstrapProgressHandler, KernelPythonSkill } from \"./bootstrap.js\";\nimport type { RestoreResult, SnapshotResult } from \"./state-snapshot.js\";\n\nexport const DEFAULT_MAX_OUTPUT_CHARS = 65536;\nexport const HOST_REQUEST_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const KERNEL_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;\nexport const SNAPSHOT_EXECUTION_TIMEOUT_MS = 5000;\nexport const KERNEL_ABORT_GRACE_MS = 1000;\nexport const KERNEL_BUSY_REUSE_WAIT_MS = 5000;\nexport const KERNEL_BUSY_INTERRUPT_INTERVAL_MS = 500;\nexport const MAX_LATE_SENT_AGENT_MESSAGE_HANDLERS = 256;\nconst KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE =\n\t\"The Python kernel is still running the previously interrupted cell. Wait and try again, or kill the kernel to start fresh.\";\n\nexport class KernelBusyAfterInterruptError extends Error {\n\tconstructor() {\n\t\tsuper(KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE);\n\t\tthis.name = \"KernelBusyAfterInterruptError\";\n\t}\n}\n\n/**\n * Handles one typed request from Python code running in the kernel.\n * The returned record is delivered verbatim to the Python caller.\n */\nexport interface HostRequestContext {\n\t/** Actual active tool/cell cancellation; never read from the Python payload. */\n\tsignal?: AbortSignal;\n\t/** A host-reserved share of this cell's aggregate recovery response budget. */\n\tnativeRecovery?: { maxBytes: number };\n}\n\nexport type HostRequestHandler = (\n\tpayload: Record<string, unknown>,\n\tcontext?: HostRequestContext,\n) => Promise<Record<string, unknown>>;\n\n/** Host request handlers keyed by request type (e.g. \"rlm.run\", \"goal.complete\"). */\nexport type HostRequestHandlers = Record<string, HostRequestHandler>;\n\n/** Where and how to persist the kernel's user namespace so it survives resume. */\nexport interface KernelSnapshotConfig {\n\t/** Absolute path for the dill payload. */\n\tpath: string;\n\t/** Absolute path for the JSON manifest written alongside the payload. */\n\tmanifestPath: string;\n\t/** Maximum aggregate snapshot size. Default 256 MiB. */\n\tmaxBytes?: number;\n\t/** Maximum serialized size of one variable. Default 16 MiB. */\n\tmaxVariableBytes?: number;\n\t/** Debounce window for the auto-snapshot after a successful execution. Default 1500 ms. */\n\tdebounceMs?: number;\n}\n\nexport interface KernelManagerOptions {\n\t/** Python interpreter with the kernel runtime available. Defaults to the auto-bootstrapped kernel. */\n\tpython?: string;\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tsessionId?: string;\n\thostHandlers?: HostRequestHandlers;\n\tpythonSkills?: readonly KernelPythonSkill[];\n\t/** Persist/revive the user namespace across kernel restarts and session resume. */\n\tsnapshot?: KernelSnapshotConfig;\n\t/** Runtime bootstrap re-run on a protocol-repaired kernel so live handles (rlm, bash, skills) exist again. */\n\tbootstrapCode?: string;\n\t/** File receiving the kernel process's stderr, rotated once at each spawn. */\n\tstderrLogPath?: string;\n}\n\nexport interface KernelStartOptions {\n\tonBootstrapProgress?: KernelBootstrapProgressHandler;\n\tsignal?: AbortSignal;\n}\n\nexport interface ExecuteOptions {\n\t/** Only a finalized ipython tool call can retain recovery output; not bootstrap/state cells. */\n\tnativeRecovery?: boolean;\n\t/** @internal Host-only closure captured by the admitted owned executor; never sent to Python. */\n\trunNativeRecovery?: <T>(read: () => Promise<T>) => Promise<T>;\n\t/** Aborting interrupts the kernel out-of-band. */\n\tsignal?: AbortSignal;\n\tonStream?: (chunk: string, name: \"stdout\" | \"stderr\") => void;\n\tonLateSentAgentMessage?: (message: KernelSentAgentMessage) => void;\n\t/** Cap stdout / stderr / result at this many characters. Default 65536. */\n\tmaxOutputChars?: number;\n\t/** Synthetic host cell (snapshot/restore/list); excluded from lastCellCode attribution. */\n\tinternal?: boolean;\n\t/** The protocol repair's own restore; exempt from waiting on the repair it belongs to. */\n\tprotocolRepair?: boolean;\n}\n\n/** MIME tag the `edit` skill emits diff payloads under. */\nexport const DIFF_DISPLAY_MIME = \"application/vnd.prime-agent.diff+json\";\n\n/** MIME tag the `attach-image` skill emits media payloads under. */\nexport const ATTACHMENT_DISPLAY_MIME = \"application/vnd.prime-agent.attachment+json\";\n\n/** MIME tag the `agent-message` skill emits after sending a message. */\nexport const AGENT_MESSAGE_DISPLAY_MIME = \"application/vnd.prime-agent.agent-message+json\";\n\n/**\n * Hard ceiling on a single attachment's base64 payload, a defensive guard\n * against a runaway direct display emit. The `attach-image` skill caps\n * its own images well under this (see `_MAX_IMAGE_BYTES`), so a skill-produced\n * attachment is never dropped here — only a non-skill emit can hit this.\n */\nexport const MAX_ATTACHMENT_DATA_CHARS = 10_000_000;\n\n/** One file edit, captured from a {@link DIFF_DISPLAY_MIME} display payload. */\nexport interface KernelDiffDisplay {\n\tpath: string;\n\toldStr: string;\n\tnewStr: string;\n\t/** 1-based line where `oldStr` begins in the file, for absolute line numbers. */\n\tstartLine?: number;\n}\n\n/** One media attachment, captured from an {@link ATTACHMENT_DISPLAY_MIME} display payload. */\nexport interface KernelAttachment {\n\tmimeType: string;\n\t/** base64-encoded bytes. */\n\tdata: string;\n\t/** Source path, surfaced to the TUI renderer. */\n\tpath?: string;\n}\n\nexport interface KernelSentAgentMessage {\n\tid: string;\n\tmessage: string;\n\tdeliveryStatus: \"delivered\" | \"queued\";\n\treceiverRole?: \"parent\" | \"sibling\" | \"child\";\n\ttarget: {\n\t\tactiveSessionId: string;\n\t\tsessionId: string;\n\t\tsessionName?: string;\n\t};\n}\n\nexport interface ExecuteResult {\n\t/** Whether the finalized textual output was captured without host truncation or interruption. */\n\toutputComplete?: boolean;\n\t/** Host-selected public data transferred once to the normal finalized ipython result. */\n\tnativeRecoveries?: NativeRecoveryResponse[];\n\tstdout: string;\n\tstderr: string;\n\t/** Text of the cell's trailing expression value, if the cell produced one. */\n\tresult?: string;\n\t/** Diffs emitted via display events, in order. */\n\tdiffs?: KernelDiffDisplay[];\n\t/** Media attachments emitted via display events, in order. */\n\tattachments?: KernelAttachment[];\n\t/** Agent messages sent from this cell, in order. */\n\tsentAgentMessages?: KernelSentAgentMessage[];\n\t/** Output that arrived without this cell's id (user threads, other cells' leftovers, raw fd writes). */\n\tbackgroundOutput?: string;\n\tstatus: \"ok\" | \"error\" | \"aborted\";\n\terror?: { ename: string; evalue: string; traceback: string[] };\n\tdurationMs: number;\n}\n\n/** Parse a {@link DIFF_DISPLAY_MIME} payload, tolerating malformed input. */\nexport function parseDiffDisplay(payload: unknown): KernelDiffDisplay | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { path, old_str: oldStr, new_str: newStr, start_line: startLine } = payload;\n\tif (typeof path !== \"string\" || typeof oldStr !== \"string\" || typeof newStr !== \"string\") {\n\t\treturn undefined;\n\t}\n\treturn { path, oldStr, newStr, startLine: typeof startLine === \"number\" ? startLine : undefined };\n}\n\n/**\n * Parse an {@link ATTACHMENT_DISPLAY_MIME} payload. Malformed payloads are\n * tolerantly ignored (`undefined`); a well-formed payload exceeding\n * {@link MAX_ATTACHMENT_DATA_CHARS} is reported as `\"oversized\"` so the caller\n * can fail the cell loudly rather than silently dropping the image.\n */\nexport function parseAttachmentDisplay(payload: unknown): KernelAttachment | \"oversized\" | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { mime_type: mimeType, data, path } = payload;\n\tif (typeof mimeType !== \"string\" || typeof data !== \"string\") {\n\t\treturn undefined;\n\t}\n\tif (data.length > MAX_ATTACHMENT_DATA_CHARS) {\n\t\treturn \"oversized\";\n\t}\n\treturn { mimeType, data, path: typeof path === \"string\" ? path : undefined };\n}\n\nexport function parseSentAgentMessage(payload: unknown): KernelSentAgentMessage | undefined {\n\tif (!isRecord(payload) || !isRecord(payload.target)) {\n\t\treturn undefined;\n\t}\n\tconst { id, message, deliveryStatus, receiverRole, target } = payload;\n\tconst { activeSessionId, sessionId, sessionName } = target;\n\tif (\n\t\ttypeof id !== \"string\" ||\n\t\ttypeof message !== \"string\" ||\n\t\t(deliveryStatus !== \"delivered\" && deliveryStatus !== \"queued\") ||\n\t\ttypeof activeSessionId !== \"string\" ||\n\t\ttypeof sessionId !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tid,\n\t\tmessage,\n\t\tdeliveryStatus,\n\t\t...(receiverRole === \"parent\" || receiverRole === \"sibling\" || receiverRole === \"child\" ? { receiverRole } : {}),\n\t\ttarget: {\n\t\t\tactiveSessionId,\n\t\t\tsessionId,\n\t\t\t...(typeof sessionName === \"string\" ? { sessionName } : {}),\n\t\t},\n\t};\n}\n\nexport function createKernelStartupAbortError(): Error {\n\treturn new Error(\"Kernel startup aborted\");\n}\n\nexport function raceStartupWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n\tif (!signal) {\n\t\treturn promise;\n\t}\n\tif (signal.aborted) {\n\t\treturn Promise.reject(createKernelStartupAbortError());\n\t}\n\treturn new Promise<T>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst cleanup = () => signal.removeEventListener(\"abort\", abort);\n\t\tconst abort = () => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(createKernelStartupAbortError());\n\t\t};\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tpromise.then(\n\t\t\t(value) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nexport interface Deferred<T> {\n\tpromise: Promise<T>;\n\tresolve: (value: T) => void;\n\treject: (error: Error) => void;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nexport function createDeferred<T>(): Deferred<T> {\n\tlet resolve!: (value: T) => void;\n\tlet reject!: (error: Error) => void;\n\tconst promise = new Promise<T>((promiseResolve, promiseReject) => {\n\t\tresolve = promiseResolve;\n\t\treject = promiseReject;\n\t});\n\treturn { promise, resolve, reject };\n}\n\nexport interface KernelShutdownOptions {\n\tsnapshot?: boolean;\n\tdrainHostRequests?: boolean;\n}\n\n/** A bounded owned lifecycle observation, not a namespace, restore, or live-health assertion. */\nexport interface KernelLifecycleState {\n\treadonly source: \"repl-manager\" | \"ipython-provisioner\" | \"unobserved\";\n\treadonly owner: string | null;\n\treadonly generation: number | null;\n\treadonly state: \"idle\" | \"starting\" | \"running\" | \"shutdown\" | \"provisioning\" | \"disposed\" | \"unobserved\";\n}\n\nexport interface CapturedKernelLifecycle {\n\treadonly snapshot: Readonly<KernelLifecycleState>;\n\t/** Checks the original observation; it never probes or substitutes a newer snapshot. */\n\tisCurrent(): boolean;\n}\n\n/** Public surface every kernel client exposes to the provisioner and session layer. */\nexport interface KernelClient {\n\treadonly ownerSessionId: string | undefined;\n\treadonly isRunning: boolean;\n\tstart(options?: KernelStartOptions): Promise<void>;\n\texecute(code: string, opts?: ExecuteOptions): Promise<ExecuteResult>;\n\tshutdown(opts?: KernelShutdownOptions): Promise<boolean>;\n\trestart(): Promise<void>;\n\tkill(): Promise<void>;\n\tdisposeSync(): void;\n\tsnapshotState(): Promise<SnapshotResult | null>;\n\tpruneOversizedVariables(): Promise<SnapshotResult | null>;\n\trestoreState(): Promise<RestoreResult | null>;\n\tlistNamespaceNames(signal?: AbortSignal): Promise<string[] | null>;\n}\n\n// One registry serves every client kind; two parallel registries would\n// double-install process signal handlers.\nexport const liveKernels = new Set<KernelClient>();\nlet signalHandlersInstalled = false;\n\nregisterSessionResourceCleanup((sessionId) => {\n\tfor (const k of liveKernels) {\n\t\tif (!sessionId || k.ownerSessionId === sessionId) {\n\t\t\tvoid k.shutdown({ snapshot: true, drainHostRequests: true });\n\t\t}\n\t}\n});\n\nexport function installSignalHandlersOnce(): void {\n\tif (signalHandlersInstalled) return;\n\tsignalHandlersInstalled = true;\n\n\tconst asyncShutdown = async (): Promise<void> => {\n\t\t// These paths can await, so flush the namespace snapshot before tearing down.\n\t\tawait Promise.allSettled([...liveKernels].map((k) => k.shutdown({ snapshot: true })));\n\t};\n\n\t// `beforeExit` and signal handlers can await async cleanup. `exit`\n\t// can only do sync work (Node won't run pending microtasks past it),\n\t// so it falls back to `disposeSync()` which kills the child synchronously.\n\tprocess.on(\"beforeExit\", () => {\n\t\tvoid asyncShutdown();\n\t});\n\tprocess.on(\"SIGINT\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(130));\n\t});\n\tprocess.on(\"SIGTERM\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(143));\n\t});\n\tprocess.on(\"exit\", () => {\n\t\tfor (const k of liveKernels) k.disposeSync();\n\t});\n}\n"]}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/core/kernel/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { registerSessionResourceCleanup } from \"@ponythewhite/base-context-ai\";\nimport type { NativeRecoveryResponse } from \"../selective-recovery.js\";\nimport type { KernelBootstrapProgressHandler, KernelPythonSkill } from \"./bootstrap.js\";\nimport type { RestoreResult, SnapshotResult } from \"./state-snapshot.js\";\n\nexport const DEFAULT_MAX_OUTPUT_CHARS = 65536;\nexport const HOST_REQUEST_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const KERNEL_SHUTDOWN_TIMEOUT_MS = 5000;\nexport const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;\nexport const SNAPSHOT_EXECUTION_TIMEOUT_MS = 5000;\nexport const KERNEL_ABORT_GRACE_MS = 1000;\nexport const KERNEL_BUSY_REUSE_WAIT_MS = 5000;\nexport const KERNEL_BUSY_INTERRUPT_INTERVAL_MS = 500;\nexport const MAX_LATE_SENT_AGENT_MESSAGE_HANDLERS = 256;\nconst KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE =\n\t\"The Python kernel is still running the previously interrupted cell. Wait and try again, or kill the kernel to start fresh.\";\n\nexport class KernelBusyAfterInterruptError extends Error {\n\tconstructor() {\n\t\tsuper(KERNEL_BUSY_AFTER_INTERRUPT_MESSAGE);\n\t\tthis.name = \"KernelBusyAfterInterruptError\";\n\t}\n}\n\n/**\n * Handles one typed request from Python code running in the kernel.\n * The returned record is delivered verbatim to the Python caller.\n */\nexport interface HostRequestContext {\n\t/** Actual active tool/cell cancellation; never read from the Python payload. */\n\tsignal?: AbortSignal;\n\t/** A host-reserved share of this cell's aggregate recovery response budget. */\n\tnativeRecovery?: { maxBytes: number };\n}\n\nexport type HostRequestHandler = (\n\tpayload: Record<string, unknown>,\n\tcontext?: HostRequestContext,\n) => Promise<Record<string, unknown>>;\n\n/** Host request handlers keyed by request type (e.g. \"rlm.run\", \"goal.complete\"). */\nexport type HostRequestHandlers = Record<string, HostRequestHandler>;\n\n/** Where and how to persist the kernel's user namespace so it survives resume. */\nexport interface KernelSnapshotConfig {\n\t/** Absolute path for the dill payload. */\n\tpath: string;\n\t/** Absolute path for the JSON manifest written alongside the payload. */\n\tmanifestPath: string;\n\t/** Maximum aggregate snapshot size. Default 256 MiB. */\n\tmaxBytes?: number;\n\t/** Maximum serialized size of one variable. Default 16 MiB. */\n\tmaxVariableBytes?: number;\n\t/** Debounce window for the auto-snapshot after a successful execution. Default 1500 ms. */\n\tdebounceMs?: number;\n}\n\nexport interface KernelManagerOptions {\n\t/** Python interpreter with the kernel runtime available. Defaults to the auto-bootstrapped kernel. */\n\tpython?: string;\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tsessionId?: string;\n\thostHandlers?: HostRequestHandlers;\n\tpythonSkills?: readonly KernelPythonSkill[];\n\t/** Persist/revive the user namespace across kernel restarts and session resume. */\n\tsnapshot?: KernelSnapshotConfig;\n\t/** Runtime bootstrap re-run on a protocol-repaired kernel so live handles (rlm, bash, skills) exist again. */\n\tbootstrapCode?: string;\n\t/** File receiving the kernel process's stderr, rotated once at each spawn. */\n\tstderrLogPath?: string;\n}\n\nexport interface KernelStartOptions {\n\tonBootstrapProgress?: KernelBootstrapProgressHandler;\n\tsignal?: AbortSignal;\n}\n\nexport interface ExecuteOptions {\n\t/** Only a finalized ipython tool call can retain recovery output; not bootstrap/state cells. */\n\tnativeRecovery?: boolean;\n\t/** @internal Host-only closure captured by the admitted owned executor; never sent to Python. */\n\trunNativeRecovery?: <T>(read: () => Promise<T>) => Promise<T>;\n\t/** Aborting interrupts the kernel out-of-band. */\n\tsignal?: AbortSignal;\n\tonStream?: (chunk: string, name: \"stdout\" | \"stderr\") => void;\n\tonLateSentAgentMessage?: (message: KernelSentAgentMessage) => void;\n\t/** Cap stdout / stderr / result at this many characters. Default 65536. */\n\tmaxOutputChars?: number;\n\t/** Synthetic host cell (snapshot/restore/list); excluded from lastCellCode attribution. */\n\tinternal?: boolean;\n\t/** The protocol repair's own restore; exempt from waiting on the repair it belongs to. */\n\tprotocolRepair?: boolean;\n}\n\n/** MIME tag the `edit` skill emits diff payloads under. */\nexport const DIFF_DISPLAY_MIME = \"application/vnd.prime-agent.diff+json\";\n\n/** MIME tag the `attach-image` skill emits media payloads under. */\nexport const ATTACHMENT_DISPLAY_MIME = \"application/vnd.prime-agent.attachment+json\";\n\n/** MIME tag the `agent-message` skill emits after sending a message. */\nexport const AGENT_MESSAGE_DISPLAY_MIME = \"application/vnd.prime-agent.agent-message+json\";\n\n/**\n * Hard ceiling on a single attachment's base64 payload, a defensive guard\n * against a runaway direct display emit. The `attach-image` skill caps\n * its own images well under this (see `_MAX_IMAGE_BYTES`), so a skill-produced\n * attachment is never dropped here — only a non-skill emit can hit this.\n */\nexport const MAX_ATTACHMENT_DATA_CHARS = 10_000_000;\n\n/** One file edit, captured from a {@link DIFF_DISPLAY_MIME} display payload. */\nexport interface KernelDiffDisplay {\n\tpath: string;\n\toldStr: string;\n\tnewStr: string;\n\t/** 1-based line where `oldStr` begins in the file, for absolute line numbers. */\n\tstartLine?: number;\n}\n\n/** One media attachment, captured from an {@link ATTACHMENT_DISPLAY_MIME} display payload. */\nexport interface KernelAttachment {\n\tmimeType: string;\n\t/** base64-encoded bytes. */\n\tdata: string;\n\t/** Source path, surfaced to the TUI renderer. */\n\tpath?: string;\n}\n\nexport interface KernelSentAgentMessage {\n\tid: string;\n\tmessage: string;\n\tdeliveryStatus: \"delivered\" | \"queued\";\n\treceiverRole?: \"parent\" | \"sibling\" | \"child\";\n\ttarget: {\n\t\tactiveSessionId: string;\n\t\tsessionId: string;\n\t\tsessionName?: string;\n\t};\n}\n\nexport interface ExecuteResult {\n\t/** Whether the finalized textual output was captured without host truncation or interruption. */\n\toutputComplete?: boolean;\n\t/** Host-selected public data transferred once to the normal finalized ipython result. */\n\tnativeRecoveries?: NativeRecoveryResponse[];\n\tstdout: string;\n\tstderr: string;\n\t/** Text of the cell's trailing expression value, if the cell produced one. */\n\tresult?: string;\n\t/** Diffs emitted via display events, in order. */\n\tdiffs?: KernelDiffDisplay[];\n\t/** Media attachments emitted via display events, in order. */\n\tattachments?: KernelAttachment[];\n\t/** Agent messages sent from this cell, in order. */\n\tsentAgentMessages?: KernelSentAgentMessage[];\n\t/** Output that arrived without this cell's id (user threads, other cells' leftovers, raw fd writes). */\n\tbackgroundOutput?: string;\n\tstatus: \"ok\" | \"error\" | \"aborted\";\n\terror?: { ename: string; evalue: string; traceback: string[] };\n\tdurationMs: number;\n}\n\n/** Parse a {@link DIFF_DISPLAY_MIME} payload, tolerating malformed input. */\nexport function parseDiffDisplay(payload: unknown): KernelDiffDisplay | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { path, old_str: oldStr, new_str: newStr, start_line: startLine } = payload;\n\tif (typeof path !== \"string\" || typeof oldStr !== \"string\" || typeof newStr !== \"string\") {\n\t\treturn undefined;\n\t}\n\treturn { path, oldStr, newStr, startLine: typeof startLine === \"number\" ? startLine : undefined };\n}\n\n/**\n * Parse an {@link ATTACHMENT_DISPLAY_MIME} payload. Malformed payloads are\n * tolerantly ignored (`undefined`); a well-formed payload exceeding\n * {@link MAX_ATTACHMENT_DATA_CHARS} is reported as `\"oversized\"` so the caller\n * can fail the cell loudly rather than silently dropping the image.\n */\nexport function parseAttachmentDisplay(payload: unknown): KernelAttachment | \"oversized\" | undefined {\n\tif (!isRecord(payload)) {\n\t\treturn undefined;\n\t}\n\tconst { mime_type: mimeType, data, path } = payload;\n\tif (typeof mimeType !== \"string\" || typeof data !== \"string\") {\n\t\treturn undefined;\n\t}\n\tif (data.length > MAX_ATTACHMENT_DATA_CHARS) {\n\t\treturn \"oversized\";\n\t}\n\treturn { mimeType, data, path: typeof path === \"string\" ? path : undefined };\n}\n\nexport function parseSentAgentMessage(payload: unknown): KernelSentAgentMessage | undefined {\n\tif (!isRecord(payload) || !isRecord(payload.target)) {\n\t\treturn undefined;\n\t}\n\tconst { id, message, deliveryStatus, receiverRole, target } = payload;\n\tconst { activeSessionId, sessionId, sessionName } = target;\n\tif (\n\t\ttypeof id !== \"string\" ||\n\t\ttypeof message !== \"string\" ||\n\t\t(deliveryStatus !== \"delivered\" && deliveryStatus !== \"queued\") ||\n\t\ttypeof activeSessionId !== \"string\" ||\n\t\ttypeof sessionId !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tid,\n\t\tmessage,\n\t\tdeliveryStatus,\n\t\t...(receiverRole === \"parent\" || receiverRole === \"sibling\" || receiverRole === \"child\" ? { receiverRole } : {}),\n\t\ttarget: {\n\t\t\tactiveSessionId,\n\t\t\tsessionId,\n\t\t\t...(typeof sessionName === \"string\" ? { sessionName } : {}),\n\t\t},\n\t};\n}\n\nexport function createKernelStartupAbortError(): Error {\n\treturn new Error(\"Kernel startup aborted\");\n}\n\nexport function raceStartupWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {\n\tif (!signal) {\n\t\treturn promise;\n\t}\n\tif (signal.aborted) {\n\t\treturn Promise.reject(createKernelStartupAbortError());\n\t}\n\treturn new Promise<T>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tconst cleanup = () => signal.removeEventListener(\"abort\", abort);\n\t\tconst abort = () => {\n\t\t\tif (settled) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(createKernelStartupAbortError());\n\t\t};\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tpromise.then(\n\t\t\t(value) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tif (settled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsettled = true;\n\t\t\t\tcleanup();\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\nexport interface Deferred<T> {\n\tpromise: Promise<T>;\n\tresolve: (value: T) => void;\n\treject: (error: Error) => void;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nexport function createDeferred<T>(): Deferred<T> {\n\tlet resolve!: (value: T) => void;\n\tlet reject!: (error: Error) => void;\n\tconst promise = new Promise<T>((promiseResolve, promiseReject) => {\n\t\tresolve = promiseResolve;\n\t\treject = promiseReject;\n\t});\n\treturn { promise, resolve, reject };\n}\n\nexport interface KernelShutdownOptions {\n\tsnapshot?: boolean;\n\tdrainHostRequests?: boolean;\n}\n\n/** A bounded owned lifecycle observation, not a namespace, restore, or live-health assertion. */\nexport interface KernelLifecycleState {\n\treadonly source: \"repl-manager\" | \"ipython-provisioner\" | \"unobserved\";\n\treadonly owner: string | null;\n\treadonly generation: number | null;\n\treadonly state: \"idle\" | \"starting\" | \"running\" | \"shutdown\" | \"provisioning\" | \"disposed\" | \"unobserved\";\n}\n\nexport interface CapturedKernelLifecycle {\n\treadonly snapshot: Readonly<KernelLifecycleState>;\n\t/** Checks the original observation; it never probes or substitutes a newer snapshot. */\n\tisCurrent(): boolean;\n}\n\nexport interface JobWatchProbeRequest {\n\twatchId: string;\n\tgeneration: string;\n\tresourceId: string;\n\tjobId: string;\n\tcompletionSource?: \"handle\" | \"probe\";\n\tcommand: string | null;\n\ttimeoutMs: number;\n}\n\n/** Public surface every kernel client exposes to the provisioner and session layer. */\nexport interface KernelClient {\n\treadonly ownerSessionId: string | undefined;\n\treadonly isRunning: boolean;\n\t/** Optional job_watch_probe_v1 capability. Never evaluates a notebook cell. */\n\tjobWatchProbe?(request: JobWatchProbeRequest): Promise<Record<string, unknown>>;\n\tcancelJobWatchProbe?(watchId: string): void;\n\tstart(options?: KernelStartOptions): Promise<void>;\n\texecute(code: string, opts?: ExecuteOptions): Promise<ExecuteResult>;\n\tshutdown(opts?: KernelShutdownOptions): Promise<boolean>;\n\trestart(): Promise<void>;\n\tkill(): Promise<void>;\n\tdisposeSync(): void;\n\tsnapshotState(): Promise<SnapshotResult | null>;\n\tpruneOversizedVariables(): Promise<SnapshotResult | null>;\n\trestoreState(): Promise<RestoreResult | null>;\n\tlistNamespaceNames(signal?: AbortSignal): Promise<string[] | null>;\n}\n\n// One registry serves every client kind; two parallel registries would\n// double-install process signal handlers.\nexport const liveKernels = new Set<KernelClient>();\nlet signalHandlersInstalled = false;\n\nregisterSessionResourceCleanup((sessionId) => {\n\tfor (const k of liveKernels) {\n\t\tif (!sessionId || k.ownerSessionId === sessionId) {\n\t\t\tvoid k.shutdown({ snapshot: true, drainHostRequests: true });\n\t\t}\n\t}\n});\n\nexport function installSignalHandlersOnce(): void {\n\tif (signalHandlersInstalled) return;\n\tsignalHandlersInstalled = true;\n\n\tconst asyncShutdown = async (): Promise<void> => {\n\t\t// These paths can await, so flush the namespace snapshot before tearing down.\n\t\tawait Promise.allSettled([...liveKernels].map((k) => k.shutdown({ snapshot: true })));\n\t};\n\n\t// `beforeExit` and signal handlers can await async cleanup. `exit`\n\t// can only do sync work (Node won't run pending microtasks past it),\n\t// so it falls back to `disposeSync()` which kills the child synchronously.\n\tprocess.on(\"beforeExit\", () => {\n\t\tvoid asyncShutdown();\n\t});\n\tprocess.on(\"SIGINT\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(130));\n\t});\n\tprocess.on(\"SIGTERM\", () => {\n\t\tvoid asyncShutdown().finally(() => process.exit(143));\n\t});\n\tprocess.on(\"exit\", () => {\n\t\tfor (const k of liveKernels) k.disposeSync();\n\t});\n}\n"]}

package/dist/core/prompts/rlm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rlm.d.ts","sourceRoot":"","sources":["../../../src/core/prompts/rlm.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AA4CD,MAAM,WAAW,yBAAyB;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,GAAG,SAAS,CAe9F;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CA6GhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GACrG,MAAM,CAuBR","sourcesContent":["import { DEFAULT_RLM_EXTRA_IMPORT_LABELS } from \"../kernel/bootstrap.js\";\n\nexport interface RlmPromptOptions {\n\tcwd: string;\n\tskillsDir?: string;\n\tinstalledSkills?: string[];\n\tmessagesPath: string;\n\tallowRecursion?: boolean;\n\tdepth?: number;\n\tparentAgent?: string;\n\tactiveTools?: string[];\n}\n\nconst LONG_RUNNING_WORK_PROMPT = [\n\t\"For slow or independently completing work, use a nonblocking control loop: start the work, record its handle or output location, then end your turn. Read the result on a later turn or when a reply arrives.\",\n\t\"When delegation is available and useful, assign independent substantive tasks to separate workers. Start independent workers without waiting for each one sequentially, and let them run in parallel.\",\n\t\"Do not keep the turn open by polling with `time.sleep()` or shell `sleep`, and do not replace polling with a long blocking `await`. Await only the short operation needed to start work or inspect a result that is already available; otherwise end the turn.\",\n].join(\"\\n\");\n\nconst USER_PROGRESS_PROMPT =\n\t\"As the user-facing root agent, when work follows a plan, uses many subagents, or spans multiple turns, proactively give regular concise progress updates so the user does not have to ask. State the current plan, what has completed, any blockers, the proposed fixes, and the next actions. Lead with user-visible outcomes rather than internal process or gate names. Mention internal details only when they explain a blocker or decision. Send an update at meaningful milestones and before ending a turn while work is still running. Do not repeat unchanged status or interrupt short work with unnecessary updates.\";\n\nconst SIMPLIFIED_TECHNICAL_ENGLISH_PROMPT = [\n\t\"Use simplified technical English by default for user-facing prose.\",\n\t\"Prefer short sentences, common words, and concrete verbs. State one main action or fact per sentence when practical. Use lists for steps or conditions.\",\n\t\"Keep necessary technical terms, names, commands, code, paths, and exact quoted text unchanged. State uncertainty directly.\",\n\t\"Treat this as clarity guidance, not a claim of formal ASD-STE100 compliance. Preserve a user-requested format, tone, terminology, and necessary precision.\",\n].join(\"\\n\");\n\nconst REPL_CONTROL_PROMPT = [\n\t\"The `ipython` tool is a persistent Python REPL — the agent's long-lived control environment for reasoning, context management, state, tool orchestration, and recursive subcalls. Top-level `await` works directly. Use it to keep intermediate variables, inspect and transform outputs, and write small helper functions. Compaction removes individual variables whose serialized form exceeds 16 MiB; keep large source data on disk and reload it when needed.\",\n\t\"\",\n\t\"Reuse a named Python function for repeated multi-step work; keep one-off operations inline. Pass changing inputs explicitly and read current data each call. Save cross-task helpers as editable .py files with short project-skill instructions, without packaging them. After editing loaded code, execute its updated definition or invoke the saved file afresh.\",\n\t\"\",\n\t\"Python is the orchestration language: use Python for loops, conditionals, parsing, and state. Use `bash()` to invoke programs, not to write shell programs — no shell loops or heredocs; do those in Python.\",\n\t\"\",\n\t\"Do not assume the REPL is the native runtime of the external thing being investigated. A repository, package, service, dataset, paper, website, benchmark, or API may have its own environment and normal interface. Evaluate external systems through their own interface, then use the REPL to coordinate the process and analyze what comes back.\",\n\t\"\",\n\t\"`bash(command)` starts a shell command in the background and returns a handle immediately: `h = bash('npm test')`. Use `h.pid` / `h.running` for liveness, `h.tail(n)` / `h.output()` for combined stdout+stderr so far, `h.poll()` for a non-blocking result, `h.kill()` to terminate (SIGTERM, escalating to SIGKILL; on Windows kill() uses taskkill /T and detached or reparented descendants may survive), and `await h` (or `await bash('cmd')`) for the completed result with exit_code, output, and duration. Prefer bash() for long-running commands so the turn keeps working. Run shell commands with `bash()`, not `subprocess`/`os.system`: subprocess calls block the kernel, show the user nothing while they run, and spawn processes the harness cannot see or stop.\",\n\t\"\",\n\t\"Important: do not install dependencies into the kernel just to make an external project import or run there. If a project import, test, script, CLI, or dependency check is needed, run it through that project's own environment and normal command interface. For example, in a Python repo use its documented commands, `uv run ...`, `.venv/bin/python ...`, or the active project interpreter from the repo root. Treat failures from that native environment as the relevant result.\",\n\t\"\",\n\t\"Use Python for reading, searching, and editing files — it gives you reusable variables you can slice, filter, and act on without re-reading. Always assign read/search results to named variables so you can revisit them later.\",\n\t\"\",\n\t\"Each `bash()` call is its own process, so shell state does not persist between calls; use `os.chdir(...)` for the working directory and `os.environ[...]` for environment variables — both persist in the REPL and apply to later `bash()` calls.\",\n\t\"\",\n\t\"Python state in the kernel persists across cells: named variables, helper functions, classes, imports, notes, parsed outputs, and helper data structures all remain available in every later turn. Tool calls are themselves Python `await` expressions, so their return values can be bound to variables and composed into program logic just like any other call.\",\n\t\"\",\n\t\"Continual harness state is available as `rlm.harness` and `rlm.get_harness_state()`. CRUD calls are local to this Base Context session by default: `rlm.harness.create_memory(...)`, `rlm.harness.update_memory(...)`, `rlm.harness.delete_memory(...)`, `rlm.harness.create_skill(...)`, `rlm.harness.update_skill(...)`, `rlm.harness.delete_skill(...)`, `rlm.harness.create_subagent(...)`, `rlm.harness.update_subagent(...)`, `rlm.harness.delete_subagent(...)`, `rlm.harness.create_prompt_note(...)`, `rlm.harness.update_prompt_note(...)`, `rlm.harness.delete_prompt_note(...)`, plus `rlm.harness.record_refinement(...)` and `rlm.harness.overview()`. Use `global_=True` only for stable cross-session lessons; Python reserves `global`, so literal `global=True` is invalid syntax.\",\n\t\"\",\n\t\"Terminology: continual harness names the persisted prompt, memory, skill, and subagent layer; RLM names the runtime, Python REPL kernel, and native call interface exposed to the model.\",\n\t\"\",\n\t\"RLM-native call contract: installed Python skills are pre-imported modules. Read the matching SKILL.md and call its documented function, such as `await <skill_import>.<function>(...)`; when a CLI exists, use `<skill_import> ...` from shell. Continual harness skill entries are Python REPL skills with an explicit Python `reference` and `arguments` contract. Spawn a reusable delegation spec with `await rlm('sub-task')`; admission returns a child handle immediately. Results arrive only through an available messaging capability or files, never as an `rlm()` return value. Do not invent non-native wrappers such as `call_skill(...)` or `run_subagent(...)`.\",\n].join(\"\\n\");\n\nexport interface ChildAgentDoctrineOptions {\n\tdepth?: number;\n\tparentAgent?: string;\n\tinstalledSkills?: string[];\n\tactiveTools?: string[];\n}\n\nexport function buildChildAgentDoctrine(options: ChildAgentDoctrineOptions): string | undefined {\n\tconst depth = options.depth ?? 0;\n\tconst hasIpython = options.activeTools === undefined || options.activeTools.includes(\"ipython\");\n\tconst hasAgentMessage = options.installedSkills?.includes(\"agent_message\") ?? false;\n\tif (depth <= 0) return undefined;\n\n\tconst lines = [\n\t\t`You are a child agent spawned by ${options.parentAgent ?? \"your parent agent\"}. Task prompts are labeled \\`[task from parent]\\`.`,\n\t];\n\tif (hasAgentMessage && hasIpython) {\n\t\tlines.push(\n\t\t\t'When a task calls for an answer, reply explicitly with `await agent_message.send(message, receiver_role=\"parent\")`. Not every message or task needs a reply; continue cleanup after sending and go idle normally.',\n\t\t);\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport function buildRlmPrompt(options: RlmPromptOptions): string {\n\tconst { cwd, skillsDir, messagesPath } = options;\n\tconst installedSkills = options.installedSkills ?? [];\n\tconst hasAgentMessage = installedSkills.includes(\"agent_message\");\n\tconst hasAgentObserve = installedSkills.includes(\"agent_observe\");\n\tconst allowRecursion = options.allowRecursion ?? true;\n\tconst depth = options.depth ?? 0;\n\tconst activeTools = options.activeTools ?? [];\n\tconst hasIpython = options.activeTools === undefined ? true : activeTools.includes(\"ipython\");\n\tconst canRunShellSkills = hasIpython || activeTools.includes(\"bash\");\n\tconst parts = [\n\t\t\"You are a general purpose agent that uses code to solve tasks.\",\n\t\t\"You solve tasks by breaking down problems into sub-tasks, writing and executing code, observing results, and iterating one step at a time.\",\n\t\t\"When you are done, stop calling tools and state your final answer.\",\n\t\t\"\",\n\t\tLONG_RUNNING_WORK_PROMPT,\n\t\t\"\",\n\t\t...(depth === 0 ? [USER_PROGRESS_PROMPT, \"\"] : []),\n\t\tSIMPLIFIED_TECHNICAL_ENGLISH_PROMPT,\n\t\t\"\",\n\t\t`Recursive agent depth: ${depth}`,\n\t\t`Pre-installed Python packages: ${DEFAULT_RLM_EXTRA_IMPORT_LABELS.join(\", \")}.`,\n\t\t\"Install additional packages with `uv pip install <pkg>` (this is a uv-managed venv with no pip module).\",\n\t];\n\n\tconst childDoctrine = buildChildAgentDoctrine(options);\n\tif (childDoctrine) {\n\t\tparts.push(\"\", childDoctrine);\n\t}\n\n\tconst skillLines: string[] = [];\n\tif (skillsDir) {\n\t\tskillLines.push(`Local skills live under ${skillsDir}. Read their SKILL.md files when helpful.`);\n\t}\n\tif (installedSkills.length > 0) {\n\t\tconst installed = installedSkills.map((skill) => `\\`${skill}\\``).join(\", \");\n\t\tif (hasIpython) {\n\t\t\tskillLines.push(`Installed Python skill modules (pre-imported): ${installed}.`);\n\t\t\tskillLines.push(\n\t\t\t\t\"Read each skill's SKILL.md for its API. Inspect a module with `help(<skill>)` or `dir(<skill>)`, then inspect a documented callable with `inspect.signature(<skill>.<function>)`.\",\n\t\t\t);\n\t\t} else if (canRunShellSkills) {\n\t\t\tskillLines.push(`Installed skills available as shell commands: ${installed}.`);\n\t\t}\n\t\tif (canRunShellSkills) {\n\t\t\tskillLines.push(\n\t\t\t\t\"Each skill is also available as a shell command by the same name: `<skill> ...`. Discover its CLI usage with `<skill> --help`.\",\n\t\t\t);\n\t\t}\n\t\tif (hasIpython && installedSkills.includes(\"edit\")) {\n\t\t\tskillLines.push(\n\t\t\t\t\"For targeted existing-file edits, prefer the pre-imported async `edit` skill from the REPL: `old = '''...'''; new = '''...'''; await edit(path=\\\"pkg/file.py\\\", old_str=old, new_str=new)`. Use exact old/new strings; if the text contains triple double quotes, use triple single-quoted variables or build `old`/`new` from inspected file slices.\",\n\t\t\t);\n\t\t}\n\t}\n\tif (skillLines.length > 0) {\n\t\tparts.push(\"\", ...skillLines);\n\t}\n\tif (hasAgentMessage) {\n\t\tparts.push(\n\t\t\t\"Agent messaging is restricted to your parent, siblings, and direct children; roots are siblings, and deeper communication relays through the intermediate child.\",\n\t\t);\n\t}\n\tif (hasAgentObserve) {\n\t\tparts.push(\n\t\t\t\"Agent observation is restricted to your parent, siblings, and direct children; roots are siblings, and deeper inspection relays through the intermediate child.\",\n\t\t);\n\t}\n\n\tif (allowRecursion && hasIpython) {\n\t\tparts.push(\n\t\t\t\"\",\n\t\t\t\"A callable `rlm` is already in your global namespace. `await rlm('sub-task')` spawns a child and returns immediately after task admission with `rlm_child_id`, `name`, `session_dir`, and `model`; it never waits for or returns the child's answer.\",\n\t\t\t\"Choose a stable child name with `await rlm('sub-task', name='api-reviewer')`; names must be unique among siblings. If omitted, the host generates a readable unique name.\",\n\t\t\t\"A child inherits your model. If a different model is explicitly requested, use `await rlm.find_models(...)` and an exact returned selector. An unavailable requested model fails spawn; decide whether to retry or omit `model`. Children also inherit your thinking level; the `thinking` option overrides it with any level the resolved child model supports, and an unsupported level fails spawn.\",\n\t\t);\n\t\tif (hasAgentMessage) {\n\t\t\tparts.push(\n\t\t\t\t\"Children reply explicitly with `await agent_message.send(message, receiver_role='parent')` when an answer is needed. Replies and follow-ups arrive as ordinary agent messages; not every task requires a reply.\",\n\t\t\t\t\"Use `await agent_message.list_agents()` to discover family and `await rlm.list_subagents()` to recover direct child handles. Use `agent_message.send(..., receiver_role='child', receiver_name=child.name)` for follow-ups.\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"Use `await rlm.list_subagents()` to recover direct child handles after admission.\");\n\t\t}\n\t\tif (hasAgentObserve) {\n\t\t\tparts.push(\n\t\t\t\t\"Use `agent_observe` to inspect a child's rollout. Observation is restricted to your parent, siblings, and direct children; relay through the intermediate child for deeper descendants.\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"Inspect files a child wrote when you need to collect its work without an observation capability.\");\n\t\t}\n\t\tparts.push(\n\t\t\t\"Spawn independent children in separate calls and end your turn instead of awaiting completion. Multiple replies may arrive over multiple turns. Delete a direct child explicitly with `await rlm.delete_subagent(child)` when it is no longer needed.\",\n\t\t);\n\t}\n\n\tif (hasIpython) {\n\t\tparts.push(\"\", REPL_CONTROL_PROMPT);\n\t\tif (installedSkills.includes(\"refine\")) {\n\t\t\tparts.push(\n\t\t\t\t\"\",\n\t\t\t\t\"Treat continual harness refinement as a small, evidence-backed update after observing a repeated failure or reusable tactic: diagnose the issue, update the smallest relevant continual harness component, validate on the next action, then record the outcome. Use `await refine.run()` to turn repeated delegation patterns into reusable subagent specs, repeated procedures into skills, durable facts/preferences into memories, and narrow behavioral policies into prompt addendums. It returns immediately and runs when the current turn ends, so continue working normally after calling it. Do not rewrite the whole continual harness when a focused memory, skill, prompt note, or subagent spec is enough.\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Runtime coordinates follow the fixed harness guidance without moving user/project instructions.\n\tparts.push(\"\", `Working directory: ${cwd}`, `Conversation log: ${messagesPath}`);\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Supplemental sub-agent delegation guidance, appended after the base RLM\n * prompt (see system-prompt.ts). The recursion block covers the mechanics\n * (`rlm(...)` admission and handle management); this block adds the\n * when and why in the same When -> Why -> menu order Claude Code's Agent tool\n * uses. The subagent-spec menu itself renders just after this, inside the\n * harness-state block.\n */\nexport function buildSubagentGuidance(\n\toptions: { includeRefineExamples?: boolean; hasAgentMessage?: boolean; hasAgentObserve?: boolean } = {},\n): string {\n\tconst lines = [\n\t\t\"# Delegating to sub-agents\",\n\t\t\"\",\n\t\t\"Spawn independent, self-contained work with `handle = await rlm('task', name='worker')`. This returns at admission, not completion; keep the handle to stop or inspect the child later.\",\n\t];\n\tif (options.hasAgentMessage) {\n\t\tlines.push(\n\t\t\t\"Ask for an explicit reply when needed. A child replies with `await agent_message.send(message, receiver_role='parent')`; parent follow-ups use `receiver_role='child'` plus the child's name or id. Not every message needs a reply.\",\n\t\t);\n\t}\n\tlines.push(\"Use `await rlm.list_subagents()` after kernel restart or compaction.\");\n\tif (options.hasAgentObserve) {\n\t\tlines.push(\"Use `agent_observe` for bounded transcript inspection.\");\n\t}\n\tlines.push(\n\t\t\"Have children write files and read those files for fan-in.\",\n\t\t\"Delegate parallel context-heavy research or independent implementation; do a single known lookup, edit, or command inline.\",\n\t);\n\tif (options.includeRefineExamples ?? true) {\n\t\tlines.push(\"Persist genuinely reusable delegation patterns with `await refine.run()`.\");\n\t}\n\treturn lines.join(\"\\n\");\n}\n"]}
+{"version":3,"file":"rlm.d.ts","sourceRoot":"","sources":["../../../src/core/prompts/rlm.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAoDD,MAAM,WAAW,yBAAyB;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,GAAG,SAAS,CAe9F;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CA6GhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GACrG,MAAM,CAyBR","sourcesContent":["import { DEFAULT_RLM_EXTRA_IMPORT_LABELS } from \"../kernel/bootstrap.js\";\n\nexport interface RlmPromptOptions {\n\tcwd: string;\n\tskillsDir?: string;\n\tinstalledSkills?: string[];\n\tmessagesPath: string;\n\tallowRecursion?: boolean;\n\tdepth?: number;\n\tparentAgent?: string;\n\tactiveTools?: string[];\n}\n\nfunction buildLongRunningWorkPrompt(hasJobWatch: boolean): string {\n\treturn [\n\t\thasJobWatch\n\t\t\t? \"Use `job_watch` for repeated job checks after an authorized launch. Consume prepared evidence; call `park` and end the turn only when no independent work remains. Parking holds goal and autonomous continuation, not user input. Preserve every required report. Tiny one-off commands stay inline.\"\n\t\t\t: \"For slow or independently completing work, use a nonblocking control loop: start the work, record its handle or output location, then end your turn. Read the result on a later turn or when a reply arrives.\",\n\t\t\"When delegation is available and useful, assign independent substantive tasks to separate workers. Start independent workers without waiting for each one sequentially, and let them run in parallel.\",\n\t\t\"Do not keep the turn open by polling with `time.sleep()` or shell `sleep`, and do not replace polling with a long blocking `await`. Await only the short operation needed to start work or inspect a result that is already available; otherwise end the turn.\",\n\t].join(\"\\n\");\n}\n\nconst USER_PROGRESS_PROMPT =\n\t\"As the user-facing root agent, when work follows a plan, uses many subagents, or spans multiple turns, proactively give regular concise progress updates so the user does not have to ask. State the current plan, what has completed, any blockers, the proposed fixes, and the next actions. Lead with user-visible outcomes rather than internal process or gate names. Mention internal details only when they explain a blocker or decision. Send an update at meaningful milestones and before ending a turn while work is still running. Do not repeat unchanged status or interrupt short work with unnecessary updates.\";\n\nconst SIMPLIFIED_TECHNICAL_ENGLISH_PROMPT = [\n\t\"Use simplified technical English by default for user-facing prose.\",\n\t\"Prefer short sentences, common words, and concrete verbs. State one main action or fact per sentence when practical. Use lists for steps or conditions.\",\n\t\"Keep necessary technical terms, names, commands, code, paths, and exact quoted text unchanged. State uncertainty directly.\",\n\t\"Treat this as clarity guidance, not a claim of formal ASD-STE100 compliance. Preserve a user-requested format, tone, terminology, and necessary precision.\",\n].join(\"\\n\");\n\nfunction buildReplControlPrompt(hasBoundedInspect: boolean): string {\n\treturn [\n\t\t\"The `ipython` tool is a persistent Python REPL — the agent's long-lived control environment for reasoning, context management, state, tool orchestration, and recursive subcalls. Top-level `await` works directly. Use it to keep intermediate variables, inspect and transform outputs, and write small helper functions. Compaction removes individual variables whose serialized form exceeds 16 MiB; keep large source data on disk and reload it when needed.\",\n\t\t\"\",\n\t\t\"Reuse a named Python function for repeated multi-step work; keep one-off operations inline. Once a stable operation has been useful twice, save a small editable project .py helper without packaging it. Pass current commit, configuration, paths, resource identity, and limits explicitly instead of capturing stale globals; read current data each call. After editing loaded code, execute its updated definition or invoke the saved file afresh. Repetition never authorizes another deployment or experiment.\",\n\t\t\"\",\n\t\t\"Python is the orchestration language: use Python for loops, conditionals, parsing, and state. Use `bash()` to invoke programs, not to write shell programs — no shell loops or heredocs; do those in Python.\",\n\t\t\"\",\n\t\t\"Do not assume the REPL is the native runtime of the external thing being investigated. A repository, package, service, dataset, paper, website, benchmark, or API may have its own environment and normal interface. Evaluate external systems through their own interface, then use the REPL to coordinate the process and analyze what comes back.\",\n\t\t\"\",\n\t\t\"`bash(command)` starts a shell command in the background and returns a handle immediately: `h = bash('npm test')`. Use `h.pid` / `h.running` for liveness, `h.tail(n)` / `h.output()` for combined stdout+stderr so far, `h.poll()` for a non-blocking result, `h.kill()` to terminate (SIGTERM, escalating to SIGKILL; on Windows kill() uses taskkill /T and detached or reparented descendants may survive), and `await h` (or `await bash('cmd')`) for the completed result with exit_code, output, and duration. Prefer bash() for long-running commands so the turn keeps working. Run shell commands with `bash()`, not `subprocess`/`os.system`: subprocess calls block the kernel, show the user nothing while they run, and spawn processes the harness cannot see or stop.\",\n\t\t\"\",\n\t\t\"Important: do not install dependencies into the kernel just to make an external project import or run there. If a project import, test, script, CLI, or dependency check is needed, run it through that project's own environment and normal command interface. For example, in a Python repo use its documented commands, `uv run ...`, `.venv/bin/python ...`, or the active project interpreter from the repo root. Treat failures from that native environment as the relevant result.\",\n\t\t\"\",\n\t\thasBoundedInspect\n\t\t\t? \"Use Python for reading, searching, and editing files; prefer `bounded_inspect` for potentially large file evidence. Select fields/windows and emit once under one aggregate byte budget. Keep small one-off reads inline. Always assign read/search results to named variables so you can revisit them later.\"\n\t\t\t: \"Use Python for reading, searching, and editing files — it gives you reusable variables you can slice, filter, and act on without re-reading. Always assign read/search results to named variables so you can revisit them later.\",\n\t\t\"\",\n\t\t\"Each `bash()` call is its own process, so shell state does not persist between calls; use `os.chdir(...)` for the working directory and `os.environ[...]` for environment variables — both persist in the REPL and apply to later `bash()` calls.\",\n\t\t\"\",\n\t\t\"Python state in the kernel persists across cells: named variables, helper functions, classes, imports, notes, parsed outputs, and helper data structures all remain available in every later turn. Tool calls are themselves Python `await` expressions, so their return values can be bound to variables and composed into program logic just like any other call.\",\n\t\t\"\",\n\t\t\"Continual harness state is available as `rlm.harness` and `rlm.get_harness_state()`. CRUD calls are local to this Base Context session by default: `rlm.harness.create_memory(...)`, `rlm.harness.update_memory(...)`, `rlm.harness.delete_memory(...)`, `rlm.harness.create_skill(...)`, `rlm.harness.update_skill(...)`, `rlm.harness.delete_skill(...)`, `rlm.harness.create_subagent(...)`, `rlm.harness.update_subagent(...)`, `rlm.harness.delete_subagent(...)`, `rlm.harness.create_prompt_note(...)`, `rlm.harness.update_prompt_note(...)`, `rlm.harness.delete_prompt_note(...)`, plus `rlm.harness.record_refinement(...)` and `rlm.harness.overview()`. Use `global_=True` only for stable cross-session lessons; Python reserves `global`, so literal `global=True` is invalid syntax.\",\n\t\t\"\",\n\t\t\"Terminology: continual harness names the persisted prompt, memory, skill, and subagent layer; RLM names the runtime, Python REPL kernel, and native call interface exposed to the model.\",\n\t\t\"\",\n\t\t\"RLM-native call contract: installed Python skills are pre-imported modules. Use the matching SKILL.md and call its documented function, such as `await <skill_import>.<function>(...)`; when a CLI exists, use `<skill_import> ...` from shell. Continual harness skill entries are Python REPL skills with an explicit Python `reference` and `arguments` contract. Spawn a reusable delegation spec with `await rlm('sub-task')`; admission returns a child handle immediately. Results arrive only through an available messaging capability or files, never as an `rlm()` return value. Do not invent non-native wrappers such as `call_skill(...)` or `run_subagent(...)`.\",\n\t].join(\"\\n\");\n}\n\nexport interface ChildAgentDoctrineOptions {\n\tdepth?: number;\n\tparentAgent?: string;\n\tinstalledSkills?: string[];\n\tactiveTools?: string[];\n}\n\nexport function buildChildAgentDoctrine(options: ChildAgentDoctrineOptions): string | undefined {\n\tconst depth = options.depth ?? 0;\n\tconst hasIpython = options.activeTools === undefined || options.activeTools.includes(\"ipython\");\n\tconst hasAgentMessage = options.installedSkills?.includes(\"agent_message\") ?? false;\n\tif (depth <= 0) return undefined;\n\n\tconst lines = [\n\t\t`You are a child agent spawned by ${options.parentAgent ?? \"your parent agent\"}. Task prompts are labeled \\`[task from parent]\\`.`,\n\t];\n\tif (hasAgentMessage && hasIpython) {\n\t\tlines.push(\n\t\t\t'When a task calls for an answer, use `await agent_message.send(message, receiver_role=\"parent\")` for short coordination and `await agent_message.send_result(summary, findings, receiver_role=\"parent\")` for substantial findings or final reports. Include the outcome and important caveats. Not every message needs a reply; finish cleanup and go idle normally.',\n\t\t);\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport function buildRlmPrompt(options: RlmPromptOptions): string {\n\tconst { cwd, skillsDir, messagesPath } = options;\n\tconst installedSkills = options.installedSkills ?? [];\n\tconst hasAgentMessage = installedSkills.includes(\"agent_message\");\n\tconst hasAgentObserve = installedSkills.includes(\"agent_observe\");\n\tconst allowRecursion = options.allowRecursion ?? true;\n\tconst depth = options.depth ?? 0;\n\tconst activeTools = options.activeTools ?? [];\n\tconst hasIpython = options.activeTools === undefined ? true : activeTools.includes(\"ipython\");\n\tconst canRunShellSkills = hasIpython || activeTools.includes(\"bash\");\n\tconst parts = [\n\t\t\"You are a general purpose agent that uses code to solve tasks.\",\n\t\t\"You solve tasks by breaking down problems into sub-tasks, writing and executing code, observing results, and iterating one step at a time.\",\n\t\t\"When you are done, stop calling tools and state your final answer.\",\n\t\t\"\",\n\t\tbuildLongRunningWorkPrompt(hasIpython && installedSkills.includes(\"job_watch\")),\n\t\t\"\",\n\t\t...(depth === 0 ? [USER_PROGRESS_PROMPT, \"\"] : []),\n\t\tSIMPLIFIED_TECHNICAL_ENGLISH_PROMPT,\n\t\t\"\",\n\t\t`Recursive agent depth: ${depth}`,\n\t\t`Pre-installed Python packages: ${DEFAULT_RLM_EXTRA_IMPORT_LABELS.join(\", \")}.`,\n\t\t\"Install additional packages with `uv pip install <pkg>` (this is a uv-managed venv with no pip module).\",\n\t];\n\n\tconst childDoctrine = buildChildAgentDoctrine(options);\n\tif (childDoctrine) {\n\t\tparts.push(\"\", childDoctrine);\n\t}\n\n\tconst skillLines: string[] = [];\n\tif (skillsDir) {\n\t\tskillLines.push(`Local skills live under ${skillsDir}. Read their SKILL.md files when helpful.`);\n\t}\n\tif (installedSkills.length > 0) {\n\t\tconst installed = installedSkills.map((skill) => `\\`${skill}\\``).join(\", \");\n\t\tif (hasIpython) {\n\t\t\tskillLines.push(`Installed Python skill modules (pre-imported): ${installed}.`);\n\t\t\tskillLines.push(\n\t\t\t\t\"A complete selected SKILL.md body already in context needs no duplicate read; recover it later if needed. Inspect a module with `help(<skill>)` or `dir(<skill>)`, then inspect a documented callable with `inspect.signature(<skill>.<function>)`.\",\n\t\t\t);\n\t\t} else if (canRunShellSkills) {\n\t\t\tskillLines.push(`Installed Python skill packages: ${installed}.`);\n\t\t}\n\t\tif (canRunShellSkills) {\n\t\t\tskillLines.push(\n\t\t\t\t\"Only use a shell command when the skill documents a CLI: `<skill> ...`. Discover its usage with `<skill> --help`; not every Python skill has a CLI.\",\n\t\t\t);\n\t\t}\n\t\tif (hasIpython && installedSkills.includes(\"edit\")) {\n\t\t\tskillLines.push(\n\t\t\t\t\"For targeted existing-file edits, prefer the pre-imported async `edit` skill from the REPL: `old = '''...'''; new = '''...'''; await edit(path=\\\"pkg/file.py\\\", old_str=old, new_str=new)`. Use exact old/new strings; if the text contains triple double quotes, use triple single-quoted variables or build `old`/`new` from inspected file slices.\",\n\t\t\t);\n\t\t}\n\t}\n\tif (skillLines.length > 0) {\n\t\tparts.push(\"\", ...skillLines);\n\t}\n\tif (hasAgentMessage) {\n\t\tparts.push(\n\t\t\t\"Agent messaging is restricted to your parent, siblings, and direct children; roots are siblings, and deeper communication relays through the intermediate child.\",\n\t\t);\n\t}\n\tif (hasAgentObserve) {\n\t\tparts.push(\n\t\t\t\"Agent observation is restricted to your parent, siblings, and direct children; roots are siblings, and deeper inspection relays through the intermediate child.\",\n\t\t);\n\t}\n\n\tif (allowRecursion && hasIpython) {\n\t\tparts.push(\n\t\t\t\"\",\n\t\t\t\"A callable `rlm` is already in your global namespace. `await rlm('sub-task')` spawns a child and returns immediately after task admission with `rlm_child_id`, `name`, `session_dir`, and `model`; it never waits for or returns the child's answer.\",\n\t\t\t\"Choose a stable child name with `await rlm('sub-task', name='api-reviewer')`; names must be unique among siblings. If omitted, the host generates a readable unique name.\",\n\t\t\t\"A child inherits your model. If a different model is explicitly requested, use `await rlm.find_models(...)` and an exact returned selector. An unavailable requested model fails spawn; decide whether to retry or omit `model`. Children also inherit your thinking level; the `thinking` option overrides it with any level the resolved child model supports, and an unsupported level fails spawn.\",\n\t\t);\n\t\tif (hasAgentMessage) {\n\t\t\tparts.push(\n\t\t\t\t\"Replies and follow-ups arrive as ordinary agent messages or result capsules; request an explicit answer only when needed.\",\n\t\t\t\t\"Use `await agent_message.list_agents()` to discover family and `await rlm.list_subagents()` to recover direct child handles. Use `agent_message.send(..., receiver_role='child', receiver_name=child.name)` for follow-ups.\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"Use `await rlm.list_subagents()` to recover direct child handles after admission.\");\n\t\t}\n\t\tif (hasAgentObserve) {\n\t\t\tparts.push(\n\t\t\t\t\"Use `agent_observe` to inspect a child's rollout. Observation is restricted to your parent, siblings, and direct children; relay through the intermediate child for deeper descendants.\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"Inspect files a child wrote when you need to collect its work without an observation capability.\");\n\t\t}\n\t\tparts.push(\n\t\t\t\"Spawn independent children in separate calls and end your turn instead of awaiting completion. Multiple replies may arrive over multiple turns. Delete a direct child explicitly with `await rlm.delete_subagent(child)` when it is no longer needed.\",\n\t\t);\n\t}\n\n\tif (hasIpython) {\n\t\tparts.push(\"\", buildReplControlPrompt(installedSkills.includes(\"bounded_inspect\")));\n\t\tif (installedSkills.includes(\"refine\")) {\n\t\t\tparts.push(\n\t\t\t\t\"\",\n\t\t\t\t\"Treat continual harness refinement as a small, evidence-backed update after observing a repeated failure or reusable tactic: diagnose the issue, update the smallest relevant continual harness component, validate on the next action, then record the outcome. Use `await refine.run()` to turn repeated delegation patterns into reusable subagent specs, repeated procedures into skills, durable facts/preferences into memories, and narrow behavioral policies into prompt addendums. It returns immediately and runs when the current turn ends, so continue working normally after calling it. Do not rewrite the whole continual harness when a focused memory, skill, prompt note, or subagent spec is enough.\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Runtime coordinates follow the fixed harness guidance without moving user/project instructions.\n\tparts.push(\"\", `Working directory: ${cwd}`, `Conversation log: ${messagesPath}`);\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Supplemental sub-agent delegation guidance, appended after the base RLM\n * prompt (see system-prompt.ts). The recursion block covers the mechanics\n * (`rlm(...)` admission and handle management); this block adds the\n * when and why in the same When -> Why -> menu order Claude Code's Agent tool\n * uses. The subagent-spec menu itself renders just after this, inside the\n * harness-state block.\n */\nexport function buildSubagentGuidance(\n\toptions: { includeRefineExamples?: boolean; hasAgentMessage?: boolean; hasAgentObserve?: boolean } = {},\n): string {\n\tconst lines = [\n\t\t\"# Delegating to sub-agents\",\n\t\t\"\",\n\t\t\"Spawn independent, self-contained work with `handle = await rlm('task', name='worker')`. This returns at admission, not completion; keep the handle to stop or inspect the child later.\",\n\t];\n\tif (options.hasAgentMessage) {\n\t\tlines.push(\n\t\t\t\"Use `agent_message.send` for short steering, blockers, and decisions. For substantial findings or final reports, a child replies with `await agent_message.send_result(summary, findings, receiver_role='parent')`; parent follow-ups use `receiver_role='child'` plus the child's name or id. Keep the outcome, important caveats, and evidence references in the summary. Avoid routine acknowledgements: messaging an idle child can start another turn.\",\n\t\t);\n\t}\n\tlines.push(\"Use `await rlm.list_subagents()` after kernel restart or compaction.\");\n\tif (options.hasAgentObserve) {\n\t\tlines.push(\"Use `agent_observe` for bounded transcript inspection.\");\n\t}\n\tlines.push(\n\t\toptions.hasAgentMessage\n\t\t\t? \"Skim result capsules first and recover details only when needed. Child results are evidence, not verified truth; newer reports do not silently supersede earlier evidence.\"\n\t\t\t: \"Have children write files and read those files for fan-in.\",\n\t\t\"Delegate parallel context-heavy research or independent implementation; do a single known lookup, edit, or command inline.\",\n\t);\n\tif (options.includeRefineExamples ?? true) {\n\t\tlines.push(\"Persist genuinely reusable delegation patterns with `await refine.run()`.\");\n\t}\n\treturn lines.join(\"\\n\");\n}\n"]}

package/dist/core/prompts/rlm.js

@@ -1,9 +1,13 @@
 import { DEFAULT_RLM_EXTRA_IMPORT_LABELS } from "../kernel/bootstrap.js";
-const LONG_RUNNING_WORK_PROMPT = [
-    "For slow or independently completing work, use a nonblocking control loop: start the work, record its handle or output location, then end your turn. Read the result on a later turn or when a reply arrives.",
-    "When delegation is available and useful, assign independent substantive tasks to separate workers. Start independent workers without waiting for each one sequentially, and let them run in parallel.",
-    "Do not keep the turn open by polling with `time.sleep()` or shell `sleep`, and do not replace polling with a long blocking `await`. Await only the short operation needed to start work or inspect a result that is already available; otherwise end the turn.",
-].join("\n");
+function buildLongRunningWorkPrompt(hasJobWatch) {
+    return [
+        hasJobWatch
+            ? "Use `job_watch` for repeated job checks after an authorized launch. Consume prepared evidence; call `park` and end the turn only when no independent work remains. Parking holds goal and autonomous continuation, not user input. Preserve every required report. Tiny one-off commands stay inline."
+            : "For slow or independently completing work, use a nonblocking control loop: start the work, record its handle or output location, then end your turn. Read the result on a later turn or when a reply arrives.",
+        "When delegation is available and useful, assign independent substantive tasks to separate workers. Start independent workers without waiting for each one sequentially, and let them run in parallel.",
+        "Do not keep the turn open by polling with `time.sleep()` or shell `sleep`, and do not replace polling with a long blocking `await`. Await only the short operation needed to start work or inspect a result that is already available; otherwise end the turn.",
+    ].join("\n");
+}
 const USER_PROGRESS_PROMPT = "As the user-facing root agent, when work follows a plan, uses many subagents, or spans multiple turns, proactively give regular concise progress updates so the user does not have to ask. State the current plan, what has completed, any blockers, the proposed fixes, and the next actions. Lead with user-visible outcomes rather than internal process or gate names. Mention internal details only when they explain a blocker or decision. Send an update at meaningful milestones and before ending a turn while work is still running. Do not repeat unchanged status or interrupt short work with unnecessary updates.";
 const SIMPLIFIED_TECHNICAL_ENGLISH_PROMPT = [
     "Use simplified technical English by default for user-facing prose.",
@@ -11,31 +15,35 @@ const SIMPLIFIED_TECHNICAL_ENGLISH_PROMPT = [
     "Keep necessary technical terms, names, commands, code, paths, and exact quoted text unchanged. State uncertainty directly.",
     "Treat this as clarity guidance, not a claim of formal ASD-STE100 compliance. Preserve a user-requested format, tone, terminology, and necessary precision.",
 ].join("\n");
-const REPL_CONTROL_PROMPT = [
-    "The `ipython` tool is a persistent Python REPL — the agent's long-lived control environment for reasoning, context management, state, tool orchestration, and recursive subcalls. Top-level `await` works directly. Use it to keep intermediate variables, inspect and transform outputs, and write small helper functions. Compaction removes individual variables whose serialized form exceeds 16 MiB; keep large source data on disk and reload it when needed.",
-    "",
-    "Reuse a named Python function for repeated multi-step work; keep one-off operations inline. Pass changing inputs explicitly and read current data each call. Save cross-task helpers as editable .py files with short project-skill instructions, without packaging them. After editing loaded code, execute its updated definition or invoke the saved file afresh.",
-    "",
-    "Python is the orchestration language: use Python for loops, conditionals, parsing, and state. Use `bash()` to invoke programs, not to write shell programs — no shell loops or heredocs; do those in Python.",
-    "",
-    "Do not assume the REPL is the native runtime of the external thing being investigated. A repository, package, service, dataset, paper, website, benchmark, or API may have its own environment and normal interface. Evaluate external systems through their own interface, then use the REPL to coordinate the process and analyze what comes back.",
-    "",
-    "`bash(command)` starts a shell command in the background and returns a handle immediately: `h = bash('npm test')`. Use `h.pid` / `h.running` for liveness, `h.tail(n)` / `h.output()` for combined stdout+stderr so far, `h.poll()` for a non-blocking result, `h.kill()` to terminate (SIGTERM, escalating to SIGKILL; on Windows kill() uses taskkill /T and detached or reparented descendants may survive), and `await h` (or `await bash('cmd')`) for the completed result with exit_code, output, and duration. Prefer bash() for long-running commands so the turn keeps working. Run shell commands with `bash()`, not `subprocess`/`os.system`: subprocess calls block the kernel, show the user nothing while they run, and spawn processes the harness cannot see or stop.",
-    "",
-    "Important: do not install dependencies into the kernel just to make an external project import or run there. If a project import, test, script, CLI, or dependency check is needed, run it through that project's own environment and normal command interface. For example, in a Python repo use its documented commands, `uv run ...`, `.venv/bin/python ...`, or the active project interpreter from the repo root. Treat failures from that native environment as the relevant result.",
-    "",
-    "Use Python for reading, searching, and editing files — it gives you reusable variables you can slice, filter, and act on without re-reading. Always assign read/search results to named variables so you can revisit them later.",
-    "",
-    "Each `bash()` call is its own process, so shell state does not persist between calls; use `os.chdir(...)` for the working directory and `os.environ[...]` for environment variables — both persist in the REPL and apply to later `bash()` calls.",
-    "",
-    "Python state in the kernel persists across cells: named variables, helper functions, classes, imports, notes, parsed outputs, and helper data structures all remain available in every later turn. Tool calls are themselves Python `await` expressions, so their return values can be bound to variables and composed into program logic just like any other call.",
-    "",
-    "Continual harness state is available as `rlm.harness` and `rlm.get_harness_state()`. CRUD calls are local to this Base Context session by default: `rlm.harness.create_memory(...)`, `rlm.harness.update_memory(...)`, `rlm.harness.delete_memory(...)`, `rlm.harness.create_skill(...)`, `rlm.harness.update_skill(...)`, `rlm.harness.delete_skill(...)`, `rlm.harness.create_subagent(...)`, `rlm.harness.update_subagent(...)`, `rlm.harness.delete_subagent(...)`, `rlm.harness.create_prompt_note(...)`, `rlm.harness.update_prompt_note(...)`, `rlm.harness.delete_prompt_note(...)`, plus `rlm.harness.record_refinement(...)` and `rlm.harness.overview()`. Use `global_=True` only for stable cross-session lessons; Python reserves `global`, so literal `global=True` is invalid syntax.",
-    "",
-    "Terminology: continual harness names the persisted prompt, memory, skill, and subagent layer; RLM names the runtime, Python REPL kernel, and native call interface exposed to the model.",
-    "",
-    "RLM-native call contract: installed Python skills are pre-imported modules. Read the matching SKILL.md and call its documented function, such as `await <skill_import>.<function>(...)`; when a CLI exists, use `<skill_import> ...` from shell. Continual harness skill entries are Python REPL skills with an explicit Python `reference` and `arguments` contract. Spawn a reusable delegation spec with `await rlm('sub-task')`; admission returns a child handle immediately. Results arrive only through an available messaging capability or files, never as an `rlm()` return value. Do not invent non-native wrappers such as `call_skill(...)` or `run_subagent(...)`.",
-].join("\n");
+function buildReplControlPrompt(hasBoundedInspect) {
+    return [
+        "The `ipython` tool is a persistent Python REPL — the agent's long-lived control environment for reasoning, context management, state, tool orchestration, and recursive subcalls. Top-level `await` works directly. Use it to keep intermediate variables, inspect and transform outputs, and write small helper functions. Compaction removes individual variables whose serialized form exceeds 16 MiB; keep large source data on disk and reload it when needed.",
+        "",
+        "Reuse a named Python function for repeated multi-step work; keep one-off operations inline. Once a stable operation has been useful twice, save a small editable project .py helper without packaging it. Pass current commit, configuration, paths, resource identity, and limits explicitly instead of capturing stale globals; read current data each call. After editing loaded code, execute its updated definition or invoke the saved file afresh. Repetition never authorizes another deployment or experiment.",
+        "",
+        "Python is the orchestration language: use Python for loops, conditionals, parsing, and state. Use `bash()` to invoke programs, not to write shell programs — no shell loops or heredocs; do those in Python.",
+        "",
+        "Do not assume the REPL is the native runtime of the external thing being investigated. A repository, package, service, dataset, paper, website, benchmark, or API may have its own environment and normal interface. Evaluate external systems through their own interface, then use the REPL to coordinate the process and analyze what comes back.",
+        "",
+        "`bash(command)` starts a shell command in the background and returns a handle immediately: `h = bash('npm test')`. Use `h.pid` / `h.running` for liveness, `h.tail(n)` / `h.output()` for combined stdout+stderr so far, `h.poll()` for a non-blocking result, `h.kill()` to terminate (SIGTERM, escalating to SIGKILL; on Windows kill() uses taskkill /T and detached or reparented descendants may survive), and `await h` (or `await bash('cmd')`) for the completed result with exit_code, output, and duration. Prefer bash() for long-running commands so the turn keeps working. Run shell commands with `bash()`, not `subprocess`/`os.system`: subprocess calls block the kernel, show the user nothing while they run, and spawn processes the harness cannot see or stop.",
+        "",
+        "Important: do not install dependencies into the kernel just to make an external project import or run there. If a project import, test, script, CLI, or dependency check is needed, run it through that project's own environment and normal command interface. For example, in a Python repo use its documented commands, `uv run ...`, `.venv/bin/python ...`, or the active project interpreter from the repo root. Treat failures from that native environment as the relevant result.",
+        "",
+        hasBoundedInspect
+            ? "Use Python for reading, searching, and editing files; prefer `bounded_inspect` for potentially large file evidence. Select fields/windows and emit once under one aggregate byte budget. Keep small one-off reads inline. Always assign read/search results to named variables so you can revisit them later."
+            : "Use Python for reading, searching, and editing files — it gives you reusable variables you can slice, filter, and act on without re-reading. Always assign read/search results to named variables so you can revisit them later.",
+        "",
+        "Each `bash()` call is its own process, so shell state does not persist between calls; use `os.chdir(...)` for the working directory and `os.environ[...]` for environment variables — both persist in the REPL and apply to later `bash()` calls.",
+        "",
+        "Python state in the kernel persists across cells: named variables, helper functions, classes, imports, notes, parsed outputs, and helper data structures all remain available in every later turn. Tool calls are themselves Python `await` expressions, so their return values can be bound to variables and composed into program logic just like any other call.",
+        "",
+        "Continual harness state is available as `rlm.harness` and `rlm.get_harness_state()`. CRUD calls are local to this Base Context session by default: `rlm.harness.create_memory(...)`, `rlm.harness.update_memory(...)`, `rlm.harness.delete_memory(...)`, `rlm.harness.create_skill(...)`, `rlm.harness.update_skill(...)`, `rlm.harness.delete_skill(...)`, `rlm.harness.create_subagent(...)`, `rlm.harness.update_subagent(...)`, `rlm.harness.delete_subagent(...)`, `rlm.harness.create_prompt_note(...)`, `rlm.harness.update_prompt_note(...)`, `rlm.harness.delete_prompt_note(...)`, plus `rlm.harness.record_refinement(...)` and `rlm.harness.overview()`. Use `global_=True` only for stable cross-session lessons; Python reserves `global`, so literal `global=True` is invalid syntax.",
+        "",
+        "Terminology: continual harness names the persisted prompt, memory, skill, and subagent layer; RLM names the runtime, Python REPL kernel, and native call interface exposed to the model.",
+        "",
+        "RLM-native call contract: installed Python skills are pre-imported modules. Use the matching SKILL.md and call its documented function, such as `await <skill_import>.<function>(...)`; when a CLI exists, use `<skill_import> ...` from shell. Continual harness skill entries are Python REPL skills with an explicit Python `reference` and `arguments` contract. Spawn a reusable delegation spec with `await rlm('sub-task')`; admission returns a child handle immediately. Results arrive only through an available messaging capability or files, never as an `rlm()` return value. Do not invent non-native wrappers such as `call_skill(...)` or `run_subagent(...)`.",
+    ].join("\n");
+}
 export function buildChildAgentDoctrine(options) {
     const depth = options.depth ?? 0;
     const hasIpython = options.activeTools === undefined || options.activeTools.includes("ipython");
@@ -46,7 +54,7 @@ export function buildChildAgentDoctrine(options) {
         `You are a child agent spawned by ${options.parentAgent ?? "your parent agent"}. Task prompts are labeled \`[task from parent]\`.`,
     ];
     if (hasAgentMessage && hasIpython) {
-        lines.push('When a task calls for an answer, reply explicitly with `await agent_message.send(message, receiver_role="parent")`. Not every message or task needs a reply; continue cleanup after sending and go idle normally.');
+        lines.push('When a task calls for an answer, use `await agent_message.send(message, receiver_role="parent")` for short coordination and `await agent_message.send_result(summary, findings, receiver_role="parent")` for substantial findings or final reports. Include the outcome and important caveats. Not every message needs a reply; finish cleanup and go idle normally.');
     }
     return lines.join("\n");
 }
@@ -65,7 +73,7 @@ export function buildRlmPrompt(options) {
         "You solve tasks by breaking down problems into sub-tasks, writing and executing code, observing results, and iterating one step at a time.",
         "When you are done, stop calling tools and state your final answer.",
         "",
-        LONG_RUNNING_WORK_PROMPT,
+        buildLongRunningWorkPrompt(hasIpython && installedSkills.includes("job_watch")),
         "",
         ...(depth === 0 ? [USER_PROGRESS_PROMPT, ""] : []),
         SIMPLIFIED_TECHNICAL_ENGLISH_PROMPT,
@@ -86,13 +94,13 @@ export function buildRlmPrompt(options) {
         const installed = installedSkills.map((skill) => `\`${skill}\``).join(", ");
         if (hasIpython) {
             skillLines.push(`Installed Python skill modules (pre-imported): ${installed}.`);
-            skillLines.push("Read each skill's SKILL.md for its API. Inspect a module with `help(<skill>)` or `dir(<skill>)`, then inspect a documented callable with `inspect.signature(<skill>.<function>)`.");
+            skillLines.push("A complete selected SKILL.md body already in context needs no duplicate read; recover it later if needed. Inspect a module with `help(<skill>)` or `dir(<skill>)`, then inspect a documented callable with `inspect.signature(<skill>.<function>)`.");
         }
         else if (canRunShellSkills) {
-            skillLines.push(`Installed skills available as shell commands: ${installed}.`);
+            skillLines.push(`Installed Python skill packages: ${installed}.`);
         }
         if (canRunShellSkills) {
-            skillLines.push("Each skill is also available as a shell command by the same name: `<skill> ...`. Discover its CLI usage with `<skill> --help`.");
+            skillLines.push("Only use a shell command when the skill documents a CLI: `<skill> ...`. Discover its usage with `<skill> --help`; not every Python skill has a CLI.");
         }
         if (hasIpython && installedSkills.includes("edit")) {
             skillLines.push("For targeted existing-file edits, prefer the pre-imported async `edit` skill from the REPL: `old = '''...'''; new = '''...'''; await edit(path=\"pkg/file.py\", old_str=old, new_str=new)`. Use exact old/new strings; if the text contains triple double quotes, use triple single-quoted variables or build `old`/`new` from inspected file slices.");
@@ -110,7 +118,7 @@ export function buildRlmPrompt(options) {
     if (allowRecursion && hasIpython) {
         parts.push("", "A callable `rlm` is already in your global namespace. `await rlm('sub-task')` spawns a child and returns immediately after task admission with `rlm_child_id`, `name`, `session_dir`, and `model`; it never waits for or returns the child's answer.", "Choose a stable child name with `await rlm('sub-task', name='api-reviewer')`; names must be unique among siblings. If omitted, the host generates a readable unique name.", "A child inherits your model. If a different model is explicitly requested, use `await rlm.find_models(...)` and an exact returned selector. An unavailable requested model fails spawn; decide whether to retry or omit `model`. Children also inherit your thinking level; the `thinking` option overrides it with any level the resolved child model supports, and an unsupported level fails spawn.");
         if (hasAgentMessage) {
-            parts.push("Children reply explicitly with `await agent_message.send(message, receiver_role='parent')` when an answer is needed. Replies and follow-ups arrive as ordinary agent messages; not every task requires a reply.", "Use `await agent_message.list_agents()` to discover family and `await rlm.list_subagents()` to recover direct child handles. Use `agent_message.send(..., receiver_role='child', receiver_name=child.name)` for follow-ups.");
+            parts.push("Replies and follow-ups arrive as ordinary agent messages or result capsules; request an explicit answer only when needed.", "Use `await agent_message.list_agents()` to discover family and `await rlm.list_subagents()` to recover direct child handles. Use `agent_message.send(..., receiver_role='child', receiver_name=child.name)` for follow-ups.");
         }
         else {
             parts.push("Use `await rlm.list_subagents()` to recover direct child handles after admission.");
@@ -124,7 +132,7 @@ export function buildRlmPrompt(options) {
         parts.push("Spawn independent children in separate calls and end your turn instead of awaiting completion. Multiple replies may arrive over multiple turns. Delete a direct child explicitly with `await rlm.delete_subagent(child)` when it is no longer needed.");
     }
     if (hasIpython) {
-        parts.push("", REPL_CONTROL_PROMPT);
+        parts.push("", buildReplControlPrompt(installedSkills.includes("bounded_inspect")));
         if (installedSkills.includes("refine")) {
             parts.push("", "Treat continual harness refinement as a small, evidence-backed update after observing a repeated failure or reusable tactic: diagnose the issue, update the smallest relevant continual harness component, validate on the next action, then record the outcome. Use `await refine.run()` to turn repeated delegation patterns into reusable subagent specs, repeated procedures into skills, durable facts/preferences into memories, and narrow behavioral policies into prompt addendums. It returns immediately and runs when the current turn ends, so continue working normally after calling it. Do not rewrite the whole continual harness when a focused memory, skill, prompt note, or subagent spec is enough.");
         }
@@ -148,13 +156,15 @@ export function buildSubagentGuidance(options = {}) {
         "Spawn independent, self-contained work with `handle = await rlm('task', name='worker')`. This returns at admission, not completion; keep the handle to stop or inspect the child later.",
     ];
     if (options.hasAgentMessage) {
-        lines.push("Ask for an explicit reply when needed. A child replies with `await agent_message.send(message, receiver_role='parent')`; parent follow-ups use `receiver_role='child'` plus the child's name or id. Not every message needs a reply.");
+        lines.push("Use `agent_message.send` for short steering, blockers, and decisions. For substantial findings or final reports, a child replies with `await agent_message.send_result(summary, findings, receiver_role='parent')`; parent follow-ups use `receiver_role='child'` plus the child's name or id. Keep the outcome, important caveats, and evidence references in the summary. Avoid routine acknowledgements: messaging an idle child can start another turn.");
     }
     lines.push("Use `await rlm.list_subagents()` after kernel restart or compaction.");
     if (options.hasAgentObserve) {
         lines.push("Use `agent_observe` for bounded transcript inspection.");
     }
-    lines.push("Have children write files and read those files for fan-in.", "Delegate parallel context-heavy research or independent implementation; do a single known lookup, edit, or command inline.");
+    lines.push(options.hasAgentMessage
+        ? "Skim result capsules first and recover details only when needed. Child results are evidence, not verified truth; newer reports do not silently supersede earlier evidence."
+        : "Have children write files and read those files for fan-in.", "Delegate parallel context-heavy research or independent implementation; do a single known lookup, edit, or command inline.");
     if (options.includeRefineExamples ?? true) {
         lines.push("Persist genuinely reusable delegation patterns with `await refine.run()`.");
     }