@giselles-ai/agent 0.1.25 → 0.1.27

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentConfig, D as DefinedAgent } from './types-cRejduhB.js';
-export { a as AgentFile, b as AgentSetup } from './types-cRejduhB.js';
+import { A as AgentConfig, D as DefinedAgent } from './types-Co_KfALw.js';
+export { a as AgentFile, b as AgentSetup, U as UICatalog } from './types-Co_KfALw.js';
 
 declare function defineAgent(config: AgentConfig): DefinedAgent;
 

package/dist/index.js

@@ -4,12 +4,29 @@ import {
 } from "./chunk-JGH5DCA7.js";
 
 // src/define-agent.ts
+function createInternalArtifactPrompt() {
+  return `
+## Artifact Convention
+- Files intended for user review or download must be written under ./artifacts/.
+- Temporary files, logs, caches, and intermediate data should stay outside ./artifacts/.
+- Before finishing, inspect ./artifacts/ and mention only files that actually exist there.
+- Mention created artifact paths in the assistant response for fallback visibility.
+`.trim();
+}
 function defineAgent(config) {
+  const catalogPrompt = config.catalog?.prompt({ mode: "inline" });
+  const internalPrompt = createInternalArtifactPrompt();
+  const agentMd = [config.agentMd, internalPrompt, catalogPrompt].filter(Boolean).join("\n\n");
   return {
     agentType: config.agentType ?? "gemini",
-    agentMd: config.agentMd,
+    agentMd: agentMd || void 0,
+    catalog: config.catalog,
     files: config.files ?? [],
-    env: config.env ?? {},
+    env: config.env ? Object.fromEntries(
+      Object.entries(config.env).filter(
+        (entry) => entry[1] != null
+      )
+    ) : {},
     setup: config.setup,
     get snapshotId() {
       const id = process.env?.GISELLE_AGENT_SNAPSHOT_ID;

package/dist/next/index.d.ts

@@ -1,5 +1,5 @@
 import { NextConfig } from 'next';
-import { A as AgentConfig } from '../types-cRejduhB.js';
+import { A as AgentConfig } from '../types-Co_KfALw.js';
 
 type GiselleAgentPluginOptions = {
     /** Base URL for the agent API. Default: process.env.GISELLE_AGENT_BASE_URL ?? "https://studio.giselles.ai/agent-api" */

package/dist/server/index.js

@@ -1,8 +1,10 @@
 // src/agent-api.ts
+import { basename } from "path";
 import {
   createRelayHandler,
   createRelaySession
 } from "@giselles-ai/browser-tool/relay";
+import { Sandbox as Sandbox3 } from "@vercel/sandbox";
 
 // src/build.ts
 import { Sandbox } from "@vercel/sandbox";
@@ -537,11 +539,19 @@ function createGeminiAgent(options = {}) {
         "--output-format",
         "stream-json",
         "--approval-mode",
-        "yolo"
+        "yolo",
+        "--sandbox",
+        "false"
       ];
       if (input.session_id) {
         args.push("--resume", input.session_id);
       }
+      console.info("[gemini-agent] createCommand", {
+        hasSessionId: Boolean(input.session_id),
+        hasSandboxId: Boolean(input.sandbox_id),
+        hasSnapshotId: Boolean(input.snapshot_id),
+        argCount: args.length
+      });
       return {
         cmd: "gemini",
         args,
@@ -597,6 +607,97 @@ function createAgent(options) {
 // src/chat-run.ts
 import { Writable } from "stream";
 import { Sandbox as Sandbox2 } from "@vercel/sandbox";
+var COMMAND_TIMEOUT_EXTENSION_MS = 5 * 60 * 1e3;
+var ARTIFACT_DIRS = ["./artifacts", "/vercel/sandbox/artifacts"];
+function getArtifactMimeType(path) {
+  const extension = path.split(".").pop()?.toLowerCase();
+  switch (extension) {
+    case "md":
+      return "text/markdown; charset=utf-8";
+    case "json":
+      return "application/json; charset=utf-8";
+    case "csv":
+      return "text/csv; charset=utf-8";
+    case "txt":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+function getArtifactLabel(path) {
+  const pieces = path.split("/");
+  return pieces[pieces.length - 1] ?? path;
+}
+async function collectArtifacts(sandbox) {
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  let discoveryFailed = false;
+  for (const artifactDir of ARTIFACT_DIRS) {
+    let output = "";
+    let discoveryStderr = "";
+    let exitCode = 0;
+    try {
+      const result = await sandbox.runCommand({
+        cmd: "find",
+        args: [artifactDir, "-type", "f", "-print"]
+      });
+      output = await result.stdout();
+      discoveryStderr = await result.stderr();
+      exitCode = typeof result.exitCode === "number" ? result.exitCode : 0;
+    } catch (error) {
+      discoveryFailed = true;
+      console.warn("[chat-run] artifact discovery failed for directory", {
+        directory: artifactDir,
+        error: error instanceof Error ? error.message : String(error),
+        stderr: discoveryStderr
+      });
+      continue;
+    }
+    if (exitCode !== 0 && !output.trim()) {
+      discoveryFailed = true;
+      console.warn(
+        "[chat-run] artifact discovery returned non-zero exit code",
+        {
+          directory: artifactDir,
+          exitCode,
+          stderr: discoveryStderr
+        }
+      );
+      continue;
+    }
+    if (!output.trim()) {
+      continue;
+    }
+    for (const line of output.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const [path, rawSize] = trimmed.split("	");
+      if (!path) {
+        continue;
+      }
+      const normalizedPath = path.startsWith("/vercel/sandbox/") ? `./${path.slice("/vercel/sandbox/".length)}` : path;
+      if (!normalizedPath.startsWith("./artifacts/") || seen.has(normalizedPath)) {
+        continue;
+      }
+      seen.add(normalizedPath);
+      const parsedSize = Number.parseInt(rawSize ?? "0", 10);
+      const size_bytes = Number.isNaN(parsedSize) ? 0 : parsedSize;
+      artifacts.push({
+        type: "artifact",
+        path: normalizedPath,
+        size_bytes,
+        mime_type: getArtifactMimeType(normalizedPath),
+        label: getArtifactLabel(normalizedPath)
+      });
+    }
+  }
+  if (discoveryFailed && artifacts.length === 0) {
+    return [];
+  }
+  return artifacts;
+}
 function emitText(controller, text, encoder) {
   if (text.length === 0) {
     return;
@@ -666,7 +767,21 @@ function runChat(input) {
           const sandbox = await (async () => {
             if (parsed.sandbox_id) {
               try {
-                return await Sandbox2.get({ sandboxId: parsed.sandbox_id });
+                const existing = await Sandbox2.get({
+                  sandboxId: parsed.sandbox_id
+                });
+                if (existing.status !== "running") {
+                  if (!snapshotId) {
+                    throw new Error(
+                      `Sandbox ${parsed.sandbox_id} is ${existing.status}, not running`
+                    );
+                  }
+                  console.log(
+                    `[sandbox] sandbox=${parsed.sandbox_id} status=${existing.status}, recreating from snapshot=${snapshotId}`
+                  );
+                  return createFromSnapshot(snapshotId);
+                }
+                return existing;
               } catch (error) {
                 if (!snapshotId) {
                   throw error;
@@ -692,6 +807,16 @@ function runChat(input) {
           const command = input.agent.createCommand({
             input: parsed
           });
+          console.info("[chat-run] starting sandbox command", {
+            sandboxId: sandbox.sandboxId,
+            cmd: command.cmd,
+            args: command.args,
+            envKeys: Object.keys(command.env ?? {}).sort(),
+            hasSessionId: typeof parsed.session_id === "string" && parsed.session_id.length > 0,
+            hasSandboxId: typeof parsed.sandbox_id === "string" && parsed.sandbox_id.length > 0,
+            hasSnapshotId: typeof parsed.snapshot_id === "string" && parsed.snapshot_id.length > 0
+          });
+          await sandbox.extendTimeout(COMMAND_TIMEOUT_EXTENSION_MS);
           await sandbox.runCommand({
             cmd: command.cmd,
             args: command.args,
@@ -713,12 +838,20 @@ function runChat(input) {
             stderr: new Writable({
               write(chunk, _encoding, callback) {
                 const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+                console.error("[chat-run] sandbox stderr", {
+                  sandboxId: sandbox.sandboxId,
+                  content: text
+                });
                 enqueueEvent({ type: "stderr", content: text });
                 callback();
               }
             }),
             signal: abortController.signal
           });
+          const discoveredArtifacts = await collectArtifacts(sandbox);
+          for (const artifact of discoveredArtifacts) {
+            enqueueEvent(artifact);
+          }
           const snapshot = await sandbox.snapshot();
           enqueueEvent({
             type: "snapshot",
@@ -969,8 +1102,12 @@ function injectRelayUrl(agent, relayUrl) {
     }
   };
 }
+function usesBrowserTool(agent) {
+  return isCreateAgentOptions2(agent) && agent.tools?.browser !== void 0;
+}
 async function runCloudChat(input) {
-  const agentParam = injectRelayUrl(input.agent, input.relayUrl);
+  const browserToolEnabled = usesBrowserTool(input.agent);
+  const agentParam = browserToolEnabled ? injectRelayUrl(input.agent, input.relayUrl) : input.agent;
   const agent = resolveAgent(agentParam);
   const now = input.now?.() ?? Date.now();
   const createRelaySub = input.createRelayRequestSubscription ?? createRelayRequestSubscription;
@@ -992,23 +1129,29 @@ async function runCloudChat(input) {
       sendResponse
     });
   }
-  const relaySession = await input.createRelaySession();
-  const relaySubscription = await createRelaySub({
-    sessionId: relaySession.sessionId,
-    token: relaySession.token
-  });
-  console.info("[cloud-chat] relay subscription ready", {
-    chatId: input.chatId,
-    relaySessionId: relaySession.sessionId
-  });
   const runtimeInput = {
     ...input.request,
     ...existing?.agentSessionId ? { session_id: existing.agentSessionId } : {},
     ...existing?.sandboxId ? { sandbox_id: existing.sandboxId } : {},
-    ...existing?.snapshotId ? { snapshot_id: existing.snapshotId } : {},
-    relay_session_id: relaySession.sessionId,
-    relay_token: relaySession.token
+    ...existing?.snapshotId ? { snapshot_id: existing.snapshotId } : {}
   };
+  let relaySession;
+  let relaySubscription = null;
+  if (browserToolEnabled) {
+    relaySession = await input.createRelaySession();
+    relaySubscription = await createRelaySub({
+      sessionId: relaySession.sessionId,
+      token: relaySession.token
+    });
+    console.info("[cloud-chat] relay subscription ready", {
+      chatId: input.chatId,
+      relaySessionId: relaySession.sessionId
+    });
+    Object.assign(runtimeInput, {
+      relay_session_id: relaySession.sessionId,
+      relay_token: relaySession.token
+    });
+  }
   let response;
   try {
     response = await (input.runChatImpl ?? runChat)({
@@ -1017,7 +1160,7 @@ async function runCloudChat(input) {
       input: runtimeInput
     });
   } catch (error) {
-    await relaySubscription.close().catch(() => void 0);
+    await relaySubscription?.close().catch(() => void 0);
     throw error;
   }
   const managed = createManagedCloudResponseFromReader({
@@ -1032,7 +1175,7 @@ async function runCloudChat(input) {
     relaySubscription,
     relaySession,
     relayUrl: input.relayUrl,
-    includeRelaySessionPrelude: true,
+    includeRelaySessionPrelude: browserToolEnabled,
     initialBuffer: "",
     initialTextBlockOpen: false
   });
@@ -1433,6 +1576,70 @@ function resolveRelayUrl(basePath, request) {
   }
   return new URL(`${basePath}/relay`, request.url).toString();
 }
+function createArtifactError(status, path, message) {
+  return errorResponse(status, "FILE_ERROR", `${path}: ${message}`);
+}
+function getArtifactMimeType2(path) {
+  const extension = path.split(".").pop()?.toLowerCase();
+  switch (extension) {
+    case "md":
+      return "text/markdown; charset=utf-8";
+    case "json":
+      return "application/json; charset=utf-8";
+    case "csv":
+      return "text/csv; charset=utf-8";
+    case "txt":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+async function resolveReadableSandbox(input) {
+  const createFromSnapshot = async (snapshotId) => Sandbox3.create({
+    source: {
+      type: "snapshot",
+      snapshotId
+    }
+  });
+  if (input.sandboxId) {
+    try {
+      const existing = await Sandbox3.get({ sandboxId: input.sandboxId });
+      if (existing.status === "running") {
+        return existing;
+      }
+      if (!input.snapshotId) {
+        throw new Error(
+          `Sandbox ${input.sandboxId} is ${existing.status}, not running`
+        );
+      }
+      console.log(
+        `[agent-api] sandbox=${input.sandboxId} status=${existing.status}, recreating from snapshot=${input.snapshotId}`
+      );
+      return createFromSnapshot(input.snapshotId);
+    } catch (error) {
+      if (!input.snapshotId) {
+        throw error;
+      }
+      console.log(
+        `[agent-api] sandbox=${input.sandboxId} expired, recreating from snapshot=${input.snapshotId}`
+      );
+      return createFromSnapshot(input.snapshotId);
+    }
+  }
+  if (!input.snapshotId) {
+    throw new Error("No sandbox_id or snapshot_id available for file read");
+  }
+  return createFromSnapshot(input.snapshotId);
+}
+function createDownloadHeaders(path, options) {
+  const filename = basename(path);
+  const mode = options.download === "1" ? "attachment" : "inline";
+  return {
+    "Content-Type": getArtifactMimeType2(path),
+    "Content-Disposition": `${mode}; filename="${filename}"`,
+    "Cache-Control": "private, no-store"
+  };
+}
 function createAgentApi(options) {
   const relay = createRelayHandler();
   const { basePath, agent: agentOptions } = options;
@@ -1474,6 +1681,45 @@ function createAgentApi(options) {
       return errorResponse(500, "INTERNAL_ERROR", message);
     }
   }
+  async function handleFiles(request) {
+    const url = new URL(request.url);
+    const chatId = url.searchParams.get("chat_id")?.trim();
+    const path = url.searchParams.get("path")?.trim();
+    const download = url.searchParams.get("download")?.trim();
+    if (!chatId || !path) {
+      return createArtifactError(400, "query", "chat_id and path are required");
+    }
+    if (!path.startsWith("./artifacts/") || path.includes("..")) {
+      return createArtifactError(400, "path", "path must be under ./artifacts");
+    }
+    const store = await getStore();
+    const chatState = await store.load(chatId);
+    if (!chatState) {
+      return createArtifactError(404, "chat_id", "chat session not found");
+    }
+    let sandbox;
+    try {
+      sandbox = await resolveReadableSandbox({
+        sandboxId: chatState.sandboxId,
+        snapshotId: chatState.snapshotId
+      });
+    } catch (error) {
+      return createArtifactError(
+        400,
+        "sandbox",
+        error instanceof Error ? error.message : "failed to resolve sandbox"
+      );
+    }
+    const fileBuffer = await sandbox.readFileToBuffer({
+      path
+    });
+    if (!fileBuffer) {
+      return createArtifactError(404, "path", "file not found");
+    }
+    return new Response(new Uint8Array(fileBuffer), {
+      headers: createDownloadHeaders(path, { download })
+    });
+  }
   async function handleRun(request) {
     try {
       const hookResult = await options.hooks?.chat?.before?.(request);
@@ -1532,6 +1778,7 @@ function createAgentApi(options) {
   function matchSubPath(request) {
     const url = new URL(request.url);
     const pathname = url.pathname;
+    const filesPath = `${basePath}/files`;
     if (pathname === authPath || pathname === `${authPath}/`) {
       return "auth";
     }
@@ -1541,6 +1788,9 @@ function createAgentApi(options) {
     if (pathname === buildPath || pathname === `${buildPath}/`) {
       return "build";
     }
+    if (pathname === filesPath || pathname === `${filesPath}/`) {
+      return "files";
+    }
     if (pathname === relayPrefix || pathname.startsWith(`${relayPrefix}/`)) {
       return "relay";
     }
@@ -1552,6 +1802,9 @@ function createAgentApi(options) {
       if (sub === "relay") {
         return relay.GET(request);
       }
+      if (sub === "files") {
+        return handleFiles(request);
+      }
       return errorResponse(404, "NOT_FOUND", "Not found.");
     },
     POST: async (request) => {
@@ -1575,6 +1828,9 @@ function createAgentApi(options) {
       if (sub === "relay") {
         return relay.OPTIONS(request);
       }
+      if (sub === "files") {
+        return new Response(null, { status: 204 });
+      }
       return new Response(null, { status: 204 });
     }
   };

package/dist/{types-cRejduhB.d.ts → types-Co_KfALw.d.ts}

@@ -1,3 +1,10 @@
+/** Minimal interface for a json-render catalog. */
+type UICatalog = {
+    prompt(options?: {
+        mode?: "inline" | "standalone";
+        customRules?: string[];
+    }): string;
+};
 type AgentFile = {
     path: string;
     content: string;
@@ -11,8 +18,10 @@ type AgentConfig = {
     agentType?: "gemini" | "codex";
     /** Content for AGENTS.md in the sandbox. */
     agentMd?: string;
+    /** Optional json-render catalog for generative UI. */
+    catalog?: UICatalog;
     /** Environment variables passed to the sandbox at build and run time. */
-    env?: Record<string, string>;
+    env?: Record<string, string | undefined>;
     /** Additional files to write into the sandbox. */
     files?: AgentFile[];
     /** Setup configuration for the sandbox build phase. */
@@ -21,6 +30,7 @@ type AgentConfig = {
 type DefinedAgent = {
     readonly agentType: "gemini" | "codex";
     readonly agentMd?: string;
+    readonly catalog?: UICatalog;
     readonly files: AgentFile[];
     /** Setup configuration. Undefined when no setup is configured. */
     readonly setup?: AgentSetup;
@@ -30,4 +40,4 @@ type DefinedAgent = {
     readonly snapshotId: string;
 };
 
-export type { AgentConfig as A, DefinedAgent as D, AgentFile as a, AgentSetup as b };
+export type { AgentConfig as A, DefinedAgent as D, UICatalog as U, AgentFile as a, AgentSetup as b };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@giselles-ai/agent",
-	"version": "0.1.25",
+	"version": "0.1.27",
 	"type": "module",
 	"sideEffects": false,
 	"license": "Apache-2.0",
@@ -37,9 +37,11 @@
 		"format": "pnpm exec biome check --write ."
 	},
 	"dependencies": {
-		"@giselles-ai/browser-tool": "0.1.25",
-		"@vercel/sandbox": "1.8.1",
+		"@giselles-ai/browser-tool": "0.1.27",
 		"@iarna/toml": "3.0.0",
+		"@json-render/core": "0.13.0",
+		"@vercel/sandbox": "1.8.1",
+		"sandbox": "2.5.5",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {