@kana-ai/edgar-ext-browserbase 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +114 -2
  3. package/dist/src/api/client.d.ts +17 -0
  4. package/dist/src/api/client.js +40 -0
  5. package/dist/src/api/failures.d.ts +10 -0
  6. package/dist/src/api/failures.js +36 -0
  7. package/dist/src/index.d.ts +93 -0
  8. package/dist/src/index.js +16 -0
  9. package/dist/src/schemas/browserbase.d.ts +83 -0
  10. package/dist/src/schemas/browserbase.js +46 -0
  11. package/dist/src/schemas/config.d.ts +20 -0
  12. package/dist/src/schemas/config.js +10 -0
  13. package/dist/src/schemas/tools.d.ts +148 -0
  14. package/dist/src/schemas/tools.js +76 -0
  15. package/dist/src/tools/contexts.d.ts +14 -0
  16. package/dist/src/tools/contexts.js +35 -0
  17. package/dist/src/tools/evidence.d.ts +37 -0
  18. package/dist/src/tools/evidence.js +70 -0
  19. package/dist/src/tools/sessions.d.ts +60 -0
  20. package/dist/src/tools/sessions.js +110 -0
  21. package/edgar-extension.json +129 -0
  22. package/package.json +41 -3
  23. package/schemas/config.json +25 -0
  24. package/schemas/create_context.in.json +10 -0
  25. package/schemas/create_context.out.json +10 -0
  26. package/schemas/create_session.in.json +24 -0
  27. package/schemas/create_session.out.json +19 -0
  28. package/schemas/delete_context.in.json +11 -0
  29. package/schemas/delete_context.out.json +13 -0
  30. package/schemas/end_session.in.json +11 -0
  31. package/schemas/end_session.out.json +26 -0
  32. package/schemas/list_sessions.in.json +10 -0
  33. package/schemas/list_sessions.out.json +35 -0
  34. package/schemas/session_downloads.in.json +11 -0
  35. package/schemas/session_downloads.out.json +33 -0
  36. package/schemas/session_logs.in.json +11 -0
  37. package/schemas/session_logs.out.json +32 -0
  38. package/schemas/session_replay.in.json +11 -0
  39. package/schemas/session_replay.out.json +35 -0
  40. package/schemas/session_state.in.json +11 -0
  41. package/schemas/session_state.out.json +26 -0
