@qilin-agent/tools 3.1.5 → 3.1.7

package/lib/types/index.d.ts

@@ -539,9 +539,10 @@ export declare class ToolRuntime extends Service {
      * Reserved presentation transport, kept outside the filterable registration
      * layers. Built on first need rather than at construction: which agents run
      * a PTC mode is no longer known when the service is constructed, and the
-     * transport is stateless beyond its closures over `this`.
+     * transport owns its PTC call tracking and state-owner registrations.
      */
     private ptcTransport;
+    private readonly ptcContext;
     constructor(ctx: Context, config?: Config);
     /**
      * The prompt statement of the `ptc` executor collapse, registered wherever

package/lib/types/index.js

@@ -248,11 +248,13 @@ export class ToolRuntime extends Service {
      * Reserved presentation transport, kept outside the filterable registration
      * layers. Built on first need rather than at construction: which agents run
      * a PTC mode is no longer known when the service is constructed, and the
-     * transport is stateless beyond its closures over `this`.
+     * transport owns its PTC call tracking and state-owner registrations.
      */
     ptcTransport;
+    ptcContext;
     constructor(ctx, config = {}) {
         super(ctx, 'tools');
+        this.ptcContext = ctx;
         // The schema already defaulted an omitted mode; the ?? narrows the
         // optional-input type for direct (non-Loader) construction in tests.
         this.defaultMode = config.mode ?? 'native';
@@ -314,7 +316,7 @@ export class ToolRuntime extends Service {
                 /* v8 ignore next -- requirePtcRuntime rejects an unknown language before this runs. */
                 if (render === undefined)
                     throw new Error(`qilin-tools: no SDK renderer for ${runtime.language}`);
-                return render(this.sdkSchemas(context.scope));
+                return render(this.sdkSchemas(context.scope), runtime.programFormat);
             },
         };
     }
@@ -372,7 +374,7 @@ export class ToolRuntime extends Service {
             peekRuntime: () => this.ctx.get('ptcRuntime'),
             maxParallel: this.maxParallelSubCalls,
             shapeDispatchLog: dispatch => this.shapeDispatchLog(dispatch),
-        });
+        }, this.ptcContext);
         return this.ptcTransport;
     }
     /**

package/lib/types/presentation.d.ts

@@ -155,10 +155,10 @@ export interface TerminalResultView {
     /** Captured command output (stdout+stderr as the tool chooses to combine them). */
     output?: string;
     /**
-     * Process exit code, when the run ended by exiting (not a signal). Lets a
-     * capable UI show an exit-status pill. Omit when killed by a signal or unknown.
+     * Process exit code, or null when the run ended without a code or signal.
+     * Omit when killed by a signal or when the result carries no exit status.
      */
-    exitCode?: number;
+    exitCode?: number | null;
     /** Signal name that killed the process (e.g. `SIGTERM`). Mutually exclusive with `exitCode`. */
     signal?: string;
 }

package/lib/types/ptc-calls.d.ts

