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: 26 Imported by: 0

Documentation

Overview

Package codemode is durable code mode: a tool that runs model-written JavaScript in a QuickJS sandbox, whose script survives a restart.

A script is in-memory VM state. A restart while

const results = await Promise.all(paths.map((path) => tools.read({ path })));

waits for the last of 200 reads would lose the script and every read it made.

The solution is deterministic replay (Sandbox.Start in package codemode). The VM only runs when the host hands it a result; given the same start data, clock, seed, and results in the same order, it makes the same calls with the same arguments. The tool is replay-safe: after a restart, Execute runs again, starts the script again from the stored start data, and hands it the results it got before, in the order it got them, from a journal written before each delivery. Nested tool calls reattach to their tasks by key (`c<VM call id>`), so they never run twice unless their own replay policy reruns them; their results come from NestedCallDoc. Then the script continues live.

Documents, scoped to the code mode call's task and gone when it settles:

  • RunDoc: the start data, written once before the VM starts, and the outcome, written once when the call decides it (with the store writes, in one transaction), so a rerun after that returns it without a VM.
  • JournalDoc: one entry per delivered result, in delivery order: the VM call ID, the clock value, the calls the VM had issued after processing it (once acknowledged), and a global's outcome, which nothing else stores.

Each result's acknowledged call count is recorded with the next journal commit, or at once when the VM has processed everything delivered: a script waiting on a long call is where a restart usually finds it. A sequential script therefore costs one journal commit and one count commit per result, on top of its nested calls' own; that is the price of checking the most common crash point.

A call is launched only once the count of calls issued in the drain that made it is committed. So every key an earlier attempt admitted is at most its last recorded count; a replay checks every recorded count, so when it releases its calls it has made every call an earlier attempt could have admitted, and later calls are new.

