@qilin-agent/ptc-runtime 3.1.5 → 3.1.7

package/lib/index.js

@@ -141,10 +141,24 @@ const PORTABLE_RESERVED_WORDS = new Set([
 * Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
 * failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
 * structured-cloneable bindings, materialize each declared namespace rejection
-* class, treat programs as hostile peers, isolate runs from one another, and
+* class, treat programs as hostile peers, isolate distinct state owners, and
 * terminate and await in-flight runs during disposal.
 */
 var PtcRuntime = class extends Service {
+	/** Source evaluation form, independent of whether the provider retains state for an owner. */
+	get programFormat() {
+		return "function-body";
+	}
+	/**
+	* Release an owner's retained environment and await its execution resources.
+	* Stateless providers have no retained resources to release.
+	* @param owner - The exact object supplied as the request's state owner.
+	* @returns Completion after all owned execution resources have been released.
+	* @throws When managed resource cleanup fails.
+	*/
+	release(owner) {
+		return Promise.resolve();
+	}
 	/** Provider-owned program usage guidance for consumers to present alongside the source language. */
 	get executionInstructions() {
 		return "";

package/lib/types/index.d.ts

@@ -63,7 +63,7 @@ declare module '@qilin-agent/kylin' {
  * Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
  * failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
  * structured-cloneable bindings, materialize each declared namespace rejection
- * class, treat programs as hostile peers, isolate runs from one another, and
+ * class, treat programs as hostile peers, isolate distinct state owners, and
  * terminate and await in-flight runs during disposal.
  */
 export declare abstract class PtcRuntime extends Service {
@@ -84,6 +84,16 @@ export declare abstract class PtcRuntime extends Service {
      * `'process'`, `'container'`.
      */
     abstract readonly isolation: string;
+    /** Source evaluation form, independent of whether the provider retains state for an owner. */
+    get programFormat(): 'function-body' | 'repl';
+    /**
+     * Release an owner's retained environment and await its execution resources.
+     * Stateless providers have no retained resources to release.
+     * @param owner - The exact object supplied as the request's state owner.
+     * @returns Completion after all owned execution resources have been released.
+     * @throws When managed resource cleanup fails.
+     */
+    release(owner: object): Promise<void>;
     /** Provider-owned program usage guidance for consumers to present alongside the source language. */
     get executionInstructions(): string;
     /** Deployment file-policy mode, or undefined for a provider without confinement support. */

package/lib/types/types.d.ts

@@ -69,11 +69,18 @@ export interface PtcBindingNamespace {
 export interface PtcRunRequest {
     /**
      * The program source, in the runtime's {@link ../index.ts | language}. It
-     * runs as the body of an async function: top-level `await` and `return`
-     * are available, and the completion value becomes
+     * follows the provider's programFormat: an async function body supports
+     * top-level `await` and `return`; a REPL supports top-level declarations,
+     * `await`, and a final expression. The completion value becomes
      * {@link PtcRunResult.value}.
      */
     program: string;
+    /**
+     * Object-identity owner for optional in-memory state. Omission requests a fresh
+     * environment. Consumers must await runtime.release(owner) when the owner ends.
+     * Stateless providers ignore this field; retained state is never durable.
+     */
+    stateOwner?: object;
     /** Host functions exposed to the program, one global object per namespace. */
     bindings: PtcBindingNamespace[];
     /** Working directory in the mounted filesystem and subprocess execution world. */
@@ -137,7 +144,7 @@ export interface PtcRunResult {
     /** Applied file policy and observed denial, when the provider enforces file policy. */
     sandbox?: PtcRunSandbox;
     /**
-     * The program's completion value (its top-level `return`), when it ran to
+     * The program's completion value (a return or final REPL expression), when it ran to
      * completion and the value crossed the runtime's lossless-JSON boundary.
      * Invalid or over-limit completions fail the run instead of substituting a
      * rendered string; a failed or value-less run leaves this absent.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/ptc-runtime",
   "description": "Abstract PTC execution seam (ctx.ptcRuntime) for the QiLin",
-  "version": "3.1.5",
+  "version": "3.1.7",
   "publishConfig": {
     "access": "public"
   },
@@ -30,11 +30,11 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/sandbox": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/sandbox": "3.1.7"
   },
   "devDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/sandbox": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/sandbox": "3.1.7"
   }
 }