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
- Variables
- func CallInitiated(ctx context.Context)
- func LoadQuickJSWasm(path string) ([]byte, error)
- func OrderStoreKeys(set map[string]json.RawMessage, written []string) []string
- func QuickJSWasm() []byte
- func RenderDeclarations(options RenderDeclarationsOptions) (string, error)
- func RenderToolOutputType(raw json.RawMessage) (string, error)
- func RenderToolSample(tool Tool, options ToolRenderOptions) (string, error)
- func RenderToolSignature(tool Tool, options ToolRenderOptions) (string, error)
- func SchemaToType(schema json.RawMessage, options SchemaToTypeOptions) (string, error)
- func ServeRemote(ctx context.Context, request RemoteRequest, exchange RemoteExchange, ...)
- func ToCodemodeIdentifier(name string) string
- type Call
- type CallStatus
- type CodemodeJsonSchema
- type DeclaredGlobal
- type DeclaredTool
- type During
- type Error
- type ErrorKind
- type ExecuteOptions
- type HostCall
- type HostToWorkerMessage
- type InlineSandbox
- type InlineSandboxOptions
- type Outcome
- type OutputItem
- type OutputItemType
- type ParsedSource
- type Remote
- type RemoteExchange
- type RemoteMessage
- type RemoteReply
- type RemoteRequest
- type RemoteSandbox
- type RemoteSandboxOptions
- type RenderDeclarationsOptions
- type Result
- type Run
- type RunOptions
- type Sandbox
- func (s *Sandbox) Close() error
- func (s *Sandbox) Execute(ctx context.Context, code string, options ExecuteOptions) (Result, error)
- func (s *Sandbox) Globals() []Tool
- func (s *Sandbox) RegisterTool(tool Tool) error
- func (s *Sandbox) Start(ctx context.Context, code string, options RunOptions) (*Run, error)
- func (s *Sandbox) Tools() []Tool
- func (s *Sandbox) UnregisterTool(name string) bool
- type SandboxOptions
- type SchemaToTypeOptions
- type ServeOptions
- type SourceError
- type SourceOptions
- type StoreWrites
- type Tool
- type ToolRenderOptions
- type URIError
- type VmDeterministic
- type VmStartData
- type VmStartGlobal
- type VmStartTool
- type WorkerToHostMessage
Constants ¶
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).
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).
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.
const CodemodeOptionsPrefix = "// @options:"
CodemodeOptionsPrefix starts the optional first line of a script.
Ports packages/codemode/src/source.ts (CODEMODE_OPTIONS_PREFIX).
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).
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).
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).
const EmbeddedQuickJSWasmPath = "assets/quickjs.wasm"
EmbeddedQuickJSWasmPath names the one QuickJS module the package has: the embedded asset.
Variables ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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).
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 ¶
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 ¶
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) RegisterTool ¶
RegisterTool fails if a tool with the same name is already registered.
func (*Sandbox) Start ¶
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) UnregisterTool ¶
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
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).
type VmDeterministic ¶
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 ¶
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.
Source Files
¶
- assets.go
- assets_quickjs.go
- declarations.go
- deterministic.go
- doc.go
- engine.go
- engine_exports.go
- engine_wazero.go
- execution.go
- halt_grace.go
- haltcheck.go
- identifier.go
- inline.go
- inline_consts.go
- inlinechannel.go
- jsvalue.go
- remote.go
- remote_protocol.go
- remote_serve.go
- remote_serve_blocking.go
- remote_types.go
- run.go
- sandbox.go
- serve_encode.go
- serve_reply.go
- source.go
- types.go
- vmdriver.go
- vmlauncher.go
- wasm.go
- workerlauncher.go
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). |