This page describes what each submilli: module does, the capabilities
that gate it, and the rules its functions share, followed by every module’s
functions and types. The globals that need no import, such as Map, JSON,
and Temporal, are on Built-ins.
Modules
Section titled “Modules”| Module | What it does | Gated by |
|---|---|---|
submilli:fs |
The program’s filesystem: read, write, list, stat, move, copy, remove | fs.* |
submilli:http |
HTTP requests, and downloads into the filesystem | http.<verb>, http.request, http.download |
submilli:llm |
Model calls: text, texts, call, batch, models |
llm.call; fs.read for files |
submilli:embedding |
Text embeddings: embed, models |
embedding.embed |
submilli:session |
Key-value state that lasts for the session | session.* |
submilli:git |
Repositories in the filesystem: history, commits, branches, clone, fetch, pull | git.open, git.read, git.write, git.init, git.clone, git.fetch, git.commit |
submilli:code |
Numbered reads, search, glob, tree, anchored edits, and diffs over the program’s files | fs.read, fs.list, fs.stat, fs.write |
submilli:crypto |
SHA-256, SHA-512, HMAC-SHA-256, random bytes | Nothing |
submilli:url |
URL and query-string parsing and building | Nothing |
submilli:uuid |
UUID v4 and v7 | Nothing |
submilli:variables |
Immutable session configuration, for Packages | variables.get |
submilli:secrets |
A declared secret’s value, for Packages | secrets.get |
submilli:cost |
report, for Packages: what a call to a paid service cost |
cost.report |
submilli:security |
check, for Packages |
The capability it names |
submilli:test |
label and expectException, for test files |
Nothing |
submilli:git is available under a Blueprint with a git block. Each
capability’s fields are on Permissions.
A module is imported by its name, as a namespace, a default, or by name:
import * as http from "submilli:http";import fs from "submilli:fs";import { sha256 } from "submilli:crypto";submilli search and submilli docs list the modules a program may import.
With --blueprint, they list only those the Blueprint lets it use.
Rules for every module
Section titled “Rules for every module”- Calls are synchronous. Every function returns its result directly.
llm.textsandllm.batchsend their prompts concurrently and return when all are done. - Paths are the program’s own.
submilli:fs,submilli:code,submilli:git, andhttp.downloadtake paths in the program’s filesystem, never the host’s. A relative path resolves against the working directory,fs.cwd(). - A denied call throws a catchable
PermissionDeniedError. A filesystem or token budget a call would pass throwsQuotaExceededError(Errors and limits).
HTTP requests
Section titled “HTTP requests”- HTTPS, unless the Blueprint sets
allow_insecure_http: true. - Redirects, up to 10, are each checked against the caller’s rules before they are sent. A redirect to another origin drops the credential headers.
- A request times out after 30 seconds and a download after 60. A
response body may be up to 50 MB, and a download up to its
maxBytes. - On a server, hosts that resolve to private addresses are refused unless the server allows them (Server settings).
Workspace tools
Section titled “Workspace tools”submilli:code works through the filesystem capabilities:
| Functions | Capabilities checked |
|---|---|
read, diffFiles |
fs.read on each file |
search, glob, tree |
fs.list, fs.stat, and fs.read for files searched and for ignore files |
edit, insertAt, applyPatch |
fs.read, then fs.write with path, length (the new size) and diff (the change as a unified diff) |
diffText |
None |
Traversal honors .gitignore and .ignore files and skips hidden entries.
An edit that fails writes nothing. One that succeeds replaces the file
atomically and returns the change as a unified diff.
Git repositories
Section titled “Git repositories”submilli:git works on Git repositories in the program’s filesystem. The
Blueprint’s git block sets the identity that authors every commit and the
username that pairs with the GIT_TOKEN secret for private remotes
(Allow Git). Repository.init,
Repository.clone, and Repository.open return a Repository:
| Method | Capability | Behavior |
|---|---|---|
Repository.init |
git.init |
Creates the directory and refuses an existing repository. Does not require git.open |
Repository.clone |
git.clone |
Needs no git.init, git.open, git.fetch or fs.* rule |
Repository.open, constructor |
git.open |
Opens path’s .git directory. A denial is the same whether the repository exists. Checked again for the current caller on every later call |
status, log, diff, show, ls, branches, remotes |
git.read |
Read only. ls lists one directory at a commit; log can start at a ref and keep only commits that changed one file |
add |
git.write |
At most 10,000 paths per call, . selects the working tree, and deletions are staged |
commit |
git.commit (branch is the current branch) |
Refuses an empty message and an empty commit. Does not require git.write |
createBranch, switchBranch |
git.write |
createBranch never overwrites an existing branch. switchBranch requires a clean working tree, untracked files included |
addRemote, setRemoteUrl |
git.write |
HTTPS URLs only |
fetch |
git.fetch |
Defaults to origin. With no branch, fetches every remote branch and checks each. Does not require git.write |
pull |
git.fetch |
Fetches and fast-forwards the current branch. Refuses divergence and a dirty working tree |
A revision is HEAD, a branch or tag name, a full ref, or a full commit ID.
Remotes are https:// URLs. Repositories created by standard Git work as
they are. Advanced layouts, such as linked worktrees, submodules, partial
clones, and SHA-256 object format, aren’t supported.
| Limit | Value |
|---|---|
| Time per operation | 60 seconds |
| Directory nesting | 64 levels |
log page |
Up to 1,000 commits, 50 by default |
| Memory | Counts against max_execution_memory |
| Files | Count against the filesystem’s size_limit |
An operation that passes a limit throws and leaves the repository as it was.
Model calls
Section titled “Model calls”submilli:llm sends prompts to the models the Blueprint declares
(Allow model calls):
| Form | Returns |
|---|---|
text(model, prompt, files?) |
A Completion<string>: value is the text |
texts(model, prompts) |
A Completion<string>[], result[i] for prompts[i] |
call<T>(model, prompt, files?) |
A Completion<T>: value is a T, checked field by field against the response |
batch<T>(model, prompts) |
A Completion<T>[], each response checked on its own |
models() |
The Models this caller may call |
- A
Completion<T>is{ ok: true, value: T }or{ ok: false, reason, message }, so a program checksokbefore it readsvalue. A truncated text completion isok: falsewithreason: "truncated"and still carries its partialtext. - The text forms send no schema: a program that wants structured output
calls a typed form. The typed forms need
T, written or supplied by the expected type: they send a JSON Schema forTand check the response against it. A response that is not JSON or doesn’t match isok: falsewithreason: "invalid-output"; its siblings in a batch are unaffected. fileslists paths in the program’s filesystem to send with the prompt: PDFs, images (PNG, JPEG, GIF, WebP) and UTF-8 text, told apart by their leading bytes. Intextsandbatcheach prompt is a string or aPrompt,{ prompt, files? }, so each prompt sends its own files:texts(model, pdfs.map((path) => ({ prompt: "Summarize.", files: [path] }))). Each file is gated and read asfs.readreads it, once however many prompts send it, and one prompt sends at most 14.25 MB of files, which still fits Amazon Bedrock’s 20 MB request limit once base64-encoded. Any other or empty file throws aTypeError.- A batch takes up to 128 prompts, each up to 256 KB. A call’s tokens are reserved against the run’s and the server’s budgets before it is sent.
Embeddings
Section titled “Embeddings”submilli:embedding turns texts into vectors through the aliases the
Blueprint declares (Blueprint file):
| Form | Returns |
|---|---|
embed(model, texts, purpose) |
One Embeddings: vector(i) is the vector of texts[i] |
models() |
The EmbeddingModels this caller may use |
purposeis"query"for text you search with and"document"for text you search over. A provider or model with no notion of purpose ignores it: OpenAI always, and Hugging Face unless the alias setsquery_prompt_nameordocument_prompt_name. Elsewhere it is sent as Voyageinput_type; Jinatask(retrieval.query,retrieval.passage); GoogletaskType, or forgemini-embedding-2a text prefix the model reads.- A call returns every vector or throws; nothing is truncated, and there are
no per-text outcomes. An empty
texts, more than 128 texts, more than 2 MiB of text, or a text longer than the alias’smaxInputBytesthrows aRangeErrorbefore anything is sent. - Every vector has unit length.
vector(i)returns anumber[]andbytes(i)returnsdimensions * 4bytes of little-endian 32-bit floats; anithat isn’t an integer belowcountthrows aRangeError. - The vectors live in the runtime at 4 bytes per number and count against
max_execution_memoryuntil the program drops the result. identityis opaque: compare the whole string, and don’t mix vectors whose identities differ. It covers the Blueprint’s configuration of the alias and can’t see a vendor changing a model behind an unchanged name (a risk for OpenAI and shared Hugging Face hosting), or a model redeployed at the same dedicated Hugging Face endpoint unless the alias’smodelchanges. A"query"and a"document"result from one alias share an identity. A differentbase_urldoesn’t change it, except a dedicated Hugging Face endpoint’s host.- Failures:
QuotaExceededErrorfor a budget or the request limit,TypeErrorfor an unusable provider response, and anErrorwith a reason ofrate-limited,request-rejected,provider-unavailable,transport,timeout, orblocked-by-network-policyfor other provider failures. No error quotes a text or a vector.
Modules for Packages and tests
Section titled “Modules for Packages and tests”secrets.get(name) returns a declared secret’s value to a Package. From the
program itself, main, it always throws, so a secret’s value never reaches
generated code.
check(capability, context) from submilli:security asks the Blueprint
whether the Package’s caller may perform capability with the fields in
context, and throws PermissionDeniedError if not
(Export a function).
label(description) from submilli:test starts a named test, and
expectException(fn, errorType?) checks that fn throws
(Write tests).
Package configuration
Section titled “Package configuration”submilli:variables.get(name: string): string | undefined reads the session’s
resolved configuration under the variables.get { name } capability.
Every read checks the Package’s permission before looking up a value. An
allowed missing name returns undefined; a denied name throws
PermissionDeniedError whether it exists or not. Main-module reads are always
denied, even under default: allow. There is no enumeration or write API.
A browser Package can use this fragment internally:
import * as variables from "submilli:variables";
const storeName = variables.get("BROWSER_STORE_NAME");if (storeName === undefined) { throw new Error("BROWSER_STORE_NAME is not configured");}Grant the Package variables.get with name == "BROWSER_STORE_NAME".
Variable declarations can alias this
name to the session’s USER_ID. The grant is checked against
BROWSER_STORE_NAME; it does not grant access to USER_ID. A configured store
name grants no access to that store: the browser service must authenticate the
caller and authorize the resource independently.
Variables hold non-secret configuration and remain fixed for the session.
Use secrets for credentials and submilli:session for mutable key-value state.
Package cost
Section titled “Package cost”submilli:cost.report(entry) adds what one of the Package’s own calls cost to
the run cost, under the cost.report
capability. entry.usd is the amount in US dollars, entry.usage the counts
behind it keyed by unit, and entry.label what was called, such as a model id.
Give usd, usage, or both; a report without usd is listed unpriced.
import { report } from "submilli:cost";
report({ usd: inputTokens * 0.042 / 1000000, usage: { input_tokens: inputTokens }, label: model });The run cost names the reporting Package itself, so a Package cannot report
under another name. Reports from main are always refused, even under
default: allow. A report is not recorded for replay: a resumed durable run
reports again as it re-runs.
Durable package finalizers
Section titled “Durable package finalizers”Packages can register cleanup for remote resources owned by a runtime session:
import * as session from "submilli:session";import * as http from "submilli:http";
export interface ResourceHandle { id: string; url: string; }
export function retain(handle: ResourceHandle): void { session.registerFinalizer(handle.id, handle);}
export function finalizer(key: string, value: ResourceHandle): void { const response = http.delete(value.url); if (response.status !== 204 && response.status !== 404) { throw new Error("Resource cleanup failed"); }}The package root exports one fixed, nongeneric
finalizer(key: string, value: T): void. Registration arguments must match
T and satisfy the same serialization rules as session KV values. Cleanup
checks the stored value against T as value as T does, so T must be a type
as accepts.
| Function | Behavior |
|---|---|
registerFinalizer(key: string, value: unknown): void |
Durably register this package’s cleanup arguments and package versions. |
unregisterFinalizer(key: string): void |
Remove this package’s registration after explicit remote release; absent keys are harmless. |
Both operations require the package-only session.finalize { key } capability.
The engine namespaces keys by session and package identity. Packages supply only
the local key; the finalizer receives that original key. Identical keys in
different packages do not conflict. Duplicate live keys within one package/session
are rejected, including across package versions.
Recorded test runs, including their live-call modes, refuse registration with a catchable error because replay cannot durably own resources. Package code must compensate for that refusal through its normal immediate-cleanup path. Replay unregistration validates the local key and treats it as absent.
A successful registration survives separate executions and server restart. Explicit close, idle expiry, and administrative termination wait for cleanup attempts. Registration concurrent with termination either commits before closure or fails; closure stops new resource work and drains existing executions before finalization. Each attempt has independent fuel/memory limits and a finite timeout (the configured execution timeout, or 30 seconds when normal runs have none).
Throws, traps, denied permissions, and exhausted budgets record terminal failure without automatic retry. Other registrations still run. Recovery attempts pending or interrupted work, so a crash after a remote effect but before its outcome commits can repeat that effect. Finalizers must be idempotent.
Cleanup uses current blueprint permissions and credentials and loads code from the installed package store. Registration records the package and dependency versions, without retaining their code. If a version changes or a package is unavailable, cleanup fails terminally; upgrades may therefore lose cleanup. Argument data is released when its registration finishes.
Registration storage has its own quota using the configured session KV limits: key/value limits, registration count, and total bytes including package-version metadata. KV writes, replacement, and deletion do not run finalizers. Finalizers cannot register/unregister finalizers.
Remote creation and registration are separate effects. On a catchable registration refusal, the package should attempt immediate cleanup. A crash or uncertain storage failure before acknowledgment still requires a remote lease/idle timeout or other recovery mechanism; a stored handle does not checkpoint remote process memory.
GET /v1/sessions/{id}/finalizers reports package, local key, status, and sanitized
failure category, without arguments or credentials.
Call registerFinalizer directly (namespace and named imports are supported)
so the compiler can validate its value against the package finalizer signature.
The REST session-close response includes sanitized finalizer outcomes when
registrations exist; sessions without registrations retain the empty 204 response.
Embedders can use end_session_with_finalizers for the same report; the existing
end_session boolean API remains available.
submilli:code
Section titled “submilli:code”Workspace tools: numbered reads, search, glob, tree, anchored edits and unified diffs.
| Function | Capability | Description |
|---|---|---|
applyPatch(path: string, patch: string): { changed: boolean; diagnostics: { hunk: number; line: number; message: string }[]; diff: string; success: boolean } |
Apply a single-file unified patch by unique context, ignoring header positions. | |
diffFiles(a: string, b: string): string |
Unified diff of two strict UTF-8 workspace files. | |
diffText(a: string, b: string): string |
Pure UTF-16 text comparison; unified diff with three context lines. | |
edit(path: string, oldString: string, newString: string, replaceAll?: boolean, nearLine?: number): { changed: boolean; diagnostics: { hunk: number; line: number; message: string }[]; diff: string; success: boolean } |
Replace a unique exact anchor; replaceAll selects every occurrence. | |
glob(pattern: string): { entries: { depth: number; kind: string; modifiedAt: number; path: string }[]; truncated: boolean } |
Match file paths relative to /; newest modification first, path breaks ties. | |
insertAt(path: string, line: number, text: string): { changed: boolean; diagnostics: { hunk: number; line: number; message: string }[]; diff: string; success: boolean } |
Insert text literally before a one-based line; one past the last line appends. | |
read(path: string, offset?: number, limit?: number): { lines: { line: number; text: string }[]; path: string; truncated: boolean } |
Numbered UTF-8 lines; one-based offset, default 200 lines. | |
search(pattern: string, options?: { caseSensitive?: boolean; context?: number; exclude?: string[]; include?: string[]; limit?: number; mode?: string; path?: string }): { counts: { count: number; path: string }[]; files: string[]; matches: { after: { line: number; text: string }[]; before: { line: number; text: string }[]; line: number; path: string; text: string }[]; truncated: boolean } |
Regex search, ignoring hidden and ignored paths. | |
tree(path: string, depth?: number): { entries: { depth: number; kind: string; modifiedAt: number; path: string }[]; truncated: boolean } |
Ignored/hidden paths omitted; symlinks listed but never traversed. |
submilli:cost
Section titled “submilli:cost”Packages report what their calls cost, so the run’s cost includes it.
| Function | Capability | Description |
|---|---|---|
report(entry: { label?: string; usage?: { [key: string]: number }; usd?: number }): void |
cost.report |
Report what one of this package’s calls cost, so the run’s cost includes it. |
submilli:crypto
Section titled “submilli:crypto”Hashing, HMAC, and random bytes.
| Function | Capability | Description |
|---|---|---|
hmacSha256(key: Uint8Array, message: string | Uint8Array): Uint8Array |
HMAC-SHA-256 of message under key. |
|
randomBytes(length: number): Uint8Array |
Cryptographically secure random bytes from the OS entropy source. | |
sha256(input: string | Uint8Array): Uint8Array |
SHA-256 digest of input. |
|
sha512(input: string | Uint8Array): Uint8Array |
SHA-512 digest of input. |
|
timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean |
Constant-time byte-array equality, suitable for comparing HMAC tags. |
submilli:embedding
Section titled “submilli:embedding”Remote text embeddings: embed batches into sealed vectors, and models() to discover aliases.
| Function | Capability | Description |
|---|---|---|
embed(model: string, texts: string[], purpose: "document" | "query"): Embeddings |
embedding.embed { model, input_count: $texts.length } |
Embed texts with the alias model and return one sealed Embeddings: result.vector(i) is the vector of texts[i], in input order. |
models(): EmbeddingModel[] |
embedding.embed { model, input_count: 0 } |
The embedding aliases this runtime serves and this caller may use. |
EmbeddingModel
Section titled “EmbeddingModel”One alias this caller may embed with.
| Member | Description |
|---|---|
readonly description: string | undefined |
Operator-authored deployment intent, or undefined when none was declared. |
readonly dimensions: number |
The length of every vector this alias returns. |
readonly identity: string |
The embedding-space identity results from this alias carry. |
readonly maxInputBytes: number |
The UTF-8 byte length above which one text is refused before sending. |
readonly maxInputTokens: number | undefined |
The alias’s input limit in tokens, or undefined when none is known. |
readonly name: string |
The alias name, exactly as embed expects it. |
Embeddings
Section titled “Embeddings”The sealed result of embed: vectors held by the runtime at 4 bytes per number, in input order, labeled with the embedding-space identity.
| Member | Description |
|---|---|
readonly count: number |
The number of vectors, equal to the number of texts embedded. |
readonly dimensions: number |
The length of every vector. |
readonly identity: string |
The embedding-space identity of every vector here. |
readonly inputTokens: number | undefined |
Input tokens the provider reported for the whole call, or undefined when it reported none. |
readonly model: string |
The alias these vectors were embedded with. |
bytes(index: number): Uint8Array |
The vector of texts[index] as little-endian 32-bit floats: dimensions * 4 bytes, the compact form for storing a vector. |
vector(index: number): number[] |
The vector of texts[index] as a number[] of dimensions numbers. |
submilli:fs
Section titled “submilli:fs”Sandbox filesystem: files and directories under the VFS root.
| Function | Capability | Description |
|---|---|---|
append(path: string, content: Uint8Array): void |
fs.write { path, length: number } |
Append content to path. |
appendText(path: string, content: string): void |
fs.write { path, length: number } |
UTF-8 append. |
bytes(path: string, chunkSize: number): Iterator<Uint8Array> |
fs.read { path, chunkSize } |
Stream the file at path as a constant-memory byte iterator. |
copy(from: string, to: string, recursive: boolean): void |
fs.copy { from, to, recursive } |
Copy from to to. |
cwd(): string |
The absolute guest working directory used by relative paths. | |
exists(path: string): boolean |
fs.stat { path } |
Returns true iff path resolves to a filesystem entry under the VFS root. |
info(): Info |
The active VFS configuration: the root’s mode ("none" / "ephemeral" / "per_session" / "named"), access, volume and sizeLimit (the cap on the bytes its files may hold, or -1 when none applies), plus mounts, the named volumes grafted below the root. |
|
isEmpty(path: string): boolean |
fs.list { path, recursive: boolean } |
Returns true when the directory at path has no entries, or the file at path has zero bytes. |
lines(path: string): Iterator<string> |
fs.read { path } |
Stream the file at path as a constant-memory line iterator. |
list(path: string, options?: RecursiveOptions): Iterator<DirEntry> |
fs.list { path, recursive: boolean } |
List the children of the directory at path as a constant-memory iterator of DirEntry. |
maxReadSize(): number |
Maximum number of bytes read / readText will load whole; past this they throw. |
|
mkdir(path: string, options?: RecursiveOptions): void |
fs.mkdir { path, recursive: boolean } |
Create the directory at path. |
move(from: string, to: string): void |
fs.move { from, to } |
Move / rename. |
peek(path: string): Peek |
fs.stat { path } |
Quick file-only inspection: preview (first ~256 bytes decoded UTF-8 lossy), detected encoding (utf-8 / utf-16le / utf-16be / latin1), lineEnding (lf / crlf), and total size. |
read(path: string): Uint8Array |
fs.read { path } |
Read the whole file as a Uint8Array. |
readBytes(path: string, offset: number, length: number): Uint8Array |
fs.read { path, length } |
Random-access byte-range read. |
readText(path: string): string |
fs.read { path } |
Read the whole file as a UTF-8 string. |
remove(path: string, options?: RecursiveOptions): void |
fs.remove { path, recursive: boolean } |
Remove the entry at path. |
size(path: string): number |
fs.stat { path } |
File size in bytes. |
stat(path: string): Stat |
fs.stat { path } |
Metadata about an entry under the VFS root. |
summary(path: string): string |
fs.list { path, recursive: boolean } |
Describe path in a few lines of text, for a program that needs to see what is there before deciding what to read. |
write(path: string, content: Uint8Array): void |
fs.write { path, length: number } |
Write content to path atomically (temp-file + rename). |
writeText(path: string, content: string): void |
fs.write { path, length: number } |
UTF-8 atomic write. |
writer(path: string): FileWriter |
fs.write { path } |
Open path as an append-only FileWriter. |
DirEntry
Section titled “DirEntry”Directory entry yielded by list(path, options).
| Member | Description |
|---|---|
readonly kind: string |
"file" / "directory" / "symlink" / "other". |
readonly name: string |
Basename of the entry (no parent path). |
readonly path: string |
Full guest-visible path under the VFS root, with a leading /. |
readonly size: number |
File size in bytes; 0 for non-files. |
FileWriter
Section titled “FileWriter”Append-only writer returned by writer(path).
| Member | Description |
|---|---|
close(): void |
Flush the internal buffer, fsync the temp file, and atomically rename it over the destination. |
writeBytes(bytes: Uint8Array): void |
Append bytes to the buffer. |
writeLine(line: string): void |
Append line followed by \n (LF). |
VFS configuration returned by info(): the root’s mode, access, volume and sizeLimit (-1 when no limit applies), plus its mounts.
| Member | Description |
|---|---|
readonly access: string |
"read_write", or "read_only" when every write to the root throws a PermissionDeniedError. |
readonly mode: string |
The root’s mode: "none" / "ephemeral" / "per_session" / "named". |
readonly mounts: MountInfo[] |
The named volumes mounted below the root, sorted by path; empty when there are none. |
readonly sizeLimit: number |
The most bytes the files in the root may hold, or -1 when no limit applies. |
readonly volume: string |
The named volume backing the root under mode: "named"; "" otherwise, and for a directory submilli run --vfs exposes. |
MountInfo
Section titled “MountInfo”One volume mounted below the VFS root, as info().mounts lists it.
| Member | Description |
|---|---|
readonly access: string |
"read_write", or "read_only" when every write under path throws a PermissionDeniedError. |
readonly mode: string |
Always "named": mounts are named volumes the server declares. |
readonly path: string |
The guest path the volume is mounted at, such as /memory. |
readonly sizeLimit: number |
The most bytes the volume may hold, shared with everyone who mounts it, or -1 when no limit applies. |
readonly volume: string |
The volume’s name. |
Lightweight file-only inspection — preview + transport metadata.
| Member | Description |
|---|---|
readonly encoding: string |
Detected text encoding: "utf-8" / "utf-16le" / "utf-16be" / "latin1". |
readonly lineEnding: string |
"crlf" if a CRLF sequence appears in the preview; "lf" otherwise (including files with no line terminators yet). |
readonly preview: string |
First ~256 bytes of the file decoded as UTF-8 lossy. |
readonly size: number |
Total file size in bytes — same value as size(path). |
RecursiveOptions
Section titled “RecursiveOptions”Options for mkdir, remove and list.
| Member | Description |
|---|---|
recursive?: boolean |
Include descendants or create missing parents. |
Filesystem metadata returned by stat(path).
| Member | Description |
|---|---|
readonly kind: string |
One of "file" / "directory" / "symlink" / "other". |
readonly modifiedAt: number |
Last-modified timestamp in milliseconds since the Unix epoch. |
readonly size: number |
File size in bytes. |
submilli:git
Section titled “submilli:git”Capability-controlled Git repositories in the VFS, with HTTPS remotes.
Repository
Section titled “Repository”A repository under the VFS root.
| Member | Capability | Description |
|---|---|---|
static clone(url: string, path: string, options?: { branch?: string }): Repository |
git.clone { path, remote: $url, remoteName: "origin", branch: string } |
Clone HTTPS into an empty VFS directory, following remote HEAD unless branch is specified. |
static init(path: string, options?: { branch?: string }): Repository |
git.init { path } |
Initialize a repository, default branch main. |
static open(path: string): Repository |
git.open { path } |
Open an ordinary repository under the VFS root. |
constructor(path: string) |
||
add(paths: string[]): void |
git.write { path: string } |
Stage explicit files or directories, including deletions. |
addRemote(name: string, url: string): void |
git.write { path: string } |
Add a named HTTPS remote, for example origin or upstream. |
branches(): { current: boolean; id: string; name: string }[] |
git.read { path: string } |
List local branches. |
commit(message: string): string |
git.commit { path: string, branch: string } |
Commit staged changes with Blueprint identity and return the commit ID. |
createBranch(name: string, start?: string): void |
git.write { path: string } |
Create a branch without overwriting an existing branch. |
diff(options?: { from?: string; mode?: string; to?: string }): { binaryPaths: string[]; patch: string } |
git.read { path: string } |
Compare working (default), staged, or refs (requires from and to). |
fetch(remote?: string, branch?: string): { branches: string[] } |
git.fetch { path: string, remoteName: $remote, remote: string, branch: string } |
Fetch remote-tracking branches. |
log(options?: { limit?: number; offset?: number; path?: string; ref?: string }): { commits: { authorEmail: string; authorName: string; id: string; message: string }[]; nextOffset?: number } |
git.read { path: string } |
Read history, default 50 commits from HEAD; limit 1..1000, nonnegative integer offset; path keeps commits that changed that file and ref starts at that commit. |
ls(ref: string, path?: string): { kind: string; path: string }[] |
git.read { path: string } |
List files and directories in a repository-relative directory at a commit. |
pull(remote?: string, branch?: string): { current: string; previous: string } |
git.fetch { path: string, remoteName: $remote, remote: string, branch: string } |
Fetch and fast-forward the current branch under git.fetch. |
remotes(): { name: string; url: string }[] |
git.read { path: string } |
List named remotes without credentials. |
setRemoteUrl(name: string, url: string): void |
git.write { path: string } |
Update an existing remote’s HTTPS URL. |
show(ref: string, path: string): Uint8Array |
git.read { path: string } |
Read file bytes from a commit. |
status(): { branch?: string; clean: boolean; entries: { path: string; staged: string; unstaged: string; untracked: boolean }[] } |
git.read { path: string } |
Inspect staged, unstaged and untracked paths. |
switchBranch(name: string): void |
git.write { path: string } |
Switch local branches; requires a completely clean working tree. |
submilli:http
Section titled “submilli:http”Outbound HTTP requests, and downloads into the filesystem.
| Function | Capability | Description |
|---|---|---|
delete(url: string, headers?: Headers): Response |
http.delete { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP DELETE. |
download(url: string, path: string, options?: DownloadOptions): DownloadResult |
http.download { host: $url.host, url_path: $url.path, vfs_path: $path, max_bytes: number, overwrite: boolean, decompress: boolean }fs.write { path, max_bytes: number } |
Download a remote file directly to the VFS — wget-style. |
get(url: string, headers?: Headers): Response |
http.get { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP GET. |
head(url: string, headers?: Headers): Response |
http.head { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP HEAD. |
options(url: string, headers?: Headers): Response |
http.options { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP OPTIONS. |
patch(url: string, body?: string | Uint8Array | { [key: string]: unknown } | unknown[] | null, headers?: Headers): Response |
http.patch { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP PATCH. |
post(url: string, body?: string | Uint8Array | { [key: string]: unknown } | unknown[] | null, headers?: Headers): Response |
http.post { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP POST. |
put(url: string, body?: string | Uint8Array | { [key: string]: unknown } | unknown[] | null, headers?: Headers): Response |
http.put { host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue a synchronous HTTP PUT. |
request(method: string, url: string, body?: string | Uint8Array | { [key: string]: unknown } | unknown[] | null, headers?: Headers): Response |
http.request { method, host: $url.host, path: $url.path, body_size: number, timeout_ms: number } |
Issue an HTTP request with a runtime-chosen verb. |
DownloadOptions
Section titled “DownloadOptions”Options bag for [download].
| Member | Description |
|---|---|
decompress?: boolean |
When true, transparently gunzip / unzstd the response if the Content-Encoding header (or URL suffix .gz / .zst) advertises a compressed stream. |
headers?: Headers | undefined |
Request headers — typically used for auth (Authorization: Bearer …). |
maxBytes?: number |
Maximum bytes to write to disk (post-decompression when decompress is true). |
overwrite?: boolean |
When true, clobber an existing file at path. |
timeout?: number |
Per-request timeout in milliseconds. |
DownloadResult
Section titled “DownloadResult”Result of [download] — what was written, where, and the response metadata.
| Member | Description |
|---|---|
readonly bytesWritten: number |
Bytes actually written to disk (post-decompression when decompress was set). |
readonly contentType: string |
Content-Type header from the response, lowercased. |
readonly duration_ms: number |
Wall-clock duration of the download in milliseconds, measured from temp-file open through atomic rename. |
readonly finalUrl: string |
Final URL after any redirects. |
readonly path: string |
The VFS path the file was written to — echoes the path argument. |
readonly status: number |
HTTP status code (e.g. 200). |
Headers
Section titled “Headers”HTTP header bag: Map<string, string> with names lowercased on the wire.
type Headers = Map<string, string>;Response
Section titled “Response”Result of an HTTP call — status, headers, body, and the final URL after any redirects.
| Member | Description |
|---|---|
readonly body: string |
Response body, decoded as UTF-8. |
readonly headers: Headers |
Response headers. |
readonly ok: boolean |
true iff status is in the 2xx range. |
readonly status: number |
HTTP status code (e.g. 200, 404). |
readonly statusText: string |
Reason phrase (e.g. "OK", "Not Found"). |
readonly url: string |
Final URL after any redirects. |
json<T>(): T |
Parse the response body as JSON and decode it as T, for example r.json<User>(). |
throwForStatus(): void |
Throw if ok is false. |
toString(): string |
Concise description of the response — "Response(200 OK, https://...)". |
submilli:llm
Section titled “submilli:llm”Gated model calls: text/texts for text, call
| Function | Capability | Description |
|---|---|---|
batch<T>(model: string, prompts: (string | Prompt)[]): Completion<T>[] |
llm.call { model, prompt_count: $prompts.length } |
Send every prompt to model and return one Completion each, positionally: result[i] is the outcome of prompts[i], including when that element failed. |
call<T>(model: string, prompt: string, files?: string[]): Completion<T> |
llm.call { model, prompt_count: 1 } |
Send one prompt to model and return its answer checked as a T: { ok: true, value } or { ok: false, reason, message }. |
models(): Model[] |
llm.call { prompt_count: 0 } |
The models this runtime serves and this caller may call. |
text(model: string, prompt: string, files?: string[]): Completion<string> |
llm.call { model, prompt_count: 1 } |
Send one prompt to model and return its completion text as a Completion<string>: { ok: true, value } or { ok: false, reason, message }. |
texts(model: string, prompts: (string | Prompt)[]): Completion<string>[] |
llm.call { model, prompt_count: $prompts.length } |
Send every prompt to model and return one Completion<string> each, positionally: result[i] is the text outcome of prompts[i], including when that element failed. |
Completion
Section titled “Completion”One prompt’s outcome: Success<T> when the model stopped naturally, Failure otherwise.
type Completion<T> = Failure | Success<T>;Failure
Section titled “Failure”The ok: false arm of a Completion<T>: why this element is not a clean completion, and the partial text when the model produced some.
| Member | Description |
|---|---|
readonly finishReason?: string |
The provider’s own raw stop reason, for diagnosis only. |
readonly inputTokens?: number |
Prompt tokens the provider reported for this element, absent when indeterminate. |
readonly message: string |
A fixed classification of the failure, or for "invalid-output" the type the response did not match. |
readonly ok: false |
false: this element is not a clean completion. |
readonly outputTokens?: number |
Completion tokens the provider reported for this element, absent when indeterminate. |
readonly reason: "cancelled" | "content-filtered" | "incomplete" | "invalid-output" | "provider-unavailable" | "rate-limited" | "request-rejected" | "transport" | "truncated" |
Why this element is not a clean completion. |
readonly retryable: boolean |
Whether re-sending this identical prompt could plausibly succeed. |
readonly status?: number |
The HTTP status the provider answered with, absent when none was observed — which is what distinguishes a dead connection from a provider that answered with an error. |
readonly text?: string |
The partial text of a truncated or filtered completion, absent when the model produced none at all. |
One model this caller may call.
| Member | Description |
|---|---|
readonly contextWindow?: number |
The model’s context window in tokens, absent when the operator declared none. |
readonly description?: string |
Operator-authored deployment intent, absent when none was declared. |
readonly name: string |
The model name, exactly as call and batch expect it. |
Prompt
Section titled “Prompt”One prompt of texts or batch with the files sent with it: { prompt: "Summarize.", files: ["/attachments/report.pdf"] }.
| Member | Description |
|---|---|
readonly files?: string[] |
Paths of files in this program’s filesystem, sent to the model with this prompt only, before its text. |
readonly prompt: string |
The prompt text. |
Success
Section titled “Success”The ok: true arm of a Completion<T>: the model stopped naturally and value is its answer — the text, or the checked T.
| Member | Description |
|---|---|
readonly inputTokens?: number |
Prompt tokens the provider reported. |
readonly ok: true |
true: the model stopped naturally and value holds its answer. |
readonly outputTokens?: number |
Completion tokens the provider reported, with the same absent-means-indeterminate rule as inputTokens. |
readonly value: T |
The completion text from text/texts, or from call<T>/batch<T> the parsed response, checked against T field by field. |
submilli:secrets
Section titled “submilli:secrets”Policy-gated access to Blueprint-declared secrets.
| Function | Capability | Description |
|---|---|---|
get(secret: string): string | undefined |
secrets.get { name: $secret } |
Resolve a Blueprint-declared secret by name. |
submilli:session
Section titled “submilli:session”Session-scoped key-value state and durable package-owned resource cleanup.
| Function | Capability | Description |
|---|---|---|
get<T>(key: string): T | undefined |
session.read { key } |
Read a session value, checked against T. |
has(key: string): boolean |
session.read { key } |
Whether the session holds an entry for key. |
list(prefix: string, limit: number, cursor?: string): Page |
session.list { prefix }session.read { key } - per candidate key |
Enumerate session keys starting with prefix, in UTF-16 code-unit order. |
registerFinalizer(key: string, value: unknown): void |
session.finalize { key } |
Register durable cleanup using this package’s finalizer(key, value). |
remove(key: string): boolean |
session.remove { key } |
Delete key. |
set(key: string, value: unknown): void |
session.write { key } |
Store value under key, replacing any previous entry. |
unregisterFinalizer(key: string): void |
session.finalize { key } |
Forget cleanup after releasing the resource. |
One key a list page discloses.
| Member | Description |
|---|---|
readonly key: string |
The session key, in the exact code units it was stored under. |
readonly sizeBytes: number |
Serialized size of the stored value in bytes — the value alone, not the key and not the store’s per-entry overhead. |
One page of a list call: the entries it discloses and the nextCursor that continues it.
| Member | Description |
|---|---|
readonly entries: Entry[] |
The keys this page discloses, in UTF-16 code-unit order. |
readonly nextCursor: string | undefined |
Opaque cursor for the next page, or undefined when no further matching key remains. |
submilli:url
Section titled “submilli:url”URL parse/build and query-string handling. Pure compute.
| Function | Capability | Description |
|---|---|---|
build(protocol: string, host: string, port: number | undefined, path: string, query: Query, fragment?: string): string |
Serialise URL parts to an absolute URL string. | |
decodeComponent(s: string): string |
Percent-decode s. |
|
decodeQuery(s: string): Query |
Parse a URL-encoded query string into a Query (Map<string, string>). |
|
encodeComponent(s: string): string |
Percent-encode s per RFC 3986 (UTF-8 then %HH for every byte that isn’t an ASCII alphanumeric or one of -, ., _, ~). |
|
encodeQuery(query: Query): string |
Serialise a Query (Map<string, string>) to a URL-encoded query string (k=v&k=v). |
|
parse(url: string): URL |
Parse an absolute URL string into its parts. |
Query-string parameter map.
type Query = Map<string, string>;Parsed URL parts — the return type of parse.
| Member | Description |
|---|---|
readonly fragment: string | undefined |
Fragment string (without the # prefix), or undefined when the URL has no # segment. |
readonly host: string |
Host name, e.g. "api.pied-piper.example". |
readonly path: string |
Path component, including the leading /. |
readonly port: number | undefined |
Port number, or undefined when the URL omits one. |
readonly protocol: string |
Scheme, e.g. "https". |
readonly query: Query |
Query parameters as a Query (Map<string, string>). |
submilli:uuid
Section titled “submilli:uuid”UUID v4/v7 generation and validation.
| Function | Capability | Description |
|---|---|---|
v4(): string |
Generate a random UUID v4 (RFC 4122). | |
v7(): string |
Generate a time-ordered UUID v7 (RFC 9562). | |
validate(string: string): boolean |
Returns true if string is a valid UUID (any version), false otherwise. |
submilli:variables
Section titled “submilli:variables”Immutable Blueprint/session configuration for packages.
| Function | Capability | Description |
|---|---|---|
get(name: string): string | undefined |
variables.get { name } |
Read immutable Blueprint/session configuration. |