@giselles-ai/sandbox-agent 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+type AgentRunnerOptions = {
+    apiKey?: string;
+    baseUrl?: string;
+};
+type AgentRunnerHandler = {
+    POST: (request: Request) => Promise<Response>;
+};
+declare function handleAgentRunner(options?: AgentRunnerOptions): AgentRunnerHandler;
+
+export { type AgentRunnerHandler, type AgentRunnerOptions, handleAgentRunner };

package/dist/index.js

@@ -0,0 +1,201 @@
+// src/index.ts
+import { z } from "zod";
+var DEFAULT_ENDPOINT = "https://studio.giselles.ai/agent-api";
+var DEBUG_ENABLED = process.env.GISELLE_AGENT_DEBUG === "true" || process.env.DEBUG === "1";
+function debugLog(context, message) {
+  if (!DEBUG_ENABLED) {
+    return;
+  }
+  console.info("[agent-runner]", JSON.stringify({ ...context, message }));
+}
+var agentRunSchema = z.object({
+  type: z.literal("agent.run"),
+  message: z.string().min(1),
+  document: z.string().optional(),
+  session_id: z.string().min(1).optional(),
+  sandbox_id: z.string().min(1).optional()
+});
+function invalidRequestResponse(detail) {
+  return Response.json(
+    {
+      ok: false,
+      errorCode: "INVALID_REQUEST",
+      message: "Invalid request payload.",
+      error: detail
+    },
+    { status: 400 }
+  );
+}
+function invalidConfigResponse(message) {
+  return Response.json(
+    {
+      ok: false,
+      errorCode: "INVALID_CONFIG",
+      message
+    },
+    { status: 500 }
+  );
+}
+function badGatewayResponse(message) {
+  return Response.json(
+    {
+      ok: false,
+      errorCode: "UPSTREAM_UNAVAILABLE",
+      message
+    },
+    { status: 502 }
+  );
+}
+function resolveApiKey(input) {
+  return input?.apiKey?.trim() || process.env.GISELLE_SANDBOX_AGENT_API_KEY?.trim() || process.env.GISELLE_API_KEY?.trim() || "";
+}
+function parseAbsoluteEndpoint(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return null;
+    }
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+function resolveEndpoint(input) {
+  const baseUrl = input.baseUrl?.trim();
+  if (baseUrl) {
+    const endpoint = parseAbsoluteEndpoint(baseUrl);
+    if (!endpoint) {
+      return {
+        ok: false,
+        message: "`baseUrl` must be an absolute HTTP(S) endpoint URL, e.g. https://studio.giselles.ai/agent-api."
+      };
+    }
+    debugLog(
+      {
+        baseUrl: input.baseUrl
+      },
+      `resolveEndpoint: using baseUrl -> ${endpoint}`
+    );
+    return { ok: true, endpoint };
+  }
+  debugLog(
+    {
+      baseUrl: input.baseUrl
+    },
+    `resolveEndpoint: using default -> ${DEFAULT_ENDPOINT}`
+  );
+  return { ok: true, endpoint: DEFAULT_ENDPOINT };
+}
+function handleAgentRunner(options) {
+  const apiKey = resolveApiKey(options);
+  const optionSnapshot = {
+    baseUrl: options?.baseUrl?.trim(),
+    hasApiKey: Boolean(apiKey),
+    hasInlineApiKey: Boolean(options?.apiKey?.trim()),
+    hasEnvApiKey: Boolean(process.env.GISELLE_SANDBOX_AGENT_API_KEY?.trim()) || Boolean(process.env.GISELLE_API_KEY?.trim())
+  };
+  debugLog(
+    optionSnapshot,
+    `handleAgentRunner initialized (${options ? "custom options" : "default options"})`
+  );
+  return {
+    POST: async (request) => {
+      debugLog(
+        {
+          baseUrl: optionSnapshot.baseUrl
+        },
+        `POST request start: host=${new URL(request.url).host}`
+      );
+      const payload = await request.json().catch(() => null);
+      const parsed = agentRunSchema.safeParse(payload);
+      if (!parsed.success) {
+        debugLog(
+          {
+            baseUrl: optionSnapshot.baseUrl
+          },
+          `payload invalid: ${parsed.error.issues.length} issues`
+        );
+        return invalidRequestResponse(parsed.error.flatten());
+      }
+      const endpointResult = resolveEndpoint({
+        baseUrl: options?.baseUrl
+      });
+      if (!endpointResult.ok) {
+        debugLog(
+          {
+            baseUrl: optionSnapshot.baseUrl
+          },
+          `invalid endpoint config: ${endpointResult.message}`
+        );
+        return invalidConfigResponse(endpointResult.message);
+      }
+      debugLog(
+        {
+          baseUrl: optionSnapshot.baseUrl
+        },
+        `POST forwarding to endpoint: ${endpointResult.endpoint}`
+      );
+      const headers = {
+        "content-type": "application/json"
+      };
+      if (apiKey) {
+        headers.authorization = `Bearer ${apiKey}`;
+        debugLog(
+          {
+            baseUrl: optionSnapshot.baseUrl
+          },
+          "Authorization header attached"
+        );
+      } else {
+        debugLog(
+          {
+            baseUrl: optionSnapshot.baseUrl
+          },
+          "Authorization header skipped (apiKey missing)"
+        );
+      }
+      let upstreamResponse;
+      try {
+        upstreamResponse = await fetch(endpointResult.endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(parsed.data),
+          signal: request.signal
+        });
+      } catch (error) {
+        debugLog(
+          {
+            baseUrl: optionSnapshot.baseUrl
+          },
+          `upstream fetch failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+        const message = error instanceof Error ? error.message : "Failed to connect to upstream API.";
+        return badGatewayResponse(message);
+      }
+      debugLog(
+        {
+          baseUrl: optionSnapshot.baseUrl
+        },
+        `upstream responded: status=${upstreamResponse.status}, content-type=${upstreamResponse.headers.get("content-type") ?? "(none)"}, content-encoding=${upstreamResponse.headers.get("content-encoding") ?? "(none)"}`
+      );
+      const responseHeaders = new Headers(upstreamResponse.headers);
+      responseHeaders.delete("content-encoding");
+      responseHeaders.delete("Content-Encoding");
+      responseHeaders.delete("content-length");
+      responseHeaders.delete("transfer-encoding");
+      responseHeaders.set(
+        "Content-Type",
+        responseHeaders.get("Content-Type") ?? "application/x-ndjson; charset=utf-8"
+      );
+      responseHeaders.set("Cache-Control", "no-cache, no-transform");
+      return new Response(upstreamResponse.body, {
+        status: upstreamResponse.status,
+        statusText: upstreamResponse.statusText,
+        headers: responseHeaders
+      });
+    }
+  };
+}
+export {
+  handleAgentRunner
+};

package/dist/react/index.d.ts

@@ -0,0 +1,73 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, Dispatch, SetStateAction } from 'react';
+import { BrowserToolStatus, SnapshotField, BrowserToolAction, ExecutionReport } from '@giselles-ai/browser-tool';
+
+type PromptPanelProps = {
+    defaultInstruction?: string;
+    defaultDocument?: string;
+    mount?: "bottom-right" | "inline";
+};
+declare function PromptPanel({ defaultInstruction, defaultDocument, mount, }: PromptPanelProps): react_jsx_runtime.JSX.Element;
+
+type RunInput = {
+    instruction: string;
+    document?: string;
+};
+type BrowserToolPlan = {
+    fields: SnapshotField[];
+    actions: BrowserToolAction[];
+    warnings: string[];
+};
+type BrowserToolProviderProps = {
+    endpoint: string;
+    children: ReactNode;
+};
+type BrowserToolContextValue = {
+    endpoint: string;
+    status: BrowserToolStatus;
+    lastPlan: BrowserToolPlan | null;
+    lastExecution: ExecutionReport | null;
+    error: string | null;
+    setError: Dispatch<SetStateAction<string | null>>;
+    run: (input: RunInput) => Promise<BrowserToolPlan>;
+    apply: (actions: BrowserToolAction[], fields: SnapshotField[]) => ExecutionReport;
+};
+declare function BrowserToolProvider({ endpoint, children, }: BrowserToolProviderProps): react_jsx_runtime.JSX.Element;
+
+type AgentMessage = {
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+};
+type ToolEvent = {
+    id: string;
+    toolId: string;
+    toolName: string;
+    status?: "success" | "error";
+    parameters?: unknown;
+    output?: unknown;
+};
+type BridgeStatus = "idle" | "connecting" | "connected" | "error";
+type AgentStatus = BridgeStatus | "running";
+type UseAgentOptions = {
+    endpoint: string;
+};
+type AgentHookState = {
+    status: AgentStatus;
+    messages: AgentMessage[];
+    tools: ToolEvent[];
+    warnings: string[];
+    stderrLogs: string[];
+    sandboxId: string | null;
+    geminiSessionId: string | null;
+    error: string | null;
+    sendMessage: (input: {
+        message: string;
+        document?: string;
+    }) => Promise<void>;
+};
+declare function useAgent({ endpoint }: UseAgentOptions): AgentHookState;
+
+declare function useBrowserTool(): BrowserToolContextValue;
+
+export { type AgentHookState, type AgentMessage, type AgentStatus, BrowserToolProvider, PromptPanel, type ToolEvent, type UseAgentOptions, useAgent, useBrowserTool };

package/dist/react/index.js

@@ -0,0 +1,821 @@
+// src/react/prompt-panel.tsx
+import { useMemo as useMemo2, useState as useState2 } from "react";
+
+// src/react/use-browser-tool.ts
+import { useContext } from "react";
+
+// src/react/provider.tsx
+import { execute, snapshot } from "@giselles-ai/browser-tool/dom";
+import {
+  createContext,
+  useCallback,
+  useMemo,
+  useState
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var BrowserToolContext = createContext(
+  null
+);
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object";
+}
+function isAction(value) {
+  if (!isRecord(value) || typeof value.action !== "string" || typeof value.fieldId !== "string") {
+    return false;
+  }
+  if (value.action === "click") {
+    return true;
+  }
+  if ((value.action === "fill" || value.action === "select") && typeof value.value === "string") {
+    return true;
+  }
+  return false;
+}
+function parseWarnings(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item) => typeof item === "string");
+}
+function BrowserToolProvider({
+  endpoint,
+  children
+}) {
+  const [status, setStatus] = useState("idle");
+  const [lastPlan, setLastPlan] = useState(null);
+  const [lastExecution, setLastExecution] = useState(
+    null
+  );
+  const [error, setError] = useState(null);
+  const run = useCallback(
+    async ({ instruction, document }) => {
+      const trimmedInstruction = instruction.trim();
+      if (!trimmedInstruction) {
+        throw new Error("Instruction is required.");
+      }
+      setError(null);
+      setStatus("snapshotting");
+      try {
+        const fields = snapshot();
+        setStatus("planning");
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json"
+          },
+          body: JSON.stringify({
+            instruction: trimmedInstruction,
+            document: document?.trim() ? document.trim() : void 0,
+            fields
+          })
+        });
+        const payload = await response.json().catch(() => null);
+        if (!response.ok) {
+          const message = isRecord(payload) && typeof payload.error === "string" ? payload.error : `Planning failed with status ${response.status}`;
+          throw new Error(message);
+        }
+        const actions = isRecord(payload) && Array.isArray(payload.actions) ? payload.actions.filter(isAction) : [];
+        const warnings = isRecord(payload) ? parseWarnings(payload.warnings) : [];
+        const plan = {
+          fields,
+          actions,
+          warnings
+        };
+        setLastPlan(plan);
+        setLastExecution(null);
+        setStatus("ready");
+        return plan;
+      } catch (runError) {
+        const message = runError instanceof Error ? runError.message : "Failed to run planner.";
+        setError(message);
+        setStatus("error");
+        throw runError;
+      }
+    },
+    [endpoint]
+  );
+  const apply = useCallback(
+    (actions, fields) => {
+      setError(null);
+      setStatus("applying");
+      try {
+        const report = execute(actions, fields);
+        setLastExecution(report);
+        setStatus("idle");
+        return report;
+      } catch (applyError) {
+        const message = applyError instanceof Error ? applyError.message : "Failed to apply actions.";
+        setError(message);
+        setStatus("error");
+        throw applyError;
+      }
+    },
+    []
+  );
+  const contextValue = useMemo(
+    () => ({
+      endpoint,
+      status,
+      lastPlan,
+      lastExecution,
+      error,
+      setError,
+      run,
+      apply
+    }),
+    [apply, endpoint, error, lastExecution, lastPlan, run, status]
+  );
+  return /* @__PURE__ */ jsx(BrowserToolContext.Provider, { value: contextValue, children });
+}
+
+// src/react/use-browser-tool.ts
+function useBrowserTool() {
+  const context = useContext(BrowserToolContext);
+  if (!context) {
+    throw new Error(
+      "useBrowserTool must be used inside <BrowserToolProvider />."
+    );
+  }
+  return context;
+}
+
+// src/react/prompt-panel.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function describeAction(action) {
+  if (action.action === "click") {
+    return `click ${action.fieldId}`;
+  }
+  if (action.action === "fill") {
+    return `fill ${action.fieldId} = ${JSON.stringify(action.value)}`;
+  }
+  return `select ${action.fieldId} = ${JSON.stringify(action.value)}`;
+}
+function PromptPanel({
+  defaultInstruction = "",
+  defaultDocument = "",
+  mount = "bottom-right"
+}) {
+  const { status, run, apply, lastPlan, lastExecution, error, setError } = useBrowserTool();
+  const [instruction, setInstruction] = useState2(defaultInstruction);
+  const [documentText, setDocumentText] = useState2(defaultDocument);
+  const [notice, setNotice] = useState2(null);
+  const isPlanning = status === "snapshotting" || status === "planning";
+  const isApplying = status === "applying";
+  const combinedWarnings = useMemo2(() => {
+    const planWarnings = lastPlan?.warnings ?? [];
+    const executionWarnings = lastExecution?.warnings ?? [];
+    return [...planWarnings, ...executionWarnings];
+  }, [lastExecution, lastPlan]);
+  async function handlePlan() {
+    if (!instruction.trim()) {
+      return;
+    }
+    setNotice(null);
+    setError(null);
+    try {
+      const plan = await run({
+        instruction: instruction.trim(),
+        document: documentText.trim() || void 0
+      });
+      if (plan.actions.length === 0) {
+        setNotice(
+          "No actions were generated. Try giving more explicit instructions."
+        );
+        return;
+      }
+      setNotice(
+        `Plan created: ${plan.actions.length} action(s). Review and click Apply.`
+      );
+    } catch (planError) {
+      setNotice(
+        planError instanceof Error ? planError.message : "Planning failed."
+      );
+    }
+  }
+  function handleApply() {
+    if (!lastPlan || lastPlan.actions.length === 0) {
+      return;
+    }
+    setNotice(null);
+    setError(null);
+    const report = apply(lastPlan.actions, lastPlan.fields);
+    setNotice(
+      `Applied ${report.applied} action(s), skipped ${report.skipped}.`
+    );
+  }
+  const wrapperClass = mount === "bottom-right" ? "fixed bottom-4 right-4 z-50 w-[min(28rem,calc(100vw-2rem))]" : "w-full max-w-xl";
+  return /* @__PURE__ */ jsx2("section", { className: wrapperClass, children: /* @__PURE__ */ jsxs("div", { className: "rounded-2xl border border-slate-700 bg-slate-950/95 p-4 shadow-2xl backdrop-blur", children: [
+    /* @__PURE__ */ jsxs("div", { className: "mb-3 flex items-center justify-between", children: [
+      /* @__PURE__ */ jsx2("p", { className: "text-xs uppercase tracking-[0.15em] text-cyan-300", children: "Browser Tool Prompt Panel" }),
+      /* @__PURE__ */ jsxs("p", { className: "text-[11px] text-slate-400", children: [
+        "status: ",
+        status
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "space-y-3", children: [
+      /* @__PURE__ */ jsxs("label", { className: "block", children: [
+        /* @__PURE__ */ jsx2("span", { className: "mb-1 block text-xs text-slate-300", children: "Instruction" }),
+        /* @__PURE__ */ jsx2(
+          "textarea",
+          {
+            rows: 2,
+            value: instruction,
+            onChange: (event) => setInstruction(event.target.value),
+            placeholder: "Fill title and body with a concise summary...",
+            className: "w-full rounded-lg border border-slate-700 bg-slate-900/90 px-3 py-2 text-sm text-slate-100 outline-none focus:border-cyan-400"
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsxs("label", { className: "block", children: [
+        /* @__PURE__ */ jsx2("span", { className: "mb-1 block text-xs text-slate-300", children: "Document (optional)" }),
+        /* @__PURE__ */ jsx2(
+          "textarea",
+          {
+            rows: 4,
+            value: documentText,
+            onChange: (event) => setDocumentText(event.target.value),
+            placeholder: "Paste source document here",
+            className: "w-full rounded-lg border border-slate-700 bg-slate-900/90 px-3 py-2 text-sm text-slate-100 outline-none focus:border-cyan-400"
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "flex gap-2", children: [
+        /* @__PURE__ */ jsx2(
+          "button",
+          {
+            type: "button",
+            onClick: handlePlan,
+            disabled: !instruction.trim() || isPlanning || isApplying,
+            className: "rounded-lg bg-cyan-400 px-3 py-2 text-sm font-semibold text-slate-950 transition hover:bg-cyan-300 disabled:cursor-not-allowed disabled:opacity-50",
+            children: isPlanning ? "Planning..." : "Plan"
+          }
+        ),
+        /* @__PURE__ */ jsx2(
+          "button",
+          {
+            type: "button",
+            onClick: handleApply,
+            disabled: !lastPlan || lastPlan.actions.length === 0 || isPlanning || isApplying,
+            className: "rounded-lg border border-slate-600 px-3 py-2 text-sm font-semibold text-slate-100 transition hover:border-slate-400 disabled:cursor-not-allowed disabled:opacity-50",
+            children: isApplying ? "Applying..." : "Apply"
+          }
+        )
+      ] }),
+      notice ? /* @__PURE__ */ jsx2("p", { className: "text-xs text-slate-300", children: notice }) : null,
+      error ? /* @__PURE__ */ jsx2("p", { className: "text-xs text-rose-400", children: error }) : null
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "mt-4 border-t border-slate-800 pt-3", children: [
+      /* @__PURE__ */ jsx2("p", { className: "text-xs font-medium uppercase tracking-[0.12em] text-slate-400", children: "Action Plan" }),
+      !lastPlan ? /* @__PURE__ */ jsx2("p", { className: "mt-2 text-xs text-slate-500", children: "No plan yet." }) : lastPlan.actions.length === 0 ? /* @__PURE__ */ jsx2("p", { className: "mt-2 text-xs text-slate-500", children: "Planner returned no actions." }) : /* @__PURE__ */ jsx2("ul", { className: "mt-2 space-y-1", children: lastPlan.actions.map((action, index) => /* @__PURE__ */ jsx2(
+        "li",
+        {
+          className: "rounded-md border border-slate-800 bg-slate-900/80 px-2 py-1 text-xs text-slate-200",
+          children: describeAction(action)
+        },
+        `${action.fieldId}-${action.action}-${index}`
+      )) }),
+      combinedWarnings.length > 0 ? /* @__PURE__ */ jsxs("div", { className: "mt-3 rounded-md border border-amber-400/30 bg-amber-400/10 p-2", children: [
+        /* @__PURE__ */ jsx2("p", { className: "text-[11px] font-semibold uppercase tracking-[0.12em] text-amber-200", children: "Warnings" }),
+        /* @__PURE__ */ jsx2("ul", { className: "mt-1 space-y-1 text-xs text-amber-100", children: combinedWarnings.map((warning, index) => /* @__PURE__ */ jsxs(
+          "li",
+          {
+            children: [
+              "- ",
+              warning
+            ]
+          },
+          `${warning}-${// biome-ignore lint/suspicious/noArrayIndexKey: wip
+          index}`
+        )) })
+      ] }) : null
+    ] })
+  ] }) });
+}
+
+// src/react/use-agent.ts
+import { execute as execute2, snapshot as snapshot2 } from "@giselles-ai/browser-tool/dom";
+import { useCallback as useCallback2, useEffect, useMemo as useMemo3, useRef, useState as useState3 } from "react";
+var LOG_PREFIX = "[agent-bridge-client]";
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object";
+}
+function asString(value) {
+  return typeof value === "string" ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function extractWarnings(value) {
+  if (!isRecord2(value) || !Array.isArray(value.warnings)) {
+    return [];
+  }
+  return value.warnings.filter(
+    (warning) => typeof warning === "string"
+  );
+}
+function extractJsonObjects(buffer) {
+  const objects = [];
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let startIndex = -1;
+  for (let index = 0; index < buffer.length; index += 1) {
+    const char = buffer[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) {
+      continue;
+    }
+    if (char === "{") {
+      if (depth === 0) {
+        startIndex = index;
+      }
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0 && startIndex >= 0) {
+        objects.push(buffer.slice(startIndex, index + 1));
+        startIndex = -1;
+      }
+    }
+  }
+  if (depth > 0 && startIndex >= 0) {
+    return {
+      objects,
+      rest: buffer.slice(startIndex)
+    };
+  }
+  return {
+    objects,
+    rest: ""
+  };
+}
+function dedupeStringArray(next) {
+  const nextSet = new Set(next);
+  return Array.from(nextSet);
+}
+function useAgent({ endpoint }) {
+  const [bridgeStatus, setBridgeStatus] = useState3("idle");
+  const [running, setRunning] = useState3(false);
+  const [messages, setMessages] = useState3([]);
+  const [tools, setTools] = useState3([]);
+  const [warnings, setWarnings] = useState3([]);
+  const [stderrLogs, setStderrLogs] = useState3([]);
+  const [sandboxId, setSandboxId] = useState3(null);
+  const [geminiSessionId, setGeminiSessionId] = useState3(null);
+  const [error, setError] = useState3(null);
+  const normalizedEndpoint = useMemo3(
+    () => endpoint.replace(/\/+$/, ""),
+    [endpoint]
+  );
+  const eventSourceRef = useRef(null);
+  const reconnectTimerRef = useRef(null);
+  const mountedRef = useRef(true);
+  const sessionRef = useRef(null);
+  const messagesAssistantId = useRef(null);
+  const assistantBufferRef = useRef("");
+  const cleanupBridge = useCallback2(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = null;
+    }
+  }, []);
+  const handleBridgeResponse = useCallback2(
+    async (payload) => {
+      const currentSession = sessionRef.current;
+      if (!currentSession) {
+        console.warn(`${LOG_PREFIX} respond.skip.no-session`, {
+          payloadType: payload.type
+        });
+        return;
+      }
+      const requestId = typeof payload.requestId === "string" ? payload.requestId : void 0;
+      const responseType = typeof payload.type === "string" ? payload.type : void 0;
+      console.info(`${LOG_PREFIX} respond.out`, {
+        sessionId: currentSession.sessionId,
+        requestId,
+        responseType
+      });
+      const bridgeBase = currentSession.bridgeUrl ?? normalizedEndpoint;
+      const response = await fetch(bridgeBase, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          type: "bridge.respond",
+          sessionId: currentSession.sessionId,
+          token: currentSession.token,
+          response: payload
+        })
+      });
+      console.info(`${LOG_PREFIX} respond.result`, {
+        sessionId: currentSession.sessionId,
+        requestId,
+        status: response.status,
+        ok: response.ok
+      });
+    },
+    [normalizedEndpoint]
+  );
+  const handleBridgeEvent = useCallback2(
+    async (event) => {
+      if (!isRecord2(event) || typeof event.type !== "string") {
+        return;
+      }
+      if (event.type === "ready") {
+        return;
+      }
+      const requestId = asString(event.requestId);
+      if (!requestId) {
+        return;
+      }
+      try {
+        if (event.type === "error_response") {
+          const message = asString(event.message);
+          if (message) {
+            setError(message);
+          }
+          return;
+        }
+        if (event.type === "snapshot_request") {
+          console.info(`${LOG_PREFIX} sse.snapshot_request`, {
+            requestId
+          });
+          const fields = snapshot2();
+          console.info(`${LOG_PREFIX} sse.snapshot_result`, {
+            requestId,
+            fieldCount: fields.length
+          });
+          await handleBridgeResponse({
+            type: "snapshot_response",
+            requestId,
+            fields
+          });
+          return;
+        }
+        if (event.type === "execute_request") {
+          console.info(`${LOG_PREFIX} sse.execute_request`, {
+            requestId,
+            actionCount: Array.isArray(event.actions) ? event.actions.length : 0
+          });
+          const actions = Array.isArray(event.actions) ? event.actions : [];
+          const fields = Array.isArray(event.fields) ? event.fields : [];
+          const report = execute2(actions, fields);
+          console.info(`${LOG_PREFIX} sse.execute_result`, {
+            requestId,
+            applied: report.applied,
+            skipped: report.skipped
+          });
+          setWarnings(
+            (current) => dedupeStringArray([...current, ...report.warnings])
+          );
+          await handleBridgeResponse({
+            type: "execute_response",
+            requestId,
+            report
+          });
+          return;
+        }
+        await handleBridgeResponse({
+          type: "error_response",
+          requestId,
+          message: `Unsupported bridge request type: ${event.type}`
+        });
+      } catch (bridgeError) {
+        const message = bridgeError instanceof Error ? bridgeError.message : "Bridge execution failed.";
+        setError(message);
+        setBridgeStatus("error");
+        await handleBridgeResponse({
+          type: "error_response",
+          requestId,
+          message
+        });
+      }
+    },
+    [handleBridgeResponse]
+  );
+  const connect = useCallback2(() => {
+    const currentSession = sessionRef.current;
+    if (!currentSession) {
+      return;
+    }
+    cleanupBridge();
+    setBridgeStatus("connecting");
+    const bridgeBase = currentSession.bridgeUrl ?? normalizedEndpoint;
+    const source = new EventSource(
+      `${bridgeBase}?type=bridge.events&sessionId=${encodeURIComponent(currentSession.sessionId)}&token=${encodeURIComponent(currentSession.token)}`
+    );
+    console.info(`${LOG_PREFIX} sse.connect`, {
+      sessionId: currentSession.sessionId
+    });
+    eventSourceRef.current = source;
+    source.onopen = () => {
+      if (!mountedRef.current) {
+        return;
+      }
+      setBridgeStatus("connected");
+      console.info(`${LOG_PREFIX} sse.open`, {
+        sessionId: currentSession.sessionId
+      });
+    };
+    source.onmessage = (message) => {
+      console.info(`${LOG_PREFIX} sse.message.raw`, {
+        sessionId: currentSession.sessionId,
+        data: message.data
+      });
+      try {
+        const payload = JSON.parse(message.data);
+        console.info(`${LOG_PREFIX} sse.message.parsed`, {
+          sessionId: currentSession.sessionId,
+          type: typeof payload === "object" && payload && "type" in payload && typeof payload.type === "string" ? payload.type : "unknown"
+        });
+        void handleBridgeEvent(payload);
+      } catch (error2) {
+        console.error(`${LOG_PREFIX} sse.message.parse_error`, {
+          sessionId: currentSession.sessionId,
+          error: error2 instanceof Error ? error2.message : String(error2),
+          data: message.data
+        });
+      }
+    };
+    source.onerror = () => {
+      if (!mountedRef.current) {
+        return;
+      }
+      setBridgeStatus("connecting");
+      console.warn(`${LOG_PREFIX} sse.error`, {
+        sessionId: currentSession.sessionId
+      });
+      if (!reconnectTimerRef.current) {
+        reconnectTimerRef.current = setTimeout(() => {
+          reconnectTimerRef.current = null;
+          connect();
+        }, 1500);
+      }
+    };
+  }, [cleanupBridge, handleBridgeEvent, normalizedEndpoint]);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      cleanupBridge();
+    };
+  }, [cleanupBridge]);
+  const handleStreamEvent = useCallback2(
+    (event) => {
+      if (typeof event.type !== "string") {
+        return;
+      }
+      if (event.type === "bridge.session") {
+        const sessionId = asString(event.sessionId);
+        const token = asString(event.token);
+        const bridgeUrl = asString(event.bridgeUrl);
+        const expiresAt = asNumber(event.expiresAt) ?? Date.now() + 10 * 60 * 1e3;
+        if (!sessionId || !token) {
+          return;
+        }
+        sessionRef.current = {
+          sessionId,
+          token,
+          expiresAt,
+          bridgeUrl
+        };
+        console.info(`${LOG_PREFIX} stream.bridge_session`, {
+          sessionId
+        });
+        connect();
+        return;
+      }
+      if (event.type === "sandbox") {
+        const nextSandboxId = asString(event.sandbox_id);
+        if (nextSandboxId) {
+          setSandboxId(nextSandboxId);
+        }
+        return;
+      }
+      if (event.type === "init") {
+        const nextSessionId = asString(event.session_id);
+        if (nextSessionId) {
+          setGeminiSessionId(nextSessionId);
+        }
+        return;
+      }
+      if (event.type === "stderr") {
+        const text = asString(event.content);
+        if (text) {
+          setStderrLogs((current) => [...current, text]);
+        }
+        return;
+      }
+      if (event.type === "message") {
+        const role = asString(event.role);
+        const content = asString(event.content) ?? "";
+        const isDelta = Boolean(event.delta);
+        if (role === "assistant") {
+          if (isDelta) {
+            const currentId = messagesAssistantId.current;
+            if (!currentId) {
+              const nextId = crypto.randomUUID();
+              messagesAssistantId.current = nextId;
+              assistantBufferRef.current = content;
+              setMessages((current) => [
+                ...current,
+                { id: nextId, role: "assistant", content }
+              ]);
+              return;
+            }
+            const merged = `${assistantBufferRef.current}${content}`;
+            assistantBufferRef.current = merged;
+            setMessages(
+              (current) => current.map(
+                (message) => message.id === currentId ? { ...message, content: merged } : message
+              )
+            );
+            return;
+          }
+          if (content.trim().length > 0) {
+            const nextId = crypto.randomUUID();
+            messagesAssistantId.current = nextId;
+            assistantBufferRef.current = content;
+            setMessages((current) => [
+              ...current,
+              { id: nextId, role: "assistant", content }
+            ]);
+          }
+          return;
+        }
+        if (role === "user" && content.trim().length > 0) {
+          setMessages((current) => {
+            const last = current[current.length - 1];
+            if (last && last.role === "user" && last.content === content) {
+              return current;
+            }
+            return [
+              ...current,
+              { id: crypto.randomUUID(), role: "user", content }
+            ];
+          });
+        }
+        return;
+      }
+      if (event.type === "tool_use") {
+        const toolId = asString(event.tool_id) ?? crypto.randomUUID();
+        const toolName = asString(event.tool_name) ?? "tool";
+        setTools((current) => [
+          ...current,
+          {
+            id: crypto.randomUUID(),
+            toolId,
+            toolName,
+            parameters: event.parameters
+          }
+        ]);
+        return;
+      }
+      if (event.type === "tool_result") {
+        const toolId = asString(event.tool_id);
+        if (!toolId) {
+          return;
+        }
+        const status2 = asString(event.status);
+        const nextStatus = status2 === "success" || status2 === "error" ? status2 : void 0;
+        setTools(
+          (current) => current.map(
+            (tool) => tool.toolId === toolId ? {
+              ...tool,
+              status: nextStatus,
+              output: event.output
+            } : tool
+          )
+        );
+        const parsedWarnings = extractWarnings(event.output);
+        if (parsedWarnings.length > 0) {
+          setWarnings(
+            (current) => dedupeStringArray([...current, ...parsedWarnings])
+          );
+        }
+      }
+    },
+    [connect]
+  );
+  const sendMessage = useCallback2(
+    async ({ message, document }) => {
+      const trimmedMessage = message.trim();
+      if (!trimmedMessage || running) {
+        return;
+      }
+      cleanupBridge();
+      sessionRef.current = null;
+      setBridgeStatus("idle");
+      setError(null);
+      setRunning(true);
+      assistantBufferRef.current = "";
+      messagesAssistantId.current = null;
+      setMessages((current) => [
+        ...current,
+        { id: crypto.randomUUID(), role: "user", content: trimmedMessage }
+      ]);
+      try {
+        console.info(`${LOG_PREFIX} run.start`, {
+          messageLength: trimmedMessage.length,
+          hasDocument: Boolean(document?.trim())
+        });
+        const response = await fetch(normalizedEndpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json"
+          },
+          body: JSON.stringify({
+            type: "agent.run",
+            message: trimmedMessage,
+            document: document?.trim() ? document.trim() : void 0,
+            session_id: geminiSessionId ?? void 0,
+            sandbox_id: sandboxId ?? void 0
+          })
+        });
+        if (!response.ok || !response.body) {
+          throw new Error(`Failed to start stream (${response.status}).`);
+        }
+        console.info(`${LOG_PREFIX} run.stream.open`, {
+          status: response.status
+        });
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            break;
+          }
+          buffer += decoder.decode(value, { stream: true });
+          const parsed = extractJsonObjects(buffer);
+          buffer = parsed.rest;
+          for (const objectText of parsed.objects) {
+            try {
+              const parsedEvent = JSON.parse(objectText);
+              handleStreamEvent(parsedEvent);
+            } catch {
+            }
+          }
+        }
+        if (buffer.trim().length > 0) {
+          try {
+            const parsedEvent = JSON.parse(buffer);
+            handleStreamEvent(parsedEvent);
+          } catch {
+          }
+        }
+      } catch (sendError) {
+        const messageText = sendError instanceof Error ? sendError.message : "Failed to send message.";
+        setError(messageText);
+        setBridgeStatus("error");
+        throw sendError;
+      } finally {
+        setRunning(false);
+      }
+    },
+    [
+      cleanupBridge,
+      geminiSessionId,
+      handleStreamEvent,
+      normalizedEndpoint,
+      running,
+      sandboxId
+    ]
+  );
+  const status = running ? "running" : bridgeStatus;
+  return {
+    status,
+    messages,
+    tools,
+    warnings,
+    stderrLogs,
+    sandboxId,
+    geminiSessionId,
+    error,
+    sendMessage
+  };
+}
+export {
+  BrowserToolProvider,
+  PromptPanel,
+  useAgent,
+  useBrowserTool
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@giselles-ai/sandbox-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/giselles-ai/agent-container.git",
+    "directory": "packages/sandbox-agent"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@giselles-ai/browser-tool": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.10",
+    "@types/react": "19.2.10",
+    "@types/react-dom": "19.2.3",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsup --config tsup.ts",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "pnpm exec biome check --write ."
+  }
+}