@hy-sde-org/dsh-code-runtime-kernels 0.2.1-rc.5 → 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. */
@@ -74,9 +75,8 @@ export interface Config {
74
75
  snapshotMaxEntryBytes?: number;
75
76
  /**
76
77
  * Session "toolbox": one preload source per language. It runs as a hidden
77
- * first cell of every fresh session kernel (before the snapshot restore,
78
- * so restored names shadow same-named helpers; user state wins). A preload
79
- * 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.
80
80
  */
81
81
  preload?: {
82
82
  python?: string;
@@ -105,10 +105,22 @@ export interface KernelRunRequest {
105
105
  code: string;
106
106
  /** Optional persistent-kernel identity: runs sharing one keep kernel state. */
107
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;
108
113
  /** Discard the session's prior kernel state before this run. */
109
114
  reset?: boolean;
110
115
  /** Abort the run host-side; in-flight binding calls are the caller's to settle. */
111
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;
112
124
  /** Optional host functions exposed to the program, one global object per namespace. */
113
125
  bindings?: PtcBindingNamespace[];
114
126
  }
@@ -120,7 +132,16 @@ export interface KernelRunRequest {
120
132
  */
121
133
  export type KernelRunResult = PtcRunResult & {
122
134
  executionCount?: number;
135
+ /** Snapshot persistence outcome for this run (saved/restored/lost/error), when snapshots are on. */
136
+ persistence?: KernelPersistenceStatus;
123
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
+ }
124
145
  /**
125
146
  * Owns the two persistent kernel registries and maps one `KernelRunRequest`
126
147
  * onto the same outcome vocabulary as the code-execution seam
@@ -131,8 +152,17 @@ export type KernelRunResult = PtcRunResult & {
131
152
  export declare class KernelManager {
132
153
  #private;
133
154
  constructor(config: Config);
134
- /** Terminate every session kernel to quiescence (plugin teardown). */
155
+ /** Abort admitted work, then terminate every session and one-shot kernel. */
135
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
+ };
136
166
  /**
137
167
  * Execute one program. Program outcomes resolve with `error` as a result
138
168
  * field; the method rejects only for contract misuse (an unknown language, a
@@ -140,30 +170,13 @@ export declare class KernelManager {
140
170
  * `sessionId` the program runs in that session's persistent kernel and
141
171
  * `executionCount` is reported; `reset: true` discards prior state first.
142
172
  *
143
- * `onOutputLimit` is a best-effort spill hook called only when the run's
144
- * output crosses `maxOutputBytes`: it receives the FULL captured program
145
- * output (the same bytes that just overflowed the result budget) and may
146
- * persist them somewhere recoverable. Returning a retrieval hint rewrites
147
- * the `output-limit` message so the caller can recover the dropped tail;
148
- * returning `undefined` (no backend, no owner, storage failure) keeps the
149
- * truncated result untouched. The manager never awaits this beyond a
150
- * 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.
151
175
  */
152
- 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>;
153
177
  /**
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
- /**
160
- * Map a kernel outcome onto the failure taxonomy through the output ledger.
161
- * Budget expiry owns a run that hit the wall clock (whether or not the
162
- * kernel survived to acknowledge it); everything else interrupted is an
163
- * abort; a died kernel is an abort unless the budget already owns the run.
164
- *
165
- * An `output-limit` outcome additionally consults `onOutputLimit` to spill
166
- * 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.
167
180
  */
168
181
  private finalize;
169
182
  /** Reject malformed binding globals or typed-error declarations as contract misuse. */
@@ -187,6 +200,13 @@ export type RunKernelCodeMeta = {
187
200
  message: string;
188
201
  };
189
202
  executionCount?: number;
203
+ persistence?: {
204
+ saved?: number;
205
+ saveLost?: string[];
206
+ saveError?: string;
207
+ restored?: number;
208
+ restoreLost?: string[];
209
+ };
190
210
  logs: string[];
191
211
  };
192
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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"}