@ljoukov/llm 7.0.14 → 7.0.15

package/README.md

@@ -699,6 +699,57 @@ console.log(result.text);
 
 `{ type: "shell" }` uses OpenAI hosted shell containers by default. It is only supported for OpenAI API models; ChatGPT-authenticated, Gemini, and Fireworks providers reject it.
 
+When the shell writes artifacts under `/mnt/data`, `generateText()` returns the
+OpenAI container reference and the library can retrieve the resulting files:
+
+```ts
+import { downloadOpenAiContainerFile, generateText, listOpenAiContainerFiles } from "@ljoukov/llm";
+
+const result = await generateText({
+  model: "gpt-5.5",
+  input:
+    "Use the shell to write /mnt/data/report.txt containing 'hello'. Reply only when done.",
+  tools: [{ type: "shell" }],
+});
+
+const containerId = result.openAi?.containers.find((c) => c.toolType === "shell")?.containerId;
+if (!containerId) throw new Error("The response did not include a hosted shell container.");
+
+const files = await listOpenAiContainerFiles(containerId);
+const report = files.find((file) => file.path === "/mnt/data/report.txt");
+if (!report) throw new Error("The shell did not create report.txt.");
+
+const bytes = await downloadOpenAiContainerFile({
+  containerId,
+  fileId: report.id,
+});
+```
+
+For persistent multi-step shell work, create a container first, upload any input
+assets, then pass it back as a `container-reference`:
+
+```ts
+import {
+  createOpenAiContainer,
+  generateText,
+  uploadOpenAiContainerFile,
+} from "@ljoukov/llm";
+
+const container = await createOpenAiContainer({ name: "latex-build", memoryLimit: "1g" });
+const cover = await uploadOpenAiContainerFile({
+  containerId: container.id,
+  filename: "cover.png",
+  data: coverPngBytes,
+  mimeType: "image/png",
+});
+
+await generateText({
+  model: "gpt-5.5",
+  input: `Use ${cover.path}, write LaTeX, run xelatex, and save /mnt/data/article.pdf.`,
+  tools: [{ type: "shell", environment: { type: "container-reference", containerId: container.id } }],
+});
+```
+
 ### Runtime Tools (`runToolLoop()`)
 
 Use this when the model should call your local runtime functions.

package/dist/index.cjs

