codemode

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package codemode runs a model-written JavaScript script against a table of host tools and globals. It ports packages/codemode: the script runs in a QuickJS VM compiled to WebAssembly and hosted by wazero, and reaches the host only through one bridge function (docs/specs/builtin-codemode-tool-search.md).

Index

Constants

View Source
const (
	MaxStoreValueChars = 256 * 1024
	MaxStoreTotalChars = 1024 * 1024
)

The store limits the prelude enforces.

Ports packages/codemode/src/runtime/prelude-source.ts (MAX_STORE_VALUE_CHARS, MAX_STORE_TOTAL_CHARS).

View Source
const (
	MaxOutputChars = 16 * 1024 * 1024
	MaxOutputItems = 100_000
)

The output limits the prelude enforces: characters of text and base64 image data, and items, that one script may produce with `text()`, `image()`, and `console.*`. The host keeps all output until the script ends, so without a limit a script that prints in a loop grows the host's memory until it crashes. The item limit covers loops that print empty strings.

Ports packages/codemode/src/runtime/prelude-source.ts (MAX_OUTPUT_CHARS, MAX_OUTPUT_ITEMS).

View Source
const (
	MessageCall   = "call"
	MessageOutput = "output"
	MessageDone   = "done"
	MessageCrash  = "crash"
	// MessageStarted and MessageIdle are sent by a deterministic VM.
	MessageStarted = "started"
	MessageIdle    = "idle"
	MessageResult  = "result"
	MessageFailure = "failure"
	MessageStop    = "stop"
)

The Type values of WorkerToHostMessage, HostToWorkerMessage and RemoteMessage.

View Source
const CodemodeOptionsPrefix = "// @options:"

CodemodeOptionsPrefix starts the optional first line of a script.

Ports packages/codemode/src/source.ts (CODEMODE_OPTIONS_PREFIX).

View Source
const CodemodeSourceGrammar = `` /* 184-byte string literal not displayed */

CodemodeSourceGrammar is the Lark grammar for providers with grammar-constrained tool input. It only fixes the shape of the options line; ParseCodemodeSource checks the options JSON and the code.

Ports packages/codemode/src/source.ts (CODEMODE_SOURCE_GRAMMAR).

View Source
const DefaultInputSchemaMaxChars = 16_000

DefaultInputSchemaMaxChars is the largest rendered input type, in characters, before it becomes `unknown`.

Ports packages/codemode/src/declarations.ts (DEFAULT_INPUT_SCHEMA_MAX_CHARS).

View Source
const DefaultInterruptBudget = 100_000

DefaultInterruptBudget is the interrupt polls an InlineSandbox execution may use before it fails with ErrorTimeout.

Ports packages/codemode/src/runtime/inline.ts (DEFAULT_INTERRUPT_BUDGET).

View Source
const EmbeddedQuickJSWasmPath = "assets/quickjs.wasm"

EmbeddedQuickJSWasmPath names the one QuickJS module the package has: the embedded asset.

Variables

View Source
var PreludeSource string

PreludeSource is the JavaScript evaluated inside the VM before the script runs, embedded byte for byte.

Ports packages/codemode/src/runtime/prelude-source.ts (PRELUDE_SOURCE).

Functions

func CallInitiated

func CallInitiated(ctx context.Context)

CallInitiated tells the host that the call ctx belongs to has initiated (see Tool.AwaitsInitiation). It is a no-op for a context the host did not create and for a second call.

func LoadQuickJSWasm

func LoadQuickJSWasm(path string) ([]byte, error)

LoadQuickJSWasm returns the QuickJS wasm module. Pi's `loadQuickJSWasm(path?)` reads the module at path, defaulting to the file of the installed quickjs-wasi package; PiG has one module source, the embedded asset (assets/PROVENANCE.md), and never reads a module from the file system. An empty path or EmbeddedQuickJSWasmPath is that module; any other path is an error. Pass the result through SandboxOptions.Wasm: sandboxes that load one module share one compilation.

Ports packages/codemode/src/wasm.ts loadQuickJSWasm(path?).

func OrderStoreKeys

func OrderStoreKeys(set map[string]json.RawMessage, written []string) []string

OrderStoreKeys returns the keys of set as a JavaScript object enumerates them: array-index keys ascending, then the others in the order of written (the order the script first wrote them). A key of set that written lacks follows in sorted order.

func QuickJSWasm

func QuickJSWasm() []byte

QuickJSWasm returns the embedded quickjs-wasi module (assets/PROVENANCE.md). The caller must not modify it.

func RenderDeclarations

func RenderDeclarations(options RenderDeclarationsOptions) (string, error)

RenderDeclarations renders TypeScript declarations for the script-visible API: tools become members of `declare const tools`, globals `declare function` statements, and `ns.member` globals members of `declare const ns`.

