@librechat/agents 3.1.79 → 3.1.80-dev.1

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -51,14 +51,22 @@ function createAIMessageWithCodeCall(callId: string): AIMessage {
 
 describe('ToolNode code execution session management', () => {
   describe('session injection via runTool (direct execution)', () => {
-    it('injects session_id and _injected_files when session has files', async () => {
+    it('injects session ids (both names) and _injected_files when session has files', async () => {
       const capturedConfigs: Record<string, unknown>[] = [];
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'prev-session-abc',
         files: [
-          { id: 'file1', name: 'data.csv', session_id: 'prev-session-abc' },
-          { id: 'file2', name: 'chart.png', session_id: 'prev-session-abc' },
+          {
+            id: 'file1',
+            name: 'data.csv',
+            storage_session_id: 'prev-session-abc',
+          },
+          {
+            id: 'file2',
+            name: 'chart.png',
+            storage_session_id: 'prev-session-abc',
+          },
         ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
@@ -70,14 +78,34 @@ describe('ToolNode code execution session management', () => {
       await toolNode.invoke({ messages: [aiMsg] });
 
       expect(capturedConfigs).toHaveLength(1);
+      /* Both names injected so pre- and post-rename consumers see the
+       * field they expect. */
       expect(capturedConfigs[0].session_id).toBe('prev-session-abc');
       expect(capturedConfigs[0]._injected_files).toEqual([
-        { session_id: 'prev-session-abc', id: 'file1', name: 'data.csv' },
-        { session_id: 'prev-session-abc', id: 'file2', name: 'chart.png' },
+        {
+          id: 'file1',
+          /* `resource_id` defaults to `id` (the storage uuid) when
+           * the input ref didn't supply it — informational for
+           * `kind: 'user'` since codeapi derives sessionKey from
+           * auth context. The real LC priming chain DOES supply
+           * resource_id explicitly; the default is a back-compat
+           * landing for inputs that haven't been updated. */
+          resource_id: 'file1',
+          name: 'data.csv',
+          storage_session_id: 'prev-session-abc',
+          kind: 'user',
+        },
+        {
+          id: 'file2',
+          resource_id: 'file2',
+          name: 'chart.png',
+          storage_session_id: 'prev-session-abc',
+          kind: 'user',
+        },
       ]);
     });
 
-    it('injects session_id even when session has no tracked files', async () => {
+    it('injects session ids even when session has no tracked files', async () => {
       const capturedConfigs: Record<string, unknown>[] = [];
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
@@ -112,14 +140,22 @@ describe('ToolNode code execution session management', () => {
       expect(capturedConfigs[0]._injected_files).toBeUndefined();
     });
 
-    it('preserves per-file session_id for multi-session files', async () => {
+    it('preserves per-file storage_session_id for multi-session files', async () => {
       const capturedConfigs: Record<string, unknown>[] = [];
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'session-B',
         files: [
-          { id: 'f1', name: 'old.csv', session_id: 'session-A' },
-          { id: 'f2', name: 'new.png', session_id: 'session-B' },
+          {
+            id: 'f1',
+            name: 'old.csv',
+            storage_session_id: 'session-A',
+          },
+          {
+            id: 'f2',
+            name: 'new.png',
+            storage_session_id: 'session-B',
+          },
         ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
@@ -131,26 +167,27 @@ describe('ToolNode code execution session management', () => {
       await toolNode.invoke({ messages: [aiMsg] });
 
       const files = capturedConfigs[0]._injected_files as t.CodeEnvFile[];
-      expect(files[0].session_id).toBe('session-A');
-      expect(files[1].session_id).toBe('session-B');
+      expect(files[0].storage_session_id).toBe('session-A');
+      expect(files[1].storage_session_id).toBe('session-B');
     });
 
-    it('forwards per-file entity_id for mixed-entity sessions', async () => {
+    it('forwards per-file kind and version for mixed-kind sessions', async () => {
       const capturedConfigs: Record<string, unknown>[] = [];
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'session-A',
         files: [
           {
-            id: 'skill-file',
+            id: 'skill-123',
             name: 'demo/SKILL.md',
-            session_id: 'session-A',
-            entity_id: 'skill-123',
+            storage_session_id: 'session-A',
+            kind: 'skill',
+            version: 7,
           },
           {
             id: 'user-file',
             name: 'attachment.csv',
-            session_id: 'session-B',
+            storage_session_id: 'session-B',
           },
         ],
         lastUpdated: Date.now(),
@@ -165,15 +202,21 @@ describe('ToolNode code execution session management', () => {
       const files = capturedConfigs[0]._injected_files as t.CodeEnvFile[];
       expect(files).toEqual([
         {
-          session_id: 'session-A',
-          id: 'skill-file',
+          id: 'skill-123',
+          /* Default fallback when input doesn't supply `resource_id`.
+           * Production LC sets it explicitly to the skill's `_id`. */
+          resource_id: 'skill-123',
           name: 'demo/SKILL.md',
-          entity_id: 'skill-123',
+          storage_session_id: 'session-A',
+          kind: 'skill',
+          version: 7,
         },
         {
-          session_id: 'session-B',
           id: 'user-file',
+          resource_id: 'user-file',
           name: 'attachment.csv',
+          storage_session_id: 'session-B',
+          kind: 'user',
         },
       ]);
     });
@@ -184,7 +227,13 @@ describe('ToolNode code execution session management', () => {
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'evt-session',
-        files: [{ id: 'ef1', name: 'out.parquet', session_id: 'evt-session' }],
+        files: [
+          {
+            id: 'ef1',
+            name: 'out.parquet',
+            storage_session_id: 'evt-session',
+          },
+        ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
 
@@ -201,7 +250,17 @@ describe('ToolNode code execution session management', () => {
 
       expect(context).toEqual({
         session_id: 'evt-session',
-        files: [{ session_id: 'evt-session', id: 'ef1', name: 'out.parquet' }],
+        files: [
+          {
+            id: 'ef1',
+            /* `resource_id` defaults to `id` when input doesn't carry
+             * separate provenance — see toInjectedFileRef. */
+            resource_id: 'ef1',
+            name: 'out.parquet',
+            storage_session_id: 'evt-session',
+            kind: 'user',
+          },
+        ],
       });
     });
 
@@ -224,7 +283,9 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as { getCodeSessionContext: () => unknown }
       ).getCodeSessionContext();
 
-      expect(context).toEqual({ session_id: 'evt-session-empty' });
+      expect(context).toEqual({
+        session_id: 'evt-session-empty',
+      });
     });
 
     it('returns undefined when no session exists', () => {
@@ -244,18 +305,23 @@ describe('ToolNode code execution session management', () => {
       expect(context).toBeUndefined();
     });
 
-    it('forwards per-file entity_id to event-driven request context', () => {
+    it('forwards per-file kind and version to event-driven request context', () => {
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'evt-session',
         files: [
           {
-            id: 'sk1',
+            id: 'skill-abc',
             name: 'demo/SKILL.md',
-            session_id: 'evt-session',
-            entity_id: 'skill-abc',
+            storage_session_id: 'evt-session',
+            kind: 'skill',
+            version: 3,
+          },
+          {
+            id: 'usr1',
+            name: 'data.csv',
+            storage_session_id: 'evt-session',
           },
-          { id: 'usr1', name: 'data.csv', session_id: 'evt-session' },
         ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
@@ -275,12 +341,21 @@ describe('ToolNode code execution session management', () => {
         session_id: 'evt-session',
         files: [
           {
-            session_id: 'evt-session',
-            id: 'sk1',
+            id: 'skill-abc',
+            /* Default fallback when input doesn't supply `resource_id`. */
+            resource_id: 'skill-abc',
             name: 'demo/SKILL.md',
-            entity_id: 'skill-abc',
+            storage_session_id: 'evt-session',
+            kind: 'skill',
+            version: 3,
+          },
+          {
+            id: 'usr1',
+            resource_id: 'usr1',
+            name: 'data.csv',
+            storage_session_id: 'evt-session',
+            kind: 'user',
           },
-          { session_id: 'evt-session', id: 'usr1', name: 'data.csv' },
         ],
       });
     });
@@ -333,7 +408,7 @@ describe('ToolNode code execution session management', () => {
         expect.objectContaining({
           id: 'f1',
           name: 'result.csv',
-          session_id: 'new-sess',
+          storage_session_id: 'new-sess',
         })
       );
     });
@@ -384,8 +459,8 @@ describe('ToolNode code execution session management', () => {
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'old-sess',
         files: [
-          { id: 'f1', name: 'data.csv', session_id: 'old-sess' },
-          { id: 'f2', name: 'chart.png', session_id: 'old-sess' },
+          { id: 'f1', name: 'data.csv', storage_session_id: 'old-sess' },
+          { id: 'f2', name: 'chart.png', storage_session_id: 'old-sess' },
         ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
@@ -430,18 +505,18 @@ describe('ToolNode code execution session management', () => {
       expect(stored.files).toHaveLength(2);
 
       const csvFile = stored.files!.find((f) => f.name === 'data.csv');
-      expect(csvFile!.session_id).toBe('old-sess');
+      expect(csvFile!.storage_session_id).toBe('old-sess');
 
       const chartFile = stored.files!.find((f) => f.name === 'chart.png');
       expect(chartFile!.id).toBe('f3');
-      expect(chartFile!.session_id).toBe('new-sess');
+      expect(chartFile!.storage_session_id).toBe('new-sess');
     });
 
     it('preserves existing files when new execution has no files', () => {
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'old-sess',
-        files: [{ id: 'f1', name: 'data.csv', session_id: 'old-sess' }],
+        files: [{ id: 'f1', name: 'data.csv', storage_session_id: 'old-sess' }],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
 
@@ -507,7 +582,7 @@ describe('ToolNode code execution session management', () => {
           {
             toolCallId: 'tc5',
             content: 'search results',
-            artifact: { session_id: 'should-not-store' },
+            artifact: { storage_session_id: 'should-not-store' },
             status: 'success',
           },
         ],
@@ -597,9 +672,13 @@ describe('ToolNode code execution session management', () => {
                 {
                   id: 'f1',
                   name: 'sentinel.txt',
-                  session_id: 'storage-session-A',
+                  storage_session_id: 'storage-session-A',
+                },
+                {
+                  id: 'f2',
+                  name: 'data.csv',
+                  storage_session_id: 'storage-session-B',
                 },
-                { id: 'f2', name: 'data.csv', session_id: 'storage-session-B' },
               ],
             },
             status: 'success',
@@ -617,18 +696,20 @@ describe('ToolNode code execution session management', () => {
         Constants.EXECUTE_CODE
       ) as t.CodeSessionContext;
       /* The session-level id is the (latest) exec id — fine for tracking
-         "what session ran last" — but per-file storage ids must survive. */
+         "what session ran last" — but per-file storage ids must survive.
+         After the rename, both names appear at the top level (exec) and
+         on each file (storage). */
       expect(stored.session_id).toBe('exec-session-123');
       expect(stored.files).toHaveLength(2);
       expect(stored.files![0]).toEqual({
         id: 'f1',
         name: 'sentinel.txt',
-        session_id: 'storage-session-A',
+        storage_session_id: 'storage-session-A',
       });
       expect(stored.files![1]).toEqual({
         id: 'f2',
         name: 'data.csv',
-        session_id: 'storage-session-B',
+        storage_session_id: 'storage-session-B',
       });
     });
 
@@ -658,7 +739,11 @@ describe('ToolNode code execution session management', () => {
               session_id: 'exec-mixed',
               files: [
                 /* Mix: one file with storage id, one without (older payload). */
-                { id: 'f1', name: 'fresh.csv', session_id: 'storage-fresh' },
+                {
+                  id: 'f1',
+                  name: 'fresh.csv',
+                  storage_session_id: 'storage-fresh',
+                },
                 { id: 'f2', name: 'legacy.csv' },
               ],
             },
@@ -676,9 +761,10 @@ describe('ToolNode code execution session management', () => {
       const stored = sessions.get(
         Constants.EXECUTE_CODE
       ) as t.CodeSessionContext;
-      expect(stored.files![0].session_id).toBe('storage-fresh');
-      /* Fallback only when the per-file id is missing. */
-      expect(stored.files![1].session_id).toBe('exec-mixed');
+      expect(stored.files![0].storage_session_id).toBe('storage-fresh');
+      /* Fallback only when the per-file id is missing — the fallback
+       * value is the exec session id. */
+      expect(stored.files![1].storage_session_id).toBe('exec-mixed');
     });
   });
 
@@ -728,7 +814,13 @@ describe('ToolNode code execution session management', () => {
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
         session_id: 'rf-session',
-        files: [{ id: 'rf1', name: 'data.csv', session_id: 'rf-session' }],
+        files: [
+          {
+            id: 'rf1',
+            name: 'data.csv',
+            storage_session_id: 'rf-session',
+          },
+        ],
         lastUpdated: Date.now(),
       } satisfies t.CodeSessionContext);
 
@@ -758,7 +850,17 @@ describe('ToolNode code execution session management', () => {
       expect(capturedRequests[0].name).toBe(Constants.READ_FILE);
       expect(capturedRequests[0].codeSessionContext).toEqual({
         session_id: 'rf-session',
-        files: [{ session_id: 'rf-session', id: 'rf1', name: 'data.csv' }],
+        files: [
+          {
+            id: 'rf1',
+            /* Default fallback for inputs that don't carry separate
+             * provenance — see toInjectedFileRef. */
+            resource_id: 'rf1',
+            name: 'data.csv',
+            storage_session_id: 'rf-session',
+            kind: 'user',
+          },
+        ],
       });
     });
 

package/src/tools/local/LocalExecutionTools.ts

@@ -115,7 +115,7 @@ export function createLocalCodeExecutionTool(
         {
           session_id: getLocalSessionId(config),
           files: [],
-        },
+        } satisfies t.CodeExecutionArtifact,
       ];
     },
     {
@@ -151,7 +151,7 @@ export function createLocalBashExecutionTool(options?: {
         {
           session_id: getLocalSessionId(config),
           files: [],
-        },
+        } satisfies t.CodeExecutionArtifact,
       ];
     },
     {

package/src/tools/local/LocalProgrammaticToolCalling.ts

@@ -79,7 +79,9 @@ type LocalProgrammaticParams = {
 
 type ToolFilter = (toolDefs: t.LCTool[], code: string) => t.LCTool[];
 
-function resolveRuntime(params: LocalProgrammaticParams): LocalProgrammaticRuntime {
+function resolveRuntime(
+  params: LocalProgrammaticParams
+): LocalProgrammaticRuntime {
   const rawRuntime = params.lang ?? params.runtime ?? params.language ?? 'bash';
   return rawRuntime === 'py' || rawRuntime === 'python' ? 'python' : 'bash';
 }
@@ -494,13 +496,17 @@ async function runLocalProgrammaticTool(args: {
   localConfig: t.LocalExecutionConfig;
   runtime: LocalProgrammaticRuntime;
 }): Promise<[string, t.ProgrammaticExecutionArtifact]> {
-  const { toolMap, toolDefs, hookContext } = getProgrammaticContext(args.config);
+  const { toolMap, toolDefs, hookContext } = getProgrammaticContext(
+    args.config
+  );
 
   if (toolMap == null || toolMap.size === 0) {
     throw new Error('No toolMap provided for local programmatic execution.');
   }
   if (toolDefs == null || toolDefs.length === 0) {
-    throw new Error('No tool definitions provided for local programmatic execution.');
+    throw new Error(
+      'No tool definitions provided for local programmatic execution.'
+    );
   }
 
   const { effectiveTools, effectiveMap } = createEffectiveToolMap(
@@ -512,17 +518,28 @@ async function runLocalProgrammaticTool(args: {
   const bridge = await createToolBridge(effectiveMap, hookContext);
 
   try {
-    const timeoutMs = args.params.timeout ?? args.localConfig.timeoutMs ?? DEFAULT_TIMEOUT;
+    const timeoutMs =
+      args.params.timeout ?? args.localConfig.timeoutMs ?? DEFAULT_TIMEOUT;
     const result =
       args.runtime === 'bash'
         ? await executeLocalBash(
-          createBashProgram(args.params.code, effectiveTools, bridge.url, bridge.token),
+          createBashProgram(
+            args.params.code,
+            effectiveTools,
+            bridge.url,
+            bridge.token
+          ),
           { ...args.localConfig, timeoutMs }
         )
         : await executeLocalCode(
           {
             lang: 'py',
-            code: createPythonProgram(args.params.code, effectiveTools, bridge.url, bridge.token),
+            code: createPythonProgram(
+              args.params.code,
+              effectiveTools,
+              bridge.url,
+              bridge.token
+            ),
           },
           { ...args.localConfig, timeoutMs }
         );

package/src/types/tools.ts

@@ -138,42 +138,114 @@ export type ToolEndEvent = {
   type?: 'tool_call';
 };
 
-export type CodeEnvFile = {
+/**
+ * Closed set of resource kinds for sandbox file caching. Defined as a
+ * `as const` tuple so the runtime list and the TypeScript union can't
+ * drift on future additions — adding a new kind to the tuple updates
+ * both at once.
+ *
+ * - `skill`: shared per skill identity. Cross-user-within-tenant
+ *   sharing. Codeapi sessionKey omits the user dimension. `version`
+ *   is required (skill's monotonic counter scopes cache per revision).
+ * - `agent`: shared per agent identity. Same sharing semantic as
+ *   skills.
+ * - `user`: user-private. Codeapi sessionKey is keyed by the
+ *   requesting user from auth context. Used for chat attachments
+ *   and code-output files.
+ */
+export const CODE_ENV_KINDS = ['skill', 'agent', 'user'] as const;
+export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];
+
+type CodeEnvFileBase = {
+  /**
+   * **Storage file id** — the per-file uuid the file_server returns
+   * at upload time. Identifies the bytes at
+   * `<storage_session_id>/<id>` in the object bucket; used by the
+   * worker to fetch the file and by codeapi's auth layer for the
+   * upload-existence check.
+   *
+   * Distinct from `resource_id` below — that's the entity that owns
+   * this file's storage session (skill `_id`, agent id, etc.), used
+   * for sessionKey resolution. Conflating the two caused
+   * shared-kind authorization to fail because the sessionKey
+   * re-derivation used the storage nanoid where the resource id was
+   * required. See codeapi #1455 review.
+   */
   id: string;
+  /**
+   * **Resource id** — the entity that owns this file's storage
+   * session. Skill `_id` for `kind: 'skill'`, agent id for `'agent'`,
+   * informational only for `'user'` (codeapi resolves user identity
+   * from auth context). Kept on the type for shape uniformity across
+   * kinds.
+   *
+   * Drives codeapi's `resolveSessionKey` switch — the sessionKey
+   * embeds this value (`<tenant>:<kind>:<resource_id>[:v:<version>]`)
+   * so cross-user-within-tenant sharing for shared kinds is a
+   * designed property of the kind switch.
+   */
+  resource_id: string;
   name: string;
-  session_id: string;
   /**
-   * Identifier of the entity that owns this file's session (skill id,
-   * agent id, etc). Forwarded to codeapi so it can resolve the
-   * per-file sessionKey instead of falling back to a single
-   * request-level entity. Required when a single execute request
-   * references files uploaded under different entities (e.g. a skill
-   * file plus a user attachment in the same call).
+   * Storage session — the long-lived bucket where this file's bytes
+   * live in object storage. Distinct from the (transient) execution
+   * session id that appears at the top level of an execute response;
+   * the two used to share the field name `session_id` and the
+   * conflation caused real bugs. See codeapi #1455 / agents #148.
    */
-  entity_id?: string;
+  storage_session_id: string;
 };
 
+/**
+ * `CodeEnvFile` is a discriminated union on `kind`. `version` is
+ * statically required for `kind: 'skill'` and statically forbidden
+ * for `agent` / `user` — the constraint holds at compile time on
+ * every consumer, not just on codeapi's runtime validator.
+ *
+ * Codeapi switches on `kind` to derive the sessionKey for cache
+ * scoping (`<tenant>:<kind>:<id>[:v:<version>]`). Cross-user sharing
+ * for `kind: 'skill'` / `'agent'` is a designed property of the
+ * kind switch.
+ */
+export type CodeEnvFile =
+  | (CodeEnvFileBase & { kind: 'skill'; version: number })
+  | (CodeEnvFileBase & { kind: 'agent' })
+  | (CodeEnvFileBase & { kind: 'user' });
+
 export type CodeExecutionToolParams =
   | undefined
   | {
+      /** Execution session — see `CodeSessionContext.session_id`. */
       session_id?: string;
       user_id?: string;
       files?: CodeEnvFile[];
     };
 
 export type FileRef = {
+  /**
+   * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
+   * the full motivation behind the storage-vs-resource split.
+   */
   id: string;
+  /**
+   * Resource id — the entity that owns this file's storage session.
+   * Optional on `FileRef` (post-execute artifact refs may not carry
+   * resource provenance for outputs); required on `CodeEnvFile`
+   * (the input wire shape).
+   */
+  resource_id?: string;
   name: string;
   path?: string;
-  /** Session ID this file belongs to (for multi-session file tracking) */
-  session_id?: string;
   /**
-   * Entity that owns this file's session (skill id, agent id, etc).
-   * Carried on tracked session files so it can flow through to
-   * `_injected_files` when a subsequent execute references a mix of
-   * files uploaded under different entities.
+   * Storage session this file lives in. See `CodeEnvFile.storage_session_id`
+   * for the full motivation.
    */
-  entity_id?: string;
+  storage_session_id?: string;
+  /** Resource kind — see `CodeEnvFile.kind`. */
+  kind?: CodeEnvKind;
+  /** Resource version — see `CodeEnvFile.version`. Only meaningful when
+   *  `kind === 'skill'`. */
+  version?: number;
   /**
    * `true` when the codeapi sandbox echoed this entry as an unchanged
    * passthrough of an input the caller already owns (skill files,
@@ -188,6 +260,11 @@ export type FileRef = {
 export type FileRefs = FileRef[];
 
 export type ExecuteResult = {
+  /**
+   * Execution session id — the (transient) sandbox run that produced
+   * this output. Distinct from per-file `storage_session_id` on the
+   * files array.
+   */
   session_id: string;
   stdout: string;
   stderr: string;
@@ -254,6 +331,7 @@ export type ToolCallRequest = {
   turn?: number;
   /** Code execution session context for session continuity in event-driven mode */
   codeSessionContext?: {
+    /** Execution session — see `CodeSessionContext.session_id`. */
     session_id: string;
     files?: CodeEnvFile[];
   };
@@ -775,6 +853,7 @@ export type PTCToolResult = {
  */
 export type ProgrammaticExecutionResponse = {
   status: 'tool_call_required' | 'completed' | 'error' | unknown;
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
 
   /** Present when status='tool_call_required' */
@@ -794,6 +873,7 @@ export type ProgrammaticExecutionResponse = {
  * Artifact returned by the PTC tool
  */
 export type ProgrammaticExecutionArtifact = {
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
 };
@@ -827,7 +907,12 @@ export type ProgrammaticToolCallingParams = {
  * Stored in Graph.sessions and injected into subsequent tool invocations.
  */
 export type CodeSessionContext = {
-  /** Session ID from the code execution environment */
+  /**
+   * Execution session id — the (transient) sandbox run id. Used by
+   * ToolNode to thread session continuity into the next code-execution
+   * tool call. Distinct from per-file `storage_session_id` carried on
+   * `files`.
+   */
   session_id: string;
   /** Files generated in this session (for context/tracking) */
   files?: FileRefs;
@@ -840,6 +925,7 @@ export type CodeSessionContext = {
  * Used to extract session context after tool completion.
  */
 export type CodeExecutionArtifact = {
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
 };