pi-ptc-subagents 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/LICENSE +201 -0
- package/README.md +191 -0
- package/dist/index.d.ts +437 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3127 -0
- package/dist/index.js.map +1 -0
- package/package.json +93 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,437 @@
|
|
|
1
|
+
import { ExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { MessagePort } from "node:worker_threads";
|
|
3
|
+
//#region src/mode/ptc-mode.d.ts
|
|
4
|
+
/** The two surfaces this package exposes. `/ptc on` needs at least one of them active. */
|
|
5
|
+
export declare const PTC_MODE_TOOL_NAMES: readonly string[];
|
|
6
|
+
/**
|
|
7
|
+
* Tools that must all be present for the **automatic** entry path to proceed.
|
|
8
|
+
*
|
|
9
|
+
* These four are pi's default session surface (`agent-session.js`: "["read", "bash", "edit",
|
|
10
|
+
* "write"]"), so "all four present" means "this session was not narrowed". Comparing against
|
|
11
|
+
* `BUILTIN_BINDING_NAMES` instead would be wrong: that list is the set of names that *can* be
|
|
12
|
+
* bound, not what a default session has (`grep` / `find` / `ls` are bindable but off by default),
|
|
13
|
+
* so requiring all seven would misread every ordinary session as restricted and never turn on.
|
|
14
|
+
*/
|
|
15
|
+
export declare const MODE_REQUIRED_TOOL_NAMES: readonly string[];
|
|
16
|
+
/** `customType` for the persisted mode entry (`pi.appendEntry`). */
|
|
17
|
+
export declare const PTC_MODE_ENTRY_TYPE = "ptc-mode";
|
|
18
|
+
/** Footer status key (`ctx.ui.setStatus`). */
|
|
19
|
+
export declare const PTC_MODE_STATUS_KEY = "ptc-mode";
|
|
20
|
+
/** Config file name, resolved against pi's agent dir (`~/.pi/agent/`). */
|
|
21
|
+
export declare const PTC_MODE_CONFIG_FILE = "ptc.json";
|
|
22
|
+
/** How much of the loadout the mode hides. */
|
|
23
|
+
type ModeHideStrategy = "builtins-only" | "all-but-ptc";
|
|
24
|
+
/**
|
|
25
|
+
* Which tools the mode hides while it is on.
|
|
26
|
+
*
|
|
27
|
+
* - `"builtins-only"` (default) — hide the seven built-in tools; tools contributed by *other*
|
|
28
|
+
* extensions (`web_search`, `todo`, `subagent`, …) stay visible and directly callable. The
|
|
29
|
+
* model is forced to program for file and shell work, which is the bulk of a coding session,
|
|
30
|
+
* without losing capabilities this package cannot re-expose: extension tools have no bindings
|
|
31
|
+
* (`pi.getAllTools()` returns metadata only — no `execute`), so hiding one makes it
|
|
32
|
+
* unreachable for the whole session.
|
|
33
|
+
* - `"all-but-ptc"` — hide everything except the two PTC surfaces. Closest to a strict reading of
|
|
34
|
+
* DSH's preset, at the cost of making other extensions' tools unreachable until `/ptc off`.
|
|
35
|
+
*/
|
|
36
|
+
export declare const DEFAULT_HIDE_STRATEGY: ModeHideStrategy;
|
|
37
|
+
/** Live mode state. `base` / `ourLoadout` are `undefined` while the mode is off. */
|
|
38
|
+
interface PtcModeState {
|
|
39
|
+
enabled: boolean;
|
|
40
|
+
/** Loadout captured before the mode narrowed anything; bindings derive from this. */
|
|
41
|
+
base: readonly string[] | undefined;
|
|
42
|
+
/** Exactly the array handed to `setActiveTools`; a mismatch means someone else changed it. */
|
|
43
|
+
ourLoadout: readonly string[] | undefined;
|
|
44
|
+
}
|
|
45
|
+
/** Fresh, disabled state. */
|
|
46
|
+
export declare function initialModeState(): PtcModeState;
|
|
47
|
+
/**
|
|
48
|
+
* A persisted mode record lives in the session (`pi.appendEntry`), so `/ptc off` survives a
|
|
49
|
+
* resume and a `/reload` can put the loadout back the way it found it.
|
|
50
|
+
*/
|
|
51
|
+
interface PersistedModeState {
|
|
52
|
+
enabled: boolean;
|
|
53
|
+
base?: readonly string[];
|
|
54
|
+
}
|
|
55
|
+
/** Result of reading the opt-out config, with enough detail to warn about a broken file. */
|
|
56
|
+
interface DefaultModeConfig {
|
|
57
|
+
defaultMode: boolean;
|
|
58
|
+
source: "file" | "default" | "invalid";
|
|
59
|
+
error?: string;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Read `defaultMode` from the agent-dir config file.
|
|
63
|
+
*
|
|
64
|
+
* Absent file → on (this package is default-on by design; see CONTEXT.md). A present file with a
|
|
65
|
+
* non-boolean `defaultMode`, or unparseable JSON, is reported as `invalid` **and still defaults to
|
|
66
|
+
* on** — the caller should surface the problem rather than silently changing behavior.
|
|
67
|
+
*/
|
|
68
|
+
export declare function readDefaultModeConfig(agentDir: string): DefaultModeConfig;
|
|
69
|
+
/** Why the mode declined to turn on. Surfaced in the entry notification / debug logs. */
|
|
70
|
+
type ModeBlockReason = "not-tui" | "config-off" | "tools-unavailable" | "restricted-session";
|
|
71
|
+
/** Either the loadout to apply, or the reason the mode stayed off. */
|
|
72
|
+
type ModeEntryDecision = {
|
|
73
|
+
enter: true;
|
|
74
|
+
base: readonly string[];
|
|
75
|
+
loadout: readonly string[];
|
|
76
|
+
} | {
|
|
77
|
+
enter: false;
|
|
78
|
+
reason: ModeBlockReason;
|
|
79
|
+
};
|
|
80
|
+
/** Inputs to the entry decision. `active` is `pi.getActiveTools()` at decision time. */
|
|
81
|
+
interface ModeEntryInput {
|
|
82
|
+
/** `ctx.mode` — only `"tui"` participates. */
|
|
83
|
+
mode: string;
|
|
84
|
+
/** Resolved `defaultMode` from the config file. */
|
|
85
|
+
defaultMode: boolean;
|
|
86
|
+
/** The session's current tool loadout. */
|
|
87
|
+
active: readonly string[];
|
|
88
|
+
/** True for `/ptc on`, which overrides the config and the restricted-session policy. */
|
|
89
|
+
manual: boolean;
|
|
90
|
+
/** Overrides `DEFAULT_HIDE_STRATEGY` (tests, or a future settings surface). */
|
|
91
|
+
hide?: ModeHideStrategy | undefined;
|
|
92
|
+
}
|
|
93
|
+
/** Order- and duplicate-insensitive set equality, for loadout comparison. */
|
|
94
|
+
export declare function sameToolSet(a: readonly string[], b: readonly string[]): boolean;
|
|
95
|
+
/**
|
|
96
|
+
* The loadout applied while the mode is on, given the session's current one.
|
|
97
|
+
*
|
|
98
|
+
* Always keeps the PTC surfaces; what else survives depends on the hide strategy (see
|
|
99
|
+
* `DEFAULT_HIDE_STRATEGY`). Order follows `active`, so the visible list reads the way the session
|
|
100
|
+
* was configured.
|
|
101
|
+
*/
|
|
102
|
+
export declare function modeLoadout(active: readonly string[], hide: ModeHideStrategy): string[];
|
|
103
|
+
/**
|
|
104
|
+
* Decide whether the mode turns on for this session.
|
|
105
|
+
*
|
|
106
|
+
* The policy, in order:
|
|
107
|
+
* 1. **TUI only** — print / JSON / RPC sessions are never touched.
|
|
108
|
+
* 2. **Config** — `{"defaultMode": false}` opts out; `/ptc on` overrides it.
|
|
109
|
+
* 3. **PTC tools must exist** — if this session has them disabled, there is nothing to run.
|
|
110
|
+
* 4. **Explicit restriction wins** — a session launched with `--tools` / `--exclude-tools` /
|
|
111
|
+
* `--no-builtin-tools` that is missing any of `MODE_REQUIRED_TOOL_NAMES` (pi's default four)
|
|
112
|
+
* stays as launched. Narrowing *further* would be the extension overriding a deliberate user
|
|
113
|
+
* instruction, and the PTC surface would be degraded anyway (bindings = `BUILTIN ∩ base`).
|
|
114
|
+
* `/ptc on` overrides this: the manual path enters with the restricted loadout as `base`, so
|
|
115
|
+
* bindings stay inside the user's allowlist.
|
|
116
|
+
*/
|
|
117
|
+
export declare function decideModeEntry(input: ModeEntryInput): ModeEntryDecision;
|
|
118
|
+
/**
|
|
119
|
+
* Tool names the binding table should be built from.
|
|
120
|
+
*
|
|
121
|
+
* While the mode is on this is the base snapshot (so the built-ins the mode just hid remain
|
|
122
|
+
* callable from inside a program); otherwise it is simply the live loadout, i.e. T7's rule.
|
|
123
|
+
*/
|
|
124
|
+
export declare function bindingSource(state: PtcModeState, active: readonly string[]): readonly string[];
|
|
125
|
+
/**
|
|
126
|
+
* Whether the live loadout is no longer the one this mode wrote — i.e. another extension (or the
|
|
127
|
+
* user) took ownership of the tool set. Always false while the mode is off.
|
|
128
|
+
*/
|
|
129
|
+
export declare function detectExternalLoadoutChange(state: PtcModeState, active: readonly string[]): boolean;
|
|
130
|
+
/**
|
|
131
|
+
* Reconstruct the base loadout on `session_start`.
|
|
132
|
+
*
|
|
133
|
+
* Two shapes are possible:
|
|
134
|
+
* - The session is still narrowed from a previous run of this mode (a `/reload`, or a resumed
|
|
135
|
+
* session): the live loadout is a subset of the PTC tools and the persisted record says the mode
|
|
136
|
+
* was on. The persisted `base` is then authoritative — but only to *undo our own hiding*.
|
|
137
|
+
* - Otherwise the live loadout is whatever this pi process was launched with, and it wins. That is
|
|
138
|
+
* what keeps a new `--tools …` choice from being overridden by an older session's snapshot.
|
|
139
|
+
*/
|
|
140
|
+
export declare function resolveBaseOnStart(persisted: PersistedModeState | undefined, active: readonly string[]): {
|
|
141
|
+
base: readonly string[];
|
|
142
|
+
restoreFirst: boolean;
|
|
143
|
+
};
|
|
144
|
+
/**
|
|
145
|
+
* Build the system-visible briefing for the mode.
|
|
146
|
+
*
|
|
147
|
+
* Generated from the *actual* binding list rather than hardcoded, because bindings vary by session
|
|
148
|
+
* (`base` is whatever the session was launched with) and a stale list would have the model calling
|
|
149
|
+
* names that are not bound.
|
|
150
|
+
*/
|
|
151
|
+
export declare function buildModeInstruction(bindings: readonly string[], hide: ModeHideStrategy): string;
|
|
152
|
+
//#endregion
|
|
153
|
+
//#region src/mode/skills-section.d.ts
|
|
154
|
+
/** The two tools pi accepts as "this session can read a skill file". */
|
|
155
|
+
export declare const SKILL_READING_TOOL_NAMES: readonly string[];
|
|
156
|
+
/** What replaces it: the same instruction, in the only call form this session has. */
|
|
157
|
+
export declare const PTC_SKILL_LOAD_INSTRUCTION = "Use tools.read({ path }) inside a ptc_run_code program to load a skill's file when the task matches its description.";
|
|
158
|
+
/**
|
|
159
|
+
* Would pi withhold the skills section for this loadout?
|
|
160
|
+
*
|
|
161
|
+
* Mirrors the gate rather than guessing: it is true exactly when neither `read` nor `bash` is
|
|
162
|
+
* directly callable, which is the state the mode deliberately puts an ordinary session in.
|
|
163
|
+
*/
|
|
164
|
+
export declare function skillsSectionDropped(visibleTools: readonly string[]): boolean;
|
|
165
|
+
/**
|
|
166
|
+
* Build the `skills` section body (pi wraps it in `<skills>…</skills>` itself).
|
|
167
|
+
*
|
|
168
|
+
* Returns `""` when nothing is advertisable — pi's formatter filters out skills marked
|
|
169
|
+
* `disable-model-invocation`, which is the correct behaviour to inherit: those are
|
|
170
|
+
* `/skill:name`-only by design.
|
|
171
|
+
*
|
|
172
|
+
* `format` is injectable so a test can drive the reworded-header branch without patching pi.
|
|
173
|
+
*/
|
|
174
|
+
export declare function buildPtcSkillsSection(skills: readonly Skill[], format?: (skills: Skill[], fileReadTool?: "read" | "bash") => string): string;
|
|
175
|
+
//#endregion
|
|
176
|
+
//#region src/runtime/limits.d.ts
|
|
177
|
+
/**
|
|
178
|
+
* PTC run limits and spawn-time hardening, in one frozen `DEFAULT_CONFIG`.
|
|
179
|
+
*
|
|
180
|
+
* The numbers are DSH's (`dsh-v0.1.6-alpha.2`, `@deepseek-ai/dsh-ptc-runtime-node`)
|
|
181
|
+
* carried over verbatim — see ADR-0003 (output budget), ADR-0004 (pending calls) and
|
|
182
|
+
* ADR-0005 (execution boundary, F1–F4). Tests assert against these constants rather
|
|
183
|
+
* than repeating the literals, so a future re-sync only has to change this file.
|
|
184
|
+
*
|
|
185
|
+
* Deliberately absent:
|
|
186
|
+
* - `syncTimeoutMs` / `maxConcurrentAgents` / `maxTotalAgents` — workflow-engine caps
|
|
187
|
+
* for a cooperative VM and for `agent()`. We run the program directly in the worker
|
|
188
|
+
* realm (no VM) and ship no `agent()` (G1 #13 → B), so there is nothing to cap.
|
|
189
|
+
* - `sandbox-unavailable` is not an error kind either: ADR-0007 ships no OS sandbox.
|
|
190
|
+
*/
|
|
191
|
+
/** The two worker surfaces. Each run gets a fresh worker with exactly one of them. */
|
|
192
|
+
type PtcSurface = "run_code" | "workflow";
|
|
193
|
+
interface PtcConfig {
|
|
194
|
+
/** Default elapsed deadline for a run, including nested binding waits (R1 §1). */
|
|
195
|
+
timeoutMs: number;
|
|
196
|
+
/** Ceiling the requested deadline is clamped to. */
|
|
197
|
+
maxTimeoutMs: number;
|
|
198
|
+
/** Joint budget for serialized logs + completion value (ADR-0003). */
|
|
199
|
+
maxOutputBytes: number;
|
|
200
|
+
/** Cap on a single control frame, either direction (R1 §1). */
|
|
201
|
+
maxMessageBytes: number;
|
|
202
|
+
/** Admission control for simultaneously in-flight worker→host binding calls (ADR-0004). */
|
|
203
|
+
maxPendingCalls: number;
|
|
204
|
+
/** Concurrent binding dispatches; DSH's `maxParallelSubCalls` (ADR-0004 consequence).
|
|
205
|
+
* Renamed in spirit by ADR-0016 section 2: the cap that really matters for
|
|
206
|
+
* resource safety is the per-run `dispatchConcurrency` below. This field
|
|
207
|
+
* is kept for backward compatibility (and for the in-process builtin
|
|
208
|
+
* binding fan-out) but is no longer the authoritative limit on the
|
|
209
|
+
* parallel binding `pi.dispatch`. */
|
|
210
|
+
maxParallelSubCalls: number;
|
|
211
|
+
/** Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls.
|
|
212
|
+
* Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
|
|
213
|
+
* ADR-0016 section 2. */
|
|
214
|
+
dispatchConcurrency: number;
|
|
215
|
+
/** Maximum recursion depth for `pi.dispatch`. The child PTC run spawned by
|
|
216
|
+
* the (depth+1)-th dispatch is allowed only when childDepth <= maxDispatchDepth.
|
|
217
|
+
* Default 3. Aligns with dsh's `SubagentCapabilities.depthLimit` and codex's
|
|
218
|
+
* `agent_max_depth`. ADR-0016 Recursive dispatch section. */
|
|
219
|
+
maxDispatchDepth: number;
|
|
220
|
+
/** Items accepted by a single `parallel()` / `pipeline()` call (R1 §1, workflow-side; pinned
|
|
221
|
+
* here because it guards a helper call rather than an agent budget). */
|
|
222
|
+
maxItemsPerCall: number;
|
|
223
|
+
/** Cooperative-cancel grace before the worker is terminated outright. */
|
|
224
|
+
graceMs: number;
|
|
225
|
+
/** V8 old-generation cap handed to `new Worker({ resourceLimits })` (F2). */
|
|
226
|
+
maxOldGenerationSizeMb: number;
|
|
227
|
+
/** V8 young-generation cap handed to `new Worker({ resourceLimits })` (F2). */
|
|
228
|
+
maxYoungGenerationSizeMb: number;
|
|
229
|
+
}
|
|
230
|
+
export declare const DEFAULT_CONFIG: Readonly<PtcConfig>;
|
|
231
|
+
/**
|
|
232
|
+
* F1 — the only environment variables a PTC worker may inherit.
|
|
233
|
+
*
|
|
234
|
+
* These are what a shell needs to resolve binaries on each platform; everything
|
|
235
|
+
* else the host has (tokens, API keys, proxies, home paths) stays out of the worker.
|
|
236
|
+
*/
|
|
237
|
+
export declare const WORKER_ENV_ALLOW_LIST: readonly string[];
|
|
238
|
+
/**
|
|
239
|
+
* Build the per-run environment snapshot: the allow-list entries that actually exist.
|
|
240
|
+
*
|
|
241
|
+
* Unset or empty entries are dropped rather than passed through as empty strings, so
|
|
242
|
+
* `Object.keys(workerEnv)` is exactly what the worker sees in `process.env`.
|
|
243
|
+
*/
|
|
244
|
+
export declare function createWorkerEnv(source?: NodeJS.ProcessEnv): Record<string, string>;
|
|
245
|
+
/**
|
|
246
|
+
* Merge per-run overrides onto `DEFAULT_CONFIG`.
|
|
247
|
+
*
|
|
248
|
+
* Overrides are validated rather than coerced: a negative or non-numeric limit is a
|
|
249
|
+
* caller bug, and silently substituting a default would hide it.
|
|
250
|
+
*/
|
|
251
|
+
export declare function resolveConfig(overrides?: Partial<PtcConfig>): PtcConfig;
|
|
252
|
+
/**
|
|
253
|
+
* Resolve the effective deadline for one run.
|
|
254
|
+
*
|
|
255
|
+
* DSH semantics (R1 §3): `0` does not disable the deadline, it falls back to the
|
|
256
|
+
* default; anything larger is clamped to `maxTimeoutMs`.
|
|
257
|
+
*/
|
|
258
|
+
export declare function effectiveTimeoutMs(requested: number | undefined, config?: PtcConfig): number;
|
|
259
|
+
//#endregion
|
|
260
|
+
//#region src/runtime/protocol.d.ts
|
|
261
|
+
/** host → worker */
|
|
262
|
+
declare const HOST_FRAME_KIND_VALUES: {
|
|
263
|
+
readonly connect: "connect";
|
|
264
|
+
readonly init: "init";
|
|
265
|
+
readonly callResult: "call-result";
|
|
266
|
+
readonly cancel: "cancel";
|
|
267
|
+
};
|
|
268
|
+
export declare const HOST_FRAME_KIND: typeof HOST_FRAME_KIND_VALUES;
|
|
269
|
+
/** worker → host */
|
|
270
|
+
declare const WORKER_FRAME_KIND_VALUES: {
|
|
271
|
+
readonly ready: "ready";
|
|
272
|
+
readonly call: "call";
|
|
273
|
+
readonly log: "log";
|
|
274
|
+
readonly narration: "narration";
|
|
275
|
+
readonly phase: "phase";
|
|
276
|
+
readonly result: "result";
|
|
277
|
+
readonly error: "error";
|
|
278
|
+
};
|
|
279
|
+
export declare const WORKER_FRAME_KIND: typeof WORKER_FRAME_KIND_VALUES;
|
|
280
|
+
declare const PTC_LOG_LEVEL_VALUES: {
|
|
281
|
+
readonly log: "log";
|
|
282
|
+
readonly info: "info";
|
|
283
|
+
readonly warn: "warn";
|
|
284
|
+
readonly error: "error";
|
|
285
|
+
readonly debug: "debug";
|
|
286
|
+
};
|
|
287
|
+
export declare const PTC_LOG_LEVEL: typeof PTC_LOG_LEVEL_VALUES;
|
|
288
|
+
declare const PTC_ERROR_KIND_VALUES: {
|
|
289
|
+
/** Program parse error or thrown exception (includes `ReferenceError` from a helper that does not exist on this surface). */
|
|
290
|
+
readonly exception: "exception";
|
|
291
|
+
/** Elapsed deadline expiry. */
|
|
292
|
+
readonly timeout: "timeout";
|
|
293
|
+
/** Caller cancellation. */
|
|
294
|
+
readonly abort: "abort";
|
|
295
|
+
/** Malformed or excessive control traffic. */
|
|
296
|
+
readonly protocol: "protocol";
|
|
297
|
+
/** Early worker exit or a worker-level crash. */
|
|
298
|
+
readonly workerExit: "worker-exit";
|
|
299
|
+
/** Completion value could not be materialized as lossless JSON. */
|
|
300
|
+
readonly invalidOutput: "invalid-output";
|
|
301
|
+
/** Oversized outer result; collected logs are retained. */
|
|
302
|
+
readonly outputLimit: "output-limit";
|
|
303
|
+
};
|
|
304
|
+
export declare const PTC_ERROR_KIND: typeof PTC_ERROR_KIND_VALUES;
|
|
305
|
+
type PtcErrorKind = (typeof PTC_ERROR_KIND)[keyof typeof PTC_ERROR_KIND];
|
|
306
|
+
/** Lossless-JSON payloads, the only values that may cross the boundary as data. */
|
|
307
|
+
interface PtcJsonObject {
|
|
308
|
+
[key: string]: PtcJsonValue;
|
|
309
|
+
}
|
|
310
|
+
type PtcJsonValue = string | number | boolean | null | PtcJsonValue[] | PtcJsonObject;
|
|
311
|
+
interface PtcErrorShape {
|
|
312
|
+
kind: PtcErrorKind;
|
|
313
|
+
message: string;
|
|
314
|
+
stack?: string;
|
|
315
|
+
}
|
|
316
|
+
//#endregion
|
|
317
|
+
//#region src/tools/text.d.ts
|
|
318
|
+
/** Hard cap for one rendered line; longer lines are truncated with `…`. */
|
|
319
|
+
export declare const MAX_LINE_CHARS = 200;
|
|
320
|
+
/** Drop ANSI escape sequences (colours, cursor moves, OSC hyperlinks). */
|
|
321
|
+
export declare function stripAnsi(value: string): string;
|
|
322
|
+
/**
|
|
323
|
+
* Make arbitrary program output safe to hand the model.
|
|
324
|
+
*
|
|
325
|
+
* Same three steps as pi's built-ins: strip ANSI, remove `\r` (a progress bar's carriage
|
|
326
|
+
* return is not a line break), then drop control characters other than `\n`/`\t` and the
|
|
327
|
+
* Unicode format characters that break width math. Lone surrogates fall out of code-point
|
|
328
|
+
* iteration for free.
|
|
329
|
+
*/
|
|
330
|
+
export declare function sanitizeText(value: string): string;
|
|
331
|
+
/**
|
|
332
|
+
* Render a completion value for the model: strings verbatim, everything else as a compact
|
|
333
|
+
* `{key: value}` summary or an indented block — never `JSON.stringify` on the whole value, whose
|
|
334
|
+
* escaping destroys exactly the content a reader needs (newlines, quotes, non-ASCII spacing).
|
|
335
|
+
*/
|
|
336
|
+
export declare function renderModelValue(value: PtcJsonValue): string;
|
|
337
|
+
//#endregion
|
|
338
|
+
//#region src/runtime/bindings.d.ts
|
|
339
|
+
/** pi's built-in tools that can be exposed as bindings, in native order. */
|
|
340
|
+
export declare const BUILTIN_BINDING_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
|
|
341
|
+
type BuiltinBindingName = (typeof BUILTIN_BINDING_NAMES)[number];
|
|
342
|
+
export declare const DEFAULT_BINDING_NAMES: readonly BuiltinBindingName[];
|
|
343
|
+
interface BindingContext {
|
|
344
|
+
/** Aborted when the run is cancelled, times out, or settles. */
|
|
345
|
+
signal?: AbortSignal;
|
|
346
|
+
/** Wire call id; also used to build the tool call id the tools see. */
|
|
347
|
+
callId: number;
|
|
348
|
+
/** Depth of the current PTC run (0 for parent turn, 1+ for a child of `pi.dispatch`). */
|
|
349
|
+
depth: number;
|
|
350
|
+
/** Maximum allowed depth; passed through to `pi.dispatch` for the depth check. */
|
|
351
|
+
maxDispatchDepth: number;
|
|
352
|
+
}
|
|
353
|
+
interface Binding {
|
|
354
|
+
readonly name: string;
|
|
355
|
+
execute(args: unknown, context: BindingContext): Promise<unknown>;
|
|
356
|
+
}
|
|
357
|
+
type BindingTable = ReadonlyMap<string, Binding>;
|
|
358
|
+
interface CreateBuiltinBindingsOptions {
|
|
359
|
+
/** Per-run working directory: the F4 `RunConfig.cwd`, used to build every tool. */
|
|
360
|
+
cwd: string;
|
|
361
|
+
/** Subset of {@link BUILTIN_BINDING_NAMES}; defaults to all of them (bash included). */
|
|
362
|
+
names?: readonly string[];
|
|
363
|
+
}
|
|
364
|
+
/**
|
|
365
|
+
* Build the binding table for one run.
|
|
366
|
+
*
|
|
367
|
+
* Tools are created once per table and reused across calls, matching pi's own extension
|
|
368
|
+
* examples (`createXxxTool(cwd)` caches nothing internally, so one instance per run is
|
|
369
|
+
* the intended granularity).
|
|
370
|
+
*/
|
|
371
|
+
export declare function createBuiltinBindings(options: CreateBuiltinBindingsOptions): BindingTable;
|
|
372
|
+
//#endregion
|
|
373
|
+
//#region src/runtime/dispatcher.d.ts
|
|
374
|
+
interface RunPtcProgramOptions {
|
|
375
|
+
/** Program body: an async function body (`return`/`await` at the top level). */
|
|
376
|
+
code: string;
|
|
377
|
+
surface: PtcSurface;
|
|
378
|
+
/** Working directory for bindings and the run's recorded cwd (F4). */
|
|
379
|
+
cwd: string;
|
|
380
|
+
/** Bindings the program may call; the table keys become `tools.<name>`. */
|
|
381
|
+
bindings: BindingTable;
|
|
382
|
+
/** Workflow surface only: value bound to the program's `args` global. */
|
|
383
|
+
args?: unknown;
|
|
384
|
+
/** Requested deadline; `0`/absent fall back to `timeoutMs`, then clamped to `maxTimeoutMs`. */
|
|
385
|
+
timeoutMs?: number;
|
|
386
|
+
/** Per-run limit overrides on top of `DEFAULT_CONFIG`. */
|
|
387
|
+
config?: Partial<PtcConfig>;
|
|
388
|
+
/** Cancels the run; the worker gets a cooperative cancel window before termination. */
|
|
389
|
+
signal?: AbortSignal;
|
|
390
|
+
/** Identifier carried to the worker; generated when omitted. */
|
|
391
|
+
runId?: string;
|
|
392
|
+
}
|
|
393
|
+
/**
|
|
394
|
+
* One image hoisted out of a successful binding result (DSH parity — see ADR-0014).
|
|
395
|
+
*
|
|
396
|
+
* `data` is base64 exactly as pi's own `read` tool returns it, so the tool layer can forward it as
|
|
397
|
+
* an `ImageContent` block without re-encoding.
|
|
398
|
+
*/
|
|
399
|
+
interface PtcImage {
|
|
400
|
+
data: string;
|
|
401
|
+
mimeType: string;
|
|
402
|
+
}
|
|
403
|
+
interface PtcRunOutcome {
|
|
404
|
+
/** `console.*` output in arrival order. */
|
|
405
|
+
logs: string[];
|
|
406
|
+
/** Workflow `log(message)` narration (observers only, never console output). */
|
|
407
|
+
narrations: string[];
|
|
408
|
+
/** Workflow `phase(title)` titles in arrival order. */
|
|
409
|
+
phases: string[];
|
|
410
|
+
/** Completion value; absent when the program returned nothing or the run failed. */
|
|
411
|
+
value?: PtcJsonValue;
|
|
412
|
+
/**
|
|
413
|
+
* Images hoisted out of successful binding results, in call order.
|
|
414
|
+
*
|
|
415
|
+
* Every image a program's tool calls produced, with no cap and no dedupe: how many images a run
|
|
416
|
+
* attaches is the program's business, exactly as it is in DSH. Present only when at least one was
|
|
417
|
+
* hoisted — a failed or cancelled run attaches nothing, because the tool layer throws for it
|
|
418
|
+
* (`codeRunFailedError`) and its image would never reach the model.
|
|
419
|
+
*/
|
|
420
|
+
images?: PtcImage[];
|
|
421
|
+
/** Failure details; absent on success. */
|
|
422
|
+
error?: PtcErrorShape;
|
|
423
|
+
}
|
|
424
|
+
/**
|
|
425
|
+
* Run one PTC program in a fresh worker and resolve with its outcome.
|
|
426
|
+
*
|
|
427
|
+
* Never rejects for program/ limit / cancellation failures — those are reported as
|
|
428
|
+
* `outcome.error` so callers have one place to render from. It only throws on caller bugs
|
|
429
|
+
* (invalid config overrides).
|
|
430
|
+
*/
|
|
431
|
+
export declare function runPtcProgram(options: RunPtcProgramOptions): Promise<PtcRunOutcome>;
|
|
432
|
+
//#endregion
|
|
433
|
+
//#region src/index.d.ts
|
|
434
|
+
export default function ptcSubagents(pi: ExtensionAPI): void;
|
|
435
|
+
//#endregion
|
|
436
|
+
export type { Binding, BindingContext, BindingTable, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions };
|
|
437
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/mode/ptc-mode.ts","../src/mode/skills-section.ts","../src/runtime/limits.ts","../src/runtime/protocol.ts","../src/tools/text.ts","../src/runtime/bindings.ts","../src/runtime/dispatcher.ts","../src/index.ts"],"mappings":";;;;qBA2Ca;;;;;;;;;;qBAWA;;qBAGA;;qBAGA;;qBAGA;;KAGD;;;;;;;;;;;;;qBAcC,uBAAuB;;UAGnB;EACf;;EAEA;;EAEA;;;wBAIc,oBAAoB;;;;;UAQnB;EACf;EACA;;;UAQe;EACf;EACA;EACA;;;;;;;;;wBAUc,sBAAsB,mBAAmB;;KAwC7C;;KAGA;EACN;EAAa;EAAyB;;EACtC;EAAc,QAAQ;;;UAGX;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA,OAAO;;;wBASO,YAAY,sBAAsB;;;;;;;;wBAclC,YAAY,2BAA2B,MAAM;;;;;;;;;;;;;;;wBAqB7C,gBAAgB,OAAO,iBAAiB;;;;;;;wBA4BxC,cAAc,OAAO,cAAc;;;;;wBAQnC,4BACd,OAAO,cACP;;;;;;;;;;;wBAgBc,mBACd,WAAW,gCACX;EACG;EAAyB;;;;;;;;;wBAoBd,qBAAqB,6BAA6B,MAAM;;;;qBCvR3D;;qBAOA;;;;;;;wBASG,qBAAqB;;;;;;;;;;wBAarB,sBACd,iBAAiB,SACjB,UAAS,QAAQ,SAAS;;;;;;;;;;;;;;;;;;KCtChB;UAEK;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;;;EAIA;;;;;EAKA;;;EAGA;;EAEA;;EAEA;;EAEA;;qBAGW,gBAAgB,SAAS;;;;;;;qBAqBzB;;;;;;;wBAeG,gBAAgB,SAAQ,OAAO,aAA2B;;;;;;;wBAe1D,cAAc,YAAW,QAAQ,aAAkB;;;;;;;wBAmBnD,mBACd,+BACA,SAAQ;;;;cC9GJ;WACJ;WACA;WACA;WACA;;qBAEW,wBAAwB;;cAG/B;WACJ;WACA;WACA;WACA;WACA;WACA;WACA;;qBAEW,0BAA0B;cAGjC;WACJ;WACA;WACA;WACA;WACA;;qBAEW,sBAAsB;cAG7B;;WAEJ;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;qBAEW,uBAAuB;KACxB,uBAAuB,6BAA6B;;UAK/C;GACA,cAAA;;KAEL,kDAAkD,iBAAiB;UAE9D;EACf,MAAM;EACN;EACA;;;;;qBCvDW;;wBAwBG,UAAU;;;;;;;;;wBAgBV,aAAa;;;;;;wBA6Ib,iBAAiB,OAAO;;;;qBC7K3B;KASD,6BAA6B;qBAiB5B,gCAAgC;UAE5B;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;UAGe;WACN;EACT,QAAQ,eAAe,SAAS,iBAAiB;;KAGvC,eAAe,oBAAoB;UAkC9B;;EAEf;;EAEA;;;;;;;;;wBAUc,sBAAsB,SAAS,+BAA+B;;;UCnF7D;;EAEf;EACA,SAAS;;EAET;;EAEA,UAAU;;EAEV;;EAEA;;EAEA,SAAS,QAAQ;;EAEjB,SAAS;;EAET;;;;;;;;UASe;EACf;EACA;;UAGe;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;;;;EASR,SAAS;;EAET,QAAQ;;;;;;;;;wBAwBY,cAAc,SAAS,uBAAuB,QAAQ;;;wBCUpD,aAAa,IAAI"}
|