Ports packages/codemode/src/declarations.ts (renderDeclarations).

func RenderToolOutputType

func RenderToolOutputType(raw json.RawMessage) (string, error)

RenderToolOutputType returns the type a tool call resolves to: the output schema's type, and `unknown` without a schema.

Ports packages/codemode/src/declarations.ts (renderToolOutputType).

func RenderToolSample

func RenderToolSample(tool Tool, options ToolRenderOptions) (string, error)

RenderToolSample renders the description followed by the tool's declaration, for tool listings and `ALL_TOOLS` entries.

Ports packages/codemode/src/declarations.ts (renderToolSample).

func RenderToolSignature

func RenderToolSignature(tool Tool, options ToolRenderOptions) (string, error)

RenderToolSignature renders one tool as a member of the `tools` object: `name(args: T): Promise<R>;` with the name as the identifier scripts use. Input types longer than options.InputMaxChars (nil means DefaultInputSchemaMaxChars) render as `unknown`.

Ports packages/codemode/src/declarations.ts (renderToolSignature).

func SchemaToType

func SchemaToType(schema json.RawMessage, options SchemaToTypeOptions) (string, error)

SchemaToType converts a JSON Schema to a TypeScript type expression: objects on one line (`{ a: string; b?: number; }`) with properties sorted by name, or one property per line with `//` comments when a property has a description or constraints the type cannot express (`// @integer @minimum 1 @default 20`); `Array<T>` for arrays. Local references (`#/$defs/...`, `#/definitions/...`) resolve against the schema; recursive and remote references render as `unknown`. A result longer than maxChars characters (options.MaxChars, nil means no limit) is rendered again without the constraint tags, and renders as `unknown` if it is still too long. A schema that is not valid JSON renders as `unknown`.

Ports packages/codemode/src/declarations.ts (schemaToType).

func ServeRemote

func ServeRemote(ctx context.Context, request RemoteRequest, exchange RemoteExchange, options ServeOptions)

ServeRemote is the remote end of RemoteSandbox: it runs one execution's VM on the calling goroutine under an interrupt budget and forwards everything it reports through exchange, asking the client for the result of every tool call. It returns once the VM has stopped and the terminal message has been delivered, or the client asked to stop. It never fails: whatever goes wrong is reported to the client, or ends the execution when the client is gone.

A Remote usually implements Execute as `ServeRemote(ctx, request, exchange, options)` with the limits of its host. The script's request is capped at those limits: see ServeOptions.

Go mechanics, not divergences: ctx ends the execution (the client cancels the context of Remote.Execute once it finished), also while a script computes, where upstream's remote runs the VM to its budget.

Ports packages/codemode/src/runtime/remote.ts (serveCodemodeRemote).

func ToCodemodeIdentifier

func ToCodemodeIdentifier(name string) string

ToCodemodeIdentifier returns the identifier a script uses for a tool: characters that are not valid in a JavaScript identifier become `_`.

Ports packages/codemode/src/identifier.ts.

Types

type Call

type Call struct {
	Name       string
	Status     CallStatus
	DurationMs float64
}

Call records one tool call the script made (globals are not recorded).

type CallStatus

type CallStatus string

CallStatus is the outcome of one nested tool call.

const (
	CallOK        CallStatus = "ok"
	CallError     CallStatus = "error"
	CallCancelled CallStatus = "cancelled"
)

The nested call outcomes.

type CodemodeJsonSchema

type CodemodeJsonSchema = json.RawMessage

CodemodeJsonSchema is a JSON Schema document, an object or a boolean schema (packages/codemode/src/types.ts:11-12). It is carried as its raw JSON.

type DeclaredGlobal

type DeclaredGlobal struct {
	Name   string
	Spread bool
}

DeclaredGlobal is a global as a Start run's script sees it; the names are those Globals allow.

Ports packages/codemode/src/types.ts (CodemodeDeclaredGlobal).

type DeclaredTool

type DeclaredTool struct {
	Name string
	// JSName is the identifier the script uses, tools.<JSName>. Empty means ToCodemodeIdentifier(Name). A host that
	// replays a run passes the one the run started with, so a changed mapping cannot rename a tool under a resumed script.
	JSName      string
	Description string
}

DeclaredTool is a tool as a Start run's script sees it: tools.<JSName> and its ALL_TOOLS entry.

Ports packages/codemode/src/types.ts (CodemodeDeclaredTool).

type During

type During struct {
	Seq    int `json:"seq"`
	Issued int `json:"issued"`
}

During is, in a Start run, the result the VM was processing when the script finished (0 for its first run) and the number of calls it had issued by then.

Ports packages/codemode/src/types.ts (CodemodeDuring).

type Error

