Work with the program.
The native pandō guide and API. Precise reads, structural changes, and a history you can return to.
START HERE
Your first versioned workspace
pandō runs locally and gives an MCP-compatible coding agent structural access to a versioned program. TypeScript and JavaScript are supported now.
1. Check the prerequisites
Use Node.js 24.10.0 or newer. Linux needs FUSE support, access to /dev/fuse, and mount permission. macOS needs macFUSE. The compatibility workspace requires a working mount; Windows support is coming soon.
2. Run the setup wizard
npx -y pando-aiThe wizard handles installation and agent setup. Follow its prompts, then start your coding agent in your project. The initial run captures and indexes your repository before structural operations become ready.
3. Connect an MCP client directly, if needed
Use an explicit project path with the stdio server. The setup wizard and the MCP server are different commands.
npx -y pando-ai serve /absolute/path/to/my-projectAn MCP client configuration can use:
{
"mcpServers": {
"pando-ai": {
"command": "npx",
"args": ["-y", "pando-ai", "serve", "/absolute/path/to/my-project"]
}
}
}For the current tool contract, ask your agent to call pando-guide({"topic":"start"}). Tool schemas and guides come from the connected server.
HOW IT WORKS
One program. A familiar workspace.
- Capture. pandō makes a private checkpoint, then captures source, configuration, assets, and repository metadata into its local store.
- Activate. The database becomes authority for the pandō workspace. Your original checkout stays independent and can diverge.
- Render. A sibling such as
my-project-pandopresents the selected snapshot as files. Use theshelltool for builds and tests there.
Managed code changes go through pandō operations. Ordinary filesystem writes do not edit managed code. Derived output belongs in the sibling’s temporary layer. The original checkout is not an automatic synchronization source or a fallback after capture.
TypeScript semantics use the project’s captured TypeScript compiler package. A missing compiler or incomplete coverage can prevent an operation. An unsupported file can still be captured and read as bytes; that does not give its language structural editing support.
Coming soon: Python, Java, Clojure, ClojureScript, C#, C/C++, and Dart.
THE AGENT WORKFLOW
Discover. Read precisely. Change by identity.
Durable IDs: nodes, symbols, documents, and snapshots are addressed with decimal strings such as "73001". Discover real IDs with browse-code; the IDs below are illustrative.
Connected changes: rename compiler-bound references across the project, update callable parameters and their invocations together, or move and wrap existing nodes while retaining their identity. The agent supplies the change it wants; existing code can be reused by ID without being copied into a prompt. Operations enforce their own coverage and atomicity rules and report what applied or refused.
Bounded context: browse queries return at most 20 results per page. Keep the selected snapshot and use a returned nextRequest unchanged. A continuation alone does not mean more matches exist; inspect exhausted and each query’s outcome.
Source access: read-node supports outlines and complete node code. Full reads disclose source to your agent. Structural operations can use IDs without resending existing bodies.
Automatic semantic commits: every committed structural change records an immutable snapshot of the program’s code and relationships, with a receipt describing the operation. The agent does no extra work to create these commits: no staging, commit command, or checkpoint bookkeeping.
Continue from any point: call history({"select":"17"}) to select an earlier snapshot, then make your next change from there. You can explore a different path without undoing each intervening change or applying reverse patches. The history you left remains available to revisit.
Compiler checks: modifying operations default to compilerCheck: true. Explicitly setting it to false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus: "unchecked". Unchecked results carry no type, binding, or reference-completeness guarantee.
Coverage and refusal: inspect the complete result. Coupled changes are atomic; batches can apply independent groups while refusing others. Deletion may leave explicit missing children with semantics unavailable until repair. A committed change is not a substitute for behavioral tests.
Parameter tables below summarize the interface. The expandable JSON schema is the exact captured contract; read the operation’s pando-guide topic for detailed semantics. Language fields may include reserved implementation values: public language support is TS/JS only.
Discover & read
3 toolsbrowse-codeBrowse code
Find files, symbols, nodes, relationships, diagnostics, text matches, and aggregates in one selected snapshot.
Parameters
| Name | Type | Details |
|---|---|---|
snapshotoptional | string | Defaults to the current committed head and binds every query in this call. |
queriesrequired | array | Independent keyed slices to execute against the same snapshot. Example selects include symbols, nodes, relationships, files, text-matches, diagnostics, and constructs. |
maxBytesoptional | integer | UTF-8 byte limit for the complete multi-query result, including continuation; defaults to 16384. |
Example request
{
"queries": [
{
"key": "user",
"select": "symbols",
"where": {
"name": {
"exact": "getUser"
}
},
"limit": 5
}
]
}For the complete usage contract, call pando-guide({"topic":"browse-code"}).
Full request schema
{
"type": "object",
"properties": {
"snapshot": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Defaults to the current committed head and binds every query in this call."
},
"queries": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"description": "Independent keyed slices to execute against the same snapshot. Example selects include symbols, nodes, relationships, files, text-matches, diagnostics, and constructs.",
"items": {
"$ref": "#/definitions/browseQuery"
}
},
"maxBytes": {
"type": "integer",
"minimum": 1024,
"maximum": 262144,
"default": 16384,
"description": "UTF-8 byte limit for the complete multi-query result, including continuation; defaults to 16384."
}
},
"required": [
"queries"
],
"additionalProperties": false,
"definitions": {
"browseQuery": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"select": {
"type": "string",
"description": "Projection to return. text-matches requires ftsQuery plus scope.files or scope.entities.",
"enum": [
"entities",
"files",
"text-matches",
"symbols",
"nodes",
"relationships",
"diagnostics",
"constructs",
"construct-relationships"
]
},
"includeViewSummary": {
"type": "boolean",
"description": "When true, return compact analytics for only the delivered ordinary page (at most 20 items and their contributing documents). This never scans beyond page delivery and cannot be combined with aggregate."
},
"include": {
"type": "array",
"maxItems": 2,
"uniqueItems": true,
"description": "Optional enrichments: editing adds exact structural coordinates; metadata returns full stored row fields.",
"items": {
"type": "string",
"enum": [
"editing",
"metadata"
]
}
},
"scope": {
"$ref": "#/definitions/browseScope"
},
"ftsQuery": {
"type": "string",
"minLength": 1,
"maxLength": 16384,
"description": "Raw SQLite FTS5 MATCH expression using the trigram tokenizer, only for select:text-matches. Quote punctuation-bearing phrases with double quotes, e.g. \"service.dispose\". No literal, regex, or exact-match translation is applied."
},
"where": {
"$ref": "#/definitions/browseWhere"
},
"facets": {
"type": "array",
"items": {
"type": "string",
"enum": [
"module",
"entity",
"language",
"kind",
"relationship"
]
}
},
"aggregate": {
"type": "object",
"description": "Replace item delivery with exact measures over the population selected by select, scope, and where. count supports files, nodes, symbols, relationships, entities, constructs, and construct-relationships. sum/avg currently support only files.byteLength. Without groupBy one scalar aggregate result is returned; grouped results use the ordinary authenticated 20-row pager.",
"properties": {
"measures": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"count",
"sum",
"avg"
]
},
"field": {
"type": "string",
"description": "Required for sum/avg and currently limited to byteLength with select:files. Omit for count."
}
},
"required": [
"op"
],
"additionalProperties": false
}
},
"groupBy": {
"type": "array",
"items": {
"type": "string",
"enum": [
"module",
"entity",
"language",
"kind",
"relationship"
]
}
}
},
"required": [
"measures"
],
"additionalProperties": false
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Start with 5 for discovery. Follow pages for a complete inventory; request larger pages only when their contents are needed."
},
"continuation": {
"type": [
"string",
"null"
],
"maxLength": 4096
}
},
"required": [
"key",
"select"
],
"additionalProperties": false
},
"browseScope": {
"type": "object",
"properties": {
"directory": {
"type": "string",
"pattern": "^(root|[1-9][0-9]*)quot;,
"description": "With select:files, list only the immediate children of root or this selected durable directory document ID. Results include entry names and durable IDs."
},
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"entities": {
"type": "array",
"items": {
"type": "string"
}
},
"files": {
"type": "array",
"maxItems": 128,
"description": "Exact repository-relative logical paths or bounded globs such as **/package.json.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"nodeIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"symbolIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"constructIds": {
"type": "array",
"maxItems": 128,
"description": "Exact durable indexed-construct IDs. Required by construct-relationships.",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
}
},
"additionalProperties": false
},
"browseWhere": {
"type": "object",
"properties": {
"kind": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"$ref": "#/definitions/browseNameFilter"
},
"role": {
"type": "array",
"items": {
"$ref": "#/definitions/browseNodeRole"
}
},
"childIndex": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
}
},
"depth": {
"$ref": "#/definitions/browseIntegerRange"
},
"preorder": {
"$ref": "#/definitions/browseIntegerRange"
},
"parent": {
"$ref": "#/definitions/browseNodePredicate"
},
"ancestor": {
"$ref": "#/definitions/browseNodePredicate"
},
"child": {
"$ref": "#/definitions/browseNodePredicate"
},
"region": {
"type": "string",
"enum": [
"whole-node",
"body"
]
},
"relationshipKinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"alias",
"call",
"construct",
"declaration",
"export",
"extends",
"implements",
"implements-member",
"import",
"module-target",
"overrides",
"reference"
]
},
"maxItems": 12
},
"constructRelationshipKinds": {
"type": "array",
"maxItems": 128,
"description": "Exact explicit indexed-construct relationship kinds.",
"items": {
"type": "string",
"minLength": 1
}
},
"constructRelationshipDirection": {
"type": "string",
"description": "Direction relative to scope.constructIds.",
"enum": [
"incoming",
"outgoing",
"either"
]
},
"declaration": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"references": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"calls": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"imports": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"exports": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"aliases": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"extends": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"implements": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"implementsMembers": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"overrides": {
"$ref": "#/definitions/browseRelationshipPredicate"
},
"relatedTo": {
"$ref": "#/definitions/browseRelatedToPredicate"
},
"signature": {
"$ref": "#/definitions/browseSignaturePredicate"
}
},
"additionalProperties": false
},
"browseNodeRole": {
"type": "string",
"enum": [
"root",
"child",
"separator",
"name",
"body",
"parameter",
"parameters",
"type-parameter",
"type-parameters",
"type",
"type-argument",
"type-arguments",
"argument",
"arguments",
"statement",
"statements",
"member",
"members",
"modifier",
"modifiers",
"initializer",
"condition",
"then",
"else",
"expression",
"element",
"elements",
"property",
"properties",
"clause",
"clauses",
"declaration",
"declarations"
]
},
"browseIntegerRange": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0
},
"max": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"browseNameFilter": {
"description": "Choose exactly one name predicate. exact is case-sensitive equality. matches is a JavaScript regular expression; flags are accepted only with matches.",
"oneOf": [
{
"type": "object",
"properties": {
"exact": {
"type": "string",
"minLength": 1
}
},
"required": [
"exact"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"matches": {
"type": "string",
"minLength": 1
},
"flags": {
"type": "string"
}
},
"required": [
"matches"
],
"additionalProperties": false
}
]
},
"browseSignaturePredicate": {
"type": "object",
"description": "Callable declaration predicate for select:symbols. Every field must match one declaration; overloads are never combined.",
"properties": {
"parameterCount": {
"$ref": "#/definitions/browseIntegerRange"
},
"parameters": {
"type": "object",
"properties": {
"any": {
"type": "object",
"properties": {
"ordinal": {
"$ref": "#/definitions/browseIntegerRange"
},
"name": {
"$ref": "#/definitions/browseNameFilter"
},
"optional": {
"type": "boolean"
},
"rest": {
"type": "boolean"
},
"hasInitializer": {
"type": "boolean"
},
"typeNodeIds": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
}
},
"minProperties": 1,
"additionalProperties": false
}
},
"required": [
"any"
],
"additionalProperties": false
},
"returnTypeNodeIds": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"hasExplicitReturnType": {
"type": "boolean"
},
"flags": {
"type": "object",
"properties": {
"async": {
"type": "boolean"
},
"generator": {
"type": "boolean"
},
"static": {
"type": "boolean"
},
"abstract": {
"type": "boolean"
},
"accessibility": {
"type": "string",
"enum": [
"public",
"protected",
"private",
"none"
]
}
},
"minProperties": 1,
"additionalProperties": false
}
},
"minProperties": 1,
"additionalProperties": false
},
"browseNodePredicate": {
"type": "object",
"properties": {
"nodeIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"kind": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"$ref": "#/definitions/browseNameFilter"
},
"role": {
"type": "array",
"items": {
"$ref": "#/definitions/browseNodeRole"
}
},
"childIndex": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
}
},
"depth": {
"$ref": "#/definitions/browseIntegerRange"
},
"preorder": {
"$ref": "#/definitions/browseIntegerRange"
}
},
"minProperties": 1,
"additionalProperties": false
},
"browseRelationshipPredicate": {
"type": "object",
"description": "Select direct stored relationship occurrences for exactly one durable target. Direction is relative to that target.",
"properties": {
"symbolId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"nodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"direction": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"either"
]
}
},
"oneOf": [
{
"required": [
"symbolId"
]
},
{
"required": [
"nodeId"
]
}
],
"additionalProperties": false
},
"browseRelatedToPredicate": {
"type": "object",
"description": "Resolve every durable node matching this predicate, then return one direct stored hop for each seed. Incoming relationships target the seed; outgoing relationships are sourced anywhere inside its exact subtree; either is their union. Results identify seedNodeId and page only final relationship rows. This is not recursive graph traversal.",
"properties": {
"nodeIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"kind": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"$ref": "#/definitions/browseNameFilter"
},
"role": {
"type": "array",
"items": {
"$ref": "#/definitions/browseNodeRole"
}
},
"childIndex": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
}
},
"preorder": {
"$ref": "#/definitions/browseIntegerRange"
},
"direction": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"either"
]
}
},
"required": [
"direction"
],
"minProperties": 2,
"additionalProperties": false
}
}
}read-nodeRead node
Read exact nodes by durable ID. Auto returns complete code when it fits, otherwise an outline. Full refuses when the node exceeds the response budget.
Parameters
| Name | Type | Details |
|---|---|---|
snapshotIdoptional | string | Defaults to the current head, like browse-code and the mutations. |
nodeIdsrequired | array | Exact durable node IDs to read, in desired result order. |
detailoptional | string | auto returns full code when it fits and otherwise an outline; outline always compacts; full requires the exact complete node. |
maxBytesoptional | integer | UTF-8 limit for the whole result. Returns a completed prefix and nextRequest when more IDs remain; a single over-budget full node refuses. |
includeMissingChildHistoryoptional | boolean | Include the former construct kind and a bounded source label for missing required children. Labels come from immutable history and are never inserted into source. |
includeNavigationoptional | boolean | Include containing declarations, callable signatures, and semantic navigation facts. Omitted by default to keep reads limited to the requested structure. When the containing declaration and callable are the same node, only containingCallable carries its signature. |
Example request
{
"nodeIds": [
"48192"
],
"detail": "auto"
}For the complete usage contract, call pando-guide({"topic":"read-node"}).
Full request schema
{
"type": "object",
"properties": {
"snapshotId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Defaults to the current head, like browse-code and the mutations."
},
"nodeIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"minItems": 1,
"maxItems": 20,
"description": "Exact durable node IDs to read, in desired result order."
},
"detail": {
"type": "string",
"description": "auto returns full code when it fits and otherwise an outline; outline always compacts; full requires the exact complete node.",
"enum": [
"auto",
"outline",
"full"
]
},
"maxBytes": {
"type": "integer",
"minimum": 0,
"description": "UTF-8 limit for the whole result. Returns a completed prefix and nextRequest when more IDs remain; a single over-budget full node refuses."
},
"includeMissingChildHistory": {
"type": "boolean",
"default": false,
"description": "Include the former construct kind and a bounded source label for missing required children. Labels come from immutable history and are never inserted into source."
},
"includeNavigation": {
"type": "boolean",
"default": false,
"description": "Include containing declarations, callable signatures, and semantic navigation facts. Omitted by default to keep reads limited to the requested structure. When the containing declaration and callable are the same node, only containingCallable carries its signature."
}
},
"required": [
"nodeIds"
],
"additionalProperties": false
}pando-guidepandō guide
Load the start guide or the complete contract for one tool.
Parameters
| Name | Type | Details |
|---|---|---|
topicrequired | string | Values: start, browse-code, read-node, insert, transform-nodes, delete-symbol-and-refs, rename-symbol-and-refs, change-callable-parameters-and-invocations, replace-opaque-values, write-entry, history, shell, read-entry |
Example request
{
"topic": "start"
}For the complete usage contract, call pando-guide({"topic":"start"}).
Full request schema
{
"type": "object",
"properties": {
"topic": {
"type": "string",
"enum": [
"start",
"browse-code",
"read-node",
"insert",
"transform-nodes",
"delete-symbol-and-refs",
"rename-symbol-and-refs",
"change-callable-parameters-and-invocations",
"replace-opaque-values",
"write-entry",
"history",
"shell",
"read-entry"
]
}
},
"required": [
"topic"
],
"additionalProperties": false
}Structural changes
5 toolsinsertInsert, move, or wrap code
Insert genuinely new code at a structural anchor, replace a child, fill a missing child, or create a source file. Move or adopt existing nodes by ID to retain their identity.
Parameters
| Name | Type | Details |
|---|---|---|
nodeIdconditional | string | Exact durable node used as the insertion boundary, body owner, or replacement target. |
positionconditional | string | before/after address a value in a supported child list. replace accepts a list value or scalar child (condition, expression, type, binary operator, or statement body), retaining its parent and siblings. body-start/body-end address statement, member, object-property, or array-element lists. New syntax receives new IDs; adopt explicitly retains existing roots. |
codeconditional | string | Genuinely new source syntax. A scalar slot requires one nonempty value of its grammar. An empty string with position=replace removes a list value; required scalar slots cannot be left empty. Existing syntax to retain is named only through adopt. |
editsconditional | array | Up to 200 edits execute in request order against the latest successful snapshot; at most 4 MiB of new source. Each smallest required atomic group publishes separately, failures are isolated, and repeated anchors are allowed while their IDs survive. Result pages contain at most 20 outcomes; all requested edits execute before paging. The receipt identifies the pre-batch snapshot for restoration. |
compilerCheckconditional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
roleconditional | string | For fill-child, the exact missing role returned by read-node. |
predecessorNodeIdconditional | string | For fill-child, the historical child ID that distinguishes the missing slot under nodeId. |
createNewFileconditional | boolean | Set true to create an absent source file and insert its complete initial code atomically. Requires parentDirectoryId and name, without nodeId, position, or edits. Existing names refuse. Defaults to false; file destinations without this flag refuse with an explanation. |
parentDirectoryIdconditional | string | For createNewFile=true only: root or the durable ID of a selected parent directory. Missing parents refuse; no automatic directory creation. |
nameconditional | string | For createNewFile=true only: one new source filename, never a path. Use language for a nonstandard extension. An existing entry of any kind refuses. |
modeconditional | string | For createNewFile=true only: optional octal mode, default 0644. |
languageconditional | string | For createNewFile=true only: explicitly classify the new file as TypeScript or JavaScript even with a nonstandard extension. Only ts/js are enabled in this build. Other language files remain opaque entries accessible through read-entry and write-entry. |
adoptconditional | array | One or more independent attachments to the same new fragment, published atomically. Existing roots may be noncontiguous. Roots and destinations must be distinct and nonoverlapping; at most 200 roots total. A scalar source must be replaced or lie inside the construct being replaced. code supplies only new syntax. compilerCheck=true also preserves bindings. |
existingNodeIdconditional | string | Existing subtree to relocate, retaining every node ID. Supply targetSequenceId and targetIndex, without code, nodeId, position, edits, or adopt. |
targetSequenceIdconditional | string | Durable ID of the existing destination child sequence. Discover it with browse-code include:["editing"]. |
targetIndexconditional | integer | Zero-based destination value index after removing the moved root from its source; commas do not count. |
Example request
{
"nodeId": "48192",
"position": "before",
"code": "const started = Date.now();"
}For the complete usage contract, call pando-guide({"topic":"insert"}).
Full request schema
{
"type": "object",
"properties": {
"nodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Exact durable node used as the insertion boundary, body owner, or replacement target."
},
"position": {
"type": "string",
"enum": [
"before",
"after",
"body-start",
"body-end",
"replace",
"fill-child"
],
"description": "before/after address a value in a supported child list. replace accepts a list value or scalar child (condition, expression, type, binary operator, or statement body), retaining its parent and siblings. body-start/body-end address statement, member, object-property, or array-element lists. New syntax receives new IDs; adopt explicitly retains existing roots."
},
"code": {
"type": "string",
"description": "Genuinely new source syntax. A scalar slot requires one nonempty value of its grammar. An empty string with position=replace removes a list value; required scalar slots cannot be left empty. Existing syntax to retain is named only through adopt."
},
"edits": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"description": "Up to 200 edits execute in request order against the latest successful snapshot; at most 4 MiB of new source. Each smallest required atomic group publishes separately, failures are isolated, and repeated anchors are allowed while their IDs survive. Result pages contain at most 20 outcomes; all requested edits execute before paging. The receipt identifies the pre-batch snapshot for restoration.",
"items": {
"type": "object",
"properties": {
"nodeId": {
"$ref": "#/properties/nodeId"
},
"position": {
"$ref": "#/properties/position"
},
"code": {
"$ref": "#/properties/code"
},
"role": {
"$ref": "#/properties/role"
},
"predecessorNodeId": {
"$ref": "#/properties/predecessorNodeId"
},
"adopt": {
"$ref": "#/properties/adopt"
}
},
"required": [
"nodeId",
"position",
"code"
],
"additionalProperties": false
}
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
},
"role": {
"type": "string",
"description": "For fill-child, the exact missing role returned by read-node."
},
"predecessorNodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "For fill-child, the historical child ID that distinguishes the missing slot under nodeId."
},
"createNewFile": {
"type": "boolean",
"default": false,
"description": "Set true to create an absent source file and insert its complete initial code atomically. Requires parentDirectoryId and name, without nodeId, position, or edits. Existing names refuse. Defaults to false; file destinations without this flag refuse with an explanation."
},
"parentDirectoryId": {
"type": "string",
"pattern": "^(root|[1-9][0-9]*)quot;,
"description": "For createNewFile=true only: root or the durable ID of a selected parent directory. Missing parents refuse; no automatic directory creation."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "For createNewFile=true only: one new source filename, never a path. Use language for a nonstandard extension. An existing entry of any kind refuses."
},
"mode": {
"type": "string",
"pattern": "^[0-7]{4}quot;,
"description": "For createNewFile=true only: optional octal mode, default 0644."
},
"language": {
"type": "string",
"enum": [
"ts",
"js"
],
"description": "For createNewFile=true only: explicitly classify the new file as TypeScript or JavaScript even with a nonstandard extension. Only ts/js are enabled in this build. Other language files remain opaque entries accessible through read-entry and write-entry."
},
"adopt": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"description": "One or more independent attachments to the same new fragment, published atomically. Existing roots may be noncontiguous. Roots and destinations must be distinct and nonoverlapping; at most 200 roots total. A scalar source must be replaced or lie inside the construct being replaced. code supplies only new syntax. compilerCheck=true also preserves bindings.",
"items": {
"type": "object",
"description": "Attach these existing roots, in the supplied order, to one child slot or empty child list in the new fragment.",
"properties": {
"nodeIds": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"destination": {
"type": "object",
"description": "Address inside the original new fragment, before any attachments. rootIndex selects a zero-based fragment root; childIndexPath follows concrete child indices, including punctuation. For try {} finally {}, [1,1] selects the try statements list and [3,1] selects the finally statements list. For if (true) {} else {}, [2] selects the condition placeholder, [4,1] the then statements list, and [6,1] the else statements list. A scalar destination requires one existing root.",
"properties": {
"rootIndex": {
"type": "integer",
"minimum": 0
},
"childIndexPath": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"items": {
"type": "integer",
"minimum": 0
},
"description": "Ordered zero-based concrete child indices from rootIndex to an empty list or a new scalar placeholder. Every path is resolved before any attachment."
}
},
"required": [
"rootIndex",
"childIndexPath"
],
"additionalProperties": false
}
},
"required": [
"nodeIds",
"destination"
],
"additionalProperties": false
}
},
"existingNodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Existing subtree to relocate, retaining every node ID. Supply targetSequenceId and targetIndex, without code, nodeId, position, edits, or adopt."
},
"targetSequenceId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Durable ID of the existing destination child sequence. Discover it with browse-code include:[\"editing\"]."
},
"targetIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based destination value index after removing the moved root from its source; commas do not count."
}
},
"oneOf": [
{
"required": [
"nodeId",
"position",
"code"
],
"not": {
"required": [
"edits"
]
},
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"parentDirectoryId"
]
},
{
"required": [
"name"
]
},
{
"required": [
"mode"
]
},
{
"required": [
"language"
]
}
]
}
},
{
"not": {
"anyOf": [
{
"required": [
"existingNodeId"
]
},
{
"required": [
"targetSequenceId"
]
},
{
"required": [
"targetIndex"
]
}
]
}
}
]
},
{
"required": [
"edits"
],
"not": {
"anyOf": [
{
"required": [
"nodeId"
]
},
{
"required": [
"position"
]
},
{
"required": [
"code"
]
},
{
"required": [
"adopt"
]
}
]
},
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"parentDirectoryId"
]
},
{
"required": [
"name"
]
},
{
"required": [
"mode"
]
},
{
"required": [
"language"
]
}
]
}
},
{
"not": {
"anyOf": [
{
"required": [
"existingNodeId"
]
},
{
"required": [
"targetSequenceId"
]
},
{
"required": [
"targetIndex"
]
}
]
}
}
]
},
{
"required": [
"parentDirectoryId",
"name",
"code"
],
"not": {
"anyOf": [
{
"required": [
"nodeId"
]
},
{
"required": [
"position"
]
},
{
"required": [
"edits"
]
},
{
"required": [
"role"
]
},
{
"required": [
"predecessorNodeId"
]
},
{
"required": [
"adopt"
]
}
]
},
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"existingNodeId"
]
},
{
"required": [
"targetSequenceId"
]
},
{
"required": [
"targetIndex"
]
}
]
}
}
]
},
{
"required": [
"existingNodeId",
"targetSequenceId",
"targetIndex"
],
"properties": {
"compilerCheck": {
"type": "boolean"
},
"createNewFile": {
"const": false
}
},
"not": {
"anyOf": [
{
"required": [
"nodeId"
]
},
{
"required": [
"position"
]
},
{
"required": [
"code"
]
},
{
"required": [
"edits"
]
},
{
"required": [
"adopt"
]
},
{
"required": [
"role"
]
},
{
"required": [
"predecessorNodeId"
]
},
{
"required": [
"parentDirectoryId"
]
},
{
"required": [
"name"
]
},
{
"required": [
"mode"
]
},
{
"required": [
"language"
]
}
]
}
}
],
"additionalProperties": false,
"examples": [
{
"nodeId": "48192",
"position": "before",
"code": "const started = Date.now();"
},
{
"existingNodeId": "48192",
"targetSequenceId": "73002",
"targetIndex": 3
},
{
"nodeId": "48192",
"position": "before",
"code": "try {} finally {}",
"adopt": [
{
"nodeIds": [
"48192",
"48193"
],
"destination": {
"rootIndex": 0,
"childIndexPath": [
1,
1
]
}
}
],
"compilerCheck": true
}
]
}transform-nodesTransform nodes
Change tokens, leading trivia, or child-sequence ordering by node ID. Use the structural operation that expresses your intent instead of replacing surviving code as text.
Parameters
| Name | Type | Details |
|---|---|---|
actionsrequired | array | Execute actions in request order. Each action sees earlier successful changes; a failed action leaves its atomic group unchanged and later actions continue. |
compilerCheckoptional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"actions": [
{
"action": "replace-leading-trivia",
"nodeId": "48192",
"trivia": "\n// Record the start time.\n"
}
]
}For the complete usage contract, call pando-guide({"topic":"transform-nodes"}).
Full request schema
{
"type": "object",
"properties": {
"actions": {
"type": "array",
"description": "Execute actions in request order. Each action sees earlier successful changes; a failed action leaves its atomic group unchanged and later actions continue.",
"minItems": 1,
"maxItems": 200,
"items": {
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"replace-token"
]
},
"nodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"token": {
"type": "string",
"description": "Exactly one new token value of the existing syntax kind. Cannot change a keyword into an identifier or replace a compound type/expression."
}
},
"required": [
"action",
"nodeId",
"token"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"replace-leading-trivia"
]
},
"nodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"trivia": {
"type": "string"
}
},
"required": [
"action",
"nodeId",
"trivia"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"permute-child-sequence"
]
},
"nodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"childNodeIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"action",
"nodeId",
"childNodeIds"
],
"additionalProperties": false
}
]
}
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"required": [
"actions"
],
"additionalProperties": false
}delete-symbol-and-refsDelete symbol and references
Delete symbols with their complete reference closure. Coupled components are atomic. Read applied and refused components, blockers, and missing children in the receipt.
Parameters
| Name | Type | Details |
|---|---|---|
symbolIdsconditional | array | Durable symbol IDs to delete. Duplicates are canonicalized. |
pageconditional | object | Bound the initial four result streams, or continue exactly one historical stream without mutating. |
compilerCheckconditional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"symbolIds": [
"73001"
]
}For the complete usage contract, call pando-guide({"topic":"delete-symbol-and-refs"}).
Full request schema
{
"type": "object",
"properties": {
"symbolIds": {
"type": "array",
"minItems": 1,
"description": "Durable symbol IDs to delete. Duplicates are canonicalized.",
"items": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"page": {
"type": "object",
"description": "Bound the initial four result streams, or continue exactly one historical stream without mutating.",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
},
"continuation": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"resultId": {
"type": "string",
"pattern": "^result_[0-9a-f-]{36}quot;
},
"field": {
"type": "string",
"enum": [
"appliedComponents",
"refusedComponents",
"missingChildren",
"blockers"
]
}
},
"additionalProperties": false
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"oneOf": [
{
"type": "object",
"required": [
"symbolIds"
],
"not": {
"required": [
"page"
],
"properties": {
"page": {
"required": [
"continuation"
]
}
}
}
},
{
"type": "object",
"required": [
"page"
],
"properties": {
"page": {
"required": [
"resultId",
"field",
"continuation"
]
}
},
"not": {
"anyOf": [
{
"required": [
"symbolIds"
]
}
]
}
}
],
"additionalProperties": false
}rename-symbol-and-refsRename symbol and references
Rename a durable symbol and its exact coupled spelling component. References render the selected name; identifier nodes and existing document versions are not rewritten.
Parameters
| Name | Type | Details |
|---|---|---|
symbolIdrequired | string | The durable semantic symbol whose complete compiler-coupled spelling component is renamed. |
newNamerequired | string | The new spelling. With compiler checking enabled, reserved words and non-identifiers are rejected. |
compilerCheckoptional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"symbolId": "73001",
"newName": "fetchProfile"
}For the complete usage contract, call pando-guide({"topic":"rename-symbol-and-refs"}).
Full request schema
{
"type": "object",
"properties": {
"symbolId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "The durable semantic symbol whose complete compiler-coupled spelling component is renamed."
},
"newName": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "The new spelling. With compiler checking enabled, reserved words and non-identifiers are rejected."
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"required": [
"symbolId",
"newName"
],
"additionalProperties": false
}change-callable-parameters-and-invocationsChange callable parameters and invocations
Change a callable’s parameters and exact invocations together. Keep existing parameters by node ID; supply text only for new parameters and any required invocation arguments.
Parameters
| Name | Type | Details |
|---|---|---|
callableSymbolIdrequired | string | Durable callable symbol ID. |
signatureAnchorNodeIdrequired | string | Exact durable compiler declaration node belonging to callableSymbolId that selects the positional anchor. |
finalParametersrequired | array | The complete final positional parameter sequence in order. |
compilerCheckoptional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"callableSymbolId": "73001",
"signatureAnchorNodeId": "48192",
"finalParameters": [
{
"parameterNodeId": "48194"
},
{
"newParameter": "trace: boolean",
"invocationArgument": "false"
}
]
}For the complete usage contract, call pando-guide({"topic":"change-callable-parameters-and-invocations"}).
Full request schema
{
"type": "object",
"properties": {
"callableSymbolId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Durable callable symbol ID."
},
"signatureAnchorNodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Exact durable compiler declaration node belonging to callableSymbolId that selects the positional anchor."
},
"finalParameters": {
"type": "array",
"minItems": 0,
"maxItems": 200,
"description": "The complete final positional parameter sequence in order.",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"parameterNodeId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
}
},
"required": [
"parameterNodeId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"newParameter": {
"type": "string",
"minLength": 1,
"maxLength": 1048576
},
"invocationArgument": {
"type": "string",
"minLength": 1,
"maxLength": 1048576
}
},
"required": [
"newParameter"
],
"additionalProperties": false
}
]
}
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"required": [
"callableSymbolId",
"signatureAnchorNodeId",
"finalParameters"
],
"additionalProperties": false
}Repository entries
3 toolsreplace-opaque-valuesReplace opaque values
Replace captured non-code values atomically. Each replacement carries a document ID, its expected version, and base64 content.
Parameters
| Name | Type | Details |
|---|---|---|
replacementsrequired | array | One through 16 complete values. Obtain documentId and expectedDocumentVersionId from browse-code at the selected head. |
compilerCheckoptional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"replacements": [
{
"documentId": "271",
"expectedDocumentVersionId": "981",
"contentBase64": "aGVsbG8K"
}
]
}For the complete usage contract, call pando-guide({"topic":"replace-opaque-values"}).
Full request schema
{
"type": "object",
"properties": {
"replacements": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"description": "One through 16 complete values. Obtain documentId and expectedDocumentVersionId from browse-code at the selected head.",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"expectedDocumentVersionId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"contentBase64": {
"type": "string"
}
},
"required": [
"documentId",
"expectedDocumentVersionId",
"contentBase64"
],
"additionalProperties": false
}
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"required": [
"replacements"
],
"additionalProperties": false
}write-entryWrite entry
Create non-code files, directories, symlinks, or hardlinks; replace or delete permitted entries with an expected document version. Create source files with insert and createNewFile=true; edit managed source through structural operations.
Parameters
| Name | Type | Details |
|---|---|---|
parentDirectoryIdconditional | string | root or the durable document ID of a selected directory. |
nameconditional | string | One entry name, never a path. |
kindconditional | string | file creates a regular value, directory a container, symlink exact target bytes, and hardlink another opaque regular-file identity. |
textconditional | string | Complete genuinely new UTF-8 text for a non-code regular file. Recognized source-code filenames refuse; use insert with createNewFile=true. |
contentBase64conditional | string | Complete genuinely new non-code regular-file bytes as canonical base64; maximum decoded size 16 MiB. Recognized source-code filenames refuse. |
targetBase64conditional | string | Exact symbolic-link target bytes as canonical base64: 1 through 1023 decoded bytes with no embedded NUL. |
targetDocumentIdconditional | string | Selected opaque regular-file durable document ID for a hard link. Managed/native source targets refuse. |
modeconditional | string | Optional four-digit octal mode such as 0644, 0755, or 0777. |
actionconditional | string | Explicit intent. Existing entries are never implicitly overwritten. |
documentIdconditional | string | See the request schema and operation guide. |
expectedDocumentVersionIdconditional | string | See the request schema and operation guide. |
compilerCheckconditional | boolean | Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus="unchecked". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results. |
Example request
{
"parentDirectoryId": "root",
"name": "notes.txt",
"kind": "file",
"text": "Project notes\n"
}For the complete usage contract, call pando-guide({"topic":"write-entry"}).
Full request schema
{
"type": "object",
"properties": {
"parentDirectoryId": {
"type": "string",
"pattern": "^(root|[1-9][0-9]*)quot;,
"description": "root or the durable document ID of a selected directory."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "One entry name, never a path."
},
"kind": {
"type": "string",
"description": "file creates a regular value, directory a container, symlink exact target bytes, and hardlink another opaque regular-file identity.",
"enum": [
"file",
"directory",
"symlink",
"hardlink"
]
},
"text": {
"type": "string",
"description": "Complete genuinely new UTF-8 text for a non-code regular file. Recognized source-code filenames refuse; use insert with createNewFile=true."
},
"contentBase64": {
"type": "string",
"description": "Complete genuinely new non-code regular-file bytes as canonical base64; maximum decoded size 16 MiB. Recognized source-code filenames refuse."
},
"targetBase64": {
"type": "string",
"description": "Exact symbolic-link target bytes as canonical base64: 1 through 1023 decoded bytes with no embedded NUL."
},
"targetDocumentId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Selected opaque regular-file durable document ID for a hard link. Managed/native source targets refuse."
},
"mode": {
"type": "string",
"pattern": "^[0-7]{4}quot;,
"description": "Optional four-digit octal mode such as 0644, 0755, or 0777."
},
"action": {
"type": "string",
"enum": [
"create",
"replace",
"delete"
],
"default": "create",
"description": "Explicit intent. Existing entries are never implicitly overwritten."
},
"documentId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"expectedDocumentVersionId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"compilerCheck": {
"type": "boolean",
"default": true,
"description": "Compiler checking defaults to true. Explicit compilerCheck=false skips compiler and binding validation, invalidates affected semantic facts, and reports semanticStatus=\"unchecked\". Syntax and durable identity still define the operation; no type, binding, or reference-completeness guarantee is made for unchecked results."
}
},
"additionalProperties": false,
"oneOf": [
{
"required": [
"parentDirectoryId",
"name",
"kind"
],
"properties": {
"action": {
"const": "create"
}
},
"not": {
"anyOf": [
{
"required": [
"documentId"
]
},
{
"required": [
"expectedDocumentVersionId"
]
}
]
}
},
{
"required": [
"action",
"documentId",
"expectedDocumentVersionId"
],
"properties": {
"action": {
"const": "replace"
}
},
"oneOf": [
{
"required": [
"text"
],
"not": {
"required": [
"contentBase64"
]
}
},
{
"required": [
"contentBase64"
],
"not": {
"required": [
"text"
]
}
}
],
"not": {
"anyOf": [
{
"required": [
"parentDirectoryId"
]
},
{
"required": [
"name"
]
},
{
"required": [
"kind"
]
},
{
"required": [
"targetBase64"
]
},
{
"required": [
"targetDocumentId"
]
},
{
"required": [
"mode"
]
}
]
}
},
{
"required": [
"action",
"documentId",
"expectedDocumentVersionId"
],
"properties": {
"action": {
"const": "delete"
}
},
"not": {
"anyOf": [
{
"required": [
"parentDirectoryId"
]
},
{
"required": [
"name"
]
},
{
"required": [
"kind"
]
},
{
"required": [
"text"
]
},
{
"required": [
"contentBase64"
]
},
{
"required": [
"targetBase64"
]
},
{
"required": [
"targetDocumentId"
]
},
{
"required": [
"mode"
]
}
]
}
}
]
}read-entryRead entry
Read captured or rendered file bytes, directory children, or a symlink target by document ID. Follow nextRequest for bounded byte ranges or directory pages.
Parameters
| Name | Type | Details |
|---|---|---|
documentIdrequired | string | Durable selected document ID, or root for repository directory children. Obtain IDs from browse-code or mutation receipts. |
snapshotIdoptional | string | Optional committed snapshot ID. Defaults to the current committed head; continuations pin the selected snapshot. |
offsetoptional | integer | Zero-based byte offset for file contents or symlink target bytes; not a character or line offset. |
maxBytesoptional | integer | Maximum returned content bytes. Native source may require rendering the full selected document before taking this range. |
encodingoptional | string | auto returns text only for a complete valid UTF-8 range, otherwise base64. utf8 refuses invalid or split characters. base64 is always byte-exact. |
limitoptional | integer | Directory children per page, at most 20. Follow nextRequest until exhausted is true. |
afterDocumentIdoptional | string | Directory continuation coordinate. Prefer copying nextRequest verbatim so the snapshot stays pinned. |
Example request
{
"documentId": "271",
"maxBytes": 16384
}For the complete usage contract, call pando-guide({"topic":"read-entry"}).
Full request schema
{
"type": "object",
"properties": {
"documentId": {
"type": "string",
"pattern": "^(root|[1-9][0-9]*)quot;,
"description": "Durable selected document ID, or root for repository directory children. Obtain IDs from browse-code or mutation receipts."
},
"snapshotId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Optional committed snapshot ID. Defaults to the current committed head; continuations pin the selected snapshot."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Zero-based byte offset for file contents or symlink target bytes; not a character or line offset."
},
"maxBytes": {
"type": "integer",
"minimum": 1,
"maximum": 1048576,
"default": 16384,
"description": "Maximum returned content bytes. Native source may require rendering the full selected document before taking this range."
},
"encoding": {
"type": "string",
"enum": [
"auto",
"utf8",
"base64"
],
"default": "auto",
"description": "auto returns text only for a complete valid UTF-8 range, otherwise base64. utf8 refuses invalid or split characters. base64 is always byte-exact."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Directory children per page, at most 20. Follow nextRequest until exhausted is true."
},
"afterDocumentId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Directory continuation coordinate. Prefer copying nextRequest verbatim so the snapshot stays pinned."
}
},
"required": [
"documentId"
],
"additionalProperties": false
}History & execution
2 toolshistoryHistory
Browse automatically created semantic commits, annotate history, page operation receipts, or select a prior snapshot. Each committed structural change records its snapshot without an extra agent step. Select an earlier snapshot and continue on a different path; no undo sequence is needed, and later history remains available.
Parameters
| Name | Type | Details |
|---|---|---|
selectconditional | string | Exact committed snapshot to select as the working head. |
annotateconditional | string | Exact committed snapshot receiving append-only metadata facts. |
titleconditional | string | Human-readable snapshot title, for example Stable service lifecycle. |
labelconditional | string | Short branch-like label, for example before-api-migration. |
addTagsconditional | array | Tags to append, for example verified or benchmark-baseline. |
removeTagsconditional | array | Existing tags to retire from this selected annotation value. |
continuationconditional | string | Authenticated continuation returned by a prior history page. |
filterconditional | object | Filter ancestry entries before collecting the 20-row page. Arrays are OR within a field; types, operations, since, and until are ANDed. Alternate branch tips remain topology summaries. |
includeconditional | array | effects reads compact count/status/result coordinates from stored receipts only for returned ancestry entries. |
resultPageconditional | choice | Retrieve one immutable retained result page directly, at most 20 items without probing item 21. Insert creation and relocation fields read committed immutable receipts. Transform outcomes/effects and insert relocation diagnostic/refusal fields read rows captured by the original attempt and never rerun the compiler or mutation. For transform-nodes, omit continuation to reopen page one from a known resultId; pass each later authenticated continuation verbatim. |
Example request
{
"select": "17"
}For the complete usage contract, call pando-guide({"topic":"history"}).
Full request schema
{
"type": "object",
"properties": {
"select": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Exact committed snapshot to select as the working head."
},
"annotate": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;,
"description": "Exact committed snapshot receiving append-only metadata facts."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Human-readable snapshot title, for example Stable service lifecycle."
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Short branch-like label, for example before-api-migration."
},
"addTags": {
"type": "array",
"maxItems": 20,
"description": "Tags to append, for example verified or benchmark-baseline.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"removeTags": {
"type": "array",
"maxItems": 20,
"description": "Existing tags to retire from this selected annotation value.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"continuation": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Authenticated continuation returned by a prior history page."
},
"filter": {
"type": "object",
"description": "Filter ancestry entries before collecting the 20-row page. Arrays are OR within a field; types, operations, since, and until are ANDed. Alternate branch tips remain topology summaries.",
"properties": {
"types": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"semantic",
"node",
"entry",
"opaque",
"indexing",
"history",
"compatibility",
"discovery"
]
}
},
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"since": {
"type": "string",
"format": "date-time"
},
"until": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"include": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"uniqueItems": true,
"description": "effects reads compact count/status/result coordinates from stored receipts only for returned ancestry entries.",
"items": {
"type": "string",
"enum": [
"effects"
]
}
},
"resultPage": {
"description": "Retrieve one immutable retained result page directly, at most 20 items without probing item 21. Insert creation and relocation fields read committed immutable receipts. Transform outcomes/effects and insert relocation diagnostic/refusal fields read rows captured by the original attempt and never rerun the compiler or mutation. For transform-nodes, omit continuation to reopen page one from a known resultId; pass each later authenticated continuation verbatim.",
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"const": "insert"
},
"snapshotId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"transactionId": {
"type": "string",
"pattern": "^[1-9][0-9]*quot;
},
"field": {
"type": "string",
"enum": [
"createdNodeIds",
"changedNodeIds",
"removedSelectionRootNodeIds",
"affectedDocumentIds",
"exactCompilerVersions",
"edits",
"documents",
"movedNodeIds"
]
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"operation",
"snapshotId",
"transactionId",
"field"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation": {
"const": "transform-nodes"
},
"resultId": {
"type": "string",
"pattern": "^result_[0-9a-f-]{36}quot;
},
"field": {
"type": "string",
"enum": [
"outcomes",
"effects"
]
},
"continuation": {
"type": "string",
"minLength": 1
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"operation",
"resultId",
"field"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation": {
"const": "insert"
},
"resultId": {
"type": "string",
"pattern": "^result_[0-9a-f-]{36}quot;
},
"field": {
"type": "string",
"enum": [
"moveDiagnosticDelta",
"moveBindingChanges",
"moveBlockingDiagnostics"
]
},
"continuation": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"operation",
"resultId",
"field",
"continuation"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation": {
"enum": [
"insert",
"transform-nodes"
]
},
"resultId": {
"type": "string",
"pattern": "^result_[0-9a-f-]{36}quot;
},
"field": {
"const": "steps"
},
"continuation": {
"type": "string",
"minLength": 1
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"operation",
"resultId",
"field"
],
"additionalProperties": false
}
]
}
},
"required": [],
"oneOf": [
{
"not": {
"anyOf": [
{
"required": [
"select"
]
},
{
"required": [
"annotate"
]
},
{
"required": [
"resultPage"
]
},
{
"required": [
"title"
]
},
{
"required": [
"label"
]
},
{
"required": [
"addTags"
]
},
{
"required": [
"removeTags"
]
}
]
}
},
{
"required": [
"select"
],
"not": {
"anyOf": [
{
"required": [
"annotate"
]
},
{
"required": [
"continuation"
]
},
{
"required": [
"filter"
]
},
{
"required": [
"include"
]
},
{
"required": [
"resultPage"
]
},
{
"required": [
"title"
]
},
{
"required": [
"label"
]
},
{
"required": [
"addTags"
]
},
{
"required": [
"removeTags"
]
}
]
}
},
{
"required": [
"annotate"
],
"anyOf": [
{
"required": [
"title"
]
},
{
"required": [
"label"
]
},
{
"required": [
"addTags"
]
},
{
"required": [
"removeTags"
]
}
],
"not": {
"anyOf": [
{
"required": [
"select"
]
},
{
"required": [
"continuation"
]
},
{
"required": [
"filter"
]
},
{
"required": [
"include"
]
},
{
"required": [
"resultPage"
]
}
]
}
},
{
"required": [
"resultPage"
],
"not": {
"anyOf": [
{
"required": [
"select"
]
},
{
"required": [
"annotate"
]
},
{
"required": [
"continuation"
]
},
{
"required": [
"filter"
]
},
{
"required": [
"include"
]
},
{
"required": [
"title"
]
},
{
"required": [
"label"
]
},
{
"required": [
"addTags"
]
},
{
"required": [
"removeTags"
]
}
]
}
}
],
"additionalProperties": false
}shellRun shell commands
Run builds and tests in the rendered sibling workspace. Start a job, then inspect status or bounded output using its jobId. Use pandō read and mutation tools for managed source.
Parameters
| Name | Type | Details |
|---|---|---|
actionrequired | string | Explicit job action. Only read returns output text. |
commandconditional | string | See the request schema and operation guide. |
timeoutMsconditional | integer | Default: 120000 |
jobIdconditional | string | See the request schema and operation guide. |
waitMsconditional | integer | Default: 0 |
streamconditional | string | Values: stdout, stderr |
offsetconditional | integer | Byte offset; reuse nextOffset. Must begin at a UTF-8 boundary. |
maxBytesconditional | integer | Default: 8192 |
Example request
{
"action": "start",
"command": "npm test",
"timeoutMs": 120000
}For the complete usage contract, call pando-guide({"topic":"shell"}).
Full request schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"start",
"status",
"read",
"cancel"
],
"description": "Explicit job action. Only read returns output text."
},
"command": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"timeoutMs": {
"type": "integer",
"minimum": 1000,
"maximum": 10800000,
"default": 120000
},
"jobId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}quot;
},
"waitMs": {
"type": "integer",
"minimum": 0,
"maximum": 30000,
"default": 0
},
"stream": {
"type": "string",
"enum": [
"stdout",
"stderr"
],
"default": "stdout"
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"default": 0,
"description": "Byte offset; reuse nextOffset. Must begin at a UTF-8 boundary."
},
"maxBytes": {
"type": "integer",
"minimum": 4,
"maximum": 65536,
"default": 8192
}
},
"required": [
"action"
],
"oneOf": [
{
"properties": {
"action": {
"const": "start"
}
},
"required": [
"command"
],
"not": {
"anyOf": [
{
"required": [
"jobId"
]
},
{
"required": [
"waitMs"
]
},
{
"required": [
"stream"
]
},
{
"required": [
"offset"
]
},
{
"required": [
"maxBytes"
]
}
]
}
},
{
"properties": {
"action": {
"const": "status"
}
},
"required": [
"jobId"
],
"not": {
"anyOf": [
{
"required": [
"command"
]
},
{
"required": [
"timeoutMs"
]
},
{
"required": [
"stream"
]
},
{
"required": [
"offset"
]
},
{
"required": [
"maxBytes"
]
}
]
}
},
{
"properties": {
"action": {
"const": "read"
}
},
"required": [
"jobId"
],
"not": {
"anyOf": [
{
"required": [
"command"
]
},
{
"required": [
"timeoutMs"
]
},
{
"required": [
"waitMs"
]
}
]
}
},
{
"properties": {
"action": {
"const": "cancel"
}
},
"required": [
"jobId"
],
"not": {
"anyOf": [
{
"required": [
"command"
]
},
{
"required": [
"timeoutMs"
]
},
{
"required": [
"waitMs"
]
},
{
"required": [
"stream"
]
},
{
"required": [
"offset"
]
},
{
"required": [
"maxBytes"
]
}
]
}
}
],
"additionalProperties": false
}