@@ -0,0 +1,46 @@
1
+ import { z } from "zod";
2
+ /** The status of a session. */
3
+ export const sessionStatus = z.enum(["PENDING", "RUNNING", "ERROR", "TIMED_OUT", "COMPLETED"]);
4
+ /** A session as the API answers it, with the fields the tools read. */
5
+ export const session = z.object({
6
+ id: z.string(),
7
+ status: sessionStatus,
8
+ startedAt: z.string(),
9
+ endedAt: z.string().nullable().optional(),
10
+ expiresAt: z.string(),
11
+ keepAlive: z.boolean(),
12
+ contextId: z.string().nullable().optional(),
13
+ region: z.string(),
14
+ });
15
+ /** The answer of `POST /v1/sessions`: the session and its CDP URL. */
16
+ export const createdSession = session.extend({ connectUrl: z.string() });
17
+ /** The answer of `GET /v1/sessions/{id}/debug`. */
18
+ export const liveUrls = z.object({ debuggerFullscreenUrl: z.string() });
19
+ /** The answer of `GET /v1/sessions/{id}/logs`. */
20
+ export const logs = z.array(z.object({
21
+ method: z.string(),
22
+ pageId: z.number().int(),
23
+ timestamp: z.number().int().optional(),
24
+ }));
25
+ /** The answer of `GET /v1/sessions/{id}/replays`. */
26
+ export const replay = z.object({
27
+ pages: z.array(z.object({
28
+ pageId: z.string(),
29
+ url: z.string(),
30
+ startTimeMs: z.number().int(),
31
+ endTimeMs: z.number().int(),
32
+ })),
33
+ });
34
+ /** The answer of `GET /v1/downloads`. */
35
+ export const downloads = z.object({
36
+ downloads: z.array(z.object({ id: z.string(), filename: z.string(), mimeType: z.string(), size: z.number() })),
37
+ total: z.number().int(),
38
+ });
39
+ /** The answer of `POST /v1/contexts`. */
40
+ export const createdContext = z.object({ id: z.string() });
41
+ /** The body of an error answer. */
42
+ export const errorBody = z.object({
43
+ code: z.string().optional(),
44
+ error: z.string().optional(),
45
+ message: z.string().optional(),
46
+ });
@@ -0,0 +1,20 @@
1
+ import { z } from "zod";
2
+ /** The regions a session can run in. */
3
+ export declare const region: z.ZodEnum<{
4
+ "ap-southeast-1": "ap-southeast-1";
5
+ "eu-central-1": "eu-central-1";
6
+ "us-east-1": "us-east-1";
7
+ "us-west-2": "us-west-2";
8
+ }>;
9
+ /** The extension's `[extensions.browserbase]` table. */
10
+ export declare const config: z.ZodObject<{
11
+ timeout_seconds: z.ZodDefault<z.ZodNumber>;
12
+ keep_alive: z.ZodDefault<z.ZodBoolean>;
13
+ record: z.ZodDefault<z.ZodBoolean>;
14
+ region: z.ZodOptional<z.ZodEnum<{
15
+ "ap-southeast-1": "ap-southeast-1";
16
+ "eu-central-1": "eu-central-1";
17
+ "us-east-1": "us-east-1";
18
+ "us-west-2": "us-west-2";
19
+ }>>;
20
+ }, z.core.$strict>;
@@ -0,0 +1,10 @@
1
+ import { z } from "zod";
2
+ /** The regions a session can run in. */
3
+ export const region = z.enum(["us-west-2", "us-east-1", "eu-central-1", "ap-southeast-1"]);
4
+ /** The extension's `[extensions.browserbase]` table. */
5
+ export const config = z.strictObject({
6
+ timeout_seconds: z.number().int().min(60).max(21600).default(300),
7
+ keep_alive: z.boolean().default(false),
8
+ record: z.boolean().default(true),
9
+ region: region.optional(),
10
+ });
@@ -0,0 +1,148 @@
1
+ import { z } from "zod";
2
+ /** The input and output of `create_session`. */
3
+ export declare const createSession: {
4
+ input: z.ZodObject<{
5
+ context_id: z.ZodOptional<z.ZodString>;
6
+ keep_alive: z.ZodOptional<z.ZodBoolean>;
7
+ timeout_seconds: z.ZodOptional<z.ZodNumber>;
8
+ record: z.ZodOptional<z.ZodBoolean>;
9
+ proxies: z.ZodOptional<z.ZodBoolean>;
10
+ }, z.core.$strip>;
11
+ output: z.ZodObject<{
12
+ session_id: z.ZodString;
13
+ connect_url_file: z.ZodNullable<z.ZodString>;
14
+ live_view_url: z.ZodNullable<z.ZodString>;
15
+ expires_at: z.ZodString;
16
+ }, z.core.$strip>;
17
+ };
18
+ /** The input and output of `session_state`. */
19
+ export declare const sessionState: {
20
+ input: z.ZodObject<{
21
+ session_id: z.ZodString;
22
+ }, z.core.$strip>;
23
+ output: z.ZodObject<{
24
+ session_id: z.ZodString;
25
+ status: z.ZodEnum<{
26
+ COMPLETED: "COMPLETED";
27
+ ERROR: "ERROR";
28
+ PENDING: "PENDING";
29
+ RUNNING: "RUNNING";
30
+ TIMED_OUT: "TIMED_OUT";
31
+ }>;
32
+ started_at: z.ZodString;
33
+ ended_at: z.ZodNullable<z.ZodString>;
34
+ expires_at: z.ZodString;
35
+ context_id: z.ZodNullable<z.ZodString>;
36
+ }, z.core.$strip>;
37
+ };
38
+ /** The input and output of `end_session`. */
39
+ export declare const endSession: {
40
+ input: z.ZodObject<{
41
+ session_id: z.ZodString;
42
+ }, z.core.$strip>;
43
+ output: z.ZodObject<{
44
+ session_id: z.ZodString;
45
+ status: z.ZodEnum<{
46
+ COMPLETED: "COMPLETED";
47
+ ERROR: "ERROR";
48
+ PENDING: "PENDING";
49
+ RUNNING: "RUNNING";
50
+ TIMED_OUT: "TIMED_OUT";
51
+ }>;
52
+ started_at: z.ZodString;
53
+ ended_at: z.ZodNullable<z.ZodString>;
54
+ expires_at: z.ZodString;
55
+ context_id: z.ZodNullable<z.ZodString>;
56
+ }, z.core.$strip>;
57
+ };
58
+ /** The input and output of `list_sessions`. */
59
+ export declare const listSessions: {
60
+ input: z.ZodObject<{
61
+ status: z.ZodOptional<z.ZodEnum<{
62
+ COMPLETED: "COMPLETED";
63
+ ERROR: "ERROR";
64
+ PENDING: "PENDING";
65
+ RUNNING: "RUNNING";
66
+ TIMED_OUT: "TIMED_OUT";
67
+ }>>;
68
+ }, z.core.$strip>;
69
+ output: z.ZodObject<{
70
+ sessions: z.ZodArray<z.ZodObject<{
71
+ session_id: z.ZodString;
72
+ status: z.ZodEnum<{
73
+ COMPLETED: "COMPLETED";
74
+ ERROR: "ERROR";
75
+ PENDING: "PENDING";
76
+ RUNNING: "RUNNING";
77
+ TIMED_OUT: "TIMED_OUT";
78
+ }>;
79
+ started_at: z.ZodString;
80
+ ended_at: z.ZodNullable<z.ZodString>;
81
+ expires_at: z.ZodString;
82
+ context_id: z.ZodNullable<z.ZodString>;
83
+ }, z.core.$strip>>;
84
+ }, z.core.$strip>;
85
+ };
86
+ /** The input and output of `session_logs`. */
87
+ export declare const sessionLogs: {
88
+ input: z.ZodObject<{
89
+ session_id: z.ZodString;
90
+ }, z.core.$strip>;
91
+ output: z.ZodObject<{
92
+ count: z.ZodNumber;
93
+ logs: z.ZodArray<z.ZodObject<{
94
+ method: z.ZodString;
95
+ page_id: z.ZodNumber;
96
+ timestamp: z.ZodNullable<z.ZodNumber>;
97
+ }, z.core.$strip>>;
98
+ }, z.core.$strip>;
99
+ };
100
+ /** The input and output of `session_replay`. */
101
+ export declare const sessionReplay: {
102
+ input: z.ZodObject<{
103
+ session_id: z.ZodString;
104
+ }, z.core.$strip>;
105
+ output: z.ZodObject<{
106
+ url: z.ZodString;
107
+ pages: z.ZodArray<z.ZodObject<{
108
+ page_id: z.ZodString;
109
+ url: z.ZodString;
110
+ start_ms: z.ZodNumber;
111
+ end_ms: z.ZodNumber;
112
+ }, z.core.$strip>>;
113
+ }, z.core.$strip>;
114
+ };
115
+ /** The input and output of `session_downloads`. */
116
+ export declare const sessionDownloads: {
117
+ input: z.ZodObject<{
118
+ session_id: z.ZodString;
119
+ }, z.core.$strip>;
120
+ output: z.ZodObject<{
121
+ total: z.ZodNumber;
122
+ downloads: z.ZodArray<z.ZodObject<{
123
+ id: z.ZodString;
124
+ filename: z.ZodString;
125
+ mime_type: z.ZodString;
126
+ size: z.ZodNumber;
127
+ }, z.core.$strip>>;
128
+ }, z.core.$strip>;
129
+ };
130
+ /** The input and output of `create_context`. */
131
+ export declare const createContext: {
132
+ input: z.ZodObject<{
133
+ name: z.ZodOptional<z.ZodString>;
134
+ }, z.core.$strip>;
135
+ output: z.ZodObject<{
136
+ context_id: z.ZodString;
137
+ }, z.core.$strip>;
138
+ };
139
+ /** The input and output of `delete_context`. */
140
+ export declare const deleteContext: {
141
+ input: z.ZodObject<{
142
+ context_id: z.ZodString;
143
+ }, z.core.$strip>;
144
+ output: z.ZodObject<{
145
+ context_id: z.ZodString;
146
+ deleted: z.ZodBoolean;
147
+ }, z.core.$strip>;
148
+ };
@@ -0,0 +1,76 @@
1
+ import { z } from "zod";
2
+ import { sessionStatus } from "#schemas/browserbase";
3
+ const sessionId = z.object({ session_id: z.string().min(1) });
4
+ const contextId = z.object({ context_id: z.string().min(1) });
5
+ const state = z.object({
6
+ session_id: z.string(),
7
+ status: sessionStatus,
8
+ started_at: z.string(),
9
+ ended_at: z.string().nullable(),
10
+ expires_at: z.string(),
11
+ context_id: z.string().nullable(),
12
+ });
13
+ /** The input and output of `create_session`. */
14
+ export const createSession = {
15
+ input: z.object({
16
+ context_id: z.string().min(1).optional(),
17
+ keep_alive: z.boolean().optional(),
18
+ timeout_seconds: z.number().int().min(60).max(21600).optional(),
19
+ record: z.boolean().optional(),
20
+ proxies: z.boolean().optional(),
21
+ }),
22
+ output: z.object({
23
+ session_id: z.string(),
24
+ connect_url_file: z.string().nullable(),
25
+ live_view_url: z.string().nullable(),
26
+ expires_at: z.string(),
27
+ }),
28
+ };
29
+ /** The input and output of `session_state`. */
30
+ export const sessionState = { input: sessionId, output: state };
31
+ /** The input and output of `end_session`. */
32
+ export const endSession = { input: sessionId, output: state };
33
+ /** The input and output of `list_sessions`. */
34
+ export const listSessions = {
35
+ input: z.object({ status: sessionStatus.optional() }),
36
+ output: z.object({ sessions: z.array(state) }),
37
+ };
38
+ /** The input and output of `session_logs`. */
39
+ export const sessionLogs = {
40
+ input: sessionId,
41
+ output: z.object({
42
+ count: z.number().int(),
43
+ logs: z.array(z.object({ method: z.string(), page_id: z.number().int(), timestamp: z.number().nullable() })),
44
+ }),
45
+ };
46
+ /** The input and output of `session_replay`. */
47
+ export const sessionReplay = {
48
+ input: sessionId,
49
+ output: z.object({
50
+ url: z.string(),
51
+ pages: z.array(z.object({
52
+ page_id: z.string(),
53
+ url: z.string(),
54
+ start_ms: z.number().int(),
55
+ end_ms: z.number().int(),
56
+ })),
57
+ }),
58
+ };
59
+ /** The input and output of `session_downloads`. */
60
+ export const sessionDownloads = {
61
+ input: sessionId,
62
+ output: z.object({
63
+ total: z.number().int(),
64
+ downloads: z.array(z.object({ id: z.string(), filename: z.string(), mime_type: z.string(), size: z.number() })),
65
+ }),
66
+ };
67
+ /** The input and output of `create_context`. */
68
+ export const createContext = {
69
+ input: z.object({ name: z.string().min(1).optional() }),
70
+ output: z.object({ context_id: z.string() }),
71
+ };
72
+ /** The input and output of `delete_context`. */
73
+ export const deleteContext = {
74
+ input: contextId,
75
+ output: z.object({ context_id: z.string(), deleted: z.boolean() }),
76
+ };
@@ -0,0 +1,14 @@
1
+ /** The context tools of the Browserbase extension: cookies and storage kept across sessions. */
2
+ export declare const contextTools: {
3
+ create_context: import("@kana-ai/edgar-sdk").Tool<{
4
+ name?: string | undefined;
5
+ }, {
6
+ context_id: string;
7
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
8
+ delete_context: import("@kana-ai/edgar-sdk").Tool<{
9
+ context_id: string;
10
+ }, {
11
+ context_id: string;
12
+ deleted: boolean;
13
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
14
+ };
@@ -0,0 +1,35 @@
1
+ import { defineTool, done } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { PROJECT, apiAccess, browserbase } from "#api/client";
4
+ import { createdContext } from "#schemas/browserbase";
5
+ import { createContext, deleteContext } from "#schemas/tools";
6
+ /** The context tools of the Browserbase extension: cookies and storage kept across sessions. */
7
+ export const contextTools = {
8
+ create_context: defineTool({
9
+ description: "Create an empty context that sessions can sign in to and keep across runs",
10
+ input: createContext.input,
11
+ output: createContext.output,
12
+ ...apiAccess,
13
+ execute: async ({ name }, ctx) => {
14
+ const made = await browserbase(ctx, "POST", "/v1/contexts", createdContext, {
15
+ projectId: ctx.secrets.get(PROJECT),
16
+ ...(name === undefined ? {} : { name }),
17
+ });
18
+ return made.ok ? done({ context_id: made.value.id }) : made.error;
19
+ },
20
+ }),
21
+ delete_context: defineTool({
22
+ description: "Delete a context with its cookies and storage",
23
+ input: deleteContext.input,
24
+ output: deleteContext.output,
25
+ ...apiAccess,
26
+ side_effect: true,
27
+ undo: "none",
28
+ undo_reason: "a deleted context's cookies and storage are gone; a person signs in again",
29
+ execute: async ({ context_id }, ctx) => {
30
+ const path = `/v1/contexts/${encodeURIComponent(context_id)}`;
31
+ const gone = await browserbase(ctx, "DELETE", path, z.null());
32
+ return gone.ok ? done({ context_id, deleted: true }) : gone.error;
33
+ },
34
+ }),
35
+ };
@@ -0,0 +1,37 @@
1
+ /** The most log entries `session_logs` returns. */
2
+ export declare const LOG_LIMIT = 200;
3
+ /** The evidence tools of the Browserbase extension: logs, replay and downloads of a session. */
4
+ export declare const evidenceTools: {
5
+ session_logs: import("@kana-ai/edgar-sdk").Tool<{
6
+ session_id: string;
7
+ }, {
8
+ count: number;
9
+ logs: {
10
+ method: string;
11
+ page_id: number;
12
+ timestamp: number | null;
13
+ }[];
14
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
15
+ session_replay: import("@kana-ai/edgar-sdk").Tool<{
16
+ session_id: string;
17
+ }, {
18
+ url: string;
19
+ pages: {
20
+ page_id: string;
21
+ url: string;
22
+ start_ms: number;
23
+ end_ms: number;
24
+ }[];
25
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
26
+ session_downloads: import("@kana-ai/edgar-sdk").Tool<{
27
+ session_id: string;
28
+ }, {
29
+ total: number;
30
+ downloads: {
31
+ id: string;
32
+ filename: string;
33
+ mime_type: string;
34
+ size: number;
35
+ }[];
36
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
37
+ };
@@ -0,0 +1,70 @@
1
+ import { defineTool, done } from "@kana-ai/edgar-sdk";
2
+ import { HOST, apiAccess, browserbase } from "#api/client";
3
+ import { downloads, logs, replay } from "#schemas/browserbase";
4
+ import { sessionDownloads, sessionLogs, sessionReplay } from "#schemas/tools";
5
+ import { sessionPath } from "#tools/sessions";
6
+ /** The most log entries `session_logs` returns. */
7
+ export const LOG_LIMIT = 200;
8
+ /** The evidence tools of the Browserbase extension: logs, replay and downloads of a session. */
9
+ export const evidenceTools = {
10
+ session_logs: defineTool({
11
+ description: `Read the CDP log of a session: the count and the first ${String(LOG_LIMIT)} methods`,
12
+ input: sessionLogs.input,
13
+ output: sessionLogs.output,
14
+ ...apiAccess,
15
+ execute: async ({ session_id }, ctx) => {
16
+ const read = await browserbase(ctx, "GET", sessionPath(session_id, "/logs"), logs);
17
+ if (!read.ok)
18
+ return read.error;
19
+ return done({
20
+ count: read.value.length,
21
+ logs: read.value.slice(0, LOG_LIMIT).map((l) => ({
22
+ method: l.method,
23
+ page_id: l.pageId,
24
+ timestamp: l.timestamp ?? null,
25
+ })),
26
+ });
27
+ },
28
+ }),
29
+ session_replay: defineTool({
30
+ description: "Read the replay pages of a session, each with its HLS playlist URL, and the URL of the replay in the dashboard",
31
+ input: sessionReplay.input,
32
+ output: sessionReplay.output,
33
+ ...apiAccess,
34
+ execute: async ({ session_id }, ctx) => {
35
+ const read = await browserbase(ctx, "GET", sessionPath(session_id, "/replays"), replay);
36
+ if (!read.ok)
37
+ return read.error;
38
+ return done({
39
+ url: `https://www.browserbase.com/sessions/${encodeURIComponent(session_id)}`,
40
+ pages: read.value.pages.map((p) => ({
41
+ page_id: p.pageId,
42
+ url: URL.parse(p.url, `https://${HOST}`)?.href ?? p.url,
43
+ start_ms: p.startTimeMs,
44
+ end_ms: p.endTimeMs,
45
+ })),
46
+ });
47
+ },
48
+ }),
49
+ session_downloads: defineTool({
50
+ description: "List the files a session downloaded, up to 100",
51
+ input: sessionDownloads.input,
52
+ output: sessionDownloads.output,
53
+ ...apiAccess,
54
+ execute: async ({ session_id }, ctx) => {
55
+ const query = new URLSearchParams({ sessionId: session_id, limit: "100" }).toString();
56
+ const read = await browserbase(ctx, "GET", `/v1/downloads?${query}`, downloads);
57
+ if (!read.ok)
58
+ return read.error;
59
+ return done({
60
+ total: read.value.total,
61
+ downloads: read.value.downloads.map((d) => ({
62
+ id: d.id,
63
+ filename: d.filename,
64
+ mime_type: d.mimeType,
65
+ size: d.size,
66
+ })),
67
+ });
68
+ },
69
+ }),
70
+ };
@@ -0,0 +1,60 @@
1
+ import type { z } from "zod";
2
+ import { type Reply } from "#api/client";
3
+ import { session } from "#schemas/browserbase";
4
+ import { createSession, sessionState } from "#schemas/tools";
5
+ /** The path of a session, with its id escaped. */
6
+ export declare function sessionPath(id: string, tail?: string): string;
7
+ /** The file in the run's sandbox that holds the CDP URL of session `id`, as a command there reads it; `/tmp` is not in the repository. */
8
+ export declare function connectFile(id: string): string;
9
+ /** A session as the tools answer it. */
10
+ export declare function stateOf(s: z.infer<typeof session>): z.infer<typeof sessionState.output>;
11
+ /** The request body of a new session: the input over the `[extensions.browserbase]` defaults. */
12
+ export declare function sessionBody(input: z.infer<typeof createSession.input>, settings: unknown, projectId: string): Reply<Readonly<Record<string, unknown>>>;
13
+ /** The session tools of the Browserbase extension, by the name the manifest gives them. */
14
+ export declare const sessionTools: {
15
+ /** The CDP URL grants the browser, so it goes to a sandbox file, never into the output; the session is billed once the POST answers, so a failed write or live view read gives `null`, never a failure that loses the session id. */
16
+ create_session: import("@kana-ai/edgar-sdk").Tool<{
17
+ context_id?: string | undefined;
18
+ keep_alive?: boolean | undefined;
19
+ timeout_seconds?: number | undefined;
20
+ record?: boolean | undefined;
21
+ proxies?: boolean | undefined;
22
+ }, {
23
+ session_id: string;
24
+ connect_url_file: string | null;
25
+ live_view_url: string | null;
26
+ expires_at: string;
27
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
28
+ session_state: import("@kana-ai/edgar-sdk").Tool<{
29
+ session_id: string;
30
+ }, {
31
+ session_id: string;
32
+ status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
33
+ started_at: string;
34
+ ended_at: string | null;
35
+ expires_at: string;
36
+ context_id: string | null;
37
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
38
+ end_session: import("@kana-ai/edgar-sdk").Tool<{
39
+ session_id: string;
40
+ }, {
41
+ session_id: string;
42
+ status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
43
+ started_at: string;
44
+ ended_at: string | null;
45
+ expires_at: string;
46
+ context_id: string | null;
47
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
48
+ list_sessions: import("@kana-ai/edgar-sdk").Tool<{
49
+ status?: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT" | undefined;
50
+ }, {
51
+ sessions: {
52
+ session_id: string;
53
+ status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
54
+ started_at: string;
55
+ ended_at: string | null;
56
+ expires_at: string;
57
+ context_id: string | null;
58
+ }[];
59
+ }, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
60
+ };
@@ -0,0 +1,110 @@
1
+ import { defineTool, done, err, ok, permanentFailure } from "@kana-ai/edgar-sdk";
2
+ import { PROJECT, apiAccess, browserbase } from "#api/client";
3
+ import { createdSession, liveUrls, session } from "#schemas/browserbase";
4
+ import { config } from "#schemas/config";
5
+ import { createSession, endSession, listSessions, sessionState } from "#schemas/tools";
6
+ /** The path of a session, with its id escaped. */
7
+ export function sessionPath(id, tail = "") {
8
+ return `/v1/sessions/${encodeURIComponent(id)}${tail}`;
9
+ }
10
+ /** The file in the run's sandbox that holds the CDP URL of session `id`, as a command there reads it; `/tmp` is not in the repository. */
11
+ export function connectFile(id) {
12
+ return `/tmp/browserbase/${encodeURIComponent(id)}.cdp`;
13
+ }
14
+ /** A session as the tools answer it. */
15
+ export function stateOf(s) {
16
+ return {
17
+ session_id: s.id,
18
+ status: s.status,
19
+ started_at: s.startedAt,
20
+ ended_at: s.endedAt ?? null,
21
+ expires_at: s.expiresAt,
22
+ context_id: s.contextId ?? null,
23
+ };
24
+ }
25
+ /** The request body of a new session: the input over the `[extensions.browserbase]` defaults. */
26
+ export function sessionBody(input, settings, projectId) {
27
+ const parsed = config.safeParse(settings ?? {});
28
+ if (!parsed.success) {
29
+ return err(permanentFailure("invalid", "the [extensions.browserbase] table does not match its schema"));
30
+ }
31
+ const defaults = parsed.data;
32
+ return ok({
33
+ projectId,
34
+ timeout: input.timeout_seconds ?? defaults.timeout_seconds,
35
+ keepAlive: input.keep_alive ?? defaults.keep_alive,
36
+ browserSettings: {
37
+ recordSession: input.record ?? defaults.record,
38
+ ...(input.context_id === undefined
39
+ ? {}
40
+ : { context: { id: input.context_id, persist: true } }),
41
+ },
42
+ ...(input.proxies === undefined ? {} : { proxies: input.proxies }),
43
+ ...(defaults.region === undefined ? {} : { region: defaults.region }),
44
+ });
45
+ }
46
+ /** The session tools of the Browserbase extension, by the name the manifest gives them. */
47
+ export const sessionTools = {
48
+ /** The CDP URL grants the browser, so it goes to a sandbox file, never into the output; the session is billed once the POST answers, so a failed write or live view read gives `null`, never a failure that loses the session id. */
49
+ create_session: defineTool({
50
+ description: "Start a cloud browser session; write its CDP URL, which grants the browser, to the sandbox file `connect_url_file`, and return its live view URL",
51
+ input: createSession.input,
52
+ output: createSession.output,
53
+ secrets: apiAccess.secrets,
54
+ capabilities: [...apiAccess.capabilities, "sandbox:write"],
55
+ side_effect: true,
56
+ undo: "none",
57
+ undo_reason: "a session ends by itself at its timeout, and end_session releases it sooner; the minute it ran is billed",
58
+ execute: async (input, ctx) => {
59
+ const body = sessionBody(input, ctx.config, ctx.secrets.get(PROJECT));
60
+ if (!body.ok)
61
+ return body.error;
62
+ const made = await browserbase(ctx, "POST", "/v1/sessions", createdSession, body.value);
63
+ if (!made.ok)
64
+ return made.error;
65
+ const live = await browserbase(ctx, "GET", sessionPath(made.value.id, "/debug"), liveUrls);
66
+ const file = connectFile(made.value.id);
67
+ const written = await ctx.sandbox.write(file, made.value.connectUrl);
68
+ return done({
69
+ session_id: made.value.id,
70
+ connect_url_file: written.ok ? file : null,
71
+ live_view_url: live.ok ? live.value.debuggerFullscreenUrl : null,
72
+ expires_at: made.value.expiresAt,
73
+ });
74
+ },
75
+ }),
76
+ session_state: defineTool({
77
+ description: "Read the status and the times of a browser session",
78
+ input: sessionState.input,
79
+ output: sessionState.output,
80
+ ...apiAccess,
81
+ execute: async ({ session_id }, ctx) => {
82
+ const read = await browserbase(ctx, "GET", sessionPath(session_id), session);
83
+ return read.ok ? done(stateOf(read.value)) : read.error;
84
+ },
85
+ }),
86
+ end_session: defineTool({
87
+ description: "End a browser session now; a session that already ended keeps its status",
88
+ input: endSession.input,
89
+ output: endSession.output,
90
+ ...apiAccess,
91
+ execute: async ({ session_id }, ctx) => {
92
+ const ended = await browserbase(ctx, "POST", sessionPath(session_id), session, {
93
+ projectId: ctx.secrets.get(PROJECT),
94
+ status: "REQUEST_RELEASE",
95
+ });
96
+ return ended.ok ? done(stateOf(ended.value)) : ended.error;
97
+ },
98
+ }),
99
+ list_sessions: defineTool({
100
+ description: "List the project's browser sessions, of one status when given, in one page",
101
+ input: listSessions.input,
102
+ output: listSessions.output,
103
+ ...apiAccess,
104
+ execute: async ({ status }, ctx) => {
105
+ const query = status === undefined ? "" : `?status=${status}`;
106
+ const list = await browserbase(ctx, "GET", `/v1/sessions${query}`, session.array());
107
+ return list.ok ? done({ sessions: list.value.map(stateOf) }) : list.error;
108
+ },
109
+ }),
110
+ };