type Error struct {
	Kind    ErrorKind `json:"kind"`
	Name    string    `json:"name,omitempty"`
	Message string    `json:"message"`
	Stack   string    `json:"stack,omitempty"`
}

Error describes a failed execution.

type ErrorKind

type ErrorKind string

ErrorKind classifies a failed execution.

const (
	// ErrorScript: the script threw or failed to parse; Name and Stack come from the script's error.
	ErrorScript ErrorKind = "script"
	// ErrorTimeout: the overall deadline expired. The execution ended and the VM was asked to stop; a worker VM may still
	// be computing.
	ErrorTimeout ErrorKind = "timeout"
	// ErrorAborted: the caller's context ended or the sandbox was closed. The execution ended and the VM was asked to stop.
	ErrorAborted ErrorKind = "aborted"
	// ErrorSandbox: the VM failed outside the script's control (a wasm trap, a missing or corrupt wasm module).
	ErrorSandbox ErrorKind = "sandbox"
)

The failure kinds.

type ExecuteOptions

type ExecuteOptions struct {
	// TimeoutMs overrides the sandbox default for this execution; zero keeps it.
	TimeoutMs float64
	// Store holds the values the script reads with load(key), each JSON text.
	Store map[string]json.RawMessage
}

ExecuteOptions configures one execution.

type HostCall

type HostCall struct {
	// ID is the VM's own number for the call: 1, 2, ... in the order the script made its calls, tools and globals.
	ID int
	// Target is "tool" or "global".
	Target string
	Name   string
	// Args is what the script passed, after a JSON round trip; for spread globals the argument list. Nil is `undefined`.
	Args json.RawMessage
}

HostCall is a call the script made in a Start run, answered with Run.Deliver.

Ports packages/codemode/src/types.ts (CodemodeHostCall).

type HostToWorkerMessage

type HostToWorkerMessage struct {
	Type       string   `json:"type"`
	ID         int      `json:"id"`
	Ok         bool     `json:"ok"`
	Payload    *string  `json:"payload,omitempty"`
	Seq        *int     `json:"seq,omitempty"`
	Now        *float64 `json:"now,omitempty"`
	Properties *string  `json:"properties,omitempty"`
}

HostToWorkerMessage is the host's answer to a nested call: Payload is the JSON result when Ok, otherwise the error message, and nil for undefined.

Ports packages/codemode/src/runtime/protocol.ts (HostToWorkerMessage).

Deterministic mode: Seq numbers the results from 1 in the order the VM applies them, and the VM's clock reads Now (ms since the epoch) while it processes this one; Properties, for a rejection, is a JSON object whose properties the script's Error gets.

type InlineSandbox

type InlineSandbox struct {
	*Sandbox
}

InlineSandbox runs each execution's QuickJS VM under an interrupt budget, for hosts that cannot afford a script that computes forever: QuickJS polls its interrupt handler periodically while a script runs, and the execution fails with ErrorTimeout once the polls of the whole execution pass the budget, whatever the deadline says. The deadline and the context still end the execution whenever they fire.

Like Pi's InlineCodemodeSandbox, the VM runs in-thread: on the goroutine that called Execute for the first segment of the script, then on whichever goroutine delivers a tool's result. The deadline is armed before the first segment, and the deadline, the context and Close take effect between turns, where a turn is a segment of the script and the delivery of the messages it queued: while the VM computes, only the budget can stop it, and a segment that computes past the deadline still delivers its result first. Whenever the script waits on a tool the deadline and the context apply.

Ports packages/codemode/src/runtime/inline.ts (InlineCodemodeSandbox).

func NewInlineSandbox

func NewInlineSandbox(options InlineSandboxOptions) (*InlineSandbox, error)

NewInlineSandbox validates the globals and registers the tools, like NewSandbox.

type InlineSandboxOptions

type InlineSandboxOptions struct {
	SandboxOptions
	// InterruptBudget is the interrupt polls an execution may use before it fails with ErrorTimeout: the only limit on a
	// script that computes without awaiting a tool. Zero means DefaultInterruptBudget.
	InterruptBudget int
}

InlineSandboxOptions configures NewInlineSandbox.

Ports packages/codemode/src/runtime/inline.ts (InlineCodemodeSandboxOptions). Wasm is optional here: nil means the embedded module.

type Outcome

type Outcome struct {
	OK bool
	// Value is the JSON text of the result when OK; nil is `undefined`.
	Value   json.RawMessage
	Message string
	// Properties is the JSON text of the rejection's properties; nil is `undefined`. Run.Deliver refuses a value that is
	// not a JSON object (null, an array, a primitive), as Pi's deliver() does (packages/codemode/src/runtime/execution.ts).
	Properties json.RawMessage
}

