scriptlayer

package
v1.148.0 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Overview

Package scriptlayer is the MCP surface of the managed-script feature: the manage_script tool and everything it needs to resolve, authorize, edit, validate, and dry-run a script.

It owns the assembly (the Postgres-backed script store) and the tool, and it depends on pkg/script for the domain rules and internal/platform/scriptrun for the engine. Nothing here decides what Starlark means and nothing here re-implements the edit gate; both live one layer down, so the tool is a translation from MCP arguments into domain calls.

The MCP server is captured at RegisterTool rather than at construction: the store must exist early, while the server exists only once the platform has assembled it, and run_draft needs that server to open its in-memory session.

Index

Constants

View Source
const (
	// DefaultWaitSeconds is how long run_script waits for a run to finish when
	// the caller names no window.
	DefaultWaitSeconds = 120

	// MaxWaitSeconds caps the wait, the same cap the portal's run route
	// applies (runcontrol.MaxWaitSeconds). Past it the tool answers with the
	// run id and a pending status rather than holding a request open for the
	// length of a run.
	MaxWaitSeconds = runcontrol.MaxWaitSeconds
)

Waiting policy for run_script.

View Source
const DialectContract = scriptcontract.Dialect

DialectContract is the dialect contract (internal/platform/scriptcontract).

View Source
const RunTaskPollInterval = 2 * time.Second

RunTaskPollInterval is how often a client following a run as a task is asked to read it again: often enough that a short run reads as finished soon after it does, and no more often than the worker reports (#2009).

View Source
const ToolNameManageScript = "manage_script"

ToolNameManageScript is the MCP tool name of the script-management tool, exported for composition roots that bind UI apps to it.

View Source
const ToolNameRunScript = "run_script"

ToolNameRunScript is the MCP tool name of the platform-execution tool, exported for composition roots that bind UI apps to it.

View Source
const ToolNameShowScripts = scriptshow.ToolName

ToolNameShowScripts is show_scripts (internal/platform/scriptshow), which RegisterTool registers beside manage_script.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// DB backs the script store; nil leaves the store nil and manage_script
	// unregistered (there is nowhere to keep a script).
	DB *sql.DB
	// Store, when non-nil, is used directly instead of building a Postgres
	// store from DB. Production passes DB and leaves this nil.
	Store script.Store
	// Runs is the run queue run_script enqueues onto and the run history the
	// run commands read. nil leaves run_script unregistered, which is the
	// correct shape for a deployment that cannot execute scripts at all.
	Runs script.RunStore
	// AdminPersona is the persona name that grants authority over every
	// script; matched against the caller's persona in each command.
	AdminPersona string
	// PortalURL is the deployment's public portal address, used by show_scripts
	// to name where the script pages are. Empty leaves the tool registered and
	// linkless: a deployment that has not been told its own address cannot be
	// given one by guessing.
	PortalURL string
	// Destinations is the deployment's configured bucket destinations, which a
	// draft run resolves platform.export names against exactly as a platform
	// run does.
	Destinations []script.Destination
	// Toolkits is the live toolkit registry a draft's write barrier reads the
	// api gateway's operation ids and an MCP gateway's proxied-tool
	// declarations through (#1664). Nil leaves the barrier classifying from
	// its declared table alone, which refuses both of those forms.
	Toolkits scriptdraft.ToolkitLister
	// DraftExports builds the writer a draft run with allow_writes persists
	// its exports through (#1822). Nil leaves every draft export a preview.
	DraftExports scriptdraft.Exports
	// RunLimits are the ceilings a platform run executes under on this
	// deployment, which the help reports so an author sizes a script against
	// the limits it will actually meet (#1843). Zero fields are the defaults.
	RunLimits scriptrun.PlatformLimits
	// Recordings keeps what each run and draft's host calls were answered, for
	// a script's tests and a save's replay (#1939, #1942). Nil builds one over
	// DB.
	Recordings scriptrec.Store
	// Sources reads the managed-resource text a save names by source_ref and
	// a script loads with load("res:...") (#2113, #2114). Nil refuses both.
	Sources *scriptsrc.Reader
	// Pending keeps a refused create to patch (#2114). Nil builds one over DB.
	Pending scriptpending.Store
	// DraftLimit is scripts.draft (#2117): how long an administrator's draft
	// may run, a long one kept in the background over DB.
	DraftLimit scriptbgdraft.Config
	// Endpoints is the assembled endpoint feature (#2170): its commands carry
	// manage_script's endpoint commands out and name a script's endpoint to
	// the save gate, and the rest is what Endpoints hands the HTTP surface.
	// Nil answers the commands as unavailable.
	Endpoints *epwire.Endpoints
}

Config carries the resolved values the owner needs to assemble the script layer. The caller translates its own config into this shape so this package stays free of the platform's config types.

type Handle

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

Handle owns the assembled script layer. All accessors are nil-safe, so a deployment without a database holds a Handle that registers nothing.

func New

func New(cfg Config) *Handle

New assembles the script layer.

func (*Handle) DraftExports added in v1.134.0

func (h *Handle) DraftExports() scriptdraft.Exports

DraftExports is the writer a draft allowed to write persists its exports through, for the other surface that runs drafts (the portal editor) to run them the way manage_script does (#1822). Nil on a nil Handle.

func (*Handle) Endpoints added in v1.148.0

func (h *Handle) Endpoints() *epwire.Endpoints

Endpoints is the assembled endpoint feature, nil on a nil Handle or a deployment with no database.

func (*Handle) HasStore added in v1.129.0

func (h *Handle) HasStore() bool

HasStore reports whether the layer has a script store, which is the condition under which it registers manage_script, run_script and show_scripts. Callers enumerating the platform's own tools ask this rather than assuming the tools exist, so a no-database deployment is not credited with them.

func (*Handle) IndexProducer added in v1.122.0

func (h *Handle) IndexProducer() *indexjobs.Producer

IndexProducer returns the write-path index-job producer behind the managed- script store, or nil on a deployment with no database. The composition root hands it to the index queue, which binds it once the scripts consumer is registered; until then, and forever where no worker runs, NotifyWrite is a no-op and the reconciler is the only route to the index.

func (*Handle) RegisterTool

func (h *Handle) RegisterTool(server *mcp.Server)

RegisterTool registers manage_script; where the deployment can execute saved scripts, run_script; and the presentation-only show_scripts. It also captures the server the two run paths open their in-memory sessions against. No-op on a nil Handle or a no-database deployment (there is nowhere to keep a script).

func (*Handle) RunTasks added in v1.143.0

func (h *Handle) RunTasks(ttl time.Duration) *RunTasks

RunTasks returns the task Source over this layer's runs, or nil when the deployment keeps no runs. ttl is how long a finished run is kept.

type RunTasks added in v1.143.0

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

RunTasks is a managed-script run as an MCP task (#2009). The task is the run: its id is the run id, its status is read from the run's row, and canceling it is cancel_run. Nothing is stored beside the run, so a task lives exactly as long as its run is kept (scripts.run_retention_days) and is answered by any replica.

func (*RunTasks) Cancel added in v1.143.0

func (t *RunTasks) Cancel(ctx context.Context, id string) error

Cancel asks the run to stop, as cancel_run does.

func (*RunTasks) Get added in v1.143.0

func (t *RunTasks) Get(ctx context.Context, id string) (*mcptask.Snapshot, error)

Get reports a run as a task, under the run reading rule: the script's owner, an administrator, and whoever requested the run.

func (*RunTasks) Prefix added in v1.143.0

func (*RunTasks) Prefix() string

Prefix is the run id prefix.

Jump to

Keyboard shortcuts

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