@@ -0,0 +1,24 @@
+/** Cancellation and settlement of complete PTC calls, including nested tools. */
+import type { Context } from '@qilin-agent/kylin';
+import type { SessionId } from '@qilin-agent/session';
+import type { SandboxMode } from '@qilin-agent/sandbox';
+/** Keeps calls under a changed policy from overlapping their canceled predecessors. */
+export declare class PtcCalls {
+    private readonly calls;
+    private disposed;
+    /**
+     * Observe policy changes for the owning tool registry.
+     * @param ctx - Registry lifecycle and Session events.
+     */
+    constructor(ctx: Context);
+    /**
+     * Await canceled predecessors before resolving authority and admitting a call.
+     * @param sessionId - Calling Session.
+     * @param signal - Caller cancellation.
+     * @param mode - Current standing mode, read after preceding cleanup.
+     * @param run - Complete call, including nested-tool cleanup.
+     * @returns The call result.
+     */
+    run<T>(sessionId: SessionId, signal: AbortSignal, mode: () => SandboxMode, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=ptc-calls.d.ts.map

package/lib/types/ptc-calls.js

@@ -0,0 +1,62 @@
+/** Keeps calls under a changed policy from overlapping their canceled predecessors. */
+export class PtcCalls {
+    calls = new Map();
+    disposed = false;
+    /**
+     * Observe policy changes for the owning tool registry.
+     * @param ctx - Registry lifecycle and Session events.
+     */
+    constructor(ctx) {
+        ctx.on('session/event', (session, event) => {
+            if (event.type !== 'sandbox/mode')
+                return;
+            for (const call of this.calls.get(session.id) ?? []) {
+                if (call.mode !== event.data.mode)
+                    call.controller.abort(new Error('sandbox mode changed'));
+            }
+        }, { global: true });
+        ctx.effect(() => async () => {
+            this.disposed = true;
+            const calls = [...this.calls.values()].flatMap(calls => [...calls]);
+            for (const call of calls)
+                call.controller.abort(new Error('PTC tool registry disposed'));
+            await Promise.all(calls.map(call => call.done));
+        }, 'PTC calls');
+    }
+    /**
+     * Await canceled predecessors before resolving authority and admitting a call.
+     * @param sessionId - Calling Session.
+     * @param signal - Caller cancellation.
+     * @param mode - Current standing mode, read after preceding cleanup.
+     * @param run - Complete call, including nested-tool cleanup.
+     * @returns The call result.
+     */
+    async run(sessionId, signal, mode, run) {
+        for (;;) {
+            const pending = [...this.calls.get(sessionId) ?? []].filter(call => call.controller.signal.aborted);
+            if (pending.length === 0)
+                break;
+            await Promise.all(pending.map(call => call.done));
+        }
+        signal.throwIfAborted();
+        if (this.disposed)
+            throw new Error('PTC tool registry disposed');
+        const controller = new AbortController();
+        const done = Promise.withResolvers();
+        const call = { mode: mode(), controller, done: done.promise };
+        let calls = this.calls.get(sessionId);
+        if (calls === undefined)
+            this.calls.set(sessionId, calls = new Set());
+        calls.add(call);
+        try {
+            return await run(AbortSignal.any([signal, controller.signal]));
+        }
+        finally {
+            calls.delete(call);
+            if (calls.size === 0)
+                this.calls.delete(sessionId);
+            done.resolve(undefined);
+        }
+    }
+}
+//# sourceMappingURL=ptc-calls.js.map

package/lib/types/ptc.d.ts

@@ -5,6 +5,7 @@
  * outer curated result enters model history.
  * @module @qilin-agent/tools/src/ptc
  */
+import { type Context } from '@qilin-agent/kylin';
 import { HarnessError } from '@qilin-agent/llm';
 declare module '@qilin-agent/llm' {
     interface MessageSourceMap {
@@ -68,15 +69,16 @@ export interface RunCodeBridgeOptions {
     shapeDispatchLog: (dispatch: PtcDispatchLog) => Promise<ContentBlock[]>;
 }
 /**
- * Build the `run_code` {@link ToolDefinition}: required `description` and
- * `code` parameters, executed through the dispatch bridge described
+ * Build the `run_code` {@link ToolDefinition}: required `code` and
+ * `description` parameters, executed through the dispatch bridge described
  * above. The
  * registry reserves it as presentation infrastructure under non-native modes,
  * outside the filterable global/scoped capability layers.
  * @param registry - the owning registry (sub-calls go through its `execute`,
  *   bindings cover its registered tools).
  * @param options - the registry-private capabilities described above.
+ * @param ctx - Owning registry context, independent of the calling Agent.
  * @returns the registry-ready definition.
  */
-export declare function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeOptions): ToolDefinition;
+export declare function createRunCodeTool(registry: ToolRuntime, options: RunCodeBridgeOptions, ctx: Context): ToolDefinition;
 //# sourceMappingURL=ptc.d.ts.map