Outcome is a call's answer. A rejection becomes an Error with Message in the script, carrying the own properties of Properties (JSON values; name, message and stack are ignored), for example structuredOutput.

Ports packages/codemode/src/types.ts (CodemodeOutcome).

type OutputItem

type OutputItem struct {
	Type OutputItemType `json:"type"`
	Text string         `json:"text,omitempty"`
	// Console marks a text item produced by console.*, so hosts can tell it apart from text() output.
	Console  bool   `json:"console,omitempty"`
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mimeType,omitempty"`
}

OutputItem is one item of the script's output, in the order the script produced it: text() and console.* produce "text" items, with Console set for console.*, and image() "image" items. Data is base64.

type OutputItemType

type OutputItemType string

OutputItemType is the closed `type` union of an output item (types.ts CodemodeOutputItem).

const (
	OutputItemText  OutputItemType = "text"
	OutputItemImage OutputItemType = "image"
)

The output item types.

type ParsedSource

type ParsedSource struct {
	// Code is the script with the options line replaced by an empty line, so line numbers are unchanged.
	Code    string
	Options SourceOptions
}

ParsedSource is a script with its options line split off.

func ParseCodemodeSource

func ParseCodemodeSource(input string) (ParsedSource, error)

ParseCodemodeSource splits an optional first-line `// @options: {...}` from the script. It fails with a *SourceError for empty input, invalid options, and an options line that is not the first line, which would otherwise be ignored without notice.

Ports packages/codemode/src/source.ts (parseCodemodeSource).

type Remote

type Remote interface {
	Execute(ctx context.Context, request RemoteRequest, exchange RemoteExchange) error
}

Remote runs one execution's VM. It is usually a proxy for a Durable Object that serves ServeRemote; any value with this method works, for example an in-process object in tests.

Ports packages/codemode/src/runtime/remote.ts (CodemodeRemote).

Execute blocks until the VM has stopped (the script settled, or the client asked to stop). Upstream's Promise settles at the same point. The client cancels ctx once it no longer wants the execution, and an Execute that honors it returns promptly instead of computing until its budget is used up.

type RemoteExchange

type RemoteExchange func(ctx context.Context, messages []RemoteMessage, reply func(*RemoteReply, error))

RemoteExchange is the function the client passes to Remote.Execute; the remote calls it to report what its VM did and to ask for the result of a tool call. Over an RPC boundary it is a proxy that calls back into the client.

Ports packages/codemode/src/runtime/remote.ts (CodemodeRemoteExchange).

Go mapping of a Promise that the caller does not await before going on: upstream runs the delivery of the messages synchronously inside the Promise executor and settles the reply later, and a remote that has several calls in flight depends on it, because "calls on one proxy are delivered in order". A blocking Go function cannot deliver in call order and also return the reply later, so the messages are delivered in order before exchange returns and the reply reaches the remote through reply, which exchange calls exactly once: from a client goroutine, or before exchange returns when there is nothing to wait for. A reply that carries an error is a rejected Promise (the RPC failed). A nil reply is upstream's `null`: the exchange carried no call. reply must not block.

type RemoteMessage

type RemoteMessage struct {
	WorkerToHostMessage
	// Failure is the error of a "failure" message.
	Failure *Error
}

RemoteMessage is what the remote sends to the client: VM messages (Type "call", "output", "done", "crash"), or a failure outside the VM bridge (Type "failure", with Failure set).

Ports packages/codemode/src/runtime/remote.ts (CodemodeRemoteMessage).

func (RemoteMessage) MarshalJSON

func (m RemoteMessage) MarshalJSON() ([]byte, error)

MarshalJSON writes a failure as `{ type: "failure", error: { kind, ... } }` and any other message as the WorkerToHostMessage it carries.

func (*RemoteMessage) UnmarshalJSON

