@hy-sde-org/dsh-code-runtime-kernels 0.2.1-rc.3 → 0.2.2-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -11,10 +11,11 @@
11
11
  * @module @hy-sde-org/dsh-code-runtime-kernels
12
12
  */
13
13
  import { Context } from '@deepseek-ai/cordis';
14
+ import type { SessionId } from '@deepseek-ai/dsh-session';
14
15
  import z from '@deepseek-ai/schemastery';
15
16
  import type { PtcBindingNamespace, PtcJsonValue, PtcRunResult } from '@deepseek-ai/dsh-ptc-runtime';
16
17
  import type { TerminalCallView, TerminalResultView, ToolResult } from '@deepseek-ai/dsh-tools';
17
- import type { KernelSandboxProvider } from './core/kernel.ts';
18
+ import type { KernelPersistenceStatus, KernelSandboxProvider } from './core/kernel.ts';
18
19
  /** Cordis plugin name for loader diagnostics. */
19
20
  export declare const name = "code-runtime-kernels";
20
21
  /** Services this plugin requires: the tool registry and the system-prompt builder. */
@@ -26,8 +27,14 @@ export declare const inject: string[];
26
27
  export interface Config {
27
28
  /** Enabled languages; kernels of disabled languages are refused at call time. */
28
29
  languages?: ('python' | 'typescript')[];
29
- /** Explicit python executable. Defaults to `python3` on PATH (fails loud at first spawn when absent). */
30
+ /**
31
+ * Explicit python interpreter, probed first; then every `python`/`python3`
32
+ * on PATH (first healthy candidate wins; fails loud with per-candidate
33
+ * reasons when none works).
34
+ */
30
35
  pythonPath?: string;
36
+ /** Probe budget per candidate while resolving the python interpreter (ms; default 5000). */
37
+ pythonProbeTimeoutMs?: number;
31
38
  /**
32
39
  * Python execution semantics: `stdlib` (default, self-contained runner) or
33
40
  * `ipykernel` (real IPython shell: magics, `!cmd`, display — the interpreter
@@ -68,9 +75,8 @@ export interface Config {
68
75
  snapshotMaxEntryBytes?: number;
69
76
  /**
70
77
  * Session "toolbox": one preload source per language. It runs as a hidden
71
- * first cell of every fresh session kernel (before the snapshot restore,
72
- * so restored names shadow same-named helpers; user state wins). A preload
73
- * failure fails the triggering run like an exception.
78
+ * first cell of every fresh session kernel with the triggering call's cwd
79
+ * and environment, before snapshot restore. A failure fails that run.
74
80
  */
75
81
  preload?: {
76
82
  python?: string;
@@ -99,10 +105,22 @@ export interface KernelRunRequest {
99
105
  code: string;
100
106
  /** Optional persistent-kernel identity: runs sharing one keep kernel state. */
101
107
  sessionId?: string;
108
+ /**
109
+ * Owning DSH session for sandbox policy. This is distinct from the
110
+ * model-chosen persistent-kernel id in {@link sessionId}.
111
+ */
112
+ sandboxSessionId?: SessionId;
102
113
  /** Discard the session's prior kernel state before this run. */
103
114
  reset?: boolean;
104
115
  /** Abort the run host-side; in-flight binding calls are the caller's to settle. */
105
116
  signal?: AbortSignal;
117
+ /**
118
+ * Per-run working directory handed to the kernel (the runner chdirs before
119
+ * the cell). Persistent kernels re-assert it on EVERY run with a session,
120
+ * so a kernel follows the caller's working directory instead of keeping a
121
+ * stale one from whenever it was spawned.
122
+ */
123
+ cwd?: string;
106
124
  /** Optional host functions exposed to the program, one global object per namespace. */
107
125
  bindings?: PtcBindingNamespace[];
108
126
  }
@@ -114,7 +132,16 @@ export interface KernelRunRequest {
114
132
  */
115
133
  export type KernelRunResult = PtcRunResult & {
116
134
  executionCount?: number;
135
+ /** Snapshot persistence outcome for this run (saved/restored/lost/error), when snapshots are on. */
136
+ persistence?: KernelPersistenceStatus;
117
137
  };
138
+ /**
139
+ * Metadata accompanying an output-limit spill. `complete` is false when the
140
+ * host-side capture cap discarded a tail before finalization.
141
+ */
142
+ export interface OutputLimitInfo {
143
+ complete: boolean;
144
+ }
118
145
  /**
119
146
  * Owns the two persistent kernel registries and maps one `KernelRunRequest`
120
147
  * onto the same outcome vocabulary as the code-execution seam
@@ -125,8 +152,17 @@ export type KernelRunResult = PtcRunResult & {
125
152
  export declare class KernelManager {
126
153
  #private;
127
154
  constructor(config: Config);
128
- /** Terminate every session kernel to quiescence (plugin teardown). */
155
+ /** Abort admitted work, then terminate every session and one-shot kernel. */
129
156
  teardown(): Promise<void>;
157
+ /**
158
+ * The surface-visible fields of the resolved config (the same defaults the
159
+ * constructor applies), so the tool guide can promise exactly what this
160
+ * deployment enables — no more.
161
+ */
162
+ static resolvedSurface(config: Config): {
163
+ snapshot: boolean;
164
+ sessionIdleMs: number;
165
+ };
130
166
  /**
131
167
  * Execute one program. Program outcomes resolve with `error` as a result
132
168
  * field; the method rejects only for contract misuse (an unknown language, a
@@ -134,30 +170,13 @@ export declare class KernelManager {
134
170
  * `sessionId` the program runs in that session's persistent kernel and
135
171
  * `executionCount` is reported; `reset: true` discards prior state first.
136
172
  *
137
- * `onOutputLimit` is a best-effort spill hook called only when the run's
138
- * output crosses `maxOutputBytes`: it receives the FULL captured program
139
- * output (the same bytes that just overflowed the result budget) and may
140
- * persist them somewhere recoverable. Returning a retrieval hint rewrites
141
- * the `output-limit` message so the caller can recover the dropped tail;
142
- * returning `undefined` (no backend, no owner, storage failure) keeps the
143
- * truncated result untouched. The manager never awaits this beyond a
144
- * best-effort `catch` — spill failure cannot fail the program.
173
+ * `onOutputLimit` keeps its original content-first callback and receives
174
+ * additive metadata describing whether host capture retained the full text.
145
175
  */
146
- run(request: KernelRunRequest, onOutputLimit?: (content: string) => Promise<string | undefined>): Promise<KernelRunResult>;
176
+ run(request: KernelRunRequest, onOutputLimit?: (content: string, info: OutputLimitInfo) => Promise<string | undefined>): Promise<KernelRunResult>;
147
177
  /**
148
- * Map a kernel outcome onto the failure taxonomy through the output ledger.
149
- * Budget expiry owns a run that hit the wall clock (whether or not the
150
- * kernel survived to acknowledge it); everything else interrupted is an
151
- * abort; a died kernel is an abort unless the budget already owns the run.
152
- */
153
- /**
154
- * Map a kernel outcome onto the failure taxonomy through the output ledger.
155
- * Budget expiry owns a run that hit the wall clock (whether or not the
156
- * kernel survived to acknowledge it); everything else interrupted is an
157
- * abort; a died kernel is an abort unless the budget already owns the run.
158
- *
159
- * An `output-limit` outcome additionally consults `onOutputLimit` to spill
160
- * the full captured output, best-effort (never awaited past a catch).
178
+ * Map one kernel outcome onto the PTC failure taxonomy. Capture truncation
179
+ * takes precedence because the discarded tail prevents a complete result.
161
180
  */
162
181
  private finalize;
163
182
  /** Reject malformed binding globals or typed-error declarations as contract misuse. */
@@ -181,6 +200,13 @@ export type RunKernelCodeMeta = {
181
200
  message: string;
182
201
  };
183
202
  executionCount?: number;
203
+ persistence?: {
204
+ saved?: number;
205
+ saveLost?: string[];
206
+ saveError?: string;
207
+ restored?: number;
208
+ restoreLost?: string[];
209
+ };
184
210
  logs: string[];
185
211
  };
186
212
  /** Project the durable, replayable presentation payload for a completed run. */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}