@xzzpig/pi-subagents 0.6.0 → 0.8.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 +45 -4
- package/README.md +1 -1
- package/agents/reviewer.md +12 -2
- package/docs/agents.md +4 -4
- package/docs/configuration.md +6 -6
- package/docs/extension-api.md +14 -4
- package/docs/models.md +47 -6
- package/docs/observability.md +14 -3
- package/docs/tool-reference.md +21 -6
- package/docs/workflows.md +7 -1
- package/index.ts +10 -1
- package/node_modules/@xzzpig/pi-components/CHANGELOG.md +102 -0
- package/node_modules/@xzzpig/pi-components/LICENSE +21 -0
- package/node_modules/@xzzpig/pi-components/README.md +59 -0
- package/node_modules/@xzzpig/pi-components/dist/index.d.ts +1 -0
- package/node_modules/@xzzpig/pi-components/dist/index.js +1 -0
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +345 -0
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +1169 -0
- package/node_modules/@xzzpig/pi-components/package.json +49 -0
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +1785 -0
- package/package.json +7 -3
- package/prompts/council.md +19 -7
- package/prompts/parallel-review.md +5 -1
- package/prompts/review-loop.md +9 -5
- package/skills/council-mode/SKILL.md +50 -26
- package/skills/pi-subagents/SKILL.md +5 -1
- package/skills/pi-subagents/references/constraints-and-recipes.md +16 -1
- package/skills/pi-subagents/references/execution-controls.md +13 -4
- package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -3
- package/skills/pi-subagents/references/prompting-and-roles.md +14 -7
- package/src/agents/agent-management.ts +115 -14
- package/src/agents/agent-serializer.ts +4 -2
- package/src/agents/agents.ts +226 -48
- package/src/api/external-job-provider.ts +10 -1
- package/src/api/preflight.ts +52 -19
- package/src/api/project-panes.ts +2 -0
- package/src/extension/doctor.ts +10 -0
- package/src/extension/fanout-child.ts +3 -2
- package/src/extension/index.ts +24 -4
- package/src/extension/public-execution.ts +12 -9
- package/src/extension/rpc.ts +77 -3
- package/src/extension/schemas.ts +7 -1
- package/src/extension/tool-description.ts +9 -6
- package/src/extension/tool-result.ts +19 -0
- package/src/inspectors/herdr/client.ts +3 -3
- package/src/inspectors/herdr/focus.ts +55 -0
- package/src/inspectors/herdr/project-panes.ts +228 -44
- package/src/integrations/herdr-status.ts +26 -4
- package/src/runs/background/async-execution.ts +146 -17
- package/src/runs/background/async-job-tracker.ts +33 -14
- package/src/runs/background/async-resume.ts +23 -2
- package/src/runs/background/async-retention.ts +1 -1
- package/src/runs/background/async-status.ts +10 -0
- package/src/runs/background/chain-root-attachment.ts +5 -0
- package/src/runs/background/control-channel.ts +98 -10
- package/src/runs/background/notify.ts +62 -1
- package/src/runs/background/result-watcher.ts +4 -3
- package/src/runs/background/run-status.ts +15 -1
- package/src/runs/background/stale-run-reconciler.ts +3 -0
- package/src/runs/background/subagent-runner.ts +333 -48
- package/src/runs/background/wait-completions.ts +2 -0
- package/src/runs/background/wait-tool.ts +4 -3
- package/src/runs/foreground/async-stop-action.ts +23 -2
- package/src/runs/foreground/execution.ts +148 -13
- package/src/runs/foreground/foreground-history.ts +3 -2
- package/src/runs/foreground/subagent-executor.ts +417 -50
- package/src/runs/foreground/workflow-detach-reconcile.ts +18 -6
- package/src/runs/shared/acceptance.ts +11 -5
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/child-identity.ts +36 -0
- package/src/runs/shared/completion-guard.ts +52 -2
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/extension-bindings.ts +78 -0
- package/src/runs/shared/external-cli-runner.ts +2 -0
- package/src/runs/shared/external-job-bridge.ts +53 -37
- package/src/runs/shared/external-job-runner.ts +126 -23
- package/src/runs/shared/fast-mode-extension.ts +10 -0
- package/src/runs/shared/model-exclusions.ts +2 -1
- package/src/runs/shared/model-fallback.ts +48 -22
- package/src/runs/shared/model-scope.ts +106 -39
- package/src/runs/shared/mutation-evidence.ts +145 -0
- package/src/runs/shared/orca-progress-tabs.ts +71 -9
- package/src/runs/shared/parallel-utils.ts +15 -0
- package/src/runs/shared/pi-args.ts +78 -1
- package/src/runs/shared/structured-output.ts +18 -4
- package/src/runs/shared/subagent-prompt-runtime.ts +48 -15
- package/src/runs/shared/tool-availability.ts +1 -3
- package/src/shared/launch-contract.ts +12 -5
- package/src/shared/settings.ts +6 -1
- package/src/shared/thinking-ceiling.ts +52 -0
- package/src/shared/types.ts +121 -5
- package/src/tui/fleet-native-transcript.ts +374 -0
- package/src/tui/fleet-status.ts +66 -13
- package/src/tui/fleet-transcript.ts +47 -1
- package/src/tui/fleet.ts +96 -24
- package/src/tui/render.ts +5 -4
- package/src/watchdog/permission-arbiter.ts +59 -52
- package/src/workflows/scripted-workflow.ts +156 -12
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to the internal `@xzzpig/pi-components` shared library are
|
|
4
|
+
documented here.
|
|
5
|
+
|
|
6
|
+
## 0.3.0
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
- **Public builder API for historical-record ingestion.** The entry-state
|
|
11
|
+
operations previously private to the module are now exported so hosts can
|
|
12
|
+
construct transcripts from persisted records instead of live agent events:
|
|
13
|
+
`appendEntry`, `ensureTurn`, `finishTurn`, `findLatestEntry`,
|
|
14
|
+
`ensureToolCall`, `upsertText`, `upsertToolResult`, and `appendNotice`.
|
|
15
|
+
Signatures match the internal implementations; existing exports are
|
|
16
|
+
unchanged.
|
|
17
|
+
- `ensureToolCall` backfills arguments onto a placeholder call entry when a
|
|
18
|
+
tool result was recorded before its start event (result-before-call replay).
|
|
19
|
+
- New `maxToolArgsChars` option (`SessionTranscriptOptions`) caps per-call
|
|
20
|
+
argument size. Oversized or non-serializable arguments degrade to a stored
|
|
21
|
+
`TruncatedToolArgs` marker (`{ truncated: true, preview, ... }`) instead of
|
|
22
|
+
throwing, keeping ingestion total and rendering bounded.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- **`ensureTranscriptTheme` never clobbers a live host theme.** The previous
|
|
27
|
+
implementation called `initTheme()` unconditionally on first use, which
|
|
28
|
+
re-resolves the default theme from environment detection and can silently
|
|
29
|
+
replace the user's chosen theme with the dark fallback — changing tool-call
|
|
30
|
+
background colors in the main session after opening an embedded transcript
|
|
31
|
+
view (e.g. `/subagents-fleet`). It now probes the SDK's shared
|
|
32
|
+
`globalThis` theme symbol (`@earendil-works/pi-coding-agent:theme`, plus the
|
|
33
|
+
legacy `@mariozechner/...` spelling) and is a strict no-op when the host has
|
|
34
|
+
already initialized the theme; `initTheme()` is only called when nothing is
|
|
35
|
+
active (headless embeds, unit tests).
|
|
36
|
+
|
|
37
|
+
## 0.2.0
|
|
38
|
+
|
|
39
|
+
### Breaking
|
|
40
|
+
|
|
41
|
+
- **Tool calls render through Pi's native `ToolExecutionComponent`.** The
|
|
42
|
+
hand-drawn badge/result renderer (`formatToolPreview`,
|
|
43
|
+
`summarizeToolResult`, tool badges, `↳ result` labels, and the
|
|
44
|
+
`maxToolResultChars` cap) is removed. `tool-call` entries now store raw
|
|
45
|
+
provider `args`, and `tool-result` entries store structured
|
|
46
|
+
`TranscriptToolResultPayload` data verbatim so built-in tools keep their
|
|
47
|
+
rich main-transcript output (diffs, file previews, images).
|
|
48
|
+
- `SessionTranscriptOptions` extends `NativeToolRenderOptions` (`tui`, `cwd`,
|
|
49
|
+
`resolveToolDefinition`, `showImages`, `imageWidthCells`, `expanded`) and no
|
|
50
|
+
longer accepts `maxToolResultChars`.
|
|
51
|
+
- `renderTranscriptLines` options replace `toolLabel` / `toolBadgeBackground`
|
|
52
|
+
/ `toolBadgeForeground` with `toolComponents` (a `ToolComponentLookup`); a
|
|
53
|
+
persistent component registry is available via `TranscriptToolComponents`
|
|
54
|
+
and `SessionTranscript.toolComponents`. Tool rows bypass line wrapping and
|
|
55
|
+
width truncation because components own their geometry.
|
|
56
|
+
- `snapshot()` deep-copies structured tool `args`/`result` data.
|
|
57
|
+
|
|
58
|
+
### Changed
|
|
59
|
+
|
|
60
|
+
- Tool result entries whose call entry was trimmed away are dropped together
|
|
61
|
+
with their component instances; `trimTranscriptState`,
|
|
62
|
+
`removeCurrentTurn()`, and `clear()` prune the registry in lockstep with the
|
|
63
|
+
entry list.
|
|
64
|
+
- `TranscriptToolComponents` requests a TUI repaint after every tool event
|
|
65
|
+
(matching Pi's interactive mode) and routes component repaint signals
|
|
66
|
+
through a forwarder, so `attachTui()` can wire — or replace — the host TUI
|
|
67
|
+
at any time, even after instances exist. This keeps streaming tool output
|
|
68
|
+
(e.g. bash's per-second invalidate interval) visible while a command runs.
|
|
69
|
+
- **Runtime entry ships TypeScript source again** (`exports["./transcript"]`
|
|
70
|
+
now resolves to `src/transcript.ts`; types still resolve to the compiled
|
|
71
|
+
`dist/src/transcript.d.ts`, so consumer typechecks are unchanged). Pi loads
|
|
72
|
+
extension code through jiti, whose core-package alias map only applies to
|
|
73
|
+
files jiti transforms itself; a precompiled `.js` entry was delegated to
|
|
74
|
+
native import and resolved `@earendil-works/pi-coding-agent` by physical
|
|
75
|
+
location, splitting into a second module instance in local-development
|
|
76
|
+
layouts (repo workspace + npm-installed plugins). With a `.ts` entry the
|
|
77
|
+
component library shares the host's core-package instances in every layout,
|
|
78
|
+
so prototype patches from other plugins (e.g. pi-starline's user-message
|
|
79
|
+
rail) apply to overlay transcripts again. This supersedes the 0.1.1
|
|
80
|
+
bundle-safe rationale: consumers run exclusively inside Pi's jiti loader,
|
|
81
|
+
which executes TypeScript directly. The unused legacy `"."` export
|
|
82
|
+
(`dist/index.js`) was removed and `files` now includes `src`.
|
|
83
|
+
|
|
84
|
+
## 0.1.1
|
|
85
|
+
|
|
86
|
+
### Fixed
|
|
87
|
+
|
|
88
|
+
- **Bundle-safe runtime artifacts.** Consumer Pi packages now bundle compiled
|
|
89
|
+
JavaScript and declarations rather than relying on Node to execute TypeScript
|
|
90
|
+
from `node_modules`.
|
|
91
|
+
|
|
92
|
+
### Changed
|
|
93
|
+
|
|
94
|
+
- **Internal distribution.** This package is intentionally private and is
|
|
95
|
+
bundled into consumer package tarballs instead of being published separately.
|
|
96
|
+
|
|
97
|
+
## 0.1.0
|
|
98
|
+
|
|
99
|
+
### Added
|
|
100
|
+
|
|
101
|
+
- Bounded session transcript state, native Pi message rendering, terminal-safe
|
|
102
|
+
tool output, and a scrollable transcript viewport for Pi extensions.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 xzzpig
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# pi-components
|
|
2
|
+
|
|
3
|
+
Reusable, internal Pi TUI primitives for extension authors. This is a shared
|
|
4
|
+
library package, not a Pi extension: consumer packages bundle it into their
|
|
5
|
+
release tarballs instead of publishing it independently. Bundled artifacts
|
|
6
|
+
expose compiled runtime JavaScript and declarations from `dist/`; the
|
|
7
|
+
TypeScript source remains in this repository for development.
|
|
8
|
+
|
|
9
|
+
## Transcript components
|
|
10
|
+
|
|
11
|
+
`@xzzpig/pi-components/transcript` provides a bounded `SessionTranscript`
|
|
12
|
+
that consumes `AgentSessionEvent` values and a keyboard- and wheel-scrollable
|
|
13
|
+
`TranscriptViewport`. User messages, assistant text, thinking, markdown, and
|
|
14
|
+
code fences render through Pi's native `UserMessageComponent`,
|
|
15
|
+
`AssistantMessageComponent`, and `getMarkdownTheme()`; tool calls render
|
|
16
|
+
through Pi's native `ToolExecutionComponent` (raw `args` and structured
|
|
17
|
+
results are preserved verbatim so built-in tools keep their rich
|
|
18
|
+
main-transcript output), so embedded transcripts match the main session
|
|
19
|
+
instead of approximating its styling.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import {
|
|
23
|
+
SessionTranscript,
|
|
24
|
+
TranscriptViewport,
|
|
25
|
+
} from "@xzzpig/pi-components/transcript";
|
|
26
|
+
|
|
27
|
+
const transcript = new SessionTranscript({
|
|
28
|
+
maxEntries: 500,
|
|
29
|
+
maxChars: 512 * 1024,
|
|
30
|
+
// Optional native tool context: tui, cwd, resolveToolDefinition,
|
|
31
|
+
// showImages, imageWidthCells, expanded.
|
|
32
|
+
});
|
|
33
|
+
const unsubscribe = session.subscribe((event) => transcript.apply(event));
|
|
34
|
+
|
|
35
|
+
const viewport = new TranscriptViewport({
|
|
36
|
+
tui,
|
|
37
|
+
theme,
|
|
38
|
+
readEntries: () => transcript.entries,
|
|
39
|
+
assistantLabel: "Auditor",
|
|
40
|
+
thinkingLabel: "Thinking",
|
|
41
|
+
// Live component registry keeps incremental renderer state per tool call;
|
|
42
|
+
// omit it and tool blocks still render via stateless ad-hoc components.
|
|
43
|
+
toolComponents: transcript.toolComponents,
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
const visible = viewport.render(width, height);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`TranscriptViewport` owns follow-latest plus keyboard and SGR mouse-wheel
|
|
50
|
+
scrolling. Hosts keep ownership of terminal mouse-reporting setup, dialog
|
|
51
|
+
chrome, focus behavior, input controls, session lifecycle, and cancellation
|
|
52
|
+
policy. `Esc` handling is intentionally delegated to the host overlay.
|
|
53
|
+
|
|
54
|
+
The transcript normalizes user/assistant events, streaming thinking and text,
|
|
55
|
+
tool calls and results, and automatic retry notices. It bounds retained history
|
|
56
|
+
(entries and total chars — raw tool data is uncapped by design) and sanitizes
|
|
57
|
+
untrusted terminal control sequences in message text before rendering. Pi core
|
|
58
|
+
packages are peer dependencies, so installed extensions use the same Pi runtime
|
|
59
|
+
and active theme as their host.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./src/transcript.js";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./src/transcript.js";
|
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
import { ToolExecutionComponent } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
/**
|
|
4
|
+
* Structural subset of Pi's theme used by transcript rendering.
|
|
5
|
+
* Pi theme-key unions vary across supported SDK versions, while the public
|
|
6
|
+
* transcript API only passes named string keys.
|
|
7
|
+
*/
|
|
8
|
+
export interface TranscriptTheme {
|
|
9
|
+
fg(color: string, text: string): string;
|
|
10
|
+
bg(color: string, text: string): string;
|
|
11
|
+
bold(text: string): string;
|
|
12
|
+
}
|
|
13
|
+
/** Structural subset of Pi's TUI used by the scroll viewport. */
|
|
14
|
+
export interface TranscriptTui {
|
|
15
|
+
requestRender(): void;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Structured tool result payload as delivered by agent session events. It is
|
|
19
|
+
* stored verbatim so Pi's native tool renderers receive the same shape the
|
|
20
|
+
* main transcript would.
|
|
21
|
+
*/
|
|
22
|
+
export interface TranscriptToolResultPayload {
|
|
23
|
+
content?: Array<{
|
|
24
|
+
type?: string;
|
|
25
|
+
text?: string;
|
|
26
|
+
data?: string;
|
|
27
|
+
mimeType?: string;
|
|
28
|
+
}>;
|
|
29
|
+
details?: unknown;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Host context used to construct Pi's native `ToolExecutionComponent`
|
|
33
|
+
* instances. Every field is optional: missing values fall back to a detached
|
|
34
|
+
* stub TUI and `process.cwd()`.
|
|
35
|
+
*/
|
|
36
|
+
export interface NativeToolRenderOptions {
|
|
37
|
+
/** Structural TUI subset; only `requestRender` is required. */
|
|
38
|
+
tui?: TranscriptTui;
|
|
39
|
+
/** Working directory used to resolve built-in tool definitions. */
|
|
40
|
+
cwd?: string;
|
|
41
|
+
/** Resolver for extension-registered custom tool definitions. */
|
|
42
|
+
resolveToolDefinition?: (toolName: string) => ToolDefinition | undefined;
|
|
43
|
+
/** Pass-through for Pi's image rendering settings. */
|
|
44
|
+
showImages?: boolean;
|
|
45
|
+
imageWidthCells?: number;
|
|
46
|
+
/** Initial expanded state for tool output. */
|
|
47
|
+
expanded?: boolean;
|
|
48
|
+
}
|
|
49
|
+
/** Structural lookup accepted by render functions; maps satisfy this. */
|
|
50
|
+
export interface ToolComponentLookup {
|
|
51
|
+
get(toolCallId: string): ToolExecutionComponent | undefined;
|
|
52
|
+
}
|
|
53
|
+
type Theme = TranscriptTheme;
|
|
54
|
+
type ThemeColor = string;
|
|
55
|
+
type ThemeBackground = string;
|
|
56
|
+
export type TranscriptNoticeTone = "info" | "warning" | "error";
|
|
57
|
+
export type TranscriptEntry = {
|
|
58
|
+
id: number;
|
|
59
|
+
turnId: number;
|
|
60
|
+
type: "turn-boundary";
|
|
61
|
+
phase: "start" | "end";
|
|
62
|
+
} | {
|
|
63
|
+
id: number;
|
|
64
|
+
turnId: number;
|
|
65
|
+
type: "user-message";
|
|
66
|
+
text: string;
|
|
67
|
+
} | {
|
|
68
|
+
id: number;
|
|
69
|
+
turnId: number;
|
|
70
|
+
type: "thinking";
|
|
71
|
+
text: string;
|
|
72
|
+
streaming: boolean;
|
|
73
|
+
} | {
|
|
74
|
+
id: number;
|
|
75
|
+
turnId: number;
|
|
76
|
+
type: "assistant-text";
|
|
77
|
+
text: string;
|
|
78
|
+
streaming: boolean;
|
|
79
|
+
} | {
|
|
80
|
+
id: number;
|
|
81
|
+
turnId: number;
|
|
82
|
+
type: "tool-call";
|
|
83
|
+
toolCallId: string;
|
|
84
|
+
toolName: string;
|
|
85
|
+
/** Raw provider arguments object, preserved for native renderers. */
|
|
86
|
+
args: unknown;
|
|
87
|
+
} | {
|
|
88
|
+
id: number;
|
|
89
|
+
turnId: number;
|
|
90
|
+
type: "tool-result";
|
|
91
|
+
toolCallId: string;
|
|
92
|
+
toolName: string;
|
|
93
|
+
/** Raw structured result; `null` until the first result arrives. */
|
|
94
|
+
result: TranscriptToolResultPayload | null;
|
|
95
|
+
isError: boolean;
|
|
96
|
+
streaming: boolean;
|
|
97
|
+
} | {
|
|
98
|
+
id: number;
|
|
99
|
+
turnId: number;
|
|
100
|
+
type: "notice";
|
|
101
|
+
text: string;
|
|
102
|
+
tone: TranscriptNoticeTone;
|
|
103
|
+
};
|
|
104
|
+
interface ActiveAssistantSegment {
|
|
105
|
+
turnId: number;
|
|
106
|
+
thinkingEntryId?: number;
|
|
107
|
+
textEntryId?: number;
|
|
108
|
+
}
|
|
109
|
+
export interface TranscriptState {
|
|
110
|
+
entries: TranscriptEntry[];
|
|
111
|
+
nextEntryId: number;
|
|
112
|
+
nextTurnId: number;
|
|
113
|
+
currentTurnId: number | null;
|
|
114
|
+
lastTurnId: number | null;
|
|
115
|
+
activeAssistant: ActiveAssistantSegment | null;
|
|
116
|
+
toolCalls: Map<string, {
|
|
117
|
+
turnId: number;
|
|
118
|
+
callEntryId: number;
|
|
119
|
+
resultEntryId?: number;
|
|
120
|
+
}>;
|
|
121
|
+
/** Persistent native tool components keyed by tool call id. */
|
|
122
|
+
toolComponents: TranscriptToolComponents;
|
|
123
|
+
/** Argument char cap applied to every recorded tool call. */
|
|
124
|
+
toolArgsCharLimit: number;
|
|
125
|
+
}
|
|
126
|
+
export interface SessionTranscriptOptions extends NativeToolRenderOptions {
|
|
127
|
+
/** Maximum retained entries. Oldest entries are discarded first. */
|
|
128
|
+
maxEntries?: number;
|
|
129
|
+
/** Maximum retained text across all entries. */
|
|
130
|
+
maxChars?: number;
|
|
131
|
+
/**
|
|
132
|
+
* Per-tool-call argument size cap in JSON characters. Oversized arguments
|
|
133
|
+
* are replaced by a truncated marker object so pathological payloads cannot
|
|
134
|
+
* break rendering or memory bounds. Defaults to 64 KiB.
|
|
135
|
+
*/
|
|
136
|
+
maxToolArgsChars?: number;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Ensures Pi's global theme is initialized so native message/tool components
|
|
140
|
+
* can render outside a live interactive session (headless embeds, unit tests).
|
|
141
|
+
*
|
|
142
|
+
* IMPORTANT: when the host has already initialized the theme (interactive Pi
|
|
143
|
+
* installs the user's chosen theme before any transcript renders), this is a
|
|
144
|
+
* strict no-op. Re-calling `initTheme()` would re-resolve the default theme
|
|
145
|
+
* from environment detection and can silently replace the user's selection
|
|
146
|
+
* with the dark fallback — changing tool-call colors in the main session too.
|
|
147
|
+
*/
|
|
148
|
+
export declare function ensureTranscriptTheme(): void;
|
|
149
|
+
/**
|
|
150
|
+
* Owns the persistent `ToolExecutionComponent` instance for every live tool
|
|
151
|
+
* call, mirroring how Pi's interactive mode keeps pending components keyed by
|
|
152
|
+
* `toolCallId`. Instances are updated incrementally as events arrive and are
|
|
153
|
+
* pruned by the host once their transcript entries disappear.
|
|
154
|
+
*/
|
|
155
|
+
export declare class TranscriptToolComponents implements ToolComponentLookup {
|
|
156
|
+
private readonly components;
|
|
157
|
+
private readonly options;
|
|
158
|
+
private attachedTui;
|
|
159
|
+
/**
|
|
160
|
+
* Components capture their TUI at construction. This forwarder lets a host
|
|
161
|
+
* attach (or replace) the real TUI at any time — including after tool
|
|
162
|
+
* events already created instances — without rebuilding them.
|
|
163
|
+
*/
|
|
164
|
+
private readonly forwardedTui;
|
|
165
|
+
constructor(options?: NativeToolRenderOptions);
|
|
166
|
+
/** Wires (or replaces) the host TUI that receives repaint requests. */
|
|
167
|
+
attachTui(tui: TranscriptTui): void;
|
|
168
|
+
get size(): number;
|
|
169
|
+
has(toolCallId: string): boolean;
|
|
170
|
+
get(toolCallId: string): ToolExecutionComponent | undefined;
|
|
171
|
+
handleStart(toolCallId: string, toolName: string, args: unknown): void;
|
|
172
|
+
handleUpdate(toolCallId: string, toolName: string, partialResult: unknown): void;
|
|
173
|
+
handleEnd(toolCallId: string, toolName: string, result: unknown, isError: boolean): void;
|
|
174
|
+
/** Drops instances whose transcript entries no longer exist. */
|
|
175
|
+
retainOnly(aliveToolCallIds: ReadonlySet<string>): void;
|
|
176
|
+
clear(): void;
|
|
177
|
+
private ensure;
|
|
178
|
+
private requestRender;
|
|
179
|
+
private readonly createdWithoutArgs;
|
|
180
|
+
}
|
|
181
|
+
export declare function createTranscriptState(nativeTools?: NativeToolRenderOptions & SessionTranscriptOptions): TranscriptState;
|
|
182
|
+
/** Escapes terminal control sequences in model and tool output before rendering. */
|
|
183
|
+
export declare function safeTerminalText(value: string): string;
|
|
184
|
+
/**
|
|
185
|
+
* Appends a fully-formed entry, assigning the next sequential id.
|
|
186
|
+
*
|
|
187
|
+
* Public building block for hosts that construct transcripts from historical
|
|
188
|
+
* records instead of live agent events. The entry must be structurally valid
|
|
189
|
+
* for its `type`; ids and array placement are owned by this function.
|
|
190
|
+
*/
|
|
191
|
+
export declare function appendEntry(state: TranscriptState, entry: Omit<TranscriptEntry, "id"> & Record<string, unknown>): TranscriptEntry;
|
|
192
|
+
/**
|
|
193
|
+
* Returns the active turn id, opening a new turn (with a start boundary)
|
|
194
|
+
* when none is open. Public building block for historical-record ingestion.
|
|
195
|
+
*/
|
|
196
|
+
export declare function ensureTurn(state: TranscriptState): number;
|
|
197
|
+
/**
|
|
198
|
+
* Finds the most recent entry of `type` inside `turnId`, scanning backwards.
|
|
199
|
+
* Public building block used by upsert-style helpers and hosts that merge
|
|
200
|
+
* repeated records (e.g. streamed message updates persisted as several lines).
|
|
201
|
+
*/
|
|
202
|
+
export declare function findLatestEntry<TType extends TranscriptEntry["type"]>(state: TranscriptState, turnId: number, type: TType): Extract<TranscriptEntry, {
|
|
203
|
+
type: TType;
|
|
204
|
+
}> | undefined;
|
|
205
|
+
/**
|
|
206
|
+
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
207
|
+
* unless one already exists, clears streaming flags on the turn's entries,
|
|
208
|
+
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
209
|
+
* a no-op for boundary creation. Public building block for hosts that know
|
|
210
|
+
* when a replayed exchange is complete.
|
|
211
|
+
*/
|
|
212
|
+
export declare function finishTurn(state: TranscriptState, turnId?: number | null): void;
|
|
213
|
+
export declare function removeTranscriptTurn(state: TranscriptState, turnId: number | null): void;
|
|
214
|
+
/**
|
|
215
|
+
* Degraded stand-in stored on a tool-call entry when the original arguments
|
|
216
|
+
* exceed the state's char limit or cannot be serialized. Consumers can narrow
|
|
217
|
+
* with the `truncated` flag; rendering falls back to the preview text.
|
|
218
|
+
*/
|
|
219
|
+
export interface TruncatedToolArgs {
|
|
220
|
+
truncated: true;
|
|
221
|
+
/** Present only when JSON serialization of the original payload failed. */
|
|
222
|
+
reason?: "unserializable";
|
|
223
|
+
/** Serialized length of the original payload, when it was serializable. */
|
|
224
|
+
originalChars?: number;
|
|
225
|
+
preview: string;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Finds or creates the tool-call record for `toolCallId`, appending a
|
|
229
|
+
* tool-call entry when none exists yet.
|
|
230
|
+
*
|
|
231
|
+
* Public building block for hosts that ingest historical records where calls
|
|
232
|
+
* and results may arrive in either order: when the result was recorded first,
|
|
233
|
+
* the placeholder entry's arguments are backfilled here from the later call
|
|
234
|
+
* record. Arguments exceeding the state's char limit are stored as a
|
|
235
|
+
* truncated marker object instead of failing.
|
|
236
|
+
*/
|
|
237
|
+
export declare function ensureToolCall(state: TranscriptState, turnId: number, toolCallId: string, toolName: string, args: unknown): {
|
|
238
|
+
turnId: number;
|
|
239
|
+
callEntryId: number;
|
|
240
|
+
resultEntryId?: number;
|
|
241
|
+
};
|
|
242
|
+
/**
|
|
243
|
+
* Inserts or updates the thinking/assistant-text entry for `turnId`.
|
|
244
|
+
* Repeated records for the same turn merge into one entry (latest text wins).
|
|
245
|
+
* Public building block for hosts that replay completed message records.
|
|
246
|
+
*/
|
|
247
|
+
export declare function upsertText(state: TranscriptState, turnId: number, type: "thinking" | "assistant-text", text: string, streaming: boolean): void;
|
|
248
|
+
/**
|
|
249
|
+
* Inserts or updates the structured result of a tool call, creating the call
|
|
250
|
+
* placeholder first when the result arrives before its start event. Safe to
|
|
251
|
+
* call repeatedly — the latest result wins and streaming flags update in place.
|
|
252
|
+
* Public building block for hosts that ingest persisted tool results.
|
|
253
|
+
*/
|
|
254
|
+
export declare function upsertToolResult(state: TranscriptState, turnId: number, toolCallId: string, toolName: string, result: TranscriptToolResultPayload | null, isError: boolean, streaming: boolean): void;
|
|
255
|
+
/**
|
|
256
|
+
* Appends a notice attached to the current turn (or the most recent one).
|
|
257
|
+
* Text is sanitized before storage. Public building block for hosts that
|
|
258
|
+
* surface stderr output, retry banners, or other non-conversation events.
|
|
259
|
+
*/
|
|
260
|
+
export declare function appendNotice(state: TranscriptState, text: string, tone: TranscriptNoticeTone): void;
|
|
261
|
+
export declare function trimTranscriptState(state: TranscriptState, options?: SessionTranscriptOptions): void;
|
|
262
|
+
export declare function applyAgentSessionEvent(state: TranscriptState, input: unknown, options?: SessionTranscriptOptions): void;
|
|
263
|
+
export declare class SessionTranscript {
|
|
264
|
+
private readonly state;
|
|
265
|
+
private readonly options;
|
|
266
|
+
constructor(options?: SessionTranscriptOptions);
|
|
267
|
+
get entries(): readonly TranscriptEntry[];
|
|
268
|
+
/** Live native tool components keyed by tool call id. */
|
|
269
|
+
get toolComponents(): ToolComponentLookup;
|
|
270
|
+
snapshot(): TranscriptEntry[];
|
|
271
|
+
get currentTurnId(): number | null;
|
|
272
|
+
apply(event: unknown): void;
|
|
273
|
+
appendCompletedTurn(details: {
|
|
274
|
+
user?: string;
|
|
275
|
+
thinking?: string;
|
|
276
|
+
assistant: string;
|
|
277
|
+
}): void;
|
|
278
|
+
appendFailure(message: string): void;
|
|
279
|
+
appendNotice(message: string, tone?: TranscriptNoticeTone): void;
|
|
280
|
+
removeCurrentTurn(): void;
|
|
281
|
+
clear(): void;
|
|
282
|
+
}
|
|
283
|
+
export declare function hasStreamingTranscriptEntry(entries: readonly TranscriptEntry[]): boolean;
|
|
284
|
+
export declare function getCompletedTranscriptExchangeCount(entries: readonly TranscriptEntry[]): number;
|
|
285
|
+
export interface TranscriptRenderOptions {
|
|
286
|
+
width: number;
|
|
287
|
+
theme: Theme;
|
|
288
|
+
emptyText?: string;
|
|
289
|
+
assistantLabel?: string;
|
|
290
|
+
thinkingLabel?: string;
|
|
291
|
+
assistantBadgeBackground?: ThemeBackground;
|
|
292
|
+
assistantBadgeForeground?: ThemeColor;
|
|
293
|
+
/**
|
|
294
|
+
* Live native tool components keyed by tool call id. When omitted, tool
|
|
295
|
+
* blocks are rendered through stateless ad-hoc components rebuilt from the
|
|
296
|
+
* entry data on every frame.
|
|
297
|
+
*/
|
|
298
|
+
toolComponents?: ToolComponentLookup;
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* Render normalized transcript entries as terminal lines. User and assistant
|
|
302
|
+
* messages deliberately use Pi's native components so markdown, code,
|
|
303
|
+
* thinking, and message theming stay consistent with the main transcript.
|
|
304
|
+
* Tool calls are rendered by Pi's native `ToolExecutionComponent`, giving
|
|
305
|
+
* built-in tools their familiar rich output (diffs, file previews, images).
|
|
306
|
+
*/
|
|
307
|
+
export declare function renderTranscriptLines(entries: readonly TranscriptEntry[], options: TranscriptRenderOptions): string[];
|
|
308
|
+
export interface TranscriptViewportOptions extends Omit<TranscriptRenderOptions, "width"> {
|
|
309
|
+
tui: TranscriptTui;
|
|
310
|
+
readEntries: () => readonly TranscriptEntry[];
|
|
311
|
+
}
|
|
312
|
+
export interface TranscriptViewportRender {
|
|
313
|
+
lines: string[];
|
|
314
|
+
hiddenAbove: number;
|
|
315
|
+
hiddenBelow: number;
|
|
316
|
+
totalLines: number;
|
|
317
|
+
following: boolean;
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Decodes an SGR mouse-wheel event into a transcript line delta.
|
|
321
|
+
* Hosts remain responsible for enabling terminal mouse reporting when their
|
|
322
|
+
* TUI mode does not already provide it.
|
|
323
|
+
*/
|
|
324
|
+
export declare function getTranscriptMouseScrollDelta(data: string): number | null;
|
|
325
|
+
/**
|
|
326
|
+
* Stateful scrolling viewport for a transcript. It owns no dialog chrome, so
|
|
327
|
+
* extensions can compose it into their own overlay layout and controls.
|
|
328
|
+
*/
|
|
329
|
+
export declare class TranscriptViewport {
|
|
330
|
+
private readonly tui;
|
|
331
|
+
private readonly readEntries;
|
|
332
|
+
private readonly renderOptions;
|
|
333
|
+
private scrollOffset;
|
|
334
|
+
private viewportHeight;
|
|
335
|
+
private totalLines;
|
|
336
|
+
private follow;
|
|
337
|
+
constructor(options: TranscriptViewportOptions);
|
|
338
|
+
get following(): boolean;
|
|
339
|
+
refresh(): void;
|
|
340
|
+
scroll(delta: number): void;
|
|
341
|
+
followLatest(): void;
|
|
342
|
+
handleInput(data: string): boolean;
|
|
343
|
+
render(width: number, height: number): TranscriptViewportRender;
|
|
344
|
+
}
|
|
345
|
+
export {};
|