func (m *RemoteMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON is the inverse of MarshalJSON.

type RemoteReply

type RemoteReply struct {
	HostToWorkerMessage
}

RemoteReply is the client's answer to an exchange: the result of the call the exchange carried (Type "result"), or "stop" once the client no longer wants the execution. A nil *RemoteReply is upstream's `null`: the exchange carried no call.

Ports packages/codemode/src/runtime/remote.ts (CodemodeRemoteReply).

func (RemoteReply) MarshalJSON

func (r RemoteReply) MarshalJSON() ([]byte, error)

MarshalJSON writes a stop as `{ type: "stop" }` and a result as the HostToWorkerMessage it carries.

type RemoteRequest

type RemoteRequest struct {
	Data VmStartData `json:"data"`
	// InterruptBudget is the requested interrupt budget; the remote may lower it (see ServeOptions). Zero asks for
	// the remote's default (`undefined` upstream).
	InterruptBudget int `json:"interruptBudget,omitempty"`
}

RemoteRequest is what the client sends to start an execution on the remote.

Ports packages/codemode/src/runtime/remote.ts (CodemodeRemoteRequest).

type RemoteSandbox

type RemoteSandbox struct {
	*Sandbox
	// contains filtered or unexported fields
}

RemoteSandbox runs each execution's VM on a remote, usually a Cloudflare Durable Object deployed with CodemodeSandboxDurableObject, while tools run here. It has the API and results of Sandbox, so it can replace it. Differences: a script that computes without calling a tool is limited by the remote's interrupt budget rather than TimeoutMs, and after a deadline or abort the remote VM keeps computing until it next calls a tool or uses up that budget, unless the Remote passes the context of Execute to ServeRemote, which stops a computing VM once the client finished.

Ports packages/codemode/src/runtime/remote.ts (RemoteCodemodeSandbox).

func NewRemoteSandbox

func NewRemoteSandbox(options RemoteSandboxOptions) (*RemoteSandbox, error)

NewRemoteSandbox validates the globals and registers the tools.

func (*RemoteSandbox) Close

func (r *RemoteSandbox) Close() error

Close aborts in-flight executions, rejects new ones, and waits for the Remote.Execute calls this sandbox started to return: each was told to stop when its execution ended. Upstream's close() does not wait for the remote; Go joins the background work it owns, so a Remote that ignores the context of Execute makes Close wait for as long as that remote runs (up to its interrupt budget).

type RemoteSandboxOptions

type RemoteSandboxOptions struct {
	Tools []Tool
	// Globals are exposed as top-level identifiers instead of on tools; see SandboxOptions.
	Globals []Tool
	// TimeoutMs is the overall deadline per execution, including time in tools. Zero means the default, 300000; +Inf
	// disables the deadline. A script that computes without calling a tool is limited by the remote's interrupt
	// budget instead.
	TimeoutMs float64
	// MemoryLimitBytes is the VM memory limit requested from the remote, which may lower it. Zero means the remote's
	// limit.
	MemoryLimitBytes uint32
	// Remote returns the remote that runs one execution, called once per Execute. For a Durable Object, pick the
	// instance here, for example by the session id. An error fails the execution as "Failed to reach the remote
	// sandbox: ...".
	Remote func() (Remote, error)
	// InterruptBudget is the interrupt budget requested from the remote. Zero means the remote's default.
	InterruptBudget int
}

RemoteSandboxOptions configures NewRemoteSandbox.

Ports packages/codemode/src/runtime/remote.ts (RemoteCodemodeSandboxOptions) and types.ts (CodemodeSandboxBaseOptions).

type RenderDeclarationsOptions

type RenderDeclarationsOptions struct {
	Tools   []Tool
	Globals []Tool
}

RenderDeclarationsOptions selects what RenderDeclarations renders.

type Result

type Result struct {
	OK          bool
	Value       json.RawMessage
	Output      []OutputItem
	Calls       []Call
	StoreWrites StoreWrites
	// Error is set when OK is false.
	Error *Error
	// During is set in a Start run that the script itself ended (it returned, threw or exited): the result being processed
	// when it did.
	//
	// Ports packages/codemode/src/types.ts (CodemodeResult.during).
	During *During
}

Result is the outcome of one execution. Output is kept for failed executions too, up to the failure. exit() completes with a nil Value.

type Run

type Run struct {
	// contains filtered or unexported fields
}

Run is a running Sandbox.Start execution.

Ports packages/codemode/src/types.ts (CodemodeRun).

func (*Run) Deliver

func (r *Run) Deliver(seq int, now float64, id int, outcome Outcome) error

Deliver answers call id as result number seq. Results are numbered 1, 2, ... without gaps, and the VM applies them strictly in that order, whatever order they arrive in: after a gap it waits for the missing number. While it processes this one, its clock reads now (ms since the epoch), or the previous value if now is earlier. It fails for a call that is not waiting for an answer, a seq used before, a now that is not finite and an answer JSON cannot hold; the call then still waits. After the run ended it does nothing.

Ports packages/codemode/src/types.ts (CodemodeRun.deliver).

func (*Run) Finished

func (r *Run) Finished() bool

Finished reports whether the run has its outcome: the script ended, timed out or failed, or the run was aborted. It is true as soon as that is decided, before Result returns, and calls can no longer be answered. It does not mean the VM has exited.

Ports packages/codemode/src/types.ts (CodemodeRun.finished).

func (*Run) Result

func (r *Run) Result() Result

Result waits for the run to end and returns its outcome. A script failure is a Result with OK false.

type RunOptions

type RunOptions struct {
	// StartedAt is the VM clock's start, in ms since the epoch: Date.now() until the first result arrives.
	StartedAt float64
	// Seed seeds Math.random() and the VM's other randomness.
	Seed    uint32
	Tools   []DeclaredTool
	Globals []DeclaredGlobal
	Store   map[string]json.RawMessage
	// TimeoutMs is the deadline of this run in ms. Nil means none (not the sandbox's default).
	TimeoutMs *float64
	// OnStarted receives the VM's fingerprint, before the script runs and before any of its calls.
	OnStarted func(fingerprint string)
	// OnCall receives a call the script made. Answer it with Run.Deliver, now or later, from any goroutine.
	OnCall func(call HostCall)
	// OnIdle receives the result the VM processed (0: the script's first run, before any result) and the calls it has
	// issued in total, each time the script waits again.
	OnIdle func(seq, issued int)
}

RunOptions configure Sandbox.Start.

Ports packages/codemode/src/types.ts (CodemodeRunOptions).

type Sandbox

type Sandbox struct {
	// contains filtered or unexported fields
}

Sandbox runs scripts in QuickJS VMs. Each Execute gets its own VM; the sandbox holds only the tool table and defaults. Close aborts in-flight executions.

Ports packages/codemode/src/runtime/host.ts (CodemodeSandbox).

func NewSandbox

func NewSandbox(options SandboxOptions) (*Sandbox, error)

NewSandbox validates the globals and registers the tools.

func (*Sandbox) Close

func (s *Sandbox) Close() error

Close aborts in-flight executions (they finish with ErrorAborted and message "Sandbox closed"), waits for them to exit, and rejects new ones.

func (*Sandbox) Execute

func (s *Sandbox) Execute(ctx context.Context, code string, options ExecuteOptions) (Result, error)

Execute runs code as an async function body: `return` and top-level `await` work. Script failures come back as a Result with OK false, never as an error; the error is for a closed sandbox. Cancelling ctx aborts the execution: the abort message is the context's cause. Execute returns after the execution's VM is closed and every goroutine it started has exited.

func (*Sandbox) Globals

func (s *Sandbox) Globals() []Tool

Globals lists the registered globals in registration order.

func (*Sandbox) RegisterTool

func (s *Sandbox) RegisterTool(tool Tool) error

RegisterTool fails if a tool with the same name is already registered.

func (*Sandbox) Start

func (s *Sandbox) Start(ctx context.Context, code string, options RunOptions) (*Run, error)

Start runs code deterministically with the caller answering its calls: the same script, start time, seed, tools, globals and store, answered with the same results in the same seq order, makes the same calls with the same arguments and produces the same output, on any VM with the same fingerprint. A host can therefore replay it after a restart. The VM runs in UTC, its clock reads StartedAt and then the now of the result being processed, its randomness comes from Seed, and WeakRef and FinalizationRegistry do not exist.

The sandbox's own tools and globals are not used: the run declares its own, and every call goes to options.OnCall. Script failures are in the Result; cancelling ctx ends the run with an error the script cannot catch (kind aborted, the context's cause as the message). Start returns at once; Result waits for the run.

