@neurocode-ai/codemode 1.18.8

package/src/codemode.ts

@@ -0,0 +1,159 @@
+import { Effect, Schema } from "effect"
+import { executeWithLimits } from "./interpreter/runtime.js"
+import { type HostTools, type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js"
+import type { Definition } from "./tool.js"
+
+/** A tool call admitted during an execution. */
+export type { ToolCall, ToolCallEnded, ToolCallHooks, ToolCallStarted, ToolDescription } from "./tool-runtime.js"
+
+/** Resource budgets enforced independently during each CodeMode program execution. */
+export type ExecutionLimits = {
+  /** Maximum wall-clock execution time in milliseconds. No default: absent means no timeout. */
+  readonly timeoutMs?: number
+  /** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */
+  readonly maxToolCalls?: number
+  /** Maximum UTF-8 bytes of model-facing output. No default: absent means no truncation. */
+  readonly maxOutputBytes?: number
+}
+
+/** Controls how much of the tool catalog is inlined in agent instructions. */
+export type DiscoveryOptions = {
+  /** Approximate token budget (chars/4, default 2000) for full catalog entries. */
+  readonly catalogBudget?: number
+}
+
+type ToolTree<R = never> = {
+  readonly [name: string]: Definition<R> | ToolTree<R>
+}
+
+export type ResolvedExecutionLimits = {
+  readonly timeoutMs: number | undefined
+  readonly maxToolCalls: number | undefined
+  readonly maxOutputBytes: number | undefined
+}
+
+/** Options for one CodeMode execution. */
+export type ExecuteOptions<Tools extends Record<string, unknown> = {}> = {
+  /** Source for one program in the supported JavaScript subset. */
+  code: string
+  /** Explicit tool tree exposed to the program as `tools`. */
+  tools?: Tools & ToolTree<Services<Tools>>
+  /** Per-execution overrides for the default resource limits. */
+  limits?: ExecutionLimits
+  /** Observes decoded tool input immediately before tool execution. */
+  onToolCallStart?: (call: ToolRuntime.ToolCallStarted) => Effect.Effect<void, never, Services<Tools>>
+  /** Observes each admitted tool call as it settles, with outcome and duration. */
+  onToolCallEnd?: (call: ToolRuntime.ToolCallEnded) => Effect.Effect<void, never, Services<Tools>>
+}
+
+/** A JSON value that can cross the confined interpreter boundary. */
+export type DataValue = Schema.Json
+
+/** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
+export type Options<Tools extends Record<string, unknown> = {}> = Omit<ExecuteOptions<Tools>, "code"> & {
+  /** Progressive-disclosure configuration for the agent-facing tool catalog. */
+  readonly discovery?: DiscoveryOptions
+}
+
+/** Schema for a host tool input containing CodeMode source. */
+export const Input = Schema.Struct({ code: Schema.String })
+export type Input = typeof Input.Type
+
+export const DiagnosticKind = Schema.Literals([
+  "ParseError",
+  "UnsupportedSyntax",
+  "UnknownTool",
+  "InvalidToolInput",
+  "InvalidToolOutput",
+  "InvalidDataValue",
+  "ToolCallLimitExceeded",
+  "TimeoutExceeded",
+  "ToolFailure",
+  "ExecutionFailure",
+])
+/** Stable categories produced by program, schema, tool, and limit failures. */
+export type DiagnosticKind = typeof DiagnosticKind.Type
+
+export const Diagnostic = Schema.Struct({
+  kind: DiagnosticKind,
+  message: Schema.String,
+  location: Schema.optionalKey(Schema.Struct({ line: Schema.Number, column: Schema.Number })),
+  suggestions: Schema.optionalKey(Schema.Array(Schema.String)),
+})
+/** A normalized program diagnostic safe to return across an agent tool boundary. */
+export type Diagnostic = typeof Diagnostic.Type
+
+const ToolCallSchema = Schema.Struct({ name: Schema.String })
+export const Success = Schema.Struct({
+  ok: Schema.Literal(true),
+  value: Schema.Json,
+  logs: Schema.optionalKey(Schema.Array(Schema.String)),
+  truncated: Schema.optionalKey(Schema.Boolean),
+  toolCalls: Schema.Array(ToolCallSchema),
+})
+/** Successful execution after the result has crossed the plain-data boundary. */
+export type Success = typeof Success.Type
+
+export const Failure = Schema.Struct({
+  ok: Schema.Literal(false),
+  error: Diagnostic,
+  logs: Schema.optionalKey(Schema.Array(Schema.String)),
+  truncated: Schema.optionalKey(Schema.Boolean),
+  toolCalls: Schema.Array(ToolCallSchema),
+})
+/** Failed execution with calls admitted before the diagnostic was produced. */
+export type Failure = typeof Failure.Type
+
+/** Schema for the structured success or diagnostic returned by CodeMode execution. */
+export const Result = Schema.Union([Success, Failure])
+/** Result of executing a CodeMode program. Program failures are data, not Effect failures. */
+export type Result = typeof Result.Type
+
+/** Reusable confined runtime over one explicit tool tree. */
+export type Runtime<R = never> = {
+  readonly catalog: () => ReadonlyArray<ToolDescription>
+  readonly instructions: () => string
+  readonly execute: (code: string) => Effect.Effect<Result, never, R>
+}
+
+const validateLimit = <Value extends number | undefined>(
+  name: keyof ExecutionLimits,
+  value: Value,
+  minimum: number,
+): Value => {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < minimum)) {
+    throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}.`)
+  }
+  return value
+}
+
+const resolveExecutionLimits = (limits?: ExecutionLimits): ResolvedExecutionLimits => ({
+  timeoutMs: validateLimit("timeoutMs", limits?.timeoutMs, 1),
+  maxToolCalls: validateLimit("maxToolCalls", limits?.maxToolCalls, 0),
+  maxOutputBytes: validateLimit("maxOutputBytes", limits?.maxOutputBytes, 0),
+})
+
+/** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
+export const execute = <const Tools extends Record<string, unknown>>(
+  options: ExecuteOptions<Tools>,
+): Effect.Effect<Result, never, Services<Tools>> => {
+  const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
+  ToolRuntime.assertValidTools(tools)
+  return executeWithLimits(options, resolveExecutionLimits(options.limits), ToolRuntime.searchIndex(tools))
+}
+
+/** Creates an Effect-native runtime over explicit, schema-described tools. */
+export const make = <const Tools extends Record<string, unknown> = {}>(
+  options: Options<Tools> = {} as Options<Tools>,
+): Runtime<Services<Tools>> => {
+  const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
+  ToolRuntime.assertValidTools(tools)
+  const limits = resolveExecutionLimits(options.limits)
+  const prepared = ToolRuntime.prepare(tools, options.discovery?.catalogBudget)
+
+  return {
+    catalog: () => prepared.catalog,
+    instructions: () => prepared.instructions,
+    execute: (code) => executeWithLimits<Tools>({ ...options, code }, limits, prepared.searchIndex),
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as CodeMode from "./codemode.js"
+export * as Tool from "./tool.js"
+export * as OpenAPI from "./openapi/index.js"
+export { ToolError, toolError } from "./tool-error.js"

package/src/interpreter/model.ts

@@ -0,0 +1,201 @@
+import type { SafeObject } from "../tool-runtime.js"
+import type { SandboxURL } from "../values.js"
+
+export type SourcePosition = {
+  line: number
+  column: number
+}
+
+export type SourceLocation = {
+  start: SourcePosition
+  end: SourcePosition
+}
+
+export type AstNode = {
+  type: string
+  loc?: SourceLocation
+  [key: string]: unknown
+}
+
+export type ProgramNode = AstNode & {
+  type: "Program"
+  body: Array<AstNode>
+}
+
+export type Binding = {
+  mutable: boolean
+  value: unknown
+  initialized?: boolean
+}
+
+export type StatementResult =
+  | { kind: "none" }
+  | { kind: "value"; value: unknown }
+  | { kind: "return"; value: unknown }
+  | { kind: "break" }
+  | { kind: "continue" }
+
+export type MemberReference = {
+  target: SafeObject | Array<unknown> | SandboxURL
+  key: string | number
+}
+
+export class CodeModeFunction {
+  constructor(
+    readonly parameters: ReadonlyArray<AstNode>,
+    readonly body: AstNode,
+    readonly capturedScopes: ReadonlyArray<Map<string, Binding>>,
+  ) {}
+}
+
+export class IntrinsicReference {
+  constructor(
+    readonly receiver: unknown,
+    readonly name: string,
+  ) {}
+}
+
+export class ComputedValue {
+  constructor(readonly value: unknown) {}
+}
+
+export class PromiseNamespace {}
+
+export type PromiseMethodName = "all" | "allSettled" | "race" | "resolve" | "reject"
+
+export class PromiseMethodReference {
+  constructor(readonly name: PromiseMethodName) {}
+}
+
+export type GlobalNamespaceName =
+  | "Object"
+  | "Math"
+  | "JSON"
+  | "Array"
+  | "console"
+  | "Date"
+  | "RegExp"
+  | "Map"
+  | "Set"
+  | "URL"
+  | "URLSearchParams"
+
+export class GlobalNamespace {
+  constructor(readonly name: GlobalNamespaceName) {}
+}
+
+export class GlobalMethodReference {
+  constructor(
+    readonly namespace: GlobalNamespaceName | "Number" | "String",
+    readonly name: string,
+  ) {}
+}
+
+export class CoercionFunction {
+  constructor(readonly name: "Number" | "String" | "Boolean" | "parseInt" | "parseFloat") {}
+}
+
+export class UriFunction {
+  constructor(readonly name: "encodeURI" | "encodeURIComponent" | "decodeURI" | "decodeURIComponent") {}
+}
+
+export class ProgramThrow {
+  constructor(readonly value: unknown) {}
+}
+
+export class ErrorConstructorReference {
+  constructor(readonly name: string) {}
+}
+
+export type DiagnosticKind =
+  | "ParseError"
+  | "UnsupportedSyntax"
+  | "UnknownTool"
+  | "InvalidToolInput"
+  | "InvalidToolOutput"
+  | "InvalidDataValue"
+  | "ToolCallLimitExceeded"
+  | "TimeoutExceeded"
+  | "ToolFailure"
+  | "ExecutionFailure"
+
+export const OptionalShortCircuit: unique symbol = Symbol("codemode.optional-short-circuit")
+
+export const supportedSyntaxMessage =
+  "Supported orchestration syntax: tools.* calls (they return promises - resolve them with await), data literals, destructuring, optional chaining, template literals, conditionals, switch, loops (incl. for...of and for...in over object/array/tools keys), arrow functions, spread, try/catch, array methods (map/filter/find/findIndex/some/every/reduce/flatMap/forEach/sort/slice/concat/indexOf/lastIndexOf/at/flat/reverse/includes/join), string methods (incl. match/matchAll/replace/split with regular expressions), Date/RegExp/Map/Set/URL/URLSearchParams, URI encoding helpers, Object/Math/JSON helpers, captured console.log/warn/error/dir/table, and Promise.all/allSettled/race/resolve/reject over arrays mixing promises and plain values for parallel tool calls (promise chaining with .then/.catch is not supported - use await with try/catch)."
+
+export class InterpreterRuntimeError extends Error {
+  readonly node?: AstNode
+  errorName: string = "Error"
+
+  constructor(
+    message: string,
+    node?: AstNode,
+    readonly kind: DiagnosticKind = "ExecutionFailure",
+    readonly suggestions?: ReadonlyArray<string>,
+  ) {
+    super(message)
+    this.name = "InterpreterRuntimeError"
+    if (node) this.node = node
+  }
+
+  as(errorName: string): this {
+    this.errorName = errorName
+    return this
+  }
+}
+
+export const unsupportedSyntax = (kind: string, node: AstNode): InterpreterRuntimeError =>
+  new InterpreterRuntimeError(
+    `Syntax '${kind}' is not supported in CodeMode. ${supportedSyntaxMessage}`,
+    node,
+    "UnsupportedSyntax",
+    [supportedSyntaxMessage],
+  )
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+export const asNode = (value: unknown, context: string): AstNode => {
+  if (!isRecord(value) || typeof value.type !== "string") {
+    throw new InterpreterRuntimeError(`Invalid AST node while reading ${context}.`)
+  }
+  return value as AstNode
+}
+
+export const getArray = (node: AstNode, key: string): Array<unknown> => {
+  const value = node[key]
+  if (!Array.isArray(value)) throw new InterpreterRuntimeError(`Expected '${key}' to be an array.`, node)
+  return value
+}
+
+export const getString = (node: AstNode, key: string): string => {
+  const value = node[key]
+  if (typeof value !== "string") throw new InterpreterRuntimeError(`Expected '${key}' to be a string.`, node)
+  return value
+}
+
+export const getBoolean = (node: AstNode, key: string): boolean => {
+  const value = node[key]
+  if (typeof value !== "boolean") throw new InterpreterRuntimeError(`Expected '${key}' to be a boolean.`, node)
+  return value
+}
+
+export const getOptionalNode = (node: AstNode, key: string): AstNode | undefined => {
+  const value = node[key]
+  if (value === undefined || value === null) return undefined
+  return asNode(value, key)
+}
+
+export const getNode = (node: AstNode, key: string): AstNode => asNode(node[key], key)
+
+export const sourceLocation = (node: AstNode): { readonly line: number; readonly column: number } => ({
+  line: Math.max(1, (node.loc?.start.line ?? 2) - 1),
+  column: Math.max(1, (node.loc?.start.column ?? 4) - 3),
+})
+
+export const formatLocation = (node?: AstNode): string => {
+  if (!node?.loc) return ""
+  const location = sourceLocation(node)
+  return ` (line ${location.line}, col ${location.column})`
+}