@@ -84,12 +84,16 @@ __export(index_exports, {
   createListDirectoryTool: () => createListDirectoryTool,
   createModelAgnosticFilesystemToolSet: () => createModelAgnosticFilesystemToolSet,
   createNodeAgentFilesystem: () => createNodeAgentFilesystem,
+  createOpenAiContainer: () => createOpenAiContainer,
   createReplaceTool: () => createReplaceTool,
   createRgSearchTool: () => createRgSearchTool,
   createToolLoopSteeringChannel: () => createToolLoopSteeringChannel,
   createViewImageTool: () => createViewImageTool,
   createWriteFileTool: () => createWriteFileTool,
   customTool: () => customTool,
+  deleteOpenAiContainer: () => deleteOpenAiContainer,
+  downloadOpenAiContainerFile: () => downloadOpenAiContainerFile,
+  downloadOpenAiContainerFileText: () => downloadOpenAiContainerFileText,
   emptyFileUploadMetrics: () => emptyFileUploadMetrics,
   encodeChatGptAuthJson: () => encodeChatGptAuthJson,
   encodeChatGptAuthJsonB64: () => encodeChatGptAuthJsonB64,
@@ -114,6 +118,7 @@ __export(index_exports, {
   isLlmTextModelId: () => isLlmTextModelId,
   isOpenAiImageModelId: () => isOpenAiImageModelId,
   isOpenAiModelId: () => isOpenAiModelId,
+  listOpenAiContainerFiles: () => listOpenAiContainerFiles,
   loadEnvFromFile: () => loadEnvFromFile,
   loadLocalEnv: () => loadLocalEnv,
   parseJsonFromLlmText: () => parseJsonFromLlmText,
@@ -134,6 +139,7 @@ __export(index_exports, {
   stripCodexCitationMarkers: () => stripCodexCitationMarkers,
   toGeminiJsonSchema: () => toGeminiJsonSchema,
   tool: () => tool,
+  uploadOpenAiContainerFile: () => uploadOpenAiContainerFile,
   validateOpenAiGptImage2Resolution: () => validateOpenAiGptImage2Resolution
 });
 module.exports = __toCommonJS(index_exports);
@@ -6462,6 +6468,50 @@ function toOpenAiTools(tools, options) {
     }
   });
 }
+function extractOpenAiResponseMetadata(response) {
+  if (!response || typeof response !== "object") {
+    return void 0;
+  }
+  const record = response;
+  const responseId = typeof record.id === "string" ? record.id : void 0;
+  const output = Array.isArray(record.output) ? record.output : [];
+  const containers = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addContainer = (container) => {
+    const key = `${container.toolType}:${container.containerId}:${container.itemId ?? ""}:${container.callId ?? ""}`;
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    containers.push(container);
+  };
+  for (const item of output) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const itemRecord = item;
+    const itemId = typeof itemRecord.id === "string" ? itemRecord.id : void 0;
+    const callId = typeof itemRecord.call_id === "string" ? itemRecord.call_id : void 0;
+    if (itemRecord.type === "shell_call") {
+      const environment = itemRecord.environment && typeof itemRecord.environment === "object" ? itemRecord.environment : void 0;
+      const containerId = environment?.type === "container_reference" && typeof environment.container_id === "string" ? environment.container_id : void 0;
+      if (containerId) {
+        addContainer({ containerId, toolType: "shell", itemId, callId });
+      }
+      continue;
+    }
+    if (itemRecord.type === "code_interpreter_call") {
+      const containerId = typeof itemRecord.container_id === "string" ? itemRecord.container_id : void 0;
+      if (containerId) {
+        addContainer({ containerId, toolType: "code_interpreter", itemId, callId });
+      }
+    }
+  }
+  if (!responseId && containers.length === 0) {
+    return void 0;
+  }
+  return { ...responseId ? { responseId } : {}, containers };
+}
 function mergeTokenUpdates(current, next) {
   if (!next) {
     return current;
@@ -8073,6 +8123,7 @@ async function runTextCall(params) {
   let modelVersion = request.model;
   let blocked = false;
   let grounding;
+  let openAi;
   const responseParts = [];
   let responseRole;
   let latestUsage;
@@ -8183,6 +8234,7 @@ async function runTextCall(params) {
             }
           }
           const finalResponse = await stream.finalResponse();
+          openAi = extractOpenAiResponseMetadata(finalResponse);
           modelVersion = typeof finalResponse.model === "string" ? finalResponse.model : request.model;
           pushEvent({ type: "model", modelVersion });
           if (finalResponse.error) {
@@ -8426,6 +8478,7 @@ async function runTextCall(params) {
           costUsd,
           usage: latestUsage,
           grounding: grounding ? sanitiseLogValue(grounding) : void 0,
+          openAi: openAi ? sanitiseLogValue(openAi) : void 0,
           responseChars: text.length,
           thoughtChars: thoughts.length,
           responseImages,
@@ -8442,7 +8495,8 @@ async function runTextCall(params) {
         blocked,
         usage: latestUsage,
         costUsd,
-        grounding
+        grounding,
+        openAi
       };
     } catch (error) {
       const partialParts = mergeConsecutiveTextParts(responseParts);
@@ -11091,6 +11145,104 @@ function appendMarkdownSourcesSection(value, sources) {
 ${lines}`;
 }
 
+// src/openai/containers.ts
+var import_openai4 = require("openai");
+function toOpenAiContainerNetworkPolicy(policy) {
+  if (!policy) {
+    return void 0;
+  }
+  if (policy.type === "disabled") {
+    return { type: "disabled" };
+  }
+  return {
+    type: "allowlist",
+    allowed_domains: Array.from(policy.allowedDomains),
+    ...policy.domainSecrets ? {
+      domain_secrets: policy.domainSecrets.map((secret) => ({
+        domain: secret.domain,
+        name: secret.name,
+        value: secret.value
+      }))
+    } : {}
+  };
+}
+function toContainer(container) {
+  return {
+    id: String(container.id),
+    name: typeof container.name === "string" ? container.name : "",
+    status: typeof container.status === "string" ? container.status : "",
+    ...typeof container.created_at === "number" ? { createdAt: container.created_at } : {},
+    ...typeof container.last_active_at === "number" ? { lastActiveAt: container.last_active_at } : {},
+    ...typeof container.memory_limit === "string" ? { memoryLimit: container.memory_limit } : {}
+  };
+}
+function toContainerFile(file) {
+  return {
+    id: String(file.id),
+    containerId: typeof file.container_id === "string" ? file.container_id : "",
+    path: typeof file.path === "string" ? file.path : "",
+    ...typeof file.bytes === "number" || file.bytes === null ? { bytes: file.bytes } : {},
+    ...typeof file.created_at === "number" ? { createdAt: file.created_at } : {},
+    ...typeof file.source === "string" ? { source: file.source } : {}
+  };
+}
+async function createOpenAiContainer(options) {
+  const container = await runOpenAiCall(
+    async (client) => await client.containers.create({
+      name: options.name,
+      ...options.fileIds ? { file_ids: Array.from(options.fileIds) } : {},
+      ...options.memoryLimit ? { memory_limit: options.memoryLimit } : {},
+      ...options.networkPolicy ? { network_policy: toOpenAiContainerNetworkPolicy(options.networkPolicy) } : {},
+      ...options.expiresAfterMinutes ? {
+        expires_after: {
+          anchor: "last_active_at",
+          minutes: options.expiresAfterMinutes
+        }
+      } : {}
+    }),
+    "openai-containers"
+  );
+  return toContainer(container);
+}
+async function deleteOpenAiContainer(containerId) {
+  await runOpenAiCall(
+    async (client) => await client.containers.delete(containerId),
+    "openai-containers"
+  );
+}
+async function listOpenAiContainerFiles(containerId) {
+  const files2 = [];
+  await runOpenAiCall(async (client) => {
+    for await (const file of client.containers.files.list(containerId)) {
+      files2.push(toContainerFile(file));
+    }
+  }, "openai-containers");
+  return files2;
+}
+async function uploadOpenAiContainerFile(upload) {
+  const file = await (0, import_openai4.toFile)(upload.data, upload.filename, {
+    ...upload.mimeType ? { type: upload.mimeType } : {}
+  });
+  const created = await runOpenAiCall(
+    async (client) => await client.containers.files.create(upload.containerId, { file }),
+    "openai-containers"
+  );
+  return toContainerFile(created);
+}
+async function downloadOpenAiContainerFile(params) {
+  const response = await runOpenAiCall(
+    async (client) => await client.containers.files.content.retrieve(params.fileId, {
+      container_id: params.containerId
+    }),
+    "openai-containers"
+  );
+  return new Uint8Array(await response.arrayBuffer());
+}
+async function downloadOpenAiContainerFileText(params) {
+  const bytes = await downloadOpenAiContainerFile(params);
+  return new TextDecoder().decode(bytes);
+}
+
 // src/agent.ts
 var import_node_crypto4 = require("crypto");
 var import_node_path9 = __toESM(require("path"), 1);
@@ -14891,12 +15043,16 @@ async function runCandidateEvolution(options) {
   createListDirectoryTool,
   createModelAgnosticFilesystemToolSet,
   createNodeAgentFilesystem,
+  createOpenAiContainer,
   createReplaceTool,
   createRgSearchTool,
   createToolLoopSteeringChannel,
   createViewImageTool,
   createWriteFileTool,
   customTool,
+  deleteOpenAiContainer,
+  downloadOpenAiContainerFile,
+  downloadOpenAiContainerFileText,
   emptyFileUploadMetrics,
   encodeChatGptAuthJson,
   encodeChatGptAuthJsonB64,
@@ -14921,6 +15077,7 @@ async function runCandidateEvolution(options) {
   isLlmTextModelId,
   isOpenAiImageModelId,
   isOpenAiModelId,
+  listOpenAiContainerFiles,
   loadEnvFromFile,
   loadLocalEnv,
   parseJsonFromLlmText,
@@ -14941,6 +15098,7 @@ async function runCandidateEvolution(options) {
   stripCodexCitationMarkers,
   toGeminiJsonSchema,
   tool,
+  uploadOpenAiContainerFile,
   validateOpenAiGptImage2Resolution
 });
 //# sourceMappingURL=index.cjs.map