Ports packages/codemode/src/runtime/execution.ts (CodemodeSandboxBase.start).

func (*Sandbox) Tools

func (s *Sandbox) Tools() []Tool

Tools lists the registered tools in registration order.

func (*Sandbox) UnregisterTool

func (s *Sandbox) UnregisterTool(name string) bool

UnregisterTool removes a tool and reports whether it existed.

type SandboxOptions

type SandboxOptions struct {
	Tools []Tool
	// Globals are exposed as top-level identifiers instead of on tools; they behave like tools but are not recorded
	// in Result.Calls. Names must be identifiers or <namespace>.<member> and may not shadow the built-in globals.
	Globals []Tool
	// TimeoutMs is the overall deadline per execution, including time in tools. Zero means the default,
	// 300000; +Inf disables the deadline.
	TimeoutMs float64
	// MemoryLimitBytes is the most memory the QuickJS VM may allocate; allocations beyond it fail inside the script
	// as `InternalError: out of memory`. Zero means no limit beyond the wasm32 address space.
	MemoryLimitBytes uint32
	// CacheDir holds wazero's on-disk compilation cache, which makes a later process start in tens of milliseconds
	// instead of hundreds. Empty compiles in memory; a directory that cannot be used is ignored.
	CacheDir string
	// Wasm supplies the QuickJS wasm module. Nil means the embedded module (upstream: loadQuickJSWasm()).
	Wasm func() ([]byte, error)
	// AcquireWorker reserves capacity immediately before each worker VM is created, after the module is loaded. An error
	// denies admission without starting a VM and fails the execution as a sandbox error with its message. Otherwise the
	// returned release, which may be nil, is called once when the VM actually exits, not when the result is returned.
	// Reservations can be shared across sandboxes. It is not called for a launch that resumes after the execution has
	// settled (aborted or closed while the module loaded): that launch starts no VM and takes no reservation.
	AcquireWorker func() (release func(), err error)
	// OnWorkerStarted is called once for each worker VM started by Execute or Start. exited is closed when that VM
	// actually exits, which may be after the result and Close return: a call that does not poll the interrupt flag runs
	// until the grace period halts the instance. An error fails the execution as a sandbox error and ends the VM.
	OnWorkerStarted func(exited <-chan struct{}) error
}

