jsrun

type Bundle struct {
	// Manifest is everything true before the run: identity, cost shape, the
	// whitelist tool() filters through, the guards checked on the way in, and
	// the output shape a finished run has to produce.
	Manifest exec.Manifest

	// Program is the source of program.js, whole. It is compiled once by [New],
	// so a bundle that will not compile is refused at load rather than at run —
	// which is what makes a syntax error an AUTHORING error with a line number
	// rather than a run that mysteriously fell back.
	Program string

	// Source is the name errors are reported against. Empty is "program.js",
	// which is what the file is actually called; a store that keeps several
	// files in one bundle names the one it handed over.
	Source string

	// Prompts is the prompt assets by name, the map ai()'s first argument
	// selects from. The key is the bare name — `summarise` for
	// `prompts/summarise.md` — and [Runner] normalizes a `prompts/` prefix and a
	// `.md` suffix on the way in, so a program that names the file the way an
	// author thinks of it still resolves.
	//
	// A NAME THAT IS NOT IN HERE IS REFUSED, which is the whole enforcement of
	// the no-inline-prompts law (PRD §5, §12): prompts are files so they can be
	// diffed, reviewed and revised, and a program that could pass its prompt as a
	// string would put the one thing worth improving somewhere nothing can
	// improve it.
	Prompts map[string]string

	// Memory is this subharness's OWN memory — its memory.md in its own bundle,
	// not the session's. Nil is a bundle whose memory the store has not opened,
	// and then remember() and recall() fall through to the [exec.Env]'s own
	// doors, which is the honest fallback rather than a silent no-op.
	Memory Memory

	// Look is the free way a guard checks the world before a run: does this file
	// exist, is this tool on the belt. It is a door rather than a filesystem
	// because this package has none — goja has no filesystem unless the host
	// hands one in, and a runtime that quietly grew one for its own guards would
	// have handed itself the thing it refuses the program.
	//
	// NIL MEANS THE WORLD CANNOT BE LOOKED AT, and a file or tool guard that
	// cannot be checked DOES NOT PASS. The safe answer to "I could not tell" is
	// the long way, not the fast path.
	Look Look

	// Fuel is what this run may spend before it stops. The zero value takes the
	// manifest's own cost shape and this package's defaults; see [Fuel].
	Fuel Fuel
}

type Fuel struct {
	// Steps is how many host calls the program may make. Zero takes
	// [DefaultSteps].
	Steps int

	// Tokens is the ceiling on what the run's own ledger reports — input plus
	// output, summed across every ai() and every tool() as the journal records
	// them. Zero is NO token ceiling, which is the honest zero value: a caller
	// that has not been given a grant must not have one invented for it.
	Tokens int

	// Wall is the deadline. Zero takes the manifest's own cost shape —
	// [exec.SubharnessInfo.Deadline] of [Fuel.Tokens] — which is the one
	// spelling of a budget the whole wave uses and the reason there is no second
	// deadline constant in this package.
	Wall time.Duration
}

type Look interface {
	// FileExists says whether the path a [exec.GuardFile] names is there.
	FileExists(path string) bool
	// ToolOnBelt says whether the tool a [exec.GuardTool] names is actually
	// available to this session. It is a different question from the whitelist:
	// the whitelist is a ceiling the manifest declares, and the belt is what the
	// session really has.
	ToolOnBelt(name string) bool
}

type Memory interface {
	Remember(ctx context.Context, note string) error
	Recall(ctx context.Context, query string) ([]exec.Note, error)
}

type Prompted interface {
	UsePrompts(prompts map[string]string)
}

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