@myagentroam/agent 0.11.28 → 0.11.29

package/dist/agent-core/tools/code-mode/cells.js

@@ -1,5 +1,5 @@
-import { randomUUID } from 'node:crypto';
 import { permissionStopFromError } from '../permissions.js';
+import { RuntimeResourceHandles } from '../runtime-resource-handles.js';
 import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { truncateModelText } from '../../runtime/token-budget.js';
 import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
@@ -39,6 +39,7 @@ function options(value, wait) {
 /** Session-owned execution, separate from the cancellable model-tool wait. */
 export class CodeCells {
     #cells = new Map();
+    #handles = new RuntimeResourceHandles('cell', (id) => this.#cells.has(id));
     #closed = false;
     #disposing = new Set();
     async start(value, context, run) {
@@ -75,7 +76,7 @@ export class CodeCells {
             throw new MarAgentError('MAR_AGENT_PROCESS_LIMIT', `The Local Host shared running-cell limit (${limits.codeMaxConcurrentCells}) was reached.`);
         const controller = new AbortController();
         const cell = {
-            cellId: randomUUID(),
+            cellId: this.#handles.create(),
             sessionId: context.sessionId,
             executionId: context.executionId,
             controller,
@@ -160,6 +161,7 @@ export class CodeCells {
     async wait(value, context) {
         const input = options(value, true);
         context.signal.throwIfAborted();
+        this.#handles.assertType(input.cellId);
         const cell = this.#cells.get(input.cellId);
         if (!cell || cell.sessionId !== context.sessionId)
             throw new MarAgentError('MAR_AGENT_CODE_CELL_NOT_FOUND', 'Code Exec cell is unavailable in this Session.');

package/dist/agent-core/tools/code-mode/index.js

@@ -45,7 +45,7 @@ Built-in namespaces:
 - catalog.tools() returns a read-only array of the tools callable in this cell, including name, description and inputSchema. It does not discover or authorize additional tools.
 - await cell.sleep(ms) performs a cancellable delay up to ${limits.codeSleepMaxMs} ms.
 - await cell.yield_control() returns accumulated output to the model immediately while this cell continues running.
-- Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and controls this call's wait window (0..${limits.codeMaxYieldMs}), not nested tool timeouts or wait windows. A running result includes cellId; use direct code_exec_wait for new output, completion or termination.
+- Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and controls this call's wait window (0..${limits.codeMaxYieldMs}), not nested tool timeouts or wait windows. A running result includes cellId (c_ plus 12 lowercase hex characters); use direct code_exec_wait for new output, completion or termination.
 - waitOutcome separates snapshot, completion, timeout, and yield from the cell status. A foreground steer returns interrupted with reason=steer without stopping the cell or its internal tool waits.
 - Registered cells are Session warm resources: ending or cancelling the model Execution cancels its wait, not the cell. Reuse retained cellId; do not start duplicate work. Host cleanup or explicit termination stops the cell.
 - tools, observe, state, catalog and cell are frozen bindings. Do not shadow their names.
@@ -84,7 +84,10 @@ export const codeExecWaitToolDefinition = {
     inputSchema: {
         type: 'object',
         properties: {
-            cellId: { type: 'string' },
+            cellId: {
+                type: 'string',
+                description: 'Copy the complete cellId returned by code_exec (c_ followed by 12 lowercase hex characters). Never use a processId (p_); use exec_wait for processes.'
+            },
             yieldMs: {
                 type: 'integer',
                 minimum: 0,

package/dist/agent-core/tools/local/exec.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { RuntimeResourceHandles } from '../runtime-resource-handles.js';
 import { StringDecoder } from 'node:string_decoder';
 import { MarAgentError } from '../../error.js';
 import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
@@ -30,7 +30,7 @@ export const execToolDefinition = {
     name: 'exec',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId, status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, call exec_wait directly with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process. waitOutcome distinguishes snapshot, completion, timeout, and yield. A foreground wait may return interrupted with reason=steer; the process keeps running.',
+    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId (p_ plus 12 lowercase hex characters), status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, call exec_wait directly with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process. waitOutcome distinguishes snapshot, completion, timeout, and yield. A foreground wait may return interrupted with reason=steer; the process keeps running.',
     outputSchema: {
         type: 'object',
         required: ['content', 'data'],
@@ -112,7 +112,7 @@ export const execWaitToolDefinition = {
             processId: {
                 type: 'string',
                 minLength: 1,
-                description: 'Stable processId returned by exec.'
+                description: 'Copy the complete processId returned by exec (p_ followed by 12 lowercase hex characters). Never use a cellId (c_); use code_exec_wait for cells.'
             },
             action: { enum: ['poll', 'write', 'cancel'], default: 'poll' },
             yieldMs: {
@@ -154,6 +154,7 @@ export class ExecTool {
     processExecutor;
     #processes = new Map();
     #completed = new Map();
+    #handles = new RuntimeResourceHandles('process', (id) => this.#processes.has(id) || this.#completed.has(id));
     #startingProcesses = new Set();
     constructor(paths, maxOutputBytes = TOOL_EXECUTION_LIMITS.execDefaultMaxOutputBytes, maxProcesses = TOOL_EXECUTION_LIMITS.maxProcesses, environment = process.env, shell, processExecutor = directLocalProcessExecutor) {
         this.paths = paths;
@@ -168,6 +169,7 @@ export class ExecTool {
             throw executionAbortReason(signal);
         const input = parseExecInput(arguments_);
         if ('processId' in input) {
+            this.#handles.assertType(input.processId);
             const process = this.#processes.get(input.processId);
             const completed = this.#completed.get(input.processId);
             if (completed) {
@@ -294,7 +296,7 @@ export class ExecTool {
                     details: { reasonCode: error?.code ?? 'UNKNOWN' }
                 });
             }
-            const id = randomUUID();
+            const id = this.#handles.create();
             let resolveExited;
             let resolveSettled;
             const managed = {

package/dist/agent-core/tools/runtime-resource-handles.d.ts

@@ -0,0 +1,21 @@
+declare const types: {
+    readonly cell: {
+        readonly prefix: "c_";
+        readonly field: "cellId";
+        readonly tool: "code_exec_wait";
+    };
+    readonly process: {
+        readonly prefix: "p_";
+        readonly field: "processId";
+        readonly tool: "exec_wait";
+    };
+};
+/** Typed runtime handles; resource owners retain registration and lifecycle authority. */
+export declare class RuntimeResourceHandles {
+    private readonly kind;
+    private readonly isReserved;
+    constructor(kind: keyof typeof types, isReserved: (id: string) => boolean);
+    create(): string;
+    assertType(id: string): void;
+}
+export {};

package/dist/agent-core/tools/runtime-resource-handles.js

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+const types = {
+    cell: { prefix: 'c_', field: 'cellId', tool: 'code_exec_wait' },
+    process: { prefix: 'p_', field: 'processId', tool: 'exec_wait' }
+};
+/** Typed runtime handles; resource owners retain registration and lifecycle authority. */
+export class RuntimeResourceHandles {
+    kind;
+    isReserved;
+    constructor(kind, isReserved) {
+        this.kind = kind;
+        this.isReserved = isReserved;
+    }
+    create() {
+        let id;
+        do {
+            id = `${types[this.kind].prefix}${randomBytes(6).toString('hex')}`;
+        } while (this.isReserved(id));
+        return id;
+    }
+    assertType(id) {
+        const expected = types[this.kind];
+        const actual = Object.values(types).find((type) => id.startsWith(type.prefix));
+        if (actual && actual !== expected)
+            throw new MarAgentError('MAR_AGENT_RESOURCE_HANDLE_TYPE_MISMATCH', `Expected ${expected.field} (${expected.prefix}...). This looks like ${actual.field}; use ${actual.tool} for that resource.`, { details: { expected: expected.field, received: actual.field, tool: actual.tool } });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.11.28",
+  "version": "0.11.29",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",