SandboxOptions configures NewSandbox.

type SchemaToTypeOptions

type SchemaToTypeOptions struct {
	// MaxChars is the largest rendered type, in characters, before it becomes `unknown`. Nil means no limit.
	MaxChars *int
}

SchemaToTypeOptions is the options object of schemaToType.

type ServeOptions

type ServeOptions struct {
	// MaxInterruptBudget is the upper bound for a request's interrupt budget, and the budget when a request names
	// none. Zero means the default.
	MaxInterruptBudget int
	// MaxMemoryLimitBytes is the upper bound for a request's VM memory, and the limit when a request names none. Zero
	// means no bound.
	MaxMemoryLimitBytes uint32
	// Wasm supplies the QuickJS wasm module. Nil means the embedded module (upstream: the `wasm` option).
	Wasm func() ([]byte, error)
	// CacheDir holds wazero's on-disk compilation cache; see SandboxOptions.
	CacheDir string
}

ServeOptions configures ServeRemote.

Ports packages/codemode/src/runtime/remote.ts (CodemodeServeOptions).

type SourceError

type SourceError struct {
	Message string
}

SourceError reports empty input or invalid options.

func NewSourceError

func NewSourceError(message string) *SourceError

NewSourceError is `new CodemodeSourceError(message)`.

func (*SourceError) Error

func (e *SourceError) Error() string

func (*SourceError) Name

func (*SourceError) Name() string

Name is the upstream error's `name`.

type SourceOptions

type SourceOptions struct {
	// MaxOutputTokens is the token budget for the script's output; nil means unset.
	MaxOutputTokens *int64
	// TimeoutMs is the hard deadline for the whole script in milliseconds; nil means unset.
	TimeoutMs *int64
}

SourceOptions are the fields of the options line.

type StoreWrites

type StoreWrites struct {
	Set map[string]json.RawMessage
	// Delete lists the keys stored as undefined.
	Delete []string
	// contains filtered or unexported fields
}

StoreWrites are the keys the script changed with store(). Only successful executions report writes.

func (StoreWrites) SetKeys

func (w StoreWrites) SetKeys() []string

SetKeys returns the keys of Set in the order a JavaScript object enumerates them once the host assigned them one by one (host.ts parseStoreWrites).

type Tool