A rerun refuses to replay (no new nested calls; nested calls admitted earlier may still resume on their own and are aborted by the call's cleanup) when this package's version or the VM's fingerprint changed, when the deadline passed, or when the script diverges: it makes another call, or calls in another order, than the journal says. Each ends the call with an error result.

Index

Constants

View Source
const (
	ClassifyTool       = InternalPrefix + "models.classify"
	GenerateImagesTool = InternalPrefix + "models.generateImages"
)

The names of the internal tools behind models.classify() and models.generateImages().

View Source
const DefaultInlineBudget = 3000

DefaultInlineBudget is the default token budget of the tool declarations in the `codemode` section, as in the coding agent.

View Source
const DefaultMaxOutputTokens = 10_000

DefaultMaxOutputTokens is the default token budget for script output.

View Source
const InternalPrefix = "pi.codemode."

InternalPrefix is the prefix of code mode's internal tools; they are never listed to scripts or the model.

View Source
const ModuleVersion = 2

ModuleVersion is the version of everything in this package that turns stored results into what a script sees: result mapping, globals, start data. Bump it when that changes, so a call started before an upgrade is not replayed by different code.

View Source
const ToolName = "codemode"

ToolName is the name of the code mode tool.

Variables

View Source
var JournalDoc = durable.DefineDoc(durable.DocDefinition[journalState]{

	CommonDocDefinition: durable.CommonDocDefinition[journalState]{Kind: "pi.codemode.journal", Version: 1, Initial: func() journalState { return journalState{Entries: []journalEntry{}} }, CheckpointWhen: func(journalState, []durable.Op, durable.CheckpointInfo) bool { return false }},
	DocumentSemantics:   durable.DocumentSemantics{Scope: durable.ScopeTask},
})

JournalDoc is the pi.codemode.journal document of a code mode call's task: one entry per delivered result, in delivery order: the VM call ID, the clock value, the calls the VM had issued after processing it (once acknowledged), and a global's outcome.

View Source
var ModelsDescription = strings.Join([]string{
	"`models` (all functions return promises):",
	"- `models.getModelsOfType(type, provider?)`, `models.getAvailableOfType(type, provider?)` (configured auth only), `models.getModelOfType(type, provider, id)`: the catalog; `type` is \"chat\", \"image\", or \"classifier\".",
	"- `models.classify(model, { state: { ... }, images?: [{ type: \"image\", data, mimeType }], questions: { <id>: { type: \"choice\", instructions, criteria: { <label>: <meaning> } } | { type: \"score\", instructions, criteria: [<lowest level>, ..., <highest level>] } | { type: \"bool\", instructions, criteria: { true: <meaning>, false: <meaning> } } } })` resolves to `{ answers: { <id>: ... }, stopReason, errorMessage?, usage? }`.",
	"- `models.generateImages(model, { input: [{ type: \"text\", text: <prompt> }, ...optional { type: \"image\", data, mimeType }] })` resolves to `{ output: [image blocks], stopReason, errorMessage?, usage? }`; show each image with `image(block)`.",
	fmt.Sprintf("At most %d classify/generateImages calls run at once; more wait.", maxConcurrentModelCalls),
}, "\n")

ModelsDescription is what the code mode tool's description says of `models`.

View Source
var RunDoc = durable.DefineDoc(durable.DocDefinition[runState]{

	CommonDocDefinition: durable.CommonDocDefinition[runState]{Kind: "pi.codemode.run", Version: 1, Initial: func() runState { return runState{} }, CheckpointWhen: func(runState, []durable.Op, durable.CheckpointInfo) bool { return false }},
	DocumentSemantics:   durable.DocumentSemantics{Scope: durable.ScopeTask},
})

RunDoc is the pi.codemode.run document of a code mode call's task: the start data, written once before the VM starts, and the outcome, written once when the call decides it (with the store writes, in one transaction), so a rerun after that returns it without a VM.

View Source
var StoreDoc = durable.DefineDoc(durable.DocDefinition[StoreState]{
	CommonDocDefinition: durable.CommonDocDefinition[StoreState]{Kind: "pi.codemode.store", Version: 1, Initial: func() StoreState { return StoreState{Values: map[string]json.RawMessage{}} }, CheckpointWhen: func(_ StoreState, _ []durable.Op, info durable.CheckpointInfo) bool {
		return info.DeltasSinceBase >= 64
	}},
	DocumentSemantics: durable.NewRewindableConversationSemantics(durable.ForkAsOf).DocumentSemantics,
})

StoreDoc is the pi.codemode.store document of a conversation: rewindable and copied as of the fork point, so a fork sees the values as they were when its entry was committed.

Functions

func CreateExtension

func CreateExtension(options ToolOptions) *durable.Extension

CreateExtension creates the `codemode` extension: the code mode tool, and the `codemode` prompt section listing the tools scripts can call.

func CreateTool

func CreateTool(options ToolOptions) *durable.ToolRegistration

CreateTool creates the code mode tool. Scripts call the conversation's callable tools as `tools.<name>(args)`.

func Description

func Description(models bool) string

Description is the code mode tool's description: the script environment and its globals, the same for every conversation.

func Section

func Section(tools []*durable.ToolRegistration, namespaces []Namespace, budget int) (*string, error)

Section is the `codemode` section: the tools scripts can call, grouped by namespace, with their declarations as far as the budget allows. Nil without callable tools.

Types

type Global

type Global struct {
	Name   string
	Spread bool
	// Execute runs the call. args is what the script passed (nil: undefined); the result is JSON, nil for undefined.
	Execute func(ctx context.Context, args json.RawMessage, api durable.ToolExecutionApi) (json.RawMessage, error)
}

Global is a function scripts call as a top-level global; its result is journaled.

type Namespace

type Namespace struct {
	Name         string
	Description  string
	Instructions string
	// Prefix: tool names starting with it belong to the namespace; the longest matching prefix wins.
	Prefix string
}

Namespace is a group of tools named by a common prefix, such as an MCP server's `mcp__github__`.

type NestedCall

type NestedCall struct {
	// ID is the VM's number for the call; its nested call ID is `<callId>/c<id>`.
	ID   int    `json:"id"`
	Name string `json:"name"`
	// Args is compact JSON of the arguments, cut for display.
	Args string `json:"args"`
	// Status is running, ok, error or cancelled.
	Status     string `json:"status"`
	DurationMs *int64 `json:"durationMs,omitempty"`
	// Error is the error text, cut for display.
	Error string `json:"error,omitempty"`
}

NestedCall is one tool call a script made, as the code mode call's details show it.

type Sandbox

type Sandbox interface {
	Start(ctx context.Context, code string, options cm.RunOptions) (*cm.Run, error)
}

Sandbox runs the scripts: a *codemode.Sandbox, or anything that starts deterministic runs as it does.

type StoreState

type StoreState struct {
	Values map[string]json.RawMessage `json:"values"`
}

StoreState is what scripts keep with `store()` and read with `load()`.

type ToolDetails

type ToolDetails struct {
	Calls []NestedCall `json:"calls"`
	// FullOutputPath is the temp file with the complete text output, when the output was cut to its token budget.
	FullOutputPath string `json:"fullOutputPath,omitempty"`
}

ToolDetails are the code mode call's details, in its result: its tool calls in the order it made them, with their status. Calls to globals are not listed. While the script runs, UIs show its nested calls from `pi.live.nestedTools`, so the list is written once, with the result.

type ToolInput

type ToolInput struct {
	Code string `json:"code"`
}

ToolInput is the input of the code mode tool.

type ToolOptions

type ToolOptions struct {
	// Sandbox runs the scripts.
	Sandbox Sandbox
	// Namespaces are groups of tools by name prefix, such as MCP servers, for the `codemode` section and tool search.
	Namespaces []Namespace
	// InlineBudget is the estimated tokens the tool declarations in the `codemode` section may use. Nil: 3000.
	InlineBudget *int
	// Models gives scripts `models.*`: the model catalog, classifiers, and image generation. Nil: true.
	Models *bool
	// Globals are host functions scripts call as globals.
	Globals []Global
}

ToolOptions are the options of the code mode tool.

Jump to

Keyboard shortcuts

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