openAgent

1import { Effect, Schema } from "effect"
2import { executeWithLimits } from "./interpreter/runtime.js"
3import { type HostTools, type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js"
4import type { Definition } from "./tool.js"
5 
6/** A tool call admitted during an execution. */
7export type { ToolCall, ToolCallEnded, ToolCallHooks, ToolCallStarted, ToolDescription } from "./tool-runtime.js"
8 
9/** Resource budgets enforced independently during each CodeMode program execution. */
10export type ExecutionLimits = {
11  /** Maximum wall-clock execution time in milliseconds. No default: absent means no timeout. */
12  readonly timeoutMs?: number
13  /** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */
14  readonly maxToolCalls?: number
15  /** Maximum UTF-8 bytes of model-facing output. No default: absent means no truncation. */
16  readonly maxOutputBytes?: number
17}
18 
19/** Controls how much of the tool catalog is inlined in agent instructions. */
20export type DiscoveryOptions = {
21  /** Approximate token budget (chars/4, default 2000) for full catalog entries. */
22  readonly catalogBudget?: number
23}
24 
25type ToolTree<R = never> = {
26  readonly [name: string]: Definition<R> | ToolTree<R>
27}
28 
29export type ResolvedExecutionLimits = {
30  readonly timeoutMs: number | undefined
31  readonly maxToolCalls: number | undefined
32  readonly maxOutputBytes: number | undefined
33}
34 
35/** Options for one CodeMode execution. */
36export type ExecuteOptions<Tools extends Record<string, unknown> = {}> = {
37  /** Source for one program in the supported JavaScript subset. */
38  code: string
39  /** Explicit tool tree exposed to the program as `tools`. */
40  tools?: Tools & ToolTree<Services<Tools>>
41  /** Per-execution overrides for the default resource limits. */
42  limits?: ExecutionLimits
43  /** Observes decoded tool input immediately before tool execution. */
44  onToolCallStart?: (call: ToolRuntime.ToolCallStarted) => Effect.Effect<void, never, Services<Tools>>
45  /** Observes each admitted tool call as it settles, with outcome and duration. */
46  onToolCallEnd?: (call: ToolRuntime.ToolCallEnded) => Effect.Effect<void, never, Services<Tools>>
47}
48 
49/** A JSON value that can cross the confined interpreter boundary. */
50export type DataValue = Schema.Json
51 
52/** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
53export type Options<Tools extends Record<string, unknown> = {}> = Omit<ExecuteOptions<Tools>, "code"> & {
54  /** Progressive-disclosure configuration for the agent-facing tool catalog. */
55  readonly discovery?: DiscoveryOptions
56}
57 
58/** Schema for a host tool input containing CodeMode source. */
59export const Input = Schema.Struct({ code: Schema.String })
60export type Input = typeof Input.Type
61 
62export const DiagnosticKind = Schema.Literals([
63  "ParseError",
64  "UnsupportedSyntax",
65  "UnknownTool",
66  "InvalidToolInput",
67  "InvalidToolOutput",
68  "InvalidDataValue",
69  "ToolCallLimitExceeded",
70  "TimeoutExceeded",
71  "ToolFailure",
72  "ExecutionFailure",
73])
74/** Stable categories produced by program, schema, tool, and limit failures. */
75export type DiagnosticKind = typeof DiagnosticKind.Type
76 
77export const Diagnostic = Schema.Struct({
78  kind: DiagnosticKind,
79  message: Schema.String,
80  location: Schema.optionalKey(Schema.Struct({ line: Schema.Number, column: Schema.Number })),
81  suggestions: Schema.optionalKey(Schema.Array(Schema.String)),
82})
83/** A normalized program diagnostic safe to return across an agent tool boundary. */
84export type Diagnostic = typeof Diagnostic.Type
85 
86const ToolCallSchema = Schema.Struct({ name: Schema.String })
87export const Success = Schema.Struct({
88  ok: Schema.Literal(true),
89  value: Schema.Json,
90  logs: Schema.optionalKey(Schema.Array(Schema.String)),
91  truncated: Schema.optionalKey(Schema.Boolean),
92  toolCalls: Schema.Array(ToolCallSchema),
93})
94/** Successful execution after the result has crossed the plain-data boundary. */
95export type Success = typeof Success.Type
96 
97export const Failure = Schema.Struct({
98  ok: Schema.Literal(false),
99  error: Diagnostic,
100  logs: Schema.optionalKey(Schema.Array(Schema.String)),
101  truncated: Schema.optionalKey(Schema.Boolean),
102  toolCalls: Schema.Array(ToolCallSchema),
103})
104/** Failed execution with calls admitted before the diagnostic was produced. */
105export type Failure = typeof Failure.Type
106 
107/** Schema for the structured success or diagnostic returned by CodeMode execution. */
108export const Result = Schema.Union([Success, Failure])
109/** Result of executing a CodeMode program. Program failures are data, not Effect failures. */
110export type Result = typeof Result.Type
111 
112/** Reusable confined runtime over one explicit tool tree. */
113export type Runtime<R = never> = {
114  readonly catalog: () => ReadonlyArray<ToolDescription>
115  readonly instructions: () => string
116  readonly execute: (code: string) => Effect.Effect<Result, never, R>
117}
118 
119const validateLimit = <Value extends number | undefined>(
120  name: keyof ExecutionLimits,
121  value: Value,
122  minimum: number,
123): Value => {
124  if (value !== undefined && (!Number.isSafeInteger(value) || value < minimum)) {
125    throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}.`)
126  }
127  return value
128}
129 
130const resolveExecutionLimits = (limits?: ExecutionLimits): ResolvedExecutionLimits => ({
131  timeoutMs: validateLimit("timeoutMs", limits?.timeoutMs, 1),
132  maxToolCalls: validateLimit("maxToolCalls", limits?.maxToolCalls, 0),
133  maxOutputBytes: validateLimit("maxOutputBytes", limits?.maxOutputBytes, 0),
134})
135 
136/** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
137export const execute = <const Tools extends Record<string, unknown>>(
138  options: ExecuteOptions<Tools>,
139): Effect.Effect<Result, never, Services<Tools>> => {
140  const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
141  ToolRuntime.assertValidTools(tools)
142  return executeWithLimits(options, resolveExecutionLimits(options.limits), ToolRuntime.searchIndex(tools))
143}
144 
145/** Creates an Effect-native runtime over explicit, schema-described tools. */
146export const make = <const Tools extends Record<string, unknown> = {}>(
147  options: Options<Tools> = {} as Options<Tools>,
148): Runtime<Services<Tools>> => {
149  const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
150  ToolRuntime.assertValidTools(tools)
151  const limits = resolveExecutionLimits(options.limits)
152  const prepared = ToolRuntime.prepare(tools, options.discovery?.catalogBudget)
153 
154  return {
155    catalog: () => prepared.catalog,
156    instructions: () => prepared.instructions,
157    execute: (code) => executeWithLimits<Tools>({ ...options, code }, limits, prepared.searchIndex),
158  }
159}
160