| name | fabric-exec |
| description | Reference for `fabric_exec` TypeScript programs: Pi core tool signatures, discovery, provider and MCP proxies, named strings, return shapes, and schema-driven error recovery. Load before the first Fabric call or after an argument-shape error. |
fabric_exec — core reference
One type-checked TS program in a fresh executor (isolated QuickJS by default). Only the return value reaches the model; print()/console.log go to the activity panel. π is not a tool.
pi core tools (full code mode only)
pi.<tool>(arg) — single arg: bare string (primary field) or options object. Multi-arg positional calls are accepted for grep/find (pattern, path, limit), write (path, content), and edit (path, oldText, newText); one-field tools (read/bash/ls) stay single-arg — a 2-arg call on those is a type error so the extra arg isn't silently dropped.
| Tool | Form | Returns |
|---|
read | path | {path,offset?,limit?} | string |
bash | command | {command,timeout?} | {ok,output,details} |
grep | pattern | {pattern,path?,glob?,ignoreCase?,literal?,context?,limit?} | (pattern, path?, limit?) | string |
find | pattern | {pattern,path?,limit?} | (pattern, path?, limit?) | string |
ls | path? | {path?,limit?} | string |
edit | {path,edits:[{oldText,newText}]} | {path,oldText,newText} | (path, oldText, newText) | {ok,output,details} |
write | {path,content} | (path, content) | {ok,output,details} |
Aliases (normalized to canonical before the host validates args): cmd/shell/cmdline→command, timeoutMs→timeout; query/regex/search→pattern; ic/caseInsensitive→ignoreCase; globPattern→glob; ctx→context; max→limit; file/dir→path; start→offset; old→oldText; new/replacement→newText; contents/body/text→content. Misspelled keys still fail the excess-property type check.
When a program needs a string containing literal ${...} (shell snippets, tool arguments, or grep patterns), do not use a TypeScript template literal: TypeScript will interpolate it. Use a plain quoted string or pass the content through strings and read it from π.key.
First-class provider calls
Use direct proxies when the action is known. No-argument actions such as schema.status(), state.get(), and compact.status() take no options object. Provider calls still cross the same registry validation, approval, audit, timeout, and cancellation path as generic calls.
Stable provider return shapes
All calls return promises. Fields ending in ? are optional; unknown marks provider data whose nested schema is not stable at this surface.
| Call | Resolves to |
|---|
memory.recall(args?) | {scope?,branches?,query?,queryMode?,matchedCount?,totalMatches?,totalItems?,segmentCount?,segments?,digestHits?,items?,page?,pageSize?,hasNext?,coverage?,text?,error?} |
memory.expand(args) | {session?,sourceHash?,branches?,lineageFingerprint?,expanded?:unknown[],error?} |
memory.sessions(args?) | {scope?,branches?,sessions?:SessionInfo[],error?}; slice result.sessions ?? [], not the wrapper |
state.transition(args) | {event:FabricMeshEvent,head:unknown} |
state.get() | {head,goal,complexity,certification,recentLabels:string[]} |
state.history(args?) | {transitions:unknown[],labels:string[],certifications:unknown[]} |
state.complexity(args?) | {files:ComplexityFile[],netDelta:number} |
state.verify(args?) | {certified,violated,certificationStatus,results,failures,certificate?,reportingError?,evidenceDigest,resultDigest} |
state.goal(args) | mesh state entry {key,value,version,updatedAt,updatedBy} |
state.checkGoal(args?) | {passed:boolean,output:string,exitCode:number|null,error?} |
schema.status() | {mode,certificateTtlMs,maxFiles,maxBytes,trustedCommands,generation,lastOutcome,hypotheses} |
schema.hypothesize(args) | {hypothesisId,status,state,fingerprint,generation} |
schema.verify(args) | {verified,hypothesisId,certificate?,issuedAt?,expiresAt?,reason?,results} |
schema.commit(args) | {outcome,transactionId,generation?,paths?,postconditions?,complexityReductionCertified?,stateTransition?,error?,rollbackError?} |
schema.abort(args) | {aborted:true,hypothesisId} |
compact.request(args?) | {requested:true,intent:{reason?,instructions?,preserve?,requestedBy,requestedAt}} |
compact.status() | {pending?:CompactIntent,last?:{at,requestedBy,status,summary?,tokensBefore?,estimatedTokensAfter?,error?}} |
compact.cancel() | {cancelled:true} |
SessionInfo is {id,file,cwd,mtime,entryCount,tier:"hot"|"cold",branches,lineageFingerprint}. Memory failures are returned in error: {code,message,...}; ambiguous-session failures may return only {error}. Check error before relying on optional success fields.
Dynamic provider return shapes
mcp.<sanitized_server>.<sanitized_tool>(args) resolves to the server-defined result, commonly {text:string,content:unknown[],structuredContent:unknown}; for example mcp.fal_ai.get_model_schema({ endpoint_id: "openai/gpt-image-2" }). See references/mcp.md.extensions.<tool>(args) in full code mode resolves to {content:Array<{type,text?,...}>,text:string,details?,isError:boolean,terminate?,source:{path,source,scope,origin,baseDir?}}.
The guest TypeScript declarations contain the complete argument and return contracts. For a discovered or dynamic action, use tools.describe({ref}); inspect outputSchema when supplied, otherwise treat the result as unknown.
tools — discovery & generic calls
Refs are namespaced (pi.grep, extensions.<tool>, mcp.<server>.<tool>, schema.<action>); bare names are rejected. tools.providers()→[{name,description}] · tools.search({query,limit?})→FabricAction[](ref,name,description,inputSchema,risk) · tools.describe({ref})→full FabricAction (read inputSchema first) · tools.call({ref,args?}) · tools.list({provider?,namespace?,query?,limit?}) · tools.models()→Pi [{provider,id,name,key}]; agents.models({runner:"claude"})→Claude Code runtime models with canonical claude/<value> keys. Use tools.call() for refs discovered or computed at runtime, or names that cannot use property access—not as the default for known actions. Calling a core-tool name on tools (e.g. tools.read(...)) throws with a hint to use pi.read(...).
Error recovery: read, describe, retry
Read the line-numbered error → await tools.describe({ref}) for the schema → match inputSchema, rerun (don't guess). Common mistakes: bare ref (grep→pi.grep); 2 positional args on read/bash/ls (use an options object — positional is supported only for grep/find/write/edit).
Orchestration surfaces (opt-in)
Multi-agent orchestration is opt-in: load /skill:fabric-workflow, /skill:fabric-council, /skill:fabric-rlm, or /skill:fabric-fusion (API detail in references/agents.md, references/mesh.md).
agents.main() returns the dashboard-owning root Pi session; agents.peers() lists other live root sessions in the shared project mesh as Peer <session-prefix> targets. Peers support agents.steer() and agents.followUp() by exact id.
Agent requests and persistent actors accept runner: "pi" | "claude". Pi is the default and is required for recursive: true, rlm.query(), and actors that must call Fabric or mesh APIs themselves. Claude invokes the official claude -p harness; it supports mapped Claude Code tools and host-managed persistent actors, but not recursive/direct Fabric APIs. Use agents.models({ runner: "claude" }) for runtime-enumerated claude/<value> model keys.
Omit timeoutMs for subagents and actors unless requesting longer than the configured subagents.timeoutMs (60 minutes by default). Per-call values below the configured default are ignored.