type Tool struct {
	// Name is the tool's name. Scripts call tools as tools.<ToCodemodeIdentifier(Name)>(args) and tools["<Name>"](args).
	// A global is called as <Name>(args) and must be an identifier or <namespace>.<member>.
	Name string
	// Description is a doc comment in RenderDeclarations and the entry text in ALL_TOOLS. Empty means none.
	Description string
	// InputSchema is the JSON Schema of the single argument, used only to render declarations. Nil means unknown.
	InputSchema CodemodeJsonSchema
	// OutputSchema is the JSON Schema of the resolved value, used only to render declarations. Nil means unknown.
	OutputSchema CodemodeJsonSchema
	// Spread makes a global receive all call arguments as an array instead of the first one.
	Spread bool
	// Signature is a TypeScript parameter list and return type that replaces the rendering from the schemas
	// (globals only). Nil means none; a non-nil empty string renders as Pi does, `declare function name;`.
	Signature *string
	// AwaitsInitiation makes the script's next tool call wait until Execute has initiated this one: until it calls
	// CallInitiated with its context, or returns. Pi runs each call's synchronous prefix in call order, so two calls a script
	// starts together reach a server in script order; a Go goroutine per call does not, and a tool whose prefix must keep the
	// order (a request to a server) sets this and calls CallInitiated once the order is fixed.
	AwaitsInitiation bool
	// Execute runs the tool. args is what the script passed, after a JSON round trip.
	Execute func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

Tool is a host function a script can call.

Ports packages/codemode/src/types.ts (CodemodeTool). Go mechanics, not divergences: the arguments and the result are JSON text, the form in which they cross the VM boundary (a nil json.RawMessage is `undefined`), and the upstream ToolContext.signal is the ctx passed to Execute, cancelled when the script finishes, times out, is aborted or the sandbox closes.

type ToolRenderOptions

type ToolRenderOptions struct {
	// InputMaxChars is the largest rendered input type, in characters, before it becomes `unknown`. Nil means
	// DefaultInputSchemaMaxChars.
	InputMaxChars *int
}

ToolRenderOptions is the options object of renderToolSignature and renderToolSample.

type URIError

type URIError struct{ Message string }

URIError is the error JavaScript's decodeURIComponent throws for a malformed percent-encoding (a `$ref` segment with one).

func (*URIError) Error

func (e *URIError) Error() string

func (*URIError) Name

func (*URIError) Name() string

Name is the JavaScript error's `name`.

type VmDeterministic

type VmDeterministic struct {
	StartedAt float64 `json:"startedAt"`
	Seed      uint32  `json:"seed"`
}

VmDeterministic is the start of a deterministic run: the clock's start and the seed of its randomness.

Ports packages/codemode/src/runtime/protocol.ts (VmStartData.deterministic).

type VmStartData

type VmStartData struct {
	Code    string          `json:"code"`
	Tools   []VmStartTool   `json:"tools"`
	Globals []VmStartGlobal `json:"globals"`
	// MemoryLimitBytes is the QuickJS heap limit; zero means none (`undefined` upstream, which JSON omits).
	MemoryLimitBytes uint32 `json:"memoryLimitBytes,omitempty"`
	// Store is the snapshot for load(): key to JSON text.
	Store map[string]string `json:"store"`
	// Deterministic, when set, runs the VM deterministically (Sandbox.Start): UTC, a virtual clock starting at StartedAt (ms
	// since the epoch) that moves only with delivered results, randomness from Seed, no WeakRef, results applied in seq
	// order, and started and idle messages.
	Deterministic *VmDeterministic `json:"deterministic,omitempty"`
}

VmStartData is everything a VM needs to run one script, independent of where it runs.

Ports packages/codemode/src/runtime/protocol.ts (VmStartData).

type VmStartGlobal

type VmStartGlobal struct {
	Name   string `json:"name"`
	Spread bool   `json:"spread"`
}

VmStartGlobal is a global as the prelude lists it.

Ports packages/codemode/src/runtime/protocol.ts (VmStartData.globals).

type VmStartTool

type VmStartTool struct {
	Name        string `json:"name"`
	JSName      string `json:"jsName"`
	Description string `json:"description"`
}

VmStartTool is a tool as the prelude lists it: JSName is the identifier the script uses and Description is listed in ALL_TOOLS.

Ports packages/codemode/src/runtime/protocol.ts (VmStartData.tools).

type WorkerToHostMessage

type WorkerToHostMessage struct {
	Type string
	// call: a nested tool call (Target "tool") or a global (Target "global"); Args is nil for undefined.
	ID     int
	Target string
	Name   string
	Args   *string
	// output
	Item *OutputItem
	// done: a script that returned (Ok, with Value and Writes) or threw (Error, a JSON `{ name?, message, stack? }`).
	Ok     bool
	Value  *string
	Writes *string
	Error  *string
	// During, with done in a deterministic run: the result the VM was processing when the script finished and the calls it
	// had issued by then.
	During *During
	// crash: the VM failed outside the script's control, for example a wasm trap.
	Message string
	// started: what the VM is, so a replay can refuse a different one.
	Fingerprint string
	// idle: having processed result Seq (0: the script's first run), the VM has issued Issued calls in total.
	Seq    int
	Issued int
}

WorkerToHostMessage is one message from a VM to the host. Type selects the fields that apply, as the discriminant of upstream's union does. Tool arguments, results and values cross as JSON strings: the VM passes them into and out of QuickJS as strings and never builds structured values itself. A message the host does not recognise (any other Type, or a field a type requires but lacks) is carried unchanged, and the host fails the execution as a broken bridge.

Ports packages/codemode/src/runtime/protocol.ts (WorkerToHostMessage).

func (WorkerToHostMessage) MarshalJSON

func (m WorkerToHostMessage) MarshalJSON() ([]byte, error)

MarshalJSON writes the fields that apply to Type, in upstream's shape.

func (*WorkerToHostMessage) UnmarshalJSON

func (m *WorkerToHostMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON reads every field that is present; Type selects which ones matter.

Directories

Path Synopsis
Package cloudflare is the Cloudflare entry of codemode: the remote end of a remote sandbox as a Durable Object, and the inline sandbox with the QuickJS module the host bundled.
Package cloudflare is the Cloudflare entry of codemode: the remote end of a remote sandbox as a Durable Object, and the inline sandbox with the QuickJS module the host bundled.
cmd/codemodewasm command
Command codemodewasm is the codemode module of the Cloudflare Worker host: package codemode built with TinyGo as a WASI reactor (see durable/core/host/cf/tools/build-codemode-wasm.sh).
Command codemodewasm is the codemode module of the Cloudflare Worker host: package codemode built with TinyGo as a WASI reactor (see durable/core/host/cf/tools/build-codemode-wasm.sh).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL