Skip to content

Desktop app that records your on-screen work session and uses the GitHub Copilot SDK to reconstruct it as an intent + ordered steps, then builds a reusable Skill or Automation for Microsoft Autopilots like Scout, Microsoft Copilot Cowork, or Copilot Studio.

Add session-scoped recorded terminal (#62)

adileic18514e3a528
diff --git a/README.md b/README.md
index b9835ec..d25131f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,8 @@
**Record yourself doing a task once, then turn it into a skill your AI agent can repeat.**
Skill Recorder captures a real work session on your screen: the clicks, the app and
-window switches, the pages you visit, and (if you want) your spoken narration. It then uses
+window switches, the pages you visit, commands/output from its optional recorded terminal,
+and (if you want) your spoken narration. It then uses
the **GitHub Copilot CLI** to reconstruct *what you actually did* as a clear **intent plus
an ordered list of steps**. From there, one step turns that single run into something an
agent can reuse:
@@ -25,9 +26,9 @@ form can teach the agent to submit *all* of them.
1. 🔴 **Record.** Hit record (or `⌘⇧R` / `Ctrl+Shift+R` from anywhere) and just do your
task. Skill Recorder captures your screen and activity locally, in the background.
-2. 🎛️ **Control.** While recording, a small always-on-top bar shows capture and
- microphone state. Mute, unmute, or switch mics on the fly, then finish, or discard
- (with a confirmation) if the take didn't go to plan.
+2. 🎛️ **Control.** While recording, a small always-on-top bar shows capture,
+ microphone, and recorded-terminal state. Open the session-scoped terminal, mute,
+ unmute, or switch mics, then finish or discard with confirmation.
3. 🧠 **Analyze.** Click Analyze and GitHub Copilot reconstructs one overall intent and
an ordered list of steps. Review and edit until it reads right.
4. ✨ **Create.** From an approved analysis, generate a reusable **Skill** and/or a
@@ -96,9 +97,11 @@ To inspect the script before running it, set install options, update, or uninsta
Recording, storage, frame extraction, and optional narration transcription all happen
**on your computer**; nothing leaves while you record. Only when you choose **Analyze**
-does Skill Recorder send the event timeline (window/document titles, URLs, and clipboard
-previews), extracted screen images, and narration text to GitHub's cloud for Copilot to
-process.
+does Skill Recorder send the event timeline (window/document titles, URLs, clipboard
+previews, and terminal commands), extracted screen images, narration text, and bounded
+terminal-output excerpts requested during analysis to GitHub's cloud for Copilot to process.
+When protection is enabled, terminal commands and the complete local terminal transcript
+participate in the same on-device secret/PII scan before any requested excerpt is returned.
The in-app "Records your screen and activity" panel spells out exactly what's collected:
@@ -109,6 +112,11 @@ The in-app "Records your screen and activity" panel spells out exactly what's co
- **Clipboard:** short previews of copied text that tie steps together.
- **Narration** *(optional)*: spoken commentary, transcribed **on-device** in any of
Whisper's 99 supported languages (a one-time ~252 MB model download on first use).
+- **Recorded terminal** *(only when opened from the floating recording bar)*: command,
+ cwd, shell, exit status, duration, and the complete terminal output. The transcript
+ has no app-imposed size cap and counts toward the saved session's storage. It captures
+ only the app-owned terminal for that recording—there are no global hooks, profile
+ edits, background command monitors, or observation of existing terminals.
> ⚠️ **Please don't capture secrets.** Passwords, access tokens, API keys, credentials, and
> other confidential information should never be recorded, typed, pasted, shown, copied,
@@ -137,6 +145,7 @@ The Copilot **describer** and **builders** have a fixture-based eval suite; see
```bash
npm run eval # score the describer against synthetic recordings
+npm run eval:terminal # score indexed terminal-output use and redaction
npm run eval:builder # score the skill/automation generalization
```
diff --git a/common/config.ts b/common/config.ts
index 5b427cc..234a15a 100644
--- a/common/config.ts
+++ b/common/config.ts
@@ -19,6 +19,8 @@ export interface CaptureConfig {
browserUrls: boolean;
/** Low-fps screen video + extracted keyframes. */
video: boolean;
+ /** Commands and output from the app-owned recorded terminal, when opened. */
+ terminal: boolean;
}
export type CaptureSourceKey = keyof CaptureConfig;
@@ -30,6 +32,7 @@ export const FULL_CAPTURE: CaptureConfig = {
windowTitles: true,
browserUrls: true,
video: true,
+ terminal: true,
};
export interface CaptureSourceInfo {
@@ -48,4 +51,5 @@ export const CAPTURE_SOURCES: readonly CaptureSourceInfo[] = [
{ key: "windowTitles", label: "Window titles", tier: 1, cost: "One-time OS permission" },
{ key: "browserUrls", label: "Browser URLs", tier: 1, cost: "One-time OS permission" },
{ key: "video", label: "Screen video + keyframes", tier: 3, cost: "Screen-capture permission" },
+ { key: "terminal", label: "Recorded terminal", tier: 0, cost: "Only the app terminal" },
];
diff --git a/common/events.ts b/common/events.ts
index 0d4605e..967ceeb 100644
--- a/common/events.ts
+++ b/common/events.ts
@@ -11,8 +11,6 @@ export const EventType = {
AppActivate: "app.activate",
AppTitleChange: "app.title-change",
ClipboardChange: "clipboard.change",
- // Retained as describer/eval vocabulary; live capture was removed (no producer
- // ships today). A safer recorded-terminal (PTY) producer is tracked in #7.
TerminalCommand: "terminal.command",
BrowserUrl: "browser.url",
VideoStart: "video.start",
@@ -53,11 +51,15 @@ export type ClipboardChangePayload = {
};
export type TerminalCommandPayload = {
+ commandId: string;
command: string;
cwd: string;
shell?: string;
exitCode?: number;
durationMs?: number;
+ interrupted?: boolean;
+ transcriptStartByte?: number;
+ transcriptEndByte?: number;
};
export type BrowserUrlPayload = { app: string; url: string; host?: string; title?: string };
diff --git a/common/ipc.ts b/common/ipc.ts
index 2533a4d..087d11d 100644
--- a/common/ipc.ts
+++ b/common/ipc.ts
@@ -11,6 +11,12 @@ import type {
TargetPlacement,
} from "./skill";
import type { RecorderState } from "./types";
+import type {
+ SupportedShellId,
+ TerminalActionResult,
+ TerminalShellDescriptor,
+ TerminalStatus,
+} from "./terminal";
export type {
SensitiveCategory,
@@ -273,12 +279,16 @@ export interface StopResult {
ok: boolean;
sessionId?: string;
sessionDir?: string;
+ requiresTerminalConfirmation?: boolean;
+ terminalCommand?: string;
error?: string;
}
export interface DiscardResult {
ok: boolean;
sessionId?: string;
+ requiresTerminalConfirmation?: boolean;
+ terminalCommand?: string;
error?: string;
}
@@ -472,6 +482,17 @@ export const IPC = {
cancelAutomation: "automation:cancel",
revealAutomation: "automation:reveal",
automationProgress: "automation:progress",
+ terminalOpen: "terminal:open",
+ terminalReady: "terminal:ready",
+ terminalStatus: "terminal:status",
+ terminalShells: "terminal:shells",
+ terminalSwitchShell: "terminal:switch-shell",
+ terminalInput: "terminal:input",
+ terminalResize: "terminal:resize",
+ terminalHide: "terminal:hide",
+ terminalStatusChanged: "terminal:status-changed",
+ terminalFinishConfirmationRequested: "terminal:finish-confirmation-requested",
+ terminalOutput: "terminal:output",
openLibrary: "ui:open-library",
closeLibrary: "ui:close-library",
recordingControlsExpanded: "ui:recording-controls-expanded",
@@ -486,8 +507,8 @@ export interface SkillRecorderApi {
confirmStart(): Promise<StartResult>;
markRecordingPrivacyReviewed(): Promise<void>;
onRecordingPrivacyWarningRequested(cb: () => void): () => void;
- stop(): Promise<StopResult>;
- discard(): Promise<DiscardResult>;
+ stop(forceTerminal?: boolean): Promise<StopResult>;
+ discard(forceTerminal?: boolean): Promise<DiscardResult>;
setMicrophoneEnabled(enabled: boolean): Promise<MicrophoneResult>;
setNarrationLanguage(language: NarrationLanguage): Promise<NarrationLanguageResult>;
microphoneSettings(): Promise<MicrophoneSettingsStatus>;
@@ -510,6 +531,17 @@ export interface SkillRecorderApi {
*/
copilotSignIn(): Promise<CopilotSignInResult>;
onStatusChanged(cb: (status: RecorderStatus) => void): () => void;
+ openTerminal(): Promise<TerminalActionResult>;
+ terminalReady(): Promise<TerminalActionResult>;
+ terminalStatus(): Promise<TerminalStatus>;
+ terminalShells(): Promise<TerminalShellDescriptor[]>;
+ switchTerminalShell(shell: SupportedShellId): Promise<TerminalActionResult>;
+ writeTerminal(data: string): void;
+ resizeTerminal(columns: number, rows: number): void;
+ hideTerminal(): Promise<void>;
+ onTerminalStatusChanged(cb: (status: TerminalStatus) => void): () => void;
+ onTerminalFinishConfirmationRequested(cb: () => void): () => void;
+ onTerminalOutput(cb: (data: string) => void): () => void;
narrationStatus(): Promise<NarrationStatus>;
downloadNarrationModel(): Promise<NarrationActionResult>;
transcribeNarration(sessionId: string): Promise<NarrationActionResult>;
diff --git a/common/plan-tools.ts b/common/plan-tools.ts
new file mode 100644
index 0000000..b72f5ec
--- /dev/null
+++ b/common/plan-tools.ts
@@ -0,0 +1,28 @@
+const TOOL_LABELS: Record<string, string> = {
+ view: "Read local file or folder",
+ glob: "Find local paths",
+ grep: "Search file contents",
+ web_fetch: "Fetch web page",
+ bash: "Run device command",
+ workiq_get_my_profile: "Get my profile",
+ workiq_search_chats: "Search Teams chats",
+ workiq_list_chats: "List Teams chats",
+ workiq_get_chat: "Read Teams chat",
+ workiq_list_chat_messages: "Read Teams messages",
+ workiq_send_chat_message: "Send Teams message",
+};
+
+/** Human-facing capability name; the exact runtime identifier remains available as a tooltip. */
+export function planToolLabel(tool: string): string {
+ const id = tool.trim();
+ const known = TOOL_LABELS[id];
+ if (known) return known;
+ if (id.startsWith("workiq_")) return `${humanizeIdentifier(id.slice("workiq_".length))} · WorkIQ`;
+ if (id.startsWith("browser_")) return `${humanizeIdentifier(id.slice("browser_".length))} · Browser`;
+ return humanizeIdentifier(id);
+}
+
+function humanizeIdentifier(value: string): string {
+ const words = value.replace(/[_-]+/g, " ").trim();
+ return words ? words.charAt(0).toUpperCase() + words.slice(1) : "Tool";
+}
diff --git a/common/sensitive.ts b/common/sensitive.ts
index 70fb7d3..3423fbc 100644
--- a/common/sensitive.ts
+++ b/common/sensitive.ts
@@ -33,6 +33,7 @@ export type SensitiveSource =
| "window-title"
| "url"
| "command"
+ | "terminal-output"
| "clipboard"
| "note"
| "narration"
@@ -326,6 +327,8 @@ export function sourceLabel(source: SensitiveSource): string {
return "URL";
case "command":
return "Terminal command";
+ case "terminal-output":
+ return "Terminal output";
case "clipboard":
return "Clipboard";
case "note":
diff --git a/common/skill.test.ts b/common/skill.test.ts
new file mode 100644
index 0000000..a6f5244
--- /dev/null
+++ b/common/skill.test.ts
@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { planToolLabel } from "./plan-tools";
+import { PlanStepSchema } from "./skill";
+
+test("PlanStepSchema migrates a legacy tool string", () => {
+ const step = PlanStepSchema.parse({
+ kind: "calculation",
+ title: "Find projects",
+ text: "Find matching project folders.",
+ tool: "glob",
+ });
+
+ assert.deepEqual(step.tools, ["glob"]);
+ assert.equal("tool" in step, false);
+});
+
+test("PlanStepSchema preserves ordered tools and removes duplicates", () => {
+ const step = PlanStepSchema.parse({
+ kind: "action",
+ title: "Message myself",
+ text: "Find my self-chat and send the result.",
+ tools: [
+ "workiq_get_my_profile",
+ "workiq_search_chats",
+ "workiq_send_chat_message",
+ "workiq_search_chats",
+ ],
+ });
+
+ assert.deepEqual(step.tools, [
+ "workiq_get_my_profile",
+ "workiq_search_chats",
+ "workiq_send_chat_message",
+ ]);
+});
+
+test("planToolLabel explains implementation-oriented runtime identifiers", () => {
+ assert.equal(planToolLabel("glob"), "Find local paths");
+ assert.equal(planToolLabel("workiq_send_chat_message"), "Send Teams message");
+ assert.equal(planToolLabel("browser_fill_form"), "Fill form · Browser");
+});
diff --git a/common/skill.ts b/common/skill.ts
index 97f4926..32a04fa 100644
--- a/common/skill.ts
+++ b/common/skill.ts
@@ -26,16 +26,26 @@ export const PlanStepKind = z.enum(["calculation", "action"]);
export type PlanStepKind = z.infer<typeof PlanStepKind>;
export const PlanStepSchema = z.preprocess(
- // Earlier plans stored steps as bare strings; surface those as (visible) actions.
- (v) => (typeof v === "string" ? { kind: "action", text: v } : v),
+ (value) => {
+ // Earlier plans stored steps as bare strings or one `tool` string.
+ if (typeof value === "string") return { kind: "action", text: value };
+ if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+ const step = value as Record<string, unknown>;
+ if (Array.isArray(step.tools)) return step;
+ const legacyTool = typeof step.tool === "string" ? step.tool.trim() : "";
+ return { ...step, tools: legacyTool ? [legacyTool] : [] };
+ },
z.object({
kind: PlanStepKind,
/** Short title/label for the step, e.g. "List open PRs". */
title: z.string().default(""),
/** Imperative, generalized description of the step. */
text: z.string(),
- /** The native tool/skill this step uses, if any (e.g. "workiq_search_chats"). */
- tool: z.string().default(""),
+ /** Concrete native tools/skills this step uses, in execution order. */
+ tools: z
+ .array(z.string())
+ .default([])
+ .transform((tools) => [...new Set(tools.map((tool) => tool.trim()).filter(Boolean))]),
}),
);
export type PlanStep = z.infer<typeof PlanStepSchema>;
diff --git a/common/terminal.ts b/common/terminal.ts
new file mode 100644
index 0000000..8b3af09
--- /dev/null
+++ b/common/terminal.ts
@@ -0,0 +1,61 @@
+export const SUPPORTED_SHELL_IDS = [
+ "zsh",
+ "bash",
+ "fish",
+ "pwsh",
+ "windows-powershell",
+] as const;
+
+export type SupportedShellId = (typeof SUPPORTED_SHELL_IDS)[number];
+
+export interface TerminalShellDescriptor {
+ id: SupportedShellId;
+ displayName: string;
+ executable: string;
+}
+
+export type TerminalLifecycleState =
+ | "closed"
+ | "starting"
+ | "idle"
+ | "running"
+ | "exited"
+ | "error";
+
+export type TerminalIntegrationQuality = "full" | "basic" | "none";
+
+/** Serializable status suitable for sending across Electron's context bridge. */
+export interface TerminalStatus {
+ state: TerminalLifecycleState;
+ shell: TerminalShellDescriptor | null;
+ integrationQuality: TerminalIntegrationQuality;
+ busy: boolean;
+ exitCode: number | null;
+ error: string | null;
+}
+
+export type TerminalActionResult =
+ | { ok: true }
+ | { ok: false; error: string };
+
+export const TERMINAL_ARTIFACTS = {
+ directory: "terminal",
+ transcript: "output.cast",
+ commands: "commands.jsonl",
+} as const;
+
+export interface TerminalCommandIndex {
+ /** Stable for the lifetime of the recorded session. */
+ id: string;
+ command: string;
+ cwd: string;
+ shell: SupportedShellId;
+ startAtMs: number;
+ endAtMs: number;
+ durationMs: number;
+ exitCode: number | null;
+ interrupted: boolean;
+ /** UTF-8 byte offsets in the marker-free terminal output stream. */
+ transcriptStartByte: number;
+ transcriptEndByte: number;
+}
diff --git a/docs/windows-capture.md b/docs/windows-capture.md
index f1e6b43..b90922c 100644
--- a/docs/windows-capture.md
+++ b/docs/windows-capture.md
@@ -118,8 +118,9 @@ PE architecture and packaged native payloads.
## Known limitations
- Browser URLs are best effort display strings, not the exact tab URL.
-- Terminal capture is not currently implemented; a recorded-terminal (PTY)
- approach is tracked in issue #7.
+- The recorded terminal captures only the PowerShell session opened from Skill
+ Recorder's floating recording bar. It uses ConPTY and does not observe existing
+ PowerShell, Windows Terminal, or cmd.exe windows. The design is tracked in issue #5.
- Semantic UI events (focus/invoke/value via UI Automation) are not implemented
on either platform yet.
- `onnxruntime-node` ships prebuilt binaries for `win32-x64` and
diff --git a/electron/architectures/catalogue-registry.test.ts b/electron/architectures/catalogue-registry.test.ts
index fd1b3b2..5b412de 100644
--- a/electron/architectures/catalogue-registry.test.ts
+++ b/electron/architectures/catalogue-registry.test.ts
@@ -183,16 +183,16 @@ test("real providers preserve versions, content, and the support matrix", () =>
// These hashes prove catalogue moves are byte-for-byte. Intentional catalogue
// changes must bump the corresponding version and update its hash here.
const scoutSkill = registry.requireCatalogue("scout", "skill");
- assert.equal(scoutSkill.version, "2026-07-26");
+ assert.equal(scoutSkill.version, "2026-08-08");
assert.equal(
sha256(scoutSkill.content),
- "2621869fe246edf1244a528824853ab5bc455811442d26c24485e48e1c2e30a7",
+ "36d61c25c960b12528f86c32ef3a99d0b7283a27538a334cc2c5191c269eed06",
);
const scoutAutomation = registry.requireCatalogue("scout", "automation");
- assert.equal(scoutAutomation.version, "2026-07-26");
+ assert.equal(scoutAutomation.version, "2026-08-08");
assert.equal(
sha256(scoutAutomation.content),
- "0fbad5a4324b270bcec5a1c8eb21c4584991093beb5802e9af99caefeb4bd475",
+ "27b8e3153085cac9b8d3e255eac256d0b215819784519026837797d6a02872a0",
);
const coworkSkill = registry.requireCatalogue("cowork", "skill");
diff --git a/electron/architectures/catalogues/scout-catalogue.ts b/electron/architectures/catalogues/scout-catalogue.ts
index ab7fd62..277724a 100644
--- a/electron/architectures/catalogues/scout-catalogue.ts
+++ b/electron/architectures/catalogues/scout-catalogue.ts
@@ -10,7 +10,61 @@ import { defineCatalogueProvider } from "../catalogue-provider";
* generated skill can only rely on what every Scout install ships with. Refresh
* this when Scout's native tools/skills change.
*/
-export const SCOUT_CATALOGUE_VERSION = "2026-07-26";
+export const SCOUT_CATALOGUE_VERSION = "2026-08-08";
+
+/** Exact runtime tool/skill identifiers accepted in Scout skill-plan steps. */
+export const SCOUT_PLAN_TOOL_IDS = [
+ "workiq_search_chats",
+ "workiq_list_chats",
+ "workiq_get_chat",
+ "workiq_list_chat_messages",
+ "workiq_send_chat_message",
+ "workiq_reply_to_chat_message",
+ "workiq_search_emails",
+ "workiq_list_emails",
+ "workiq_get_email",
+ "workiq_send_email",
+ "workiq_create_draft",
+ "workiq_reply_to_email",
+ "workiq_forward_email",
+ "workiq_get_schedule",
+ "workiq_list_events",
+ "workiq_get_event",
+ "workiq_create_event",
+ "workiq_update_event",
+ "workiq_find_meeting_times",
+ "workiq_respond_to_event",
+ "workiq_search_files",
+ "workiq_list_files",
+ "workiq_get_recent_files",
+ "workiq_download_file",
+ "workiq_upload_file",
+ "workiq_search_people",
+ "workiq_get_my_profile",
+ "workiq_get_my_manager",
+ "workiq_get_relevant_people",
+ "view",
+ "glob",
+ "grep",
+ "web_fetch",
+ "bash",
+ "browser_navigate",
+ "browser_snapshot",
+ "browser_click",
+ "browser_type",
+ "browser_fill_form",
+ "browser_select_option",
+ "browser_press_key",
+ "browser_wait_for",
+ "browser_take_screenshot",
+ "pptx",
+ "docx",
+ "xlsx",
+ "loop",
+ "web-artifacts-builder",
+ "expense-report",
+ "excalidraw",
+] as const;
/**
* The reusable core of the Scout catalogue: the native tools, built-in skills, and
@@ -38,8 +92,10 @@ a web UI. Reach for these in order:
\`workiq_download_file\`, \`workiq_upload_file\`.
- People: \`workiq_search_people\`, \`workiq_get_my_profile\`, \`workiq_get_my_manager\`,
\`workiq_get_relevant_people\`.
-2. **SDK built-ins — local files, code, and the web.** \`view\` (read a file), \`glob\`
- (find files by pattern), \`grep\` (search file contents), \`web_fetch\` (fetch a URL).
+2. **SDK built-ins — local files, code, and the web.** \`view\` (read a known file or
+ list a known directory), \`glob\` (discover paths by pattern), \`grep\` (search file
+ contents), \`web_fetch\` (fetch a URL). For the immediate children of an already-known
+ directory use \`view\`; use \`glob\` when the path itself must be discovered or matched.
These are how a skill DISCOVERS inputs on the local OS instead of asking the user.
3. **The device shell + installed CLIs (\`bash\`).** Scout runs on a real Mac or Windows
machine, so when a service ships a first-class CLI, that CLI IS its native tool —
@@ -77,12 +133,15 @@ skill being installed.
| Recording shows | Prefer |
| --- | --- |
| Searching / reading a Teams chat | \`workiq_search_chats\` → \`workiq_list_chat_messages\` |
+| Finding the user's self-chat, then sending to it | \`workiq_get_my_profile\` → \`workiq_search_chats\` or \`workiq_list_chats\` → \`workiq_send_chat_message\` (approval) |
| Reading / searching Outlook mail | \`workiq_search_emails\` / \`workiq_list_emails\` / \`workiq_get_email\` |
| Checking a calendar / free-busy | \`workiq_get_schedule\` / \`workiq_list_events\` |
| Sending a message, email, or invite | \`workiq_send_chat_message\` / \`workiq_send_email\` / \`workiq_create_event\` (approval) |
-| Opening / reading a local file or folder | \`view\` / \`glob\` / \`grep\` |
+| Listing an already-known local folder | \`view\` |
+| Discovering local paths by name or pattern | \`glob\` |
+| Searching inside local files | \`grep\` |
| Reading a public web page | \`web_fetch\` |
-| Acting on GitHub — issues, PRs, releases, repos, gists, Actions | the \`gh\` CLI via \`Bash(gh *)\` (\`gh issue\`, \`gh pr\`, \`gh release\`, \`gh api\`) — never the browser |
+| Acting on GitHub — issues, PRs, releases, repos, gists, Actions | the \`gh\` CLI via runtime tool \`bash\`, allowed by \`Bash(gh *)\` — never the browser |
| Running git, cloud, or package operations | the matching CLI via the shell (\`git\`, \`az\`/\`aws\`/\`gcloud\`, \`npm\`, \`docker\`) |
| Editing a spreadsheet / doc / deck | the \`xlsx\` / \`docx\` / \`pptx\` built-in skill |
| Filling a form on a web app with no API or CLI | \`browser_navigate\` + \`browser_snapshot\` + \`browser_fill_form\`/\`browser_type\`/\`browser_click\` |
@@ -123,7 +182,7 @@ ${SCOUT_NATIVE_CAPABILITIES}
* Authored by inspecting `~/projects/m` (electron/automations/*). Refresh when
* Scout's automation model or native tools change.
*/
-export const SCOUT_AUTOMATION_CATALOGUE_VERSION = "2026-07-26";
+export const SCOUT_AUTOMATION_CATALOGUE_VERSION = "2026-08-08";
const SCOUT_AUTOMATION_CATALOGUE = `
# Target: Microsoft Scout — automation catalogue (built-ins only)
diff --git a/electron/describer/instructions.ts b/electron/describer/instructions.ts
index a99e18e..005c3a2 100644
--- a/electron/describer/instructions.ts
+++ b/electron/describer/instructions.ts
@@ -23,7 +23,8 @@ The recorder harvested cheap, high-signal OS events as the PRIMARY source:
- **window titles**,
- **browser URLs** (the pages visited),
- **clipboard changes** (copied text),
-- **terminal commands** (only if a terminal producer was active for the session).
+- **terminal commands** and a full local terminal transcript (only for the
+ app-owned recorded terminal, when the user opened it).
A low-frame-rate **screen video** may also exist. It is OPPORTUNISTIC enrichment
— you pull frames only where the events are ambiguous. Do NOT assume you must
@@ -40,6 +41,12 @@ All times are **\`atMs\` = milliseconds since the recording started**.
commands / clipboard counts / markers) with their \`atMs\` start + duration. Start here.
- **get_events({ types?, fromMs?, toMs? })** — the raw event stream (with clipboard
text, full titles, full URLs, commands). Use to inspect a specific window closely.
+- **list_terminal_commands({ cursor?, limit?, fromMs?, toMs? })** — indexed commands,
+ cwd, timing, exit status and command ids from the recorded terminal.
+- **search_terminal_output({ query?, commandId?, fromMs?, toMs?, cursor?, limit? })**
+ — grep bounded, locally redacted excerpts from the full local terminal transcript.
+ Use only when command metadata does not explain the result; never request broad
+ output speculatively.
- **get_narration({ query? })** — the user's spoken narration as timestamped lines,
in their own words. Optionally \`query\` to grep it. Absent/empty means the user did
not narrate. When it exists, let it lead the intent and step ordering.
@@ -61,7 +68,11 @@ All times are **\`atMs\` = milliseconds since the recording started**.
goal to build, not a task performed").
3. **Form a hypothesis** about the overall intent from apps + urls + commands.
4. **Read events** (get_events) around anything unclear — clipboard text, exact
- URLs, the sequence of title changes.
+ URLs, the sequence of title changes. If a terminal command's outcome matters,
+ list its command id and search only that command's output or a narrow literal.
+ A failed or interrupted command followed by a recovery/retry always makes the
+ outcome matter: inspect the failed command's output for the cause and the final
+ command's output for the concrete result. Do not infer either from command text.
5. **Look at frames ONLY where events are silent or ambiguous** (get_frames): e.g. a
step with a visual change but no explaining event, a clipboard copy whose purpose
is unclear, or a terminal step with no captured command. Budget ~5 frames for a
@@ -162,7 +173,8 @@ usual — do not turn ordinary research into a hypothetical automation.
passage from the article and pasted it into Google." Do NOT use the third person ("The user…",
"User was…") or the present/continuous tense.
- **startMs / endMs**: the step's \`atMs\` span when known.
- - **apps[]**: apps involved (e.g. ["Microsoft Edge"]).
+ - **apps[]**: apps involved (e.g. ["Microsoft Edge"]). Never include "Skill Recorder";
+ for recorded-terminal-only steps with no other app, use an empty array.
- **evidence[]**: brief refs you relied on — event types, a URL, a frame file, a
copied string. Keep them short.
- **confidence**: "high" | "medium" | "low".
diff --git a/electron/describer/tools.ts b/electron/describer/tools.ts
index 7108e78..6de9010 100644
--- a/electron/describer/tools.ts
+++ b/electron/describer/tools.ts
@@ -12,6 +12,10 @@ import { readEvents } from "../frames/correlate";
import type { FrameExtractor } from "../frames/extractor";
import type { FrameRedactor } from "../sensitive/frame-redact";
import { createLogger } from "../logger";
+import {
+ listTerminalCommands,
+ searchTerminalOutput,
+} from "../terminal/artifacts";
const log = createLogger("Describer/tools");
@@ -43,6 +47,7 @@ const MAX_IMAGES_PER_CALL = 6;
const MAX_STR = 2000;
/** Cap rows returned by get_events so an un-windowed call can't dump the whole log. */
const MAX_EVENTS = 500;
+const MAX_TERMINAL_COMMANDS = 50;
const truncate = (v: unknown): unknown =>
typeof v === "string" && v.length > MAX_STR ? v.slice(0, MAX_STR) + "…[truncated]" : v;
@@ -182,6 +187,98 @@ export function createDescriberTools(ctx: ToolContext): Tool[] {
},
};
+ const listTerminalCommandsTool: Tool = {
+ name: "list_terminal_commands",
+ description:
+ "List indexed commands from the app-owned recorded terminal with command ids, timing, cwd, shell, exit status, interruption state and transcript ranges. Output is local-redacted. Use cursor/limit to page.",
+ parameters: {
+ type: "object",
+ properties: {
+ cursor: { type: "number", description: "Zero-based command cursor." },
+ limit: { type: "number", description: "Rows to return, maximum 50." },
+ fromMs: { type: "number", description: "Optional command start-time lower bound." },
+ toMs: { type: "number", description: "Optional command start-time upper bound." },
+ },
+ additionalProperties: false,
+ },
+ handler: async (raw) => {
+ const args = (raw ?? {}) as {
+ cursor?: number;
+ limit?: number;
+ fromMs?: number;
+ toMs?: number;
+ };
+ progress("Reading terminal command index…");
+ const page = await listTerminalCommands(
+ sessionDir,
+ args.cursor ?? 0,
+ Math.min(
+ Math.max(Math.trunc(args.limit ?? MAX_TERMINAL_COMMANDS), 1),
+ MAX_TERMINAL_COMMANDS,
+ ),
+ );
+ const commands = page.commands
+ .filter(
+ (command) =>
+ (args.fromMs == null || command.startAtMs >= args.fromMs) &&
+ (args.toMs == null || command.startAtMs <= args.toMs),
+ )
+ .map((command) => ({
+ ...command,
+ command: truncate(command.command),
+ cwd: truncate(command.cwd),
+ }));
+ return redact(
+ JSON.stringify(
+ {
+ count: commands.length,
+ nextCursor: page.nextCursor,
+ commands,
+ },
+ null,
+ 2,
+ ),
+ );
+ },
+ };
+
+ const searchTerminalOutputTool: Tool = {
+ name: "search_terminal_output",
+ description:
+ "Search the full local recorded-terminal transcript by literal query, command id, or time window. Returns bounded, paginated, locally redacted excerpts only; it never sends the full transcript.",
+ parameters: {
+ type: "object",
+ properties: {
+ query: { type: "string", description: "Case-insensitive literal text to find." },
+ commandId: { type: "string", description: "Restrict output to one indexed command." },
+ fromMs: { type: "number", description: "Output window start." },
+ toMs: { type: "number", description: "Output window end." },
+ cursor: { type: "number", description: "Cursor from a previous page." },
+ limit: { type: "number", description: "Excerpt count, maximum 50." },
+ },
+ additionalProperties: false,
+ },
+ handler: async (raw) => {
+ const args = (raw ?? {}) as {
+ query?: string;
+ commandId?: string;
+ fromMs?: number;
+ toMs?: number;
+ cursor?: number;
+ limit?: number;
+ };
+ progress("Searching recorded terminal output…");
+ try {
+ const page = await searchTerminalOutput(sessionDir, args);
+ return redact(JSON.stringify(page, null, 2));
+ } catch (error) {
+ return `Could not search terminal output: ${
+ error instanceof Error ? error.message : String(error)
+ }`;
+ }
+ },
+ };
+
const listFrames: Tool = {
name: "list_frames",
description:
@@ -417,5 +514,14 @@ export function createDescriberTools(ctx: ToolContext): Tool[] {
},
};
- return [getTimeline, getEvents, getNarration, listFrames, getFrames, submitAnalysis];
+ return [
+ getTimeline,
+ getEvents,
+ listTerminalCommandsTool,
+ searchTerminalOutputTool,
+ getNarration,
+ listFrames,
+ getFrames,
+ submitAnalysis,
+ ];
}
diff --git a/electron/ipc.ts b/electron/ipc.ts
index 73d9ccf..c803988 100644
--- a/electron/ipc.ts
+++ b/electron/ipc.ts
@@ -5,6 +5,7 @@ import {
shell,
type OpenDialogOptions,
type SaveDialogOptions,
+ type WebContents,
} from "electron";
import os from "node:os";
import path from "node:path";
@@ -65,9 +66,20 @@ export function registerIpc(
screens: ScreenSourceService,
sensitiveModels: SensitiveModelManager,
isRecordingStartPending: () => boolean,
+ canForceTerminalFinish: (sender: WebContents) => boolean,
): void {
- ipcMain.handle(IPC.stop, () => recorder.stop());
- ipcMain.handle(IPC.discard, () => recorder.discard());
+ ipcMain.handle(IPC.stop, (event, forceTerminal?: boolean) => {
+ if (forceTerminal === true && !canForceTerminalFinish(event.sender)) {
+ return { ok: false, error: "Terminal interruption confirmation is unavailable." };
+ }
+ return recorder.stop(forceTerminal === true);
+ });
+ ipcMain.handle(IPC.discard, (event, forceTerminal?: boolean) => {
+ if (forceTerminal === true && !canForceTerminalFinish(event.sender)) {
+ return { ok: false, error: "Terminal interruption confirmation is unavailable." };
+ }
+ return recorder.discard(forceTerminal === true);
+ });
ipcMain.handle(IPC.microphone, (_event, enabled: boolean) =>
recorder.setMicrophoneEnabled(enabled, microphones.effectiveDeviceId()),
);
diff --git a/electron/main.ts b/electron/main.ts
index 78fa3c3..7425857 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -1,7 +1,20 @@
-import { app, BrowserWindow, globalShortcut, ipcMain, Menu, screen } from "electron";
+import {
+ app,
+ BrowserWindow,
+ dialog,
+ globalShortcut,
+ ipcMain,
+ Menu,
+ screen,
+} from "electron";
import { FULL_CAPTURE } from "../common/config";
import { IPC, type RecorderStatus, type StartResult } from "../common/ipc";
+import type {
+ SupportedShellId,
+ TerminalActionResult,
+ TerminalStatus,
+} from "../common/terminal";
import { createCollectors } from "./collectors";
import { installCrashGuards } from "./crash-guards";
import { Describer } from "./describer/describer";
@@ -18,6 +31,7 @@ import { AutomationBuilder } from "./automationbuilder/builder";
import { createTray } from "./tray";
import { dockIcon } from "./icons";
import { AudioRecorder } from "./audio/recorder";
+import { TerminalSession } from "./terminal/session";
import { VideoRecorder } from "./video/recorder";
import { ScreenSourceService } from "./video/sources";
import {
@@ -25,6 +39,7 @@ import {
createLibraryWindow,
createRecorderWindow,
createRecordingControlsWindow,
+ createTerminalWindow,
fitRecorderHeight,
redockLibrary,
setRecordingControlsExpanded,
@@ -42,6 +57,10 @@ const dock = dockIcon();
let recorderWindow: BrowserWindow | null = null;
let libraryWindow: BrowserWindow | null = null;
let recordingControlsWindow: BrowserWindow | null = null;
+let terminalWindow: BrowserWindow | null = null;
+let terminalWindowClosing = false;
+let terminalSession: TerminalSession | null = null;
+let terminalSessionId: string | null = null;
let recorderHome: Electron.Rectangle | null = null;
let controlsExpanded = false;
let quitReady = false;
@@ -60,12 +79,35 @@ const microphones = new AudioRecorder((status) =>
const screens = new ScreenSourceService((status) =>
broadcast(IPC.screenSettingsChanged, status),
);
+
+async function finishRecordedTerminal(): Promise<void> {
+ const session = terminalSession;
+ try {
+ if (session) await session.finish();
+ } catch (error) {
+ session?.destroy();
+ throw error;
+ } finally {
+ terminalSession = null;
+ terminalSessionId = null;
+ if (terminalWindow && !terminalWindow.isDestroyed()) {
+ terminalWindowClosing = true;
+ terminalWindow.destroy();
+ }
+ terminalWindow = null;
+ terminalWindowClosing = false;
+ }
+}
+
const recorder = new RecorderController({
resolveConfig: () => ({ ...FULL_CAPTURE }),
buildCollectors: createCollectors,
createVideoRecorder: () => new VideoRecorder(),
createAudioRecorder: (onCaptureEnded) =>
microphones.createSession(onCaptureEnded),
+ terminalBusy: () =>
+ terminalSession?.busyDetails() ?? { busy: false, command: null },
+ finishTerminal: finishRecordedTerminal,
deleteSession,
postProcess: async (dir) => {
await processSession(dir);
@@ -149,6 +191,92 @@ function ensureRecordingControlsWindow(): BrowserWindow {
return recordingControlsWindow;
}
+function ensureTerminalWindow(): BrowserWindow {
+ if (terminalWindow && !terminalWindow.isDestroyed()) return terminalWindow;
+ terminalWindowClosing = false;
+ const win = createTerminalWindow();
+ terminalWindow = win;
+ win.on("close", (event) => {
+ if (!terminalWindowClosing && recorder.state === "recording") {
+ event.preventDefault();
+ win.hide();
+ }
+ });
+ win.on("closed", () => {
+ if (terminalWindow === win) terminalWindow = null;
+ });
+ return win;
+}
+
+function emptyTerminalStatus(): TerminalStatus {
+ return {
+ state: "closed",
+ shell: null,
+ integrationQuality: "none",
+ busy: false,
+ exitCode: null,
+ error: null,
+ };
+}
+
+async function openRecordedTerminal(): Promise<TerminalActionResult> {
+ const active = recorder.activeSession();
+ if (!active) {
+ return { ok: false, error: "Open the recorded terminal while a recording is active." };
+ }
+ const win = ensureTerminalWindow();
+ if (!terminalSession || terminalSessionId !== active.id) {
+ terminalSession = new TerminalSession({
+ sessionDir: active.dir,
+ sessionStartedAt: active.startedAt,
+ publishCommand: (payload) => {
+ recorder.recordTerminalCommand(payload);
+ },
+ });
+ terminalSessionId = active.id;
+ terminalSession.onStatus((status) =>
+ broadcast(IPC.terminalStatusChanged, status),
+ );
+ terminalSession.onOutput((data) => {
+ if (terminalWindow && !terminalWindow.isDestroyed()) {
+ terminalWindow.webContents.send(IPC.terminalOutput, data);
+ }
+ });
+ }
+
+ const reveal = () => {
+ if (win.isDestroyed()) return;
+ win.show();
+ win.focus();
+ win.webContents.send(IPC.terminalStatusChanged, terminalSession?.status());
+ };
+ if (win.webContents.isLoading()) win.webContents.once("did-finish-load", reveal);
+ else reveal();
+
+ const state = terminalSession.status().state;
+ if (
+ !win.webContents.isLoading() &&
+ (state === "closed" || state === "exited" || state === "error")
+ ) {
+ return terminalSession.start();
+ }
+ return { ok: true };
+}
+
+async function requestStopRecording(): Promise<void> {
+ const result = await recorder.stop();
+ if (!result.requiresTerminalConfirmation) return;
+ const win = ensureRecordingControlsWindow();
+ showRecordingControls();
+ const notify = () => {
+ if (!win.isDestroyed()) {
+ win.webContents.send(IPC.terminalFinishConfirmationRequested);
+ }
+ };
+ if (win.webContents.isLoading()) win.webContents.once("did-finish-load", notify);
+ else notify();
+}
+
function showRecordingControls(): void {
const win = ensureRecordingControlsWindow();
clampRecordingControlsWindow(win);
@@ -258,6 +386,12 @@ app.whenReady().then(async () => {
screens,
sensitiveModels,
() => recordingStartPending,
+ (sender) => {
+ const controls = recordingControlsWindow;
+ return Boolean(
+ controls && !controls.isDestroyed() && sender === controls.webContents,
+ );
+ },
);
sensitiveModels.initialize();
ipcMain.handle(IPC.start, () => requestStartRecording());
@@ -269,6 +403,79 @@ app.whenReady().then(async () => {
ipcMain.handle(IPC.closeLibrary, () => {
if (libraryWindow && !libraryWindow.isDestroyed()) libraryWindow.close();
});
+ ipcMain.handle(IPC.terminalOpen, (event) => {
+ const controls = recordingControlsWindow;
+ if (!controls || controls.isDestroyed() || event.sender !== controls.webContents) {
+ return { ok: false, error: "The recorded terminal can only be opened from the recording bar." };
+ }
+ return openRecordedTerminal();
+ });
+ ipcMain.handle(IPC.terminalReady, (event) => {
+ const win = terminalWindow;
+ if (
+ !win ||
+ win.isDestroyed() ||
+ event.sender !== win.webContents ||
+ !terminalSession
+ ) {
+ return { ok: false, error: "The recorded terminal is unavailable." };
+ }
+ const state = terminalSession.status().state;
+ if (state === "closed" || state === "exited" || state === "error") {
+ return terminalSession.start();
+ }
+ return { ok: true };
+ });
+ ipcMain.handle(IPC.terminalStatus, () =>
+ terminalSession?.status() ?? emptyTerminalStatus(),
+ );
+ ipcMain.handle(IPC.terminalShells, () => [...(terminalSession?.shells ?? [])]);
+ ipcMain.handle(IPC.terminalSwitchShell, (event, shellId: SupportedShellId) => {
+ const win = terminalWindow;
+ if (
+ !win ||
+ win.isDestroyed() ||
+ event.sender !== win.webContents ||
+ !terminalSession
+ ) {
+ return { ok: false, error: "The recorded terminal is unavailable." };
+ }
+ return terminalSession.switchShell(shellId);
+ });
+ ipcMain.on(IPC.terminalInput, (event, data: unknown) => {
+ const win = terminalWindow;
+ if (
+ !win ||
+ win.isDestroyed() ||
+ event.sender !== win.webContents ||
+ typeof data !== "string" ||
+ data.length > 1_000_000
+ ) {
+ return;
+ }
+ terminalSession?.write(data);
+ });
+ ipcMain.on(
+ IPC.terminalResize,
+ (event, size: { columns?: unknown; rows?: unknown } | null) => {
+ const win = terminalWindow;
+ if (
+ !win ||
+ win.isDestroyed() ||
+ event.sender !== win.webContents ||
+ !size ||
+ typeof size.columns !== "number" ||
+ typeof size.rows !== "number"
+ ) {
+ return;
+ }
+ terminalSession?.resize(size.columns, size.rows);
+ },
+ );
+ ipcMain.handle(IPC.terminalHide, (event) => {
+ const win = terminalWindow;
+ if (win && !win.isDestroyed() && event.sender === win.webContents) win.hide();
+ });
ipcMain.handle(IPC.recordingControlsExpanded, (event, expanded: boolean) => {
const win = recordingControlsWindow;
if (
@@ -314,6 +521,7 @@ app.whenReady().then(async () => {
createTray(
recorder,
requestStartRecording,
+ requestStopRecording,
showRecorderWindow,
showRecordingControls,
);
@@ -324,7 +532,7 @@ app.whenReady().then(async () => {
const toggle = () => {
const status = recorder.status();
if (status.transition !== "none") return;
- void (status.state === "recording" ? recorder.stop() : requestStartRecording());
+ void (status.state === "recording" ? requestStopRecording() : requestStartRecording());
};
if (!globalShortcut.register("CommandOrControl+Shift+R", toggle)) {
log.warn("Global shortcut registration failed");
@@ -347,19 +555,36 @@ app.on("before-quit", (event) => {
if (quitReady) return;
event.preventDefault();
if (quitTask) return;
- recorder.beginShutdown();
quitTask = (async () => {
+ const terminal = terminalSession?.busyDetails() ?? { busy: false, command: null };
+ if (terminal.busy) {
+ const { response } = await dialog.showMessageBox({
+ type: "warning",
+ buttons: ["Keep recording", "Close terminal and quit"],
+ defaultId: 0,
+ cancelId: 0,
+ message: "A terminal command is still running.",
+ detail: terminal.command
+ ? `Closing Skill Recorder will interrupt: ${terminal.command}`
+ : "Closing Skill Recorder will interrupt the active terminal session.",
+ });
+ if (response === 0) return;
+ }
+ recorder.beginShutdown();
// stop() is serialized behind any start/mic/discard operation already in
// flight, and is a harmless "Not recording" result when the app is idle.
- await recorder.stop();
+ await recorder.stop(terminal.busy);
await recorder.whenProcessed();
+ quitReady = true;
+ app.quit();
})()
.catch((error) => {
log.warn("graceful shutdown failed:", error);
- })
- .finally(() => {
quitReady = true;
app.quit();
+ })
+ .finally(() => {
+ quitTask = null;
});
});
diff --git a/electron/preload.cjs b/electron/preload.cjs
index cfc5a3a..bc78f2c 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -53,6 +53,17 @@ const IPC = {
cancelAutomation: "automation:cancel",
revealAutomation: "automation:reveal",
automationProgress: "automation:progress",
+ terminalOpen: "terminal:open",
+ terminalReady: "terminal:ready",
+ terminalStatus: "terminal:status",
+ terminalShells: "terminal:shells",
+ terminalSwitchShell: "terminal:switch-shell",
+ terminalInput: "terminal:input",
+ terminalResize: "terminal:resize",
+ terminalHide: "terminal:hide",
+ terminalStatusChanged: "terminal:status-changed",
+ terminalFinishConfirmationRequested: "terminal:finish-confirmation-requested",
+ terminalOutput: "terminal:output",
openLibrary: "ui:open-library",
closeLibrary: "ui:close-library",
recordingControlsExpanded: "ui:recording-controls-expanded",
@@ -83,8 +94,8 @@ contextBridge.exposeInMainWorld("skillRecorder", {
if (recordingPrivacyWarningCallback === cb) recordingPrivacyWarningCallback = null;
};
},
- stop: () => ipcRenderer.invoke(IPC.stop),
- discard: () => ipcRenderer.invoke(IPC.discard),
+ stop: (forceTerminal) => ipcRenderer.invoke(IPC.stop, forceTerminal),
+ discard: (forceTerminal) => ipcRenderer.invoke(IPC.discard, forceTerminal),
setMicrophoneEnabled: (enabled) => ipcRenderer.invoke(IPC.microphone, enabled),
setNarrationLanguage: (language) => ipcRenderer.invoke(IPC.narrationLanguage, language),
microphoneSettings: () => ipcRenderer.invoke(IPC.microphoneSettings),
@@ -111,6 +122,31 @@ contextBridge.exposeInMainWorld("skillRecorder", {
ipcRenderer.on(IPC.statusChanged, listener);
return () => ipcRenderer.removeListener(IPC.statusChanged, listener);
},
+ openTerminal: () => ipcRenderer.invoke(IPC.terminalOpen),
+ terminalReady: () => ipcRenderer.invoke(IPC.terminalReady),
+ terminalStatus: () => ipcRenderer.invoke(IPC.terminalStatus),
+ terminalShells: () => ipcRenderer.invoke(IPC.terminalShells),
+ switchTerminalShell: (shell) => ipcRenderer.invoke(IPC.terminalSwitchShell, shell),
+ writeTerminal: (data) => ipcRenderer.send(IPC.terminalInput, data),
+ resizeTerminal: (columns, rows) =>
+ ipcRenderer.send(IPC.terminalResize, { columns, rows }),
+ hideTerminal: () => ipcRenderer.invoke(IPC.terminalHide),
+ onTerminalStatusChanged: (cb) => {
+ const listener = (_event, status) => cb(status);
+ ipcRenderer.on(IPC.terminalStatusChanged, listener);
+ return () => ipcRenderer.removeListener(IPC.terminalStatusChanged, listener);
+ },
+ onTerminalFinishConfirmationRequested: (cb) => {
+ const listener = () => cb();
+ ipcRenderer.on(IPC.terminalFinishConfirmationRequested, listener);
+ return () =>
+ ipcRenderer.removeListener(IPC.terminalFinishConfirmationRequested, listener);
+ },
+ onTerminalOutput: (cb) => {
+ const listener = (_event, data) => cb(data);
+ ipcRenderer.on(IPC.terminalOutput, listener);
+ return () => ipcRenderer.removeListener(IPC.terminalOutput, listener);
+ },
narrationStatus: () => ipcRenderer.invoke(IPC.narrationStatus),
downloadNarrationModel: () => ipcRenderer.invoke(IPC.narrationDownload),
transcribeNarration: (sessionId) => ipcRenderer.invoke(IPC.narrationTranscribe, sessionId),
diff --git a/electron/recorder/controller.test.ts b/electron/recorder/controller.test.ts
index 11a6ee0..d6cacd8 100644
--- a/electron/recorder/controller.test.ts
+++ b/electron/recorder/controller.test.ts
@@ -64,38 +64,6 @@ test("microphone toggles are serialized and finalized on save", async () => {
},
});
- test("selected screen source is passed to the video recorder", async () => {
- await withSessionsRoot(async () => {
- let selectedSourceId: string | undefined;
- let selectedDisplayId: string | undefined;
- const controller = new RecorderController({
- resolveConfig: () => ({ ...FULL_CAPTURE }),
- buildCollectors: () => [],
- createVideoRecorder: () => ({
- start: async (_dir, sourceId, displayId) => {
- selectedSourceId = sourceId;
- selectedDisplayId = displayId;
- },
- stop: async () => null,
- }),
- deleteSession: async () => undefined,
- });
-
- assert.equal(
- (
- await controller.start({
- screenSourceId: "screen:2:0",
- screenDisplayId: "202",
- })
- ).ok,
- true,
- );
- assert.equal(selectedSourceId, "screen:2:0");
- assert.equal(selectedDisplayId, "202");
- assert.equal((await controller.stop()).ok, true);
- });
- });
-
const started = await controller.start();
assert.equal(started.ok, true);
assert.equal(audio.narrationLanguage, "en");
@@ -130,6 +98,38 @@ test("microphone toggles are serialized and finalized on save", async () => {
});
});
+test("selected screen source is passed to the video recorder", async () => {
+ await withSessionsRoot(async () => {
+ let selectedSourceId: string | undefined;
+ let selectedDisplayId: string | undefined;
+ const controller = new RecorderController({
+ resolveConfig: () => ({ ...FULL_CAPTURE }),
+ buildCollectors: () => [],
+ createVideoRecorder: () => ({
+ start: async (_dir, sourceId, displayId) => {
+ selectedSourceId = sourceId;
+ selectedDisplayId = displayId;
+ },
+ stop: async () => null,
+ }),
+ deleteSession: async () => undefined,
+ });
+
+ assert.equal(
+ (
+ await controller.start({
+ screenSourceId: "screen:2:0",
+ screenDisplayId: "202",
+ })
+ ).ok,
+ true,
+ );
+ assert.equal(selectedSourceId, "screen:2:0");
+ assert.equal(selectedDisplayId, "202");
+ assert.equal((await controller.stop()).ok, true);
+ });
+});
+
test("preferred narration language is reused by optionless recording starts", async () => {
await withSessionsRoot(async () => {
const audio = new FakeAudioRecorder();
@@ -195,6 +195,90 @@ test("discard removes the active session and skips post-processing", async () =>
});
});
+test("stop requires confirmation before interrupting a busy recorded terminal", async () => {
+ await withSessionsRoot(async () => {
+ let finishCalls = 0;
+ const controller = new RecorderController({
+ resolveConfig: () => ({ ...FULL_CAPTURE, video: false }),
+ buildCollectors: () => [],
+ terminalBusy: () => ({ busy: true, command: "npm test" }),
+ finishTerminal: async () => {
+ finishCalls += 1;
+ },
+ deleteSession: async () => undefined,
+ });
+
+ assert.equal((await controller.start()).ok, true);
+ assert.deepEqual(await controller.stop(), {
+ ok: false,
+ requiresTerminalConfirmation: true,
+ terminalCommand: "npm test",
+ });
+ assert.equal(controller.status().state, "recording");
+ assert.equal(controller.status().transition, "none");
+ assert.equal(finishCalls, 0);
+
+ assert.equal((await controller.stop(true)).ok, true);
+ assert.equal(controller.status().state, "idle");
+ assert.equal(finishCalls, 1);
+ });
+});
+
+test("terminal finalization failure keeps the recording active and is retryable", async () => {
+ await withSessionsRoot(async () => {
+ let failTerminal = true;
+ const controller = new RecorderController({
+ resolveConfig: () => ({ ...FULL_CAPTURE, video: false }),
+ buildCollectors: () => [],
+ terminalBusy: () => ({ busy: false, command: null }),
+ finishTerminal: async () => {
+ if (failTerminal) throw new Error("Transcript flush failed.");
+ },
+ deleteSession: async () => undefined,
+ });
+
+ assert.equal((await controller.start()).ok, true);
+ const failed = await controller.stop();
+ assert.equal(failed.ok, false);
+ assert.match(failed.error ?? "", /transcript flush failed/i);
+ assert.equal(controller.status().state, "recording");
+ assert.equal(controller.status().transition, "none");
+
+ failTerminal = false;
+ assert.equal((await controller.stop()).ok, true);
+ assert.equal(controller.status().state, "idle");
+ });
+});
+
+test("discard keeps session files until busy-terminal confirmation is forced", async () => {
+ await withSessionsRoot(async (root) => {
+ let deleted = false;
+ const controller = new RecorderController({
+ resolveConfig: () => ({ ...FULL_CAPTURE, video: false }),
+ buildCollectors: () => [],
+ terminalBusy: () => ({ busy: true, command: null }),
+ finishTerminal: async () => undefined,
+ deleteSession: async (id) => {
+ deleted = true;
+ await rm(path.join(root, id), { recursive: true });
+ },
+ });
+
+ const started = await controller.start();
+ assert.equal(started.ok, true);
+ const blocked = await controller.discard();
+ assert.equal(blocked.ok, false);
+ assert.equal(blocked.requiresTerminalConfirmation, true);
+ assert.equal(deleted, false);
+ assert.ok(started.sessionId);
+ await access(path.join(root, started.sessionId));
+
+ assert.equal((await controller.discard(true)).ok, true);
+ assert.equal(deleted, true);
+ await assert.rejects(access(path.join(root, started.sessionId)), { code: "ENOENT" });
+ });
+});
+
test("failed discard retains and post-processes the finalized session", async () => {
await withSessionsRoot(async () => {
let processed = 0;
diff --git a/electron/recorder/controller.ts b/electron/recorder/controller.ts
index a7e1077..a9f85a4 100644
--- a/electron/recorder/controller.ts
+++ b/electron/recorder/controller.ts
@@ -4,6 +4,7 @@ import { app } from "electron";
import type { CaptureConfig } from "../../common/config";
import { EventType } from "../../common/events";
+import type { TerminalCommandPayload } from "../../common/events";
import type {
DiscardResult,
MarkerResult,
@@ -81,6 +82,10 @@ export interface RecorderDeps {
deleteSession?: (sessionId: string) => Promise<void>;
/** Optional best-effort post-processing (frames + correlation) after save. */
postProcess?: (sessionDir: string) => Promise<void>;
+ /** Current recorded-terminal activity, used to guard stop/discard. */
+ terminalBusy?: () => { busy: boolean; command: string | null };
+ /** Flush and close the recorded terminal before the event stream is finalized. */
+ finishTerminal?: () => Promise<void>;
}
type FinishIntent = "save" | "discard";
@@ -127,6 +132,23 @@ export class RecorderController {
return this.lastCompleted?.dir ?? null;
}
+ activeSession(): { id: string; dir: string; startedAt: number } | null {
+ const store = this.store;
+ return store
+ ? { id: store.meta.id, dir: store.dir, startedAt: store.meta.startedAt }
+ : null;
+ }
+
+ recordTerminalCommand(payload: TerminalCommandPayload): boolean {
+ if (!this.store) return false;
+ this.bus.publish({
+ type: EventType.TerminalCommand,
+ source: "recorded-terminal",
+ payload,
+ });
+ return true;
+ }
+
/**
* Forget a session if it's the one being tracked as "last completed" — called
* after a session is deleted, so status()/analyze no longer point at a dir that
@@ -176,12 +198,12 @@ export class RecorderController {
);
}
- stop(): Promise<StopResult> {
- return this.enqueue(() => this.finish("save"));
+ stop(forceTerminal = false): Promise<StopResult> {
+ return this.enqueue(() => this.finish("save", forceTerminal));
}
- discard(): Promise<DiscardResult> {
- return this.enqueue(() => this.finish("discard"));
+ discard(forceTerminal = false): Promise<DiscardResult> {
+ return this.enqueue(() => this.finish("discard", forceTerminal));
}
setMicrophoneEnabled(
@@ -485,10 +507,22 @@ export class RecorderController {
}
}
- private async finish(intent: FinishIntent): Promise<FinishResult> {
+ private async finish(
+ intent: FinishIntent,
+ forceTerminal = false,
+ ): Promise<FinishResult> {
const store = this.store;
if (!store) return { ok: false, error: "Not recording" };
+ const terminal = this.deps.terminalBusy?.();
+ if (terminal?.busy && !forceTerminal) {
+ return {
+ ok: false,
+ requiresTerminalConfirmation: true,
+ terminalCommand: terminal.command ?? undefined,
+ };
+ }
+ const previousMicrophone = this.microphone;
this.transition = intent === "save" ? "stopping" : "discarding";
if (this.microphone.state !== "off") {
this.microphone = {
@@ -499,7 +533,24 @@ export class RecorderController {
}
this.emit();
- // Stop producers before finalizing the event stream. Audio is flushed before
+ // Stop producers before finalizing the event stream. The terminal goes first
+ // so its final command event can still be persisted to the attached event bus.
+ if (this.deps.finishTerminal) {
+ try {
+ await this.deps.finishTerminal();
+ } catch (error) {
+ const terminalError = error instanceof Error ? error.message : String(error);
+ this.transition = "none";
+ this.microphone = previousMicrophone;
+ this.emit();
+ log.warn("terminal stop failed:", terminalError);
+ return {
+ ok: false,
+ error: `Could not finalize the recorded terminal: ${terminalError}`,
+ };
+ }
+ }
+ // Audio is flushed before
// video so the mic-off boundary is anchored as close as possible to the click.
try {
await this.host.stopAll();
diff --git a/electron/recording-controls-bounds.test.ts b/electron/recording-controls-bounds.test.ts
index 4f3f5c4..1654491 100644
--- a/electron/recording-controls-bounds.test.ts
+++ b/electron/recording-controls-bounds.test.ts
@@ -11,7 +11,7 @@ import {
test("recording controls start bottom-center inside the work area", () => {
const workArea = { x: -1920, y: 0, width: 1920, height: 1040 };
assert.deepEqual(initialRecordingControlsBounds(workArea), {
- x: -1194,
+ x: -1240,
y: 946,
width: RECORDING_CONTROLS_SIZE.width,
height: RECORDING_CONTROLS_SIZE.collapsedHeight,
@@ -21,15 +21,15 @@ test("recording controls start bottom-center inside the work area", () => {
test("recording controls clamp to negative-coordinate and small displays", () => {
assert.deepEqual(
clampRecordingControlsBounds(
- { x: -2500, y: 1300, width: 468, height: 232 },
+ { x: -2500, y: 1300, width: 560, height: 250 },
{ x: -1920, y: 0, width: 1280, height: 720 },
),
- { x: -1920, y: 488, width: 468, height: 232 },
+ { x: -1920, y: 470, width: 560, height: 250 },
);
assert.deepEqual(
clampRecordingControlsBounds(
- { x: 10, y: 10, width: 468, height: 232 },
+ { x: 10, y: 10, width: 560, height: 250 },
{ x: 0, y: 0, width: 320, height: 180 },
),
{ x: 0, y: 0, width: 320, height: 180 },
@@ -38,9 +38,9 @@ test("recording controls clamp to negative-coordinate and small displays", () =>
test("overlay panel expansion preserves the bar's bottom edge", () => {
const workArea = { x: 0, y: 0, width: 1440, height: 900 };
- const collapsed = { x: 486, y: 806, width: 468, height: 76 };
+ const collapsed = { x: 440, y: 806, width: 560, height: 76 };
const expanded = resizeRecordingControlsBounds(collapsed, true, workArea);
- assert.deepEqual(expanded, { x: 486, y: 650, width: 468, height: 232 });
+ assert.deepEqual(expanded, { x: 440, y: 632, width: 560, height: 250 });
assert.equal(expanded.y + expanded.height, collapsed.y + collapsed.height);
assert.deepEqual(
resizeRecordingControlsBounds(expanded, false, workArea),
diff --git a/electron/recording-controls-bounds.ts b/electron/recording-controls-bounds.ts
index a878527..d8dcf5b 100644
--- a/electron/recording-controls-bounds.ts
+++ b/electron/recording-controls-bounds.ts
@@ -6,9 +6,9 @@ export interface WindowBounds {
}
export const RECORDING_CONTROLS_SIZE = {
- width: 468,
+ width: 560,
collapsedHeight: 76,
- expandedHeight: 232,
+ expandedHeight: 250,
margin: 18,
} as const;
diff --git a/electron/sensitive/scanner.test.ts b/electron/sensitive/scanner.test.ts
index 87794fe..a5b591f 100644
--- a/electron/sensitive/scanner.test.ts
+++ b/electron/sensitive/scanner.test.ts
@@ -121,6 +121,32 @@ test("scanSession leaves personal names alone (NER layer removed)", async () =>
// is neither detected nor added to the redaction values (secrets + PII only).
assert.ok(!values.includes(PERSON), "a bare name must not be a redaction value");
});
+
+});
+
+test("scanSession streams and scans terminal output split across PTY chunks", async () => {
+ await withSessionRoot(async (root) => {
+ const id = "terminal-output";
+ const dir = path.join(root, id);
+ await mkdir(path.join(dir, "terminal"), { recursive: true });
+ await writeFile(
+ path.join(dir, "session.json"),
+ JSON.stringify({ id, startedAt: STARTED_AT, stoppedAt: STARTED_AT + 2_000 }),
+ );
+ await writeFile(path.join(dir, "events.jsonl"), "");
+ const cast = [
+ JSON.stringify({ version: 2, width: 80, height: 24, timestamp: 10 }),
+ JSON.stringify([0.5, "o", `token: ${GH_TOKEN.slice(0, 20)}`]),
+ JSON.stringify([0.6, "o", `${GH_TOKEN.slice(20)}\r\n`]),
+ ].join("\n");
+ await writeFile(path.join(dir, "terminal", "output.cast"), `${cast}\n`);
+
+ const { report, values } = await scanSession(id);
+ assert.ok(values.includes(GH_TOKEN));
+ const finding = report.findings.find((item) => item.label === "GitHub token");
+ assert.equal(finding?.source, "terminal-output");
+ assert.equal(JSON.stringify(report).includes(GH_TOKEN), false);
+ });
});
test("scanSession scans the whole event payload, not just primary fields", async () => {
diff --git a/electron/sensitive/scanner.ts b/electron/sensitive/scanner.ts
index b3acaff..5f832f1 100644
--- a/electron/sensitive/scanner.ts
+++ b/electron/sensitive/scanner.ts
@@ -1,4 +1,12 @@
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+ createReadStream,
+ existsSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { createInterface } from "node:readline";
+import { stripVTControlCharacters } from "node:util";
import path from "node:path";
import { NARRATION_FILE, type NarrationTranscript } from "../../common/narration";
@@ -13,6 +21,7 @@ import {
type SensitiveSource,
} from "../../common/sensitive";
import type { RecEvent, SessionMeta } from "../../common/types";
+import { TERMINAL_ARTIFACTS } from "../../common/terminal";
import { readEvents } from "../frames/correlate";
import { createLogger } from "../logger";
import { isValidSessionId, sessionDir } from "../recorder/session-store";
@@ -117,6 +126,74 @@ function collectFields(dir: string): ScanField[] {
return fields;
}
+/** Stream searchable terminal output without ever materializing an unbounded
+ * transcript in memory. PTY chunks can split a token, so retain a small overlap
+ * when a command emits a very long line. */
+async function* terminalOutputFields(dir: string): AsyncGenerator<ScanField> {
+ const file = path.join(
+ dir,
+ TERMINAL_ARTIFACTS.directory,
+ TERMINAL_ARTIFACTS.transcript,
+ );
+ if (!existsSync(file)) return;
+ const lines = createInterface({
+ input: createReadStream(file, { encoding: "utf8" }),
+ crlfDelay: Infinity,
+ });
+ let first = true;
+ let pending = "";
+ let pendingAtMs: number | null = null;
+ for await (const line of lines) {
+ if (first) {
+ first = false;
+ continue;
+ }
+ let row: unknown;
+ try {
+ row = JSON.parse(line);
+ } catch {
+ continue;
+ }
+ if (
+ !Array.isArray(row) ||
+ row[1] !== "o" ||
+ typeof row[0] !== "number" ||
+ typeof row[2] !== "string"
+ ) {
+ continue;
+ }
+ if (pendingAtMs === null) pendingAtMs = Math.max(0, Math.round(row[0] * 1000));
+ pending += stripVTControlCharacters(row[2]).replaceAll("\u0000", "");
+ while (true) {
+ const newline = pending.indexOf("\n");
+ if (newline >= 0) {
+ const text = pending.slice(0, newline + 1);
+ pending = pending.slice(newline + 1);
+ if (text.trim()) {
+ yield { text, source: "terminal-output", atMs: pendingAtMs };
+ }
+ pendingAtMs = Math.max(0, Math.round(row[0] * 1000));
+ continue;
+ }
+ if (pending.length > 16_384) {
+ yield {
+ text: pending.slice(0, 16_384),
+ source: "terminal-output",
+ atMs: pendingAtMs,
+ };
+ pending = pending.slice(12_288);
+ pendingAtMs = Math.max(0, Math.round(row[0] * 1000));
+ continue;
+ }
+ break;
+ }
+ }
+ lines.close();
+ if (pending.trim()) {
+ yield { text: pending, source: "terminal-output", atMs: pendingAtMs };
+ }
+}
+
/** Run every detection layer over one string and merge them (overlaps resolved). */
async function matchesFor(text: string): Promise<SensitiveMatch[]> {
const secrets = await scanSecrets(text);
@@ -148,22 +225,21 @@ function findingKey(source: SensitiveSource, match: SensitiveMatch): string {
*/
export async function scanSession(sessionId: string): Promise<ScanResult> {
const dir = sessionDir(sessionId); // throws on an unsafe id (traversal guard)
- const fields = collectFields(dir);
-
const byKey = new Map<string, SensitiveFinding>();
const values = new Set<string>();
// Payload fields repeat verbatim across events (app name, cwd, host, url), so
// cache detector results by exact text to avoid re-scanning identical strings.
const scanCache = new Map<string, SensitiveMatch[]>();
- for (const field of fields) {
+ const scanField = async (field: ScanField): Promise<void> => {
let matches = scanCache.get(field.text);
if (!matches) {
try {
matches = await matchesFor(field.text);
} catch (err) {
log.warn("field scan failed:", err instanceof Error ? err.message : err);
- continue;
+ return;
}
+ if (scanCache.size >= 512) scanCache.clear();
scanCache.set(field.text, matches);
}
for (const match of matches) {
@@ -189,6 +265,10 @@ export async function scanSession(sessionId: string): Promise<ScanResult> {
occurrences: 1,
});
}
+ };
+ for (const field of collectFields(dir)) await scanField(field);
+ for await (const field of terminalOutputFields(dir)) {
+ await scanField(field);
}
const findings = [...byKey.values()].sort((a, b) => {
diff --git a/electron/skillbuilder/builder.ts b/electron/skillbuilder/builder.ts
index e939883..116e121 100644
--- a/electron/skillbuilder/builder.ts
+++ b/electron/skillbuilder/builder.ts
@@ -35,7 +35,7 @@ const KICKOFF_PROMPT =
"Read get_analysis (and get_timeline where the tool mapping needs evidence), then call " +
"propose_plan with how you'll generalize this task, its fixed values (each an id + name + " +
"value, referenced from steps as {{id}}), and its ordered steps (each a short title + " +
- "description, with the native tool it uses). Stop after propose_plan so the user can review it.";
+ "description, with every concrete native tool it calls). Stop after propose_plan so the user can review it.";
const CREATE_PROMPT =
"The user reviewed and edited the plan below. Build the SKILL.md from EXACTLY this plan — do not " +
@@ -333,7 +333,7 @@ function renderPlanForPrompt(plan: SkillPlan): string {
plan.steps.forEach((s, idx) => {
const head = [s.title, s.text].filter(Boolean).join(" — ");
const bits = [`${idx + 1}. (${s.kind}) ${head}`];
- if (s.tool) bits.push(`[tool: ${s.tool}]`);
+ if (s.tools.length) bits.push(`[tools: ${s.tools.join(" → ")}]`);
lines.push(bits.join(" "));
});
}
diff --git a/electron/skillbuilder/instructions.ts b/electron/skillbuilder/instructions.ts
index f6a58a6..81a4df0 100644
--- a/electron/skillbuilder/instructions.ts
+++ b/electron/skillbuilder/instructions.ts
@@ -69,8 +69,13 @@ because the recording used it once.
UI-only steps (a web app with no API and no CLI). Gate the shell with \`allowed-tools\`
(e.g. \`Bash(gh *)\`) and write commands for the device OS (zsh/bash on macOS,
PowerShell on Windows).
-- Record the chosen tool on each step (the step's \`tool\`), and set \`allowedTools\` to the
- patterns the skill actually needs.
+- Record every concrete runtime tool a step needs in execution order (the step's \`tools\`).
+ Use runtime identifiers such as \`glob\`, \`workiq_search_chats\`, and \`bash\` here; do
+ not put permission patterns such as \`Glob\` or \`Bash(gh *)\` in \`tools\`.
+- Set \`allowedTools\` separately to the canonical permission patterns the skill actually
+ needs, such as \`Glob\` or \`Bash(gh *)\`.
+- Never use vague labels such as "reasoning", "filesystem", or "WorkIQ". If the prose says
+ a step locates a chat and then sends to it, list both the lookup and send tools.
- Rely ONLY on the built-in tools and skills in the catalogue — never on a skill the
user might have added.
@@ -83,8 +88,8 @@ Break the generalized procedure into ordered **steps**, each with a short **titl
- **action** — changes the world: submits a form, sends a message, creates/edits/deletes a
file or record, posts, pays. These are the risky surface — keep them explicit.
-Put the native tool each step uses in its \`tool\`. Order matters: interleave calculations and
-actions in the real sequence the task runs.
+Put every native tool each step uses in its \`tools\`, in call order. Order also matters
+between steps: interleave calculations and actions in the real sequence the task runs.
## Write a good SKILL.md (authoring principles)
diff --git a/electron/skillbuilder/plan-tools.test.ts b/electron/skillbuilder/plan-tools.test.ts
new file mode 100644
index 0000000..1a17f51
--- /dev/null
+++ b/electron/skillbuilder/plan-tools.test.ts
@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { SkillPlanSchema } from "../../common/skill";
+import { validatePlanTooling } from "./plan-tools";
+
+const plan = (tools: string[], allowedTools: string[]) =>
+ SkillPlanSchema.parse({
+ architecture: "scout",
+ name: "test-plan",
+ title: "Test plan",
+ description: "Test plan tools.",
+ steps: [{ kind: "calculation", title: "Test", text: "Test the tools.", tools }],
+ allowedTools,
+ });
+
+test("validatePlanTooling accepts runtime IDs with matching permissions", () => {
+ assert.deepEqual(validatePlanTooling(plan(["view", "glob"], ["Read", "Glob"])), []);
+});
+
+test("validatePlanTooling rejects permission names as runtime IDs", () => {
+ assert.deepEqual(validatePlanTooling(plan(["Glob"], ["Glob"])), [
+ 'Unknown Scout runtime tool or skill "Glob".',
+ ]);
+});
+
+test("validatePlanTooling requires matching filesystem and scoped shell permissions", () => {
+ assert.deepEqual(validatePlanTooling(plan(["grep", "bash"], [])), [
+ 'Runtime tool "grep" requires allowedTools to include "Grep".',
+ 'Runtime tool "bash" requires a scoped allowedTools pattern such as "Bash(gh *)".',
+ ]);
+});
diff --git a/electron/skillbuilder/plan-tools.ts b/electron/skillbuilder/plan-tools.ts
new file mode 100644
index 0000000..dcd957a
--- /dev/null
+++ b/electron/skillbuilder/plan-tools.ts
@@ -0,0 +1,33 @@
+import type { SkillPlan } from "../../common/skill";
+import { SCOUT_PLAN_TOOL_IDS } from "../architectures/catalogues/scout-catalogue";
+
+const SCOUT_TOOLS = new Set<string>(SCOUT_PLAN_TOOL_IDS);
+
+/** Validate runtime identifiers independently from frontmatter permission patterns. */
+export function validatePlanTooling(plan: SkillPlan): string[] {
+ if (plan.architecture !== "scout") return [];
+
+ const issues: string[] = [];
+ const tools = new Set(plan.steps.flatMap((step) => step.tools));
+ for (const tool of tools) {
+ if (!SCOUT_TOOLS.has(tool)) {
+ issues.push(`Unknown Scout runtime tool or skill ${JSON.stringify(tool)}.`);
+ }
+ }
+
+ const permissions = new Set(plan.allowedTools);
+ for (const [tool, permission] of [
+ ["view", "Read"],
+ ["glob", "Glob"],
+ ["grep", "Grep"],
+ ] as const) {
+ if (tools.has(tool) && !permissions.has(permission)) {
+ issues.push(`Runtime tool ${JSON.stringify(tool)} requires allowedTools to include ${JSON.stringify(permission)}.`);
+ }
+ }
+ if (tools.has("bash") && !plan.allowedTools.some((permission) => /^Bash\(.+\)$/.test(permission))) {
+ issues.push('Runtime tool "bash" requires a scoped allowedTools pattern such as "Bash(gh *)".');
+ }
+
+ return issues;
+}
diff --git a/electron/skillbuilder/tools.ts b/electron/skillbuilder/tools.ts
index 99ce61d..4c2d96e 100644
--- a/electron/skillbuilder/tools.ts
+++ b/electron/skillbuilder/tools.ts
@@ -7,6 +7,7 @@ import {
type SkillPlan,
type SkillSubmission,
} from "../../common/skill";
+import { validatePlanTooling } from "./plan-tools";
/** Everything the builder's skill-specific tools are bound to for one session. */
export interface SkillToolContext {
@@ -33,7 +34,7 @@ export function createSkillBuilderTools(ctx: SkillToolContext): Tool[] {
const proposePlan: Tool = {
name: "propose_plan",
description:
- "Propose your reviewable plan for the skill: how you'll generalize the task, the fixed values it hard-codes (each a small id + human name + the literal, referenced from the steps by a {{id}} token), the ordered steps (each with a short title, a description, and the native tool it uses), and the allowed-tools. Call this once per turn, then STOP so the user can review or refine it. Do NOT write the skill body yet.",
+ "Propose your reviewable plan for the skill: how you'll generalize the task, the fixed values it hard-codes (each a small id + human name + the literal, referenced from the steps by a {{id}} token), the ordered steps (each with a short title, a description, and every concrete native tool it uses in call order), and the allowed-tools. Call this once per turn, then STOP so the user can review or refine it. Do NOT write the skill body yet.",
parameters: {
type: "object",
properties: {
@@ -94,13 +95,14 @@ export function createSkillBuilderTools(ctx: SkillToolContext): Tool[] {
description:
"Imperative, generalized description of the step. Reference any fixed value by its {{id}} token instead of writing the literal (e.g. \"open {{backlog_url}} and read the table\").",
},
- tool: {
- type: "string",
+ tools: {
+ type: "array",
+ items: { type: "string" },
description:
- "The native tool/skill this step uses, e.g. \"workiq_search_chats\" or \"Bash(gh *)\".",
+ "Every concrete runtime tool/skill this step calls, in order, e.g. [\"workiq_get_my_profile\", \"workiq_search_chats\"] or [\"bash\"]. Use lowercase runtime identifiers here; permission patterns belong only in allowedTools.",
},
},
- required: ["kind", "title", "text"],
+ required: ["kind", "title", "text", "tools"],
additionalProperties: false,
},
},
@@ -124,6 +126,15 @@ export function createSkillBuilderTools(ctx: SkillToolContext): Tool[] {
resultType: "failure",
};
}
+ const toolingIssues = validatePlanTooling(parsed.data);
+ if (toolingIssues.length) {
+ return {
+ textResultForLlm:
+ "propose_plan rejected — fix the runtime tool identifiers and allowed-tools:\n" +
+ toolingIssues.map((issue) => `- ${issue}`).join("\n"),
+ resultType: "failure",
+ };
+ }
progress("Proposed a plan for your review.");
onPlan(parsed.data);
return "Plan recorded and shown to the user. Stop now and wait for their review or refinement.";
diff --git a/electron/terminal/artifacts.ts b/electron/terminal/artifacts.ts
new file mode 100644
index 0000000..e71e486
--- /dev/null
+++ b/electron/terminal/artifacts.ts
@@ -0,0 +1,210 @@
+import { createReadStream, existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { stripVTControlCharacters } from "node:util";
+import path from "node:path";
+
+import {
+ TERMINAL_ARTIFACTS,
+ type TerminalCommandIndex,
+} from "../../common/terminal";
+
+export interface TerminalCommandPage {
+ commands: TerminalCommandIndex[];
+ nextCursor: number | null;
+}
+
+export interface TerminalOutputQuery {
+ query?: string;
+ commandId?: string;
+ fromMs?: number;
+ toMs?: number;
+ cursor?: number;
+ limit?: number;
+}
+
+export interface TerminalOutputHit {
+ cursor: number;
+ atMs: number;
+ commandId: string | null;
+ text: string;
+}
+
+export interface TerminalOutputPage {
+ hits: TerminalOutputHit[];
+ nextCursor: number | null;
+}
+
+function artifact(sessionDir: string, file: string): string {
+ return path.join(sessionDir, TERMINAL_ARTIFACTS.directory, file);
+}
+
+function parseCommand(line: string): TerminalCommandIndex | null {
+ try {
+ const value = JSON.parse(line) as Partial<TerminalCommandIndex>;
+ if (
+ typeof value.id !== "string" ||
+ typeof value.command !== "string" ||
+ typeof value.cwd !== "string" ||
+ typeof value.startAtMs !== "number" ||
+ typeof value.endAtMs !== "number"
+ ) {
+ return null;
+ }
+ return value as TerminalCommandIndex;
+ } catch {
+ return null;
+ }
+}
+
+export async function listTerminalCommands(
+ sessionDir: string,
+ cursor = 0,
+ limit = 100,
+): Promise<TerminalCommandPage> {
+ const file = artifact(sessionDir, TERMINAL_ARTIFACTS.commands);
+ if (!existsSync(file)) return { commands: [], nextCursor: null };
+ const start = Math.max(0, Math.floor(cursor));
+ const boundedLimit = Math.max(1, Math.min(200, Math.floor(limit)));
+ const commands: TerminalCommandIndex[] = [];
+ let row = 0;
+ let more = false;
+ const lines = createInterface({
+ input: createReadStream(file, { encoding: "utf8" }),
+ crlfDelay: Infinity,
+ });
+ for await (const line of lines) {
+ if (row++ < start) continue;
+ const command = parseCommand(line);
+ if (!command) continue;
+ if (commands.length < boundedLimit) commands.push(command);
+ else {
+ more = true;
+ break;
+ }
+ }
+ lines.close();
+ return {
+ commands,
+ nextCursor: more ? start + commands.length : null,
+ };
+}
+
+async function commandRange(
+ sessionDir: string,
+ commandId: string,
+): Promise<TerminalCommandIndex | null> {
+ let cursor = 0;
+ while (true) {
+ const page = await listTerminalCommands(sessionDir, cursor, 200);
+ const found = page.commands.find((command) => command.id === commandId);
+ if (found) return found;
+ if (page.nextCursor === null) return null;
+ cursor = page.nextCursor;
+ }
+}
+
+function excerpt(text: string, query?: string): string {
+ const clean = stripVTControlCharacters(text).replaceAll("\u0000", "");
+ if (!query) return clean.slice(0, 2000);
+ const lower = clean.toLocaleLowerCase();
+ const at = lower.indexOf(query.toLocaleLowerCase());
+ if (at < 0) return "";
+ const start = Math.max(0, at - 500);
+ return clean.slice(start, Math.min(clean.length, at + query.length + 1000));
+}
+
+/** Streams the asciicast transcript and returns only bounded matching excerpts. */
+export async function searchTerminalOutput(
+ sessionDir: string,
+ input: TerminalOutputQuery,
+): Promise<TerminalOutputPage> {
+ if (
+ !input.query?.trim() &&
+ !input.commandId &&
+ input.fromMs == null &&
+ input.toMs == null
+ ) {
+ throw new Error("Search terminal output by query, command, or time window.");
+ }
+ const file = artifact(sessionDir, TERMINAL_ARTIFACTS.transcript);
+ if (!existsSync(file)) return { hits: [], nextCursor: null };
+ const range = input.commandId
+ ? await commandRange(sessionDir, input.commandId)
+ : null;
+ if (input.commandId && !range) return { hits: [], nextCursor: null };
+ const fromMs = Math.max(
+ 0,
+ input.fromMs ?? range?.startAtMs ?? 0,
+ );
+ const toMs = Math.max(
+ fromMs,
+ input.toMs ?? range?.endAtMs ?? Number.POSITIVE_INFINITY,
+ );
+ const startCursor = Math.max(0, Math.floor(input.cursor ?? 0));
+ const limit = Math.max(1, Math.min(50, Math.floor(input.limit ?? 20)));
+ const hits: TerminalOutputHit[] = [];
+ let outputCursor = 0;
+ let more = false;
+ let activeCommand: string | null = null;
+ let commandCursor = 0;
+ let commandsPage = await listTerminalCommands(sessionDir, 0, 200);
+ let commands = commandsPage.commands;
+ let commandIndex = 0;
+
+ const lines = createInterface({
+ input: createReadStream(file, { encoding: "utf8" }),
+ crlfDelay: Infinity,
+ });
+ let first = true;
+ for await (const line of lines) {
+ if (first) {
+ first = false;
+ continue;
+ }
+ let row: unknown;
+ try {
+ row = JSON.parse(line);
+ } catch {
+ continue;
+ }
+ if (
+ !Array.isArray(row) ||
+ row[1] !== "o" ||
+ typeof row[0] !== "number" ||
+ typeof row[2] !== "string"
+ ) {
+ continue;
+ }
+ const atMs = Math.max(0, Math.round(row[0] * 1000));
+ while (commands[commandIndex] && atMs > commands[commandIndex].endAtMs) {
+ commandIndex++;
+ if (commandIndex >= commands.length && commandsPage.nextCursor !== null) {
+ commandCursor = commandsPage.nextCursor;
+ commandsPage = await listTerminalCommands(sessionDir, commandCursor, 200);
+ commands = commandsPage.commands;
+ commandIndex = 0;
+ }
+ }
+ const command = commands[commandIndex];
+ activeCommand =
+ command && atMs >= command.startAtMs && atMs <= command.endAtMs
+ ? command.id
+ : null;
+ if (atMs < fromMs || atMs > toMs) continue;
+ const text = excerpt(row[2], input.query?.trim());
+ if (!text) continue;
+ const cursor = outputCursor++;
+ if (cursor < startCursor) continue;
+ if (hits.length < limit) {
+ hits.push({ cursor, atMs, commandId: activeCommand, text });
+ } else {
+ more = true;
+ break;
+ }
+ }
+ lines.close();
+ return {
+ hits,
+ nextCursor: more ? startCursor + hits.length : null,
+ };
+}
diff --git a/electron/terminal/protocol.ts b/electron/terminal/protocol.ts
new file mode 100644
index 0000000..8b66758
--- /dev/null
+++ b/electron/terminal/protocol.ts
@@ -0,0 +1,220 @@
+import type { SupportedShellId } from "../../common/terminal";
+
+export const RECORDER_OSC_PREFIX = "\u001b]6973;skill-recorder;1;";
+export const RECORDER_OSC_BEL = "\u0007";
+const RECORDER_OSC_ST = "\u001b\\";
+const MAX_MARKER_LENGTH = 64 * 1024;
+
+export interface PromptReadyEvent {
+ type: "prompt-ready";
+}
+
+export interface CommandStartEvent {
+ type: "command-start";
+ id: string;
+ command: string;
+ cwd: string;
+ shell: SupportedShellId;
+ atMs: number;
+}
+
+export interface CommandFinishEvent {
+ type: "command-finish";
+ id: string;
+ exitCode: number | null;
+ atMs: number;
+}
+
+export type TerminalProtocolEvent =
+ | PromptReadyEvent
+ | CommandStartEvent
+ | CommandFinishEvent;
+
+export type TerminalProtocolItem =
+ | { type: "output"; data: string }
+ | { type: "event"; event: TerminalProtocolEvent };
+
+function encodeField(value: string | number): string {
+ return encodeURIComponent(String(value));
+}
+
+export function encodeRecorderMarker(
+ nonce: string,
+ event: TerminalProtocolEvent,
+): string {
+ let body: string;
+ switch (event.type) {
+ case "prompt-ready":
+ body = "ready";
+ break;
+ case "command-start":
+ body = [
+ "start",
+ event.id,
+ event.command,
+ event.cwd,
+ event.shell,
+ event.atMs,
+ ]
+ .map(encodeField)
+ .join(";");
+ break;
+ case "command-finish":
+ body = [
+ "finish",
+ event.id,
+ event.exitCode === null ? "" : event.exitCode,
+ event.atMs,
+ ]
+ .map(encodeField)
+ .join(";");
+ break;
+ }
+ return `${RECORDER_OSC_PREFIX}${nonce};${body}${RECORDER_OSC_BEL}`;
+}
+
+function decodeField(value: string): string | null {
+ try {
+ return decodeURIComponent(value);
+ } catch {
+ return null;
+ }
+}
+
+function parseFiniteTimestamp(value: string): number | null {
+ if (!/^\d{1,16}$/.test(value)) return null;
+ const parsed = Number(value);
+ return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function parseMarkerBody(body: string, nonce: string): TerminalProtocolEvent | null {
+ const fields = body.split(";");
+ if (fields[0] !== nonce) return null;
+ const kind = fields[1];
+
+ if (kind === "ready" && fields.length === 2) {
+ return { type: "prompt-ready" };
+ }
+
+ if (kind === "start" && fields.length === 7) {
+ const decoded = fields.slice(2).map(decodeField);
+ if (decoded.some((field) => field === null)) return null;
+ const [id, command, cwd, shellValue, atValue] = decoded as string[];
+ if (
+ id.length === 0 ||
+ !["zsh", "bash", "fish", "pwsh", "windows-powershell"].includes(shellValue)
+ ) {
+ return null;
+ }
+ const atMs = parseFiniteTimestamp(atValue);
+ if (atMs === null) return null;
+ return {
+ type: "command-start",
+ id,
+ command,
+ cwd,
+ shell: shellValue as SupportedShellId,
+ atMs,
+ };
+ }
+
+ if (kind === "finish" && fields.length === 5) {
+ const id = decodeField(fields[2]);
+ const exitValue = decodeField(fields[3]);
+ const atValue = decodeField(fields[4]);
+ if (id === null || id.length === 0 || exitValue === null || atValue === null) {
+ return null;
+ }
+ const atMs = parseFiniteTimestamp(atValue);
+ if (atMs === null || (exitValue !== "" && !/^-?\d+$/.test(exitValue))) return null;
+ const exitCode = exitValue === "" ? null : Number(exitValue);
+ if (exitCode !== null && !Number.isSafeInteger(exitCode)) return null;
+ return { type: "command-finish", id, exitCode, atMs };
+ }
+
+ return null;
+}
+
+function terminatorAt(value: string, from: number): { index: number; length: number } | null {
+ const bel = value.indexOf(RECORDER_OSC_BEL, from);
+ const st = value.indexOf(RECORDER_OSC_ST, from);
+ if (bel < 0 && st < 0) return null;
+ if (bel >= 0 && (st < 0 || bel < st)) return { index: bel, length: 1 };
+ return { index: st, length: 2 };
+}
+
+function partialPrefixLength(value: string): number {
+ const max = Math.min(value.length, RECORDER_OSC_PREFIX.length - 1);
+ for (let length = max; length > 0; length--) {
+ if (RECORDER_OSC_PREFIX.startsWith(value.slice(-length))) return length;
+ }
+ return 0;
+}
+
+/**
+ * Incrementally removes only authenticated, structurally valid recorder markers.
+ * Foreign or malformed OSC sequences are returned byte-for-byte as terminal output.
+ */
+export class TerminalProtocolParser {
+ private pending = "";
+
+ constructor(private readonly nonce: string) {
+ if (!/^[A-Za-z0-9_-]{16,128}$/.test(nonce)) {
+ throw new Error("Terminal protocol nonce must be 16-128 URL-safe characters");
+ }
+ }
+
+ push(chunk: string): TerminalProtocolItem[] {
+ let input = this.pending + chunk;
+ this.pending = "";
+ const items: TerminalProtocolItem[] = [];
+ const emitOutput = (data: string): void => {
+ if (!data) return;
+ const previous = items.at(-1);
+ if (previous?.type === "output") previous.data += data;
+ else items.push({ type: "output", data });
+ };
+
+ while (input.length > 0) {
+ const markerStart = input.indexOf(RECORDER_OSC_PREFIX);
+ if (markerStart < 0) {
+ const held = partialPrefixLength(input);
+ emitOutput(input.slice(0, input.length - held));
+ this.pending = input.slice(input.length - held);
+ break;
+ }
+
+ emitOutput(input.slice(0, markerStart));
+ const terminator = terminatorAt(input, markerStart + RECORDER_OSC_PREFIX.length);
+ if (!terminator) {
+ if (input.length - markerStart <= MAX_MARKER_LENGTH) {
+ this.pending = input.slice(markerStart);
+ break;
+ }
+ emitOutput(input.slice(markerStart, markerStart + RECORDER_OSC_PREFIX.length));
+ input = input.slice(markerStart + RECORDER_OSC_PREFIX.length);
+ continue;
+ }
+
+ const markerEnd = terminator.index + terminator.length;
+ const marker = input.slice(markerStart, markerEnd);
+ const body = input.slice(
+ markerStart + RECORDER_OSC_PREFIX.length,
+ terminator.index,
+ );
+ const event = parseMarkerBody(body, this.nonce);
+ if (event) items.push({ type: "event", event });
+ else emitOutput(marker);
+ input = input.slice(markerEnd);
+ }
+
+ return items;
+ }
+
+ flush(): TerminalProtocolItem[] {
+ if (!this.pending) return [];
+ const output = this.pending;
+ this.pending = "";
+ return [{ type: "output", data: output }];
+ }
+}
diff --git a/electron/terminal/session.ts b/electron/terminal/session.ts
new file mode 100644
index 0000000..cc91dd6
--- /dev/null
+++ b/electron/terminal/session.ts
@@ -0,0 +1,522 @@
+import { randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+
+import { spawn, type IPty } from "node-pty";
+
+import {
+ type SupportedShellId,
+ type TerminalActionResult,
+ type TerminalShellDescriptor,
+ type TerminalStatus,
+} from "../../common/terminal";
+import type { TerminalCommandPayload } from "../../common/events";
+import {
+ TerminalProtocolParser,
+ type TerminalProtocolEvent,
+} from "./protocol";
+import {
+ discoverShells,
+ selectDefaultShell,
+ type ShellDiscoveryOptions,
+} from "./shell-discovery";
+import {
+ prepareShellIntegration,
+ type IntegratedShellLaunch,
+} from "./shell-integration";
+import { TerminalTranscriptWriter } from "./transcript";
+
+export interface TerminalSessionOptions {
+ sessionDir: string;
+ sessionStartedAt: number;
+ publishCommand: (payload: TerminalCommandPayload) => void;
+ shellDiscovery?: ShellDiscoveryOptions;
+ initialCwd?: string;
+ closeGraceMs?: number;
+ spawnPty?: typeof spawn;
+}
+
+type StatusListener = (status: TerminalStatus) => void;
+type OutputListener = (data: string) => void;
+const execFileAsync = promisify(execFile);
+
+function message(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+function nonce(): string {
+ return randomBytes(24).toString("base64url");
+}
+
+/**
+ * Owns the one PTY associated with a recording. It has no global hooks and does
+ * no work until start() is called from the recording bar's Open terminal action.
+ */
+export class TerminalSession {
+ readonly shells: readonly TerminalShellDescriptor[];
+
+ private readonly options: TerminalSessionOptions;
+ private readonly statusListeners = new Set<StatusListener>();
+ private readonly outputListeners = new Set<OutputListener>();
+ private readonly writer: TerminalTranscriptWriter;
+ private process: IPty | null = null;
+ private launch: IntegratedShellLaunch | null = null;
+ private parser: TerminalProtocolParser | null = null;
+ private currentStatus: TerminalStatus;
+ private selected: TerminalShellDescriptor | null;
+ private closing: Promise<void> | null = null;
+ private starting: Promise<TerminalActionResult> | null = null;
+ private finishing: Promise<void> | null = null;
+ private finalizing = false;
+ private destroyed = false;
+ private readonly ownedProcessIds = new Set<number>();
+ private transcriptPaused = false;
+ private activeCommand: string | null = null;
+
+ constructor(options: TerminalSessionOptions) {
+ this.options = options;
+ this.shells = discoverShells(options.shellDiscovery);
+ this.selected = selectDefaultShell(this.shells, options.shellDiscovery);
+ this.currentStatus = {
+ state: "closed",
+ shell: this.selected,
+ integrationQuality: "none",
+ busy: false,
+ exitCode: null,
+ error: this.selected ? null : "No supported terminal shell was found.",
+ };
+ this.writer = new TerminalTranscriptWriter({
+ sessionDir: options.sessionDir,
+ sessionStartedAt: options.sessionStartedAt,
+ onCommand: ({ index }) => {
+ options.publishCommand({
+ commandId: index.id,
+ command: index.command,
+ cwd: index.cwd,
+ shell: index.shell,
+ exitCode: index.exitCode ?? undefined,
+ durationMs: index.durationMs,
+ interrupted: index.interrupted || undefined,
+ transcriptStartByte: index.transcriptStartByte,
+ transcriptEndByte: index.transcriptEndByte,
+ });
+ },
+ onError: (error) => this.fail(`Terminal transcript capture failed: ${error.message}`),
+ onDrain: () => {
+ if (!this.transcriptPaused || !this.process) return;
+ this.transcriptPaused = false;
+ this.process.resume();
+ },
+ });
+ }
+
+ status(): TerminalStatus {
+ return {
+ ...this.currentStatus,
+ shell: this.currentStatus.shell ? { ...this.currentStatus.shell } : null,
+ };
+ }
+
+ onStatus(listener: StatusListener): () => void {
+ this.statusListeners.add(listener);
+ listener(this.status());
+ return () => this.statusListeners.delete(listener);
+ }
+
+ onOutput(listener: OutputListener): () => void {
+ this.outputListeners.add(listener);
+ return () => this.outputListeners.delete(listener);
+ }
+
+ async start(shellId?: SupportedShellId): Promise<TerminalActionResult> {
+ if (this.finalizing || this.destroyed) {
+ return { ok: false, error: "The recorded terminal is closing." };
+ }
+ if (this.process) return { ok: true };
+ if (this.starting) return this.starting;
+ this.starting = this.startInternal(shellId).finally(() => {
+ this.starting = null;
+ });
+ return this.starting;
+ }
+
+ private async startInternal(
+ shellId?: SupportedShellId,
+ ): Promise<TerminalActionResult> {
+ if (this.closing) await this.closing;
+ const selected = shellId
+ ? this.shells.find((candidate) => candidate.id === shellId) ?? null
+ : this.selected;
+ if (!selected) return { ok: false, error: "The selected shell is unavailable." };
+ this.selected = selected;
+ this.setStatus({
+ state: "starting",
+ shell: selected,
+ integrationQuality: "none",
+ busy: true,
+ exitCode: null,
+ error: null,
+ });
+
+ const markerNonce = nonce();
+ try {
+ const launch = await prepareShellIntegration(selected, {
+ nonce: markerNonce,
+ env: process.env,
+ });
+ if (this.finalizing || this.destroyed) {
+ await launch.cleanup();
+ return { ok: false, error: "The recorded terminal is closing." };
+ }
+ const pty = (this.options.spawnPty ?? spawn)(
+ launch.executable,
+ launch.args,
+ {
+ name: "xterm-256color",
+ cols: 100,
+ rows: 30,
+ cwd: this.options.initialCwd ?? homedir(),
+ env: {
+ ...launch.env,
+ TERM: "xterm-256color",
+ TERM_PROGRAM: "skill-recorder",
+ SKILL_RECORDER_TERMINAL: "1",
+ },
+ },
+ );
+ this.launch = launch;
+ this.ownedProcessIds.clear();
+ this.parser = new TerminalProtocolParser(markerNonce);
+ this.process = pty;
+ this.setStatus({
+ state: "starting",
+ shell: selected,
+ integrationQuality: launch.integrationQuality,
+ busy: true,
+ exitCode: null,
+ error: null,
+ });
+ pty.onData((data) => this.handleData(data));
+ pty.onExit(({ exitCode }) => void this.handleExit(exitCode));
+ return { ok: true };
+ } catch (error) {
+ await this.cleanupLaunch();
+ this.process = null;
+ this.parser = null;
+ this.fail(`Could not start the recorded terminal: ${message(error)}`);
+ return { ok: false, error: this.currentStatus.error ?? "Could not start terminal." };
+ }
+ }
+
+ write(data: string): TerminalActionResult {
+ if (!this.process) return { ok: false, error: "The terminal is not running." };
+ this.process.write(data);
+ return { ok: true };
+ }
+
+ resize(columns: number, rows: number): TerminalActionResult {
+ if (
+ !this.process ||
+ !Number.isInteger(columns) ||
+ !Number.isInteger(rows) ||
+ columns < 2 ||
+ rows < 1 ||
+ columns > 1000 ||
+ rows > 500
+ ) {
+ return { ok: false, error: "Invalid terminal size." };
+ }
+ this.process.resize(columns, rows);
+ this.writer.resize(columns, rows);
+ return { ok: true };
+ }
+
+ isBusy(): boolean {
+ return this.currentStatus.busy;
+ }
+
+ busyDetails(): { busy: boolean; command: string | null } {
+ return { busy: this.currentStatus.busy, command: this.activeCommand };
+ }
+
+ async switchShell(shellId: SupportedShellId): Promise<TerminalActionResult> {
+ if (this.finalizing || this.destroyed) {
+ return { ok: false, error: "The recorded terminal is closing." };
+ }
+ const shell = this.shells.find((candidate) => candidate.id === shellId);
+ if (!shell) return { ok: false, error: "The selected shell is unavailable." };
+ if (this.currentStatus.busy && this.process) {
+ return { ok: false, error: "Finish the running command before switching shells." };
+ }
+ await this.closeProcess(250);
+ return this.start(shellId);
+ }
+
+ finish(): Promise<void> {
+ if (this.finishing) return this.finishing;
+ this.finalizing = true;
+ this.finishing = this.finishInternal();
+ return this.finishing;
+ }
+
+ private async finishInternal(): Promise<void> {
+ if (this.starting) await this.starting;
+ await this.closeProcess();
+ try {
+ await this.writer.close();
+ this.setStatus({
+ state: "closed",
+ shell: this.selected,
+ integrationQuality: this.currentStatus.integrationQuality,
+ busy: false,
+ exitCode: this.currentStatus.exitCode,
+ error: this.currentStatus.error,
+ });
+ } catch (error) {
+ this.fail(`Could not finalize the terminal transcript: ${message(error)}`);
+ throw error;
+ }
+ }
+
+ destroy(): void {
+ this.finalizing = true;
+ this.destroyed = true;
+ if (this.process) this.killProcessTreeSync(this.process, true);
+ this.process = null;
+ this.writer.destroy();
+ void this.cleanupLaunch();
+ }
+
+ private handleData(data: string): void {
+ const parser = this.parser;
+ if (!parser) return;
+ for (const item of parser.push(data)) {
+ if (item.type === "event") this.handleEvent(item.event);
+ else this.emitOutput(item.data);
+ }
+ }
+
+ private handleEvent(event: TerminalProtocolEvent): void {
+ switch (event.type) {
+ case "prompt-ready":
+ this.activeCommand = null;
+ this.setStatus({
+ ...this.currentStatus,
+ state: "idle",
+ busy: false,
+ error: this.writer.writeError?.message ?? null,
+ });
+ break;
+ case "command-start":
+ this.activeCommand = event.command;
+ this.writer.startCommand({ ...event, atMs: Date.now() });
+ this.setStatus({
+ ...this.currentStatus,
+ state: "running",
+ busy: true,
+ error: this.writer.writeError?.message ?? null,
+ });
+ break;
+ case "command-finish":
+ this.writer.finishCommand({ ...event, atMs: Date.now() });
+ this.activeCommand = null;
+ break;
+ }
+ }
+
+ private emitOutput(data: string): void {
+ if (!data) return;
+ const writable = this.writer.appendOutput(data);
+ if (!writable && this.process && !this.transcriptPaused) {
+ this.transcriptPaused = true;
+ this.process.pause();
+ }
+ for (const listener of this.outputListeners) listener(data);
+ }
+
+ private async handleExit(exitCode: number): Promise<void> {
+ const process = this.process;
+ if (!process) return;
+ this.process = null;
+ const parser = this.parser;
+ this.parser = null;
+ for (const item of parser?.flush() ?? []) {
+ if (item.type === "output") this.emitOutput(item.data);
+ }
+ this.writer.interruptActive();
+ this.activeCommand = null;
+ await this.cleanupLaunch();
+ this.setStatus({
+ state: "exited",
+ shell: this.selected,
+ integrationQuality: this.currentStatus.integrationQuality,
+ busy: false,
+ exitCode,
+ error: this.writer.writeError?.message ?? null,
+ });
+ }
+
+ private closeProcess(closeGraceMs = this.options.closeGraceMs ?? 750): Promise<void> {
+ if (this.closing) return this.closing;
+ this.closing = this.closeProcessInternal(closeGraceMs).finally(() => {
+ this.closing = null;
+ });
+ return this.closing;
+ }
+
+ private async closeProcessInternal(closeGraceMs: number): Promise<void> {
+ const pty = this.process;
+ if (!pty) {
+ await this.cleanupLaunch();
+ return;
+ }
+ const exited = new Promise<void>((resolve) => {
+ const disposable = pty.onExit(() => {
+ disposable.dispose();
+ resolve();
+ });
+ });
+ if (!this.currentStatus.busy) await this.killProcessTree(pty, false);
+ const grace = new Promise<void>((resolve) =>
+ setTimeout(resolve, closeGraceMs),
+ );
+ await Promise.race([exited, grace]);
+ if (this.process === pty) {
+ await this.killProcessTree(pty, false);
+ await Promise.race([
+ exited,
+ new Promise<void>((resolve) => setTimeout(resolve, 250)),
+ ]);
+ }
+ if (this.ownedProcessIds.size > 0 || this.process === pty) {
+ await this.killProcessTree(pty, true);
+ await Promise.race([
+ exited,
+ new Promise<void>((resolve) => setTimeout(resolve, 1_000)),
+ ]);
+ if (this.process === pty) {
+ throw new Error("The recorded terminal process did not exit after forced shutdown.");
+ }
+ }
+ this.ownedProcessIds.clear();
+ await this.cleanupLaunch();
+ }
+
+ private async killProcessTree(pty: IPty, force: boolean): Promise<void> {
+ const signal = force ? "SIGKILL" : "SIGHUP";
+ if (process.platform === "win32") {
+ try {
+ await execFileAsync(
+ "taskkill.exe",
+ ["/PID", String(pty.pid), "/T", ...(force ? ["/F"] : [])],
+ {
+ timeout: 2_000,
+ windowsHide: true,
+ },
+ );
+ } catch {
+ // The process tree may already have exited before taskkill inspected it.
+ }
+ } else {
+ for (const pid of await this.unixProcessTree(pty.pid)) {
+ this.ownedProcessIds.add(pid);
+ }
+ for (const pid of this.ownedProcessIds) {
+ try {
+ process.kill(pid, signal);
+ } catch {
+ // Descendants can exit while the process snapshot is being signalled.
+ }
+ }
+ }
+ try {
+ pty.kill(signal);
+ } catch {
+ // The PTY may exit between the identity check and kill().
+ }
+ }
+
+ private killProcessTreeSync(pty: IPty, force: boolean): void {
+ const signal = force ? "SIGKILL" : "SIGHUP";
+ try {
+ if (process.platform !== "win32") process.kill(-pty.pid, signal);
+ } catch {
+ // Best-effort fallback used only after asynchronous teardown failed.
+ }
+ try {
+ pty.kill(signal);
+ } catch {
+ // The PTY may already have exited.
+ }
+ }
+
+ private async unixProcessTree(rootPid: number): Promise<number[]> {
+ try {
+ const { stdout } = await execFileAsync(
+ "ps",
+ ["-axo", "pid=,ppid=,sess="],
+ { timeout: 2_000, maxBuffer: 8 * 1024 * 1024 },
+ );
+ const rows = stdout
+ .split(/\r?\n/)
+ .map((line) => line.trim().split(/\s+/).map(Number))
+ .filter(
+ (row): row is [number, number, number] =>
+ row.length === 3 && row.every(Number.isInteger),
+ );
+ const selected = new Set<number>([rootPid]);
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const [pid, parentPid, sessionId] of rows) {
+ if (
+ pid !== process.pid &&
+ !selected.has(pid) &&
+ (sessionId === rootPid || selected.has(parentPid))
+ ) {
+ selected.add(pid);
+ changed = true;
+ }
+ }
+ }
+ const depth = (pid: number): number => {
+ let current = pid;
+ let value = 0;
+ const visited = new Set<number>();
+ while (current !== rootPid && !visited.has(current)) {
+ visited.add(current);
+ const parent = rows.find(([candidate]) => candidate === current)?.[1];
+ if (parent == null) break;
+ current = parent;
+ value += 1;
+ }
+ return value;
+ };
+ return [...selected].sort((left, right) => depth(right) - depth(left));
+ } catch {
+ return [rootPid];
+ }
+ }
+
+ private async cleanupLaunch(): Promise<void> {
+ const launch = this.launch;
+ this.launch = null;
+ if (launch) await launch.cleanup();
+ }
+
+ private fail(error: string): void {
+ this.setStatus({
+ ...this.currentStatus,
+ state: "error",
+ busy: Boolean(this.process),
+ error,
+ });
+ }
+
+ private setStatus(status: TerminalStatus): void {
+ this.currentStatus = status;
+ const snapshot = this.status();
+ for (const listener of this.statusListeners) listener(snapshot);
+ }
+}
diff --git a/electron/terminal/shell-discovery.ts b/electron/terminal/shell-discovery.ts
new file mode 100644
index 0000000..9aaa66e
--- /dev/null
+++ b/electron/terminal/shell-discovery.ts
@@ -0,0 +1,180 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import type {
+ SupportedShellId,
+ TerminalShellDescriptor,
+} from "../../common/terminal";
+
+export interface ShellDiscoveryOptions {
+ platform?: NodeJS.Platform;
+ env?: NodeJS.ProcessEnv;
+ fileExists?: (candidate: string) => boolean;
+}
+
+const SHELL_NAMES: Record<SupportedShellId, string> = {
+ zsh: "Z shell",
+ bash: "Bash",
+ fish: "fish",
+ pwsh: "PowerShell",
+ "windows-powershell": "Windows PowerShell",
+};
+
+function shellIdFromExecutable(executable: string): SupportedShellId | null {
+ const name = path.basename(executable).toLowerCase().replace(/\.exe$/, "");
+ switch (name) {
+ case "zsh":
+ case "bash":
+ case "fish":
+ case "pwsh":
+ return name;
+ case "powershell":
+ return "windows-powershell";
+ default:
+ return null;
+ }
+}
+
+function descriptor(
+ id: SupportedShellId,
+ executable: string,
+): TerminalShellDescriptor {
+ return { id, displayName: SHELL_NAMES[id], executable };
+}
+
+function envValue(env: NodeJS.ProcessEnv, name: string): string | undefined {
+ const direct = env[name];
+ if (direct !== undefined) return direct;
+ const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+ return key ? env[key] : undefined;
+}
+
+function pathCandidates(
+ env: NodeJS.ProcessEnv,
+ names: readonly string[],
+ platform: NodeJS.Platform,
+): string[] {
+ const pathValue = envValue(env, "PATH") ?? "";
+ const delimiter = platform === "win32" ? ";" : ":";
+ const join = platform === "win32" ? path.win32.join : path.posix.join;
+ const candidates: string[] = [];
+ for (const directory of pathValue.split(delimiter)) {
+ const cleaned = directory.trim().replace(/^"(.*)"$/, "$1");
+ if (!cleaned) continue;
+ for (const name of names) candidates.push(join(cleaned, name));
+ }
+ return candidates;
+}
+
+function discoverUnix(
+ env: NodeJS.ProcessEnv,
+ fileExists: (candidate: string) => boolean,
+): TerminalShellDescriptor[] {
+ const found = new Map<SupportedShellId, TerminalShellDescriptor>();
+ const add = (candidate: string): void => {
+ const id = shellIdFromExecutable(candidate);
+ if (id !== "zsh" && id !== "bash" && id !== "fish" && id !== "pwsh") return;
+ if (!found.has(id) && fileExists(candidate)) found.set(id, descriptor(id, candidate));
+ };
+
+ const configured = envValue(env, "SHELL");
+ if (configured) add(configured);
+
+ for (const candidate of [
+ "/bin/zsh",
+ "/usr/bin/zsh",
+ "/opt/homebrew/bin/zsh",
+ "/usr/local/bin/zsh",
+ "/bin/bash",
+ "/usr/bin/bash",
+ "/usr/local/bin/bash",
+ "/opt/homebrew/bin/fish",
+ "/usr/local/bin/fish",
+ "/usr/bin/fish",
+ "/bin/fish",
+ "/opt/homebrew/bin/pwsh",
+ "/usr/local/bin/pwsh",
+ "/usr/bin/pwsh",
+ ...pathCandidates(env, ["zsh", "bash", "fish", "pwsh"], "darwin"),
+ ]) {
+ add(candidate);
+ }
+
+ return [...found.values()];
+}
+
+function discoverWindows(
+ env: NodeJS.ProcessEnv,
+ fileExists: (candidate: string) => boolean,
+): TerminalShellDescriptor[] {
+ const found = new Map<SupportedShellId, TerminalShellDescriptor>();
+ const add = (id: SupportedShellId, candidate: string): void => {
+ if (!found.has(id) && fileExists(candidate)) found.set(id, descriptor(id, candidate));
+ };
+
+ for (const candidate of pathCandidates(env, ["pwsh.exe"], "win32")) add("pwsh", candidate);
+ const programFiles = envValue(env, "ProgramFiles");
+ if (programFiles) {
+ add(
+ "pwsh",
+ path.win32.join(programFiles, "PowerShell", "7", "pwsh.exe"),
+ );
+ }
+
+ for (const candidate of pathCandidates(env, ["powershell.exe"], "win32")) {
+ add("windows-powershell", candidate);
+ }
+ const systemRoot = envValue(env, "SystemRoot") ?? envValue(env, "WINDIR");
+ if (systemRoot) {
+ add(
+ "windows-powershell",
+ path.win32.join(
+ systemRoot,
+ "System32",
+ "WindowsPowerShell",
+ "v1.0",
+ "powershell.exe",
+ ),
+ );
+ }
+
+ return [...found.values()];
+}
+
+/** Discovers known shells using only environment and filesystem lookups. */
+export function discoverShells(
+ options: ShellDiscoveryOptions = {},
+): TerminalShellDescriptor[] {
+ const platform = options.platform ?? process.platform;
+ const env = options.env ?? process.env;
+ const fileExists = options.fileExists ?? existsSync;
+ return platform === "win32"
+ ? discoverWindows(env, fileExists)
+ : discoverUnix(env, fileExists);
+}
+
+export function selectDefaultShell(
+ shells: readonly TerminalShellDescriptor[],
+ options: Pick<ShellDiscoveryOptions, "platform" | "env"> = {},
+): TerminalShellDescriptor | null {
+ const platform = options.platform ?? process.platform;
+ const env = options.env ?? process.env;
+ if (platform !== "win32") {
+ const configured = envValue(env, "SHELL");
+ if (configured) {
+ const normalized = path.resolve(configured);
+ const match = shells.find((shell) => path.resolve(shell.executable) === normalized);
+ if (match) return match;
+ }
+ }
+
+ const preference: readonly SupportedShellId[] =
+ platform === "win32"
+ ? ["pwsh", "windows-powershell"]
+ : ["zsh", "bash", "fish", "pwsh"];
+ for (const id of preference) {
+ const match = shells.find((shell) => shell.id === id);
+ if (match) return match;
+ }
+ return null;
+}
diff --git a/electron/terminal/shell-integration.ts b/electron/terminal/shell-integration.ts
new file mode 100644
index 0000000..1be60fa
--- /dev/null
+++ b/electron/terminal/shell-integration.ts
@@ -0,0 +1,428 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+
+import type {
+ TerminalIntegrationQuality,
+ TerminalShellDescriptor,
+} from "../../common/terminal";
+
+export interface ShellIntegrationOptions {
+ nonce: string;
+ env?: NodeJS.ProcessEnv;
+ homeDir?: string;
+ temporaryRoot?: string;
+}
+
+export interface IntegratedShellLaunch {
+ executable: string;
+ args: string[];
+ env: Record<string, string>;
+ integrationQuality: TerminalIntegrationQuality;
+ integrationDirectory: string;
+ cleanup: () => Promise<void>;
+}
+
+const OSC = "6973;skill-recorder;1";
+
+function environment(input: NodeJS.ProcessEnv): Record<string, string> {
+ return Object.fromEntries(
+ Object.entries(input).filter((entry): entry is [string, string] => entry[1] !== undefined),
+ );
+}
+
+function shQuote(value: string): string {
+ return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function psQuote(value: string): string {
+ return `'${value.replaceAll("'", "''")}'`;
+}
+
+const POSIX_ENCODER = `
+__sr_pct() {
+ local LC_ALL=C __sr_input="$1" __sr_output="" __sr_char __sr_hex __sr_i
+ __sr_i=0
+ while [ "$__sr_i" -lt "\${#__sr_input}" ]; do
+ __sr_char="\${__sr_input:$__sr_i:1}"
+ case "$__sr_char" in
+ [a-zA-Z0-9._~-]) __sr_output="\${__sr_output}\${__sr_char}" ;;
+ *) printf -v __sr_hex '%02X' "'$__sr_char"; __sr_output="\${__sr_output}%\${__sr_hex}" ;;
+ esac
+ __sr_i=$((__sr_i + 1))
+ done
+ REPLY="$__sr_output"
+}
+`;
+
+function zshScript(nonce: string, profile: string): string {
+ return `# Skill Recorder generated shell integration. This file is session-local.
+if [[ -r ${shQuote(profile)} ]]; then
+ source ${shQuote(profile)}
+fi
+${POSIX_ENCODER}
+zmodload zsh/datetime 2>/dev/null
+typeset -g __sr_active_id=""
+typeset -gi __sr_counter=0
+
+__sr_now() {
+ local __sr_raw="\${EPOCHREALTIME/./}"
+ REPLY="\${__sr_raw[1,13]}"
+}
+
+__sr_emit_ready() {
+ printf '\\033]${OSC};${nonce};ready\\007'
+}
+
+__sr_preexec() {
+ local __sr_command="$1" __sr_cwd="$PWD" __sr_command_enc __sr_cwd_enc __sr_id_enc
+ __sr_counter=$((__sr_counter + 1))
+ __sr_active_id="$$-$__sr_counter"
+ __sr_pct "$__sr_active_id"; __sr_id_enc="$REPLY"
+ __sr_pct "$__sr_command"; __sr_command_enc="$REPLY"
+ __sr_pct "$__sr_cwd"; __sr_cwd_enc="$REPLY"
+ __sr_now
+ printf '\\033]${OSC};${nonce};start;%s;%s;%s;zsh;%s\\007' "$__sr_id_enc" "$__sr_command_enc" "$__sr_cwd_enc" "$REPLY"
+}
+
+__sr_precmd() {
+ local __sr_status="$?" __sr_id_enc
+ if [[ -n "$__sr_active_id" ]]; then
+ __sr_pct "$__sr_active_id"; __sr_id_enc="$REPLY"
+ __sr_now
+ printf '\\033]${OSC};${nonce};finish;%s;%s;%s\\007' "$__sr_id_enc" "$__sr_status" "$REPLY"
+ __sr_active_id=""
+ fi
+ __sr_emit_ready
+}
+
+autoload -Uz add-zsh-hook
+add-zsh-hook preexec __sr_preexec
+add-zsh-hook precmd __sr_precmd
+`;
+}
+
+function bashScript(nonce: string, profile: string): string {
+ return `# Skill Recorder generated shell integration. This file is session-local.
+if [ -r ${shQuote(profile)} ]; then
+ . ${shQuote(profile)}
+fi
+${POSIX_ENCODER}
+__sr_active_id=""
+__sr_counter=0
+__sr_guard=0
+__sr_user_prompt_commands=()
+__sr_prompt_command_decl="$(declare -p PROMPT_COMMAND 2>/dev/null || :)"
+if [[ "$__sr_prompt_command_decl" == "declare -a"* ]]; then
+ __sr_user_prompt_commands=("\${PROMPT_COMMAND[@]}")
+elif [ -n "\${PROMPT_COMMAND-}" ]; then
+ __sr_user_prompt_commands=("\${PROMPT_COMMAND}")
+fi
+__sr_user_histcontrol="\${HISTCONTROL-}"
+__sr_user_histignore="\${HISTIGNORE-}"
+HISTFILE=/dev/null
+
+__sr_arm_history() {
+ __sr_user_histcontrol="\${HISTCONTROL-}"
+ __sr_user_histignore="\${HISTIGNORE-}"
+ HISTCONTROL=
+ HISTIGNORE=
+}
+
+__sr_now() {
+ REPLY="$(date +%s)000"
+}
+
+__sr_emit_ready() {
+ printf '\\033]${OSC};${nonce};ready\\007'
+}
+
+__sr_debug() {
+ local __sr_trigger="$BASH_COMMAND" __sr_command __sr_cwd __sr_command_enc __sr_cwd_enc __sr_id_enc
+ [ "$__sr_guard" -ne 0 ] && return
+ [ -n "$__sr_active_id" ] && return
+ case "$__sr_trigger" in __sr_*|trap\\ *|PROMPT_COMMAND=*) return ;; esac
+ __sr_guard=1
+ HISTCONTROL="$__sr_user_histcontrol"
+ HISTIGNORE="$__sr_user_histignore"
+ __sr_command="$(HISTTIMEFORMAT= builtin history 1)"
+ __sr_command="\${__sr_command#"\${__sr_command%%[![:space:]]*}"}"
+ __sr_command="\${__sr_command#* }"
+ __sr_command="\${__sr_command#"\${__sr_command%%[![:space:]]*}"}"
+ if [ -z "$__sr_command" ]; then
+ __sr_guard=0
+ return
+ fi
+ __sr_counter=$((__sr_counter + 1))
+ __sr_active_id="$$-$__sr_counter"
+ __sr_cwd="$PWD"
+ __sr_pct "$__sr_active_id"; __sr_id_enc="$REPLY"
+ __sr_pct "$__sr_command"; __sr_command_enc="$REPLY"
+ __sr_pct "$__sr_cwd"; __sr_cwd_enc="$REPLY"
+ __sr_now
+ printf '\\033]${OSC};${nonce};start;%s;%s;%s;bash;%s\\007' "$__sr_id_enc" "$__sr_command_enc" "$__sr_cwd_enc" "$REPLY"
+ __sr_guard=0
+}
+
+__sr_prompt() {
+ local __sr_status="$?" __sr_id_enc __sr_prompt_hook
+ __sr_guard=1
+ HISTCONTROL="$__sr_user_histcontrol"
+ HISTIGNORE="$__sr_user_histignore"
+ if [ -n "$__sr_active_id" ]; then
+ __sr_pct "$__sr_active_id"; __sr_id_enc="$REPLY"
+ __sr_now
+ printf '\\033]${OSC};${nonce};finish;%s;%s;%s\\007' "$__sr_id_enc" "$__sr_status" "$REPLY"
+ __sr_active_id=""
+ fi
+ __sr_emit_ready
+ for __sr_prompt_hook in "\${__sr_user_prompt_commands[@]}"; do
+ [ -n "$__sr_prompt_hook" ] && eval "$__sr_prompt_hook"
+ done
+ __sr_arm_history
+ __sr_guard=0
+ return "$__sr_status"
+}
+
+__sr_guard=1
+__sr_arm_history
+trap '__sr_debug' DEBUG
+PROMPT_COMMAND='__sr_prompt'
+__sr_guard=0
+`;
+}
+
+function fishScript(nonce: string, profile: string): string {
+ return `# Skill Recorder generated shell integration. This file is session-local.
+if test -r ${shQuote(profile)}
+ source ${shQuote(profile)}
+end
+
+set -g __sr_active_id ""
+set -g __sr_counter 0
+
+function __sr_pct
+ string escape --style=url -- "$argv[1]"
+end
+
+function __sr_now
+ printf '%s000' (date +%s)
+end
+
+function __sr_prompt_ready --on-event fish_prompt
+ printf '\\e]${OSC};${nonce};ready\\a'
+end
+
+function __sr_preexec --on-event fish_preexec
+ set -g __sr_counter (math $__sr_counter + 1)
+ set -g __sr_active_id "$fish_pid-$__sr_counter"
+ printf '\\e]${OSC};${nonce};start;%s;%s;%s;fish;%s\\a' (__sr_pct "$__sr_active_id") (__sr_pct "$argv[1]") (__sr_pct "$PWD") (__sr_now)
+end
+
+function __sr_postexec --on-event fish_postexec
+ set -l __sr_status $status
+ if test -n "$__sr_active_id"
+ printf '\\e]${OSC};${nonce};finish;%s;%s;%s\\a' (__sr_pct "$__sr_active_id") "$__sr_status" (__sr_now)
+ set -g __sr_active_id ""
+ end
+end
+`;
+}
+
+function powershellScript(
+ nonce: string,
+ shell: "pwsh" | "windows-powershell",
+): string {
+ return `# Skill Recorder generated shell integration. This file is session-local.
+$__srProfile = $PROFILE
+if (Test-Path -LiteralPath $__srProfile) { . $__srProfile }
+
+$script:__srNonce = ${psQuote(nonce)}
+$script:__srShell = ${psQuote(shell)}
+$script:__srCounter = 0
+$script:__srActiveId = $null
+$script:__srActiveIsNative = $false
+$script:__srLastHistoryId = -1
+$__srPromptCommand = Get-Command prompt -CommandType Function -ErrorAction SilentlyContinue
+$__srReadLineCommand = Get-Command PSConsoleHostReadLine -CommandType Function -ErrorAction SilentlyContinue
+$script:__srPriorPrompt = if ($null -ne $__srPromptCommand) { $__srPromptCommand.ScriptBlock } else { $null }
+$script:__srPriorReadLine = if ($null -ne $__srReadLineCommand) { $__srReadLineCommand.ScriptBlock } else { $null }
+
+function script:__srPct([string] $Value) {
+ $builder = [System.Text.StringBuilder]::new()
+ foreach ($byte in [System.Text.Encoding]::UTF8.GetBytes($Value)) {
+ if (($byte -ge 0x41 -and $byte -le 0x5A) -or
+ ($byte -ge 0x61 -and $byte -le 0x7A) -or
+ ($byte -ge 0x30 -and $byte -le 0x39) -or
+ $byte -in 0x2D, 0x2E, 0x5F, 0x7E) {
+ [void] $builder.Append([char] $byte)
+ } else {
+ [void] $builder.Append(('%{0:X2}' -f $byte))
+ }
+ }
+ $builder.ToString()
+}
+
+function script:__srNow { [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() }
+
+function script:__srStart([string] $Command, [long] $At = 0) {
+ $script:__srCounter++
+ $script:__srActiveId = "$PID-$script:__srCounter"
+ $tokens = $null
+ $parseErrors = $null
+ $ast = [System.Management.Automation.Language.Parser]::ParseInput($Command, [ref] $tokens, [ref] $parseErrors)
+ $commandAsts = @($ast.FindAll({
+ param($node)
+ $node -is [System.Management.Automation.Language.CommandAst]
+ }, $true))
+ $script:__srActiveIsNative = $false
+ if ($commandAsts.Count -gt 0) {
+ $commandName = $commandAsts[-1].GetCommandName()
+ if ($null -ne $commandName) {
+ $resolved = Get-Command $commandName -ErrorAction SilentlyContinue |
+ Select-Object -First 1
+ $script:__srActiveIsNative =
+ $null -ne $resolved -and
+ $resolved.CommandType -in @(
+ [System.Management.Automation.CommandTypes]::Application,
+ [System.Management.Automation.CommandTypes]::ExternalScript
+ )
+ }
+ }
+ if ($At -le 0) { $At = __srNow }
+ $marker = "$([char]27)]${OSC};$script:__srNonce;start;$(__srPct $script:__srActiveId);$(__srPct $Command);$(__srPct (Get-Location).Path);$script:__srShell;$At$([char]7)"
+ [Console]::Write($marker)
+}
+
+function script:__srFinish([int] $Code) {
+ if ($null -ne $script:__srActiveId) {
+ $marker = "$([char]27)]${OSC};$script:__srNonce;finish;$(__srPct $script:__srActiveId);$Code;$(__srNow)$([char]7)"
+ [Console]::Write($marker)
+ $script:__srActiveId = $null
+ $script:__srActiveIsNative = $false
+ }
+}
+
+function script:__srExitCode([bool] $Succeeded) {
+ if ($Succeeded) { return 0 }
+ if ($script:__srActiveIsNative -and $null -ne $global:LASTEXITCODE) {
+ return [int] $global:LASTEXITCODE
+ }
+ return 1
+}
+
+function global:PSConsoleHostReadLine {
+ if ($null -ne $script:__srPriorReadLine) {
+ $line = & $script:__srPriorReadLine
+ } else {
+ $line = [Microsoft.PowerShell.PSConsoleReadLine]::ReadLine($Host.Runspace, $ExecutionContext)
+ }
+ __srStart $line
+ return $line
+}
+
+function global:prompt {
+ $succeeded = $?
+ $exitCode = __srExitCode $succeeded
+ $latest = Get-History -Count 1 -ErrorAction SilentlyContinue
+ if ($null -ne $script:__srActiveId) {
+ __srFinish $exitCode
+ if ($null -ne $latest) { $script:__srLastHistoryId = $latest.Id }
+ } elseif ($null -ne $latest -and $latest.Id -ne $script:__srLastHistoryId) {
+ $script:__srLastHistoryId = $latest.Id
+ __srStart $latest.CommandLine ([DateTimeOffset]$latest.StartExecutionTime).ToUnixTimeMilliseconds()
+ __srFinish $(__srExitCode $succeeded)
+ }
+ [Console]::Write("$([char]27)]${OSC};$script:__srNonce;ready$([char]7)")
+ if ($null -ne $script:__srPriorPrompt) {
+ return & $script:__srPriorPrompt
+ }
+ return "PS $($executionContext.SessionState.Path.CurrentLocation)> "
+}
+`;
+}
+
+/**
+ * Builds a session-local shell startup file. The user's profile is sourced from
+ * the wrapper, but is never written or replaced.
+ */
+export async function prepareShellIntegration(
+ shell: TerminalShellDescriptor,
+ options: ShellIntegrationOptions,
+): Promise<IntegratedShellLaunch> {
+ if (!/^[A-Za-z0-9_-]{16,128}$/.test(options.nonce)) {
+ throw new Error("Terminal integration nonce must be 16-128 URL-safe characters");
+ }
+ const baseEnv = options.env ?? process.env;
+ const home = options.homeDir ?? homedir();
+ const root = options.temporaryRoot ?? tmpdir();
+ const directory = await mkdtemp(path.join(root, "skill-recorder-terminal-"));
+ const env = environment(baseEnv);
+ let scriptPath: string;
+ let script: string;
+ let args: string[];
+
+ switch (shell.id) {
+ case "zsh": {
+ scriptPath = path.join(directory, ".zshrc");
+ const originalZdotdir = baseEnv.ZDOTDIR || home;
+ script = zshScript(options.nonce, path.join(originalZdotdir, ".zshrc"));
+ args = ["-i"];
+ env.ZDOTDIR = directory;
+ break;
+ }
+ case "bash":
+ scriptPath = path.join(directory, "bashrc");
+ script = bashScript(options.nonce, path.join(home, ".bashrc"));
+ args = ["--rcfile", scriptPath, "-i"];
+ break;
+ case "fish": {
+ const fishDirectory = path.join(directory, "fish");
+ await writeFile(path.join(directory, ".keep"), "", { mode: 0o600 });
+ const originalConfig = baseEnv.XDG_CONFIG_HOME
+ ? path.join(baseEnv.XDG_CONFIG_HOME, "fish", "config.fish")
+ : path.join(home, ".config", "fish", "config.fish");
+ await mkdir(fishDirectory, { recursive: true });
+ scriptPath = path.join(fishDirectory, "config.fish");
+ script = fishScript(options.nonce, originalConfig);
+ args = ["-i"];
+ env.XDG_CONFIG_HOME = directory;
+ break;
+ }
+ case "pwsh":
+ case "windows-powershell":
+ scriptPath = path.join(directory, "profile.ps1");
+ script = powershellScript(options.nonce, shell.id);
+ args = [
+ "-NoLogo",
+ "-NoProfile",
+ "-NoExit",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ scriptPath,
+ ];
+ break;
+ }
+
+ try {
+ await writeFile(scriptPath, script, { encoding: "utf8", mode: 0o600 });
+ } catch (error) {
+ await rm(directory, { recursive: true, force: true });
+ throw error;
+ }
+
+ let cleaned = false;
+ return {
+ executable: shell.executable,
+ args,
+ env,
+ integrationQuality: "full",
+ integrationDirectory: directory,
+ cleanup: async () => {
+ if (cleaned) return;
+ cleaned = true;
+ await rm(directory, { recursive: true, force: true });
+ },
+ };
+}
diff --git a/electron/terminal/terminal.test.ts b/electron/terminal/terminal.test.ts
new file mode 100644
index 0000000..c19282c
--- /dev/null
+++ b/electron/terminal/terminal.test.ts
@@ -0,0 +1,304 @@
+import assert from "node:assert/strict";
+import { readFile, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import type { TerminalShellDescriptor } from "../../common/terminal";
+import {
+ encodeRecorderMarker,
+ TerminalProtocolParser,
+} from "./protocol";
+import { discoverShells, selectDefaultShell } from "./shell-discovery";
+import { prepareShellIntegration } from "./shell-integration";
+import {
+ listTerminalCommands,
+ searchTerminalOutput,
+} from "./artifacts";
+import { TerminalTranscriptWriter } from "./transcript";
+import { createDescriberTools } from "../describer/tools";
+
+const NONCE = "recorded_terminal_nonce_1234";
+
+test("terminal protocol removes only valid nonce-authenticated markers across chunks", () => {
+ const parser = new TerminalProtocolParser(NONCE);
+ const marker = encodeRecorderMarker(NONCE, {
+ type: "command-start",
+ id: "cmd-1",
+ command: "printf 'hello world'",
+ cwd: "/tmp/a b",
+ shell: "bash",
+ atMs: 1_000,
+ });
+ const split = Math.floor(marker.length / 2);
+ assert.deepEqual(parser.push(`before${marker.slice(0, split)}`), [
+ { type: "output", data: "before" },
+ ]);
+ assert.deepEqual(parser.push(`${marker.slice(split)}after`), [
+ {
+ type: "event",
+ event: {
+ type: "command-start",
+ id: "cmd-1",
+ command: "printf 'hello world'",
+ cwd: "/tmp/a b",
+ shell: "bash",
+ atMs: 1_000,
+ },
+ },
+ { type: "output", data: "after" },
+ ]);
+
+ const foreign = encodeRecorderMarker("different_nonce_123456", {
+ type: "prompt-ready",
+ });
+ assert.deepEqual(parser.push(foreign), [{ type: "output", data: foreign }]);
+});
+
+test("shell discovery honors supported defaults without invoking a shell", () => {
+ const files = new Set([
+ "/custom/fish",
+ "/custom/pwsh",
+ "/bin/zsh",
+ "C:\\Tools\\pwsh.exe",
+ ]);
+ const unix = discoverShells({
+ platform: "darwin",
+ env: { SHELL: "/custom/fish", PATH: "/bin:/custom" },
+ fileExists: (candidate) => files.has(candidate),
+ });
+ assert.equal(unix[0].id, "fish");
+ assert.equal(unix.some((shell) => shell.id === "pwsh"), true);
+ assert.equal(
+ selectDefaultShell(unix, {
+ platform: "darwin",
+ env: { SHELL: "/custom/fish" },
+ })?.id,
+ "fish",
+ );
+ assert.equal(
+ selectDefaultShell(
+ [{ id: "pwsh", displayName: "PowerShell", executable: "/custom/pwsh" }],
+ { platform: "linux", env: {} },
+ )?.id,
+ "pwsh",
+ );
+
+ const windows = discoverShells({
+ platform: "win32",
+ env: { PATH: "C:\\Tools" },
+ fileExists: (candidate) => files.has(candidate),
+ });
+ assert.equal(selectDefaultShell(windows, { platform: "win32" })?.id, "pwsh");
+});
+
+test("temporary shell integration chains but never modifies the real profile", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "skill-recorder-shell-test-"));
+ const home = path.join(root, "home");
+ await mkdir(home);
+ const profile = path.join(home, ".bashrc");
+ await writeFile(profile, "export USER_SETTING=kept\n");
+ const shell: TerminalShellDescriptor = {
+ id: "bash",
+ displayName: "Bash",
+ executable: "/bin/bash",
+ };
+ try {
+ const launch = await prepareShellIntegration(shell, {
+ nonce: NONCE,
+ homeDir: home,
+ temporaryRoot: root,
+ env: {},
+ });
+ assert.equal(await readFile(profile, "utf8"), "export USER_SETTING=kept\n");
+ assert.equal(launch.executable, "/bin/bash");
+ assert.deepEqual(launch.args.slice(0, 1), ["--rcfile"]);
+ const wrapper = await readFile(launch.args[1], "utf8");
+ assert.match(wrapper, /Skill Recorder generated shell integration/);
+ assert.match(wrapper, /USER_SETTING|\.bashrc/);
+ assert.match(wrapper, /HISTTIMEFORMAT= builtin history 1/);
+ assert.match(wrapper, /HISTFILE=\/dev\/null/);
+ assert.match(wrapper, /__sr_user_prompt_commands=\("\$\{PROMPT_COMMAND\[@\]\}"\)/);
+ await launch.cleanup();
+ await assert.rejects(readFile(launch.args[1], "utf8"));
+
+ const powerShell = await prepareShellIntegration(
+ {
+ id: "pwsh",
+ displayName: "PowerShell",
+ executable: "/custom/pwsh",
+ },
+ {
+ nonce: NONCE,
+ homeDir: home,
+ temporaryRoot: root,
+ env: {},
+ },
+ );
+ const powerShellWrapper = await readFile(powerShell.args.at(-1)!, "utf8");
+ assert.match(powerShellWrapper, /__srPromptCommand\.ScriptBlock/);
+ assert.doesNotMatch(powerShellWrapper, /__srPriorPrompt\.ScriptBlock/);
+ assert.doesNotMatch(powerShellWrapper, /__srPriorReadLine\.ScriptBlock/);
+ await powerShell.cleanup();
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("transcript persists full output and an indexed command range", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "skill-recorder-terminal-test-"));
+ try {
+ const commands: string[] = [];
+ const writer = new TerminalTranscriptWriter({
+ sessionDir: root,
+ sessionStartedAt: 10_000,
+ onCommand: ({ index }) => commands.push(index.id),
+ });
+ writer.appendOutput("prompt$ ", 10_050);
+ writer.startCommand({
+ type: "command-start",
+ id: "cmd-1",
+ command: "printf secret-result",
+ cwd: "/work",
+ shell: "bash",
+ atMs: 10_100,
+ });
+ writer.appendOutput("secret-result\r\n", 10_125);
+ writer.finishCommand({
+ type: "command-finish",
+ id: "cmd-1",
+ exitCode: 0,
+ atMs: 10_175,
+ });
+ await writer.close(10_200);
+
+ assert.deepEqual(commands, ["cmd-1"]);
+ const page = await listTerminalCommands(root);
+ assert.equal(page.commands.length, 1);
+ assert.equal(page.commands[0].durationMs, 75);
+ assert.equal(page.commands[0].exitCode, 0);
+ assert(
+ page.commands[0].transcriptEndByte >
+ page.commands[0].transcriptStartByte,
+ );
+
+ const output = await searchTerminalOutput(root, {
+ commandId: "cmd-1",
+ query: "secret-result",
+ });
+ assert.equal(output.hits.length, 1);
+ assert.match(output.hits[0].text, /secret-result/);
+ assert.equal(output.hits[0].commandId, "cmd-1");
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("closing a transcript marks an active command interrupted", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "skill-recorder-terminal-test-"));
+ try {
+ const writer = new TerminalTranscriptWriter({
+ sessionDir: root,
+ sessionStartedAt: 1_000,
+ });
+
+ writer.startCommand({
+ type: "command-start",
+ id: "cmd-running",
+ command: "long-task",
+ cwd: "/work",
+ shell: "zsh",
+ atMs: 1_100,
+ });
+ writer.appendOutput("still running", 1_200);
+ await writer.close(1_250);
+ const page = await listTerminalCommands(root);
+ assert.equal(page.commands[0].interrupted, true);
+ assert.equal(page.commands[0].exitCode, null);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("terminal output tool applies redaction before returning an excerpt", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "skill-recorder-terminal-test-"));
+ const secret = "ghp_" + "Q1w2E3r4T5y6U7i8O9p0A1s2D3f4G5h6J7k8";
+ try {
+ const writer = new TerminalTranscriptWriter({
+ sessionDir: root,
+ sessionStartedAt: 1_000,
+ });
+ writer.appendOutput(`token=${secret}\r\n`, 1_500);
+ await writer.close();
+ const tools = createDescriberTools({
+ sessionDir: root,
+ startedAt: 1_000,
+ extractor: null,
+ redaction: {
+ current: {
+ redactText: (text) => text.split(secret).join("[redacted]"),
+ frameRedactor: null,
+ },
+ },
+ onSubmit: () => undefined,
+ });
+ const tool = tools.find((candidate) => candidate.name === "search_terminal_output");
+ assert.ok(tool?.handler);
+ const handler = tool.handler as (args: unknown) => Promise<unknown> | unknown;
+ const result = await handler({ query: "ghp_" });
+ const serialized = String(result);
+ assert.equal(serialized.includes(secret), false);
+ assert.match(serialized, /\[redacted\]/);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("terminal command tool truncates fields and caps oversized page requests", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "skill-recorder-terminal-test-"));
+ try {
+ const writer = new TerminalTranscriptWriter({
+ sessionDir: root,
+ sessionStartedAt: 1_000,
+ });
+ for (let index = 0; index < 55; index += 1) {
+ writer.startCommand({
+ type: "command-start",
+ id: `cmd-${index}`,
+ command: index === 0 ? "x".repeat(70_000) : `echo ${index}`,
+ cwd: index === 0 ? `/${"y".repeat(70_000)}` : "/work",
+ shell: "bash",
+ atMs: 1_100 + index * 10,
+ });
+ writer.finishCommand({
+ type: "command-finish",
+ id: `cmd-${index}`,
+ exitCode: 0,
+ atMs: 1_105 + index * 10,
+ });
+ }
+ await writer.close();
+ const tools = createDescriberTools({
+ sessionDir: root,
+ startedAt: 1_000,
+ extractor: null,
+ redaction: { current: null },
+ onSubmit: () => undefined,
+ });
+ const tool = tools.find((candidate) => candidate.name === "list_terminal_commands");
+ assert.ok(tool?.handler);
+ const handler = tool.handler as (args: unknown) => Promise<unknown> | unknown;
+ const serialized = String(await handler({ limit: 1_000 }));
+ const result = JSON.parse(serialized) as {
+ count: number;
+ commands: Array<{ command: string; cwd: string }>;
+ };
+ assert.equal(result.count, 50);
+ assert.match(result.commands[0].command, /\[truncated\]$/);
+ assert.match(result.commands[0].cwd, /\[truncated\]$/);
+ assert(serialized.length < 20_000);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/electron/terminal/transcript.ts b/electron/terminal/transcript.ts
new file mode 100644
index 0000000..623fde9
--- /dev/null
+++ b/electron/terminal/transcript.ts
@@ -0,0 +1,191 @@
+import { createWriteStream, mkdirSync, type WriteStream } from "node:fs";
+import path from "node:path";
+
+import {
+ TERMINAL_ARTIFACTS,
+ type TerminalCommandIndex,
+} from "../../common/terminal";
+import type {
+ CommandFinishEvent,
+ CommandStartEvent,
+} from "./protocol";
+
+export interface FinalizedTerminalCommand {
+ index: TerminalCommandIndex;
+}
+
+export interface TerminalTranscriptWriterOptions {
+ sessionDir: string;
+ sessionStartedAt: number;
+ columns?: number;
+ rows?: number;
+ onCommand?: (command: FinalizedTerminalCommand) => void;
+ onError?: (error: Error) => void;
+ onDrain?: () => void;
+}
+
+interface ActiveCommand {
+ event: CommandStartEvent;
+ transcriptStartByte: number;
+}
+
+function streamClosed(stream: WriteStream): Promise<void> {
+ return new Promise((resolve) => stream.once("close", resolve));
+}
+
+function asError(error: unknown): Error {
+ return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Streams the marker-free PTY output and its command index to session artifacts.
+ * The transcript is asciicast v2 so it remains replayable and grep-able without
+ * introducing a second, unbounded copy of terminal output.
+ */
+export class TerminalTranscriptWriter {
+ readonly directory: string;
+ readonly transcriptPath: string;
+ readonly commandsPath: string;
+
+ private readonly transcript: WriteStream;
+ private readonly commands: WriteStream;
+ private readonly transcriptClosed: Promise<void>;
+ private readonly commandsClosed: Promise<void>;
+ private readonly sessionStartedAt: number;
+ private readonly onCommand?: (command: FinalizedTerminalCommand) => void;
+ private readonly onError?: (error: Error) => void;
+ private transcriptBytes = 0;
+ private active: ActiveCommand | null = null;
+ private error: Error | null = null;
+ private ended = false;
+
+ constructor(options: TerminalTranscriptWriterOptions) {
+ this.sessionStartedAt = options.sessionStartedAt;
+ this.onCommand = options.onCommand;
+ this.onError = options.onError;
+ this.directory = path.join(options.sessionDir, TERMINAL_ARTIFACTS.directory);
+ this.transcriptPath = path.join(this.directory, TERMINAL_ARTIFACTS.transcript);
+ this.commandsPath = path.join(this.directory, TERMINAL_ARTIFACTS.commands);
+ mkdirSync(this.directory, { recursive: true });
+
+ this.transcript = createWriteStream(this.transcriptPath, { flags: "a" });
+ this.commands = createWriteStream(this.commandsPath, { flags: "a" });
+ this.transcriptClosed = streamClosed(this.transcript);
+ this.commandsClosed = streamClosed(this.commands);
+ const handleError = (value: unknown): void => {
+ if (this.error) return;
+ this.error = asError(value);
+ this.onError?.(this.error);
+ };
+ this.transcript.on("error", handleError);
+ this.commands.on("error", handleError);
+ if (options.onDrain) this.transcript.on("drain", options.onDrain);
+
+ const header = {
+ version: 2,
+ width: options.columns ?? 100,
+ height: options.rows ?? 30,
+ timestamp: Math.floor(options.sessionStartedAt / 1000),
+ env: { TERM: "xterm-256color", SHELL: "skill-recorder" },
+ };
+ this.writeTranscriptLine(JSON.stringify(header));
+ }
+
+ get writeError(): Error | null {
+ return this.error;
+ }
+
+ get byteOffset(): number {
+ return this.transcriptBytes;
+ }
+
+ appendOutput(data: string, epoch = Date.now()): boolean {
+ if (this.ended || !data) return true;
+ const atSeconds = Math.max(0, epoch - this.sessionStartedAt) / 1000;
+ return this.writeTranscriptLine(JSON.stringify([atSeconds, "o", data]));
+ }
+
+ resize(columns: number, rows: number, epoch = Date.now()): boolean {
+ if (this.ended) return true;
+ const atSeconds = Math.max(0, epoch - this.sessionStartedAt) / 1000;
+ return this.writeTranscriptLine(
+ JSON.stringify([atSeconds, "r", `${columns}x${rows}`]),
+ );
+ }
+
+ startCommand(event: CommandStartEvent): void {
+ if (this.ended) return;
+ if (this.active) this.finalizeActive(null, event.atMs, true);
+ this.active = {
+ event,
+ transcriptStartByte: this.transcriptBytes,
+ };
+ }
+
+ finishCommand(event: CommandFinishEvent): TerminalCommandIndex | null {
+ if (!this.active || this.active.event.id !== event.id) return null;
+ return this.finalizeActive(event.exitCode, event.atMs, false);
+ }
+
+ interruptActive(epoch = Date.now()): TerminalCommandIndex | null {
+ return this.active ? this.finalizeActive(null, epoch, true) : null;
+ }
+
+ async close(epoch = Date.now()): Promise<void> {
+ if (this.ended) {
+ await Promise.all([this.transcriptClosed, this.commandsClosed]);
+ if (this.error) throw this.error;
+ return;
+ }
+ this.ended = true;
+ if (this.active) this.finalizeActive(null, epoch, true);
+ this.transcript.end();
+ this.commands.end();
+ await Promise.all([this.transcriptClosed, this.commandsClosed]);
+ if (this.error) throw this.error;
+ }
+
+ destroy(): void {
+ this.ended = true;
+ this.transcript.destroy();
+ this.commands.destroy();
+ }
+
+ private relative(epoch: number): number {
+ return Math.max(0, Math.round(epoch - this.sessionStartedAt));
+ }
+
+ private finalizeActive(
+ exitCode: number | null,
+ endEpoch: number,
+ interrupted: boolean,
+ ): TerminalCommandIndex {
+ const active = this.active;
+ if (!active) throw new Error("No active terminal command to finalize");
+ this.active = null;
+ const startAtMs = this.relative(active.event.atMs);
+ const endAtMs = Math.max(startAtMs, this.relative(endEpoch));
+ const index: TerminalCommandIndex = {
+ id: active.event.id,
+ command: active.event.command,
+ cwd: active.event.cwd,
+ shell: active.event.shell,
+ startAtMs,
+ endAtMs,
+ durationMs: endAtMs - startAtMs,
+ exitCode,
+ interrupted,
+ transcriptStartByte: active.transcriptStartByte,
+ transcriptEndByte: this.transcriptBytes,
+ };
+ this.commands.write(`${JSON.stringify(index)}\n`);
+ this.onCommand?.({ index });
+ return index;
+ }
+
+ private writeTranscriptLine(line: string): boolean {
+ const output = `${line}\n`;
+ this.transcriptBytes += Buffer.byteLength(output);
+ return this.transcript.write(output);
+ }
+}
diff --git a/electron/tray.ts b/electron/tray.ts
index 4635841..0a5396a 100644
--- a/electron/tray.ts
+++ b/electron/tray.ts
@@ -25,6 +25,7 @@ function fallbackTrayIcon(): Electron.NativeImage {
export function createTray(
recorder: RecorderController,
startRecording: () => Promise<unknown>,
+ stopRecording: () => Promise<unknown>,
showRecorderWindow: () => void,
showRecordingControls: () => void,
): Tray {
@@ -37,7 +38,7 @@ export function createTray(
Menu.buildFromTemplate([
{
label: recording ? "Stop recording" : "Start recording",
- click: () => void (recording ? recorder.stop() : startRecording()),
+ click: () => void (recording ? stopRecording() : startRecording()),
},
{ type: "separator" },
{
diff --git a/electron/window.ts b/electron/window.ts
index 3849fc2..45ec19d 100644
--- a/electron/window.ts
+++ b/electron/window.ts
@@ -84,6 +84,7 @@ export function createRecordingControlsWindow(): BrowserWindow {
const display = screen.getDisplayNearestPoint(screen.getCursorScreenPoint());
bounds = initialRecordingControlsBounds(display.workArea);
}
+
const win = new BrowserWindow({
...bounds,
show: false,
@@ -122,6 +123,34 @@ export function createRecordingControlsWindow(): BrowserWindow {
return win;
}
+/** Resizable app-owned terminal; the PTY remains in the main process. */
+export function createTerminalWindow(): BrowserWindow {
+ const display = screen.getDisplayNearestPoint(screen.getCursorScreenPoint());
+ const width = Math.min(960, Math.max(640, display.workArea.width - 80));
+ const height = Math.min(640, Math.max(420, display.workArea.height - 100));
+ const win = new BrowserWindow({
+ width,
+ height,
+ minWidth: 560,
+ minHeight: 360,
+ show: false,
+ title: "Skill Recorder: Recorded terminal",
+ icon: windowIcon(),
+ backgroundColor: "#211f1e",
+ webPreferences: {
+ preload: path.join(dirname, "preload.cjs"),
+ contextIsolation: true,
+ nodeIntegration: false,
+ sandbox: false,
+ backgroundThrottling: false,
+ },
+ });
+ registerDevelopmentDevToolsShortcut(win);
+ win.setContentProtection(true);
+ loadRoute(win, "terminal");
+ return win;
+}
+
/** Resize a panel above the bar while preserving its on-screen bottom edge. */
export function setRecordingControlsExpanded(
win: BrowserWindow,
diff --git a/evals/README.md b/evals/README.md
index cedbbaa..4dff971 100644
--- a/evals/README.md
+++ b/evals/README.md
@@ -20,6 +20,7 @@ faithful stand-in for a real recording. Matching **mock pages** live in
```bash
npm run eval # all scenarios
+npm run eval:terminal # recorded-terminal command/output scenarios
npm run eval -- --only=web-to-spreadsheet
npm run eval -- --judge # also run the semantic LLM judge
npm run eval -- --keep # print the temp sessions dir (artifacts kept)
@@ -86,6 +87,9 @@ Business, repeatable knowledge-work patterns (`evals/scenarios/`):
| `release-notes` | Compile release notes from merged PRs, then version + deploy (Terminal + GitHub + editor) |
| `lead-to-crm` | Qualify inbound leads and enter them into the CRM (Mail + LinkedIn + Salesforce) |
| `windows-deploy` | Deploy a web app to Azure and log the live URL, on Windows (Edge + Windows Terminal/pwsh + Excel) |
+| `terminal-output-required` | Diagnose a failing test by querying indexed terminal output |
+| `terminal-failure-recovery` | Distinguish a failed deployment from the successful retry |
+| `terminal-sensitive-output` | Use terminal results without leaking a captured token |
The last three are longer, multi-app **business processes** — they loop over several
records, mix a native app with the browser and/or terminal, and end in a submit /
diff --git a/evals/run.ts b/evals/run.ts
index 3f98062..13d00e8 100644
--- a/evals/run.ts
+++ b/evals/run.ts
@@ -19,8 +19,10 @@ import os from "node:os";
import path from "node:path";
import type { Analysis } from "../common/analysis";
+import { TERMINAL_ARTIFACTS } from "../common/terminal";
import { processSession } from "../electron/pipeline";
import { Describer } from "../electron/describer/describer";
+import { buildRedactor, scanSession } from "../electron/sensitive/scanner";
import { judgeAnalysis, type JudgeResult } from "./judge";
import { makeSessionMeta, materializeEvents, type Scenario } from "./scenario";
import { scenarios } from "./scenarios/index";
@@ -70,6 +72,30 @@ function materialize(root: string, scenario: Scenario): string {
path.join(dir, "events.jsonl"),
events.map((e) => JSON.stringify(e)).join("\n") + "\n",
);
+ if (scenario.terminal) {
+ const terminalDir = path.join(dir, TERMINAL_ARTIFACTS.directory);
+ mkdirSync(terminalDir, { recursive: true });
+ const cast = [
+ JSON.stringify({
+ version: 2,
+ width: 100,
+ height: 30,
+ timestamp: Math.floor(startedAt / 1000),
+ env: { TERM: "xterm-256color", SHELL: "eval" },
+ }),
+ ...scenario.terminal.output.map((entry) =>
+ JSON.stringify([entry.atMs / 1000, "o", entry.text]),
+ ),
+ ];
+ writeFileSync(
+ path.join(terminalDir, TERMINAL_ARTIFACTS.transcript),
+ `${cast.join("\n")}\n`,
+ );
+ writeFileSync(
+ path.join(terminalDir, TERMINAL_ARTIFACTS.commands),
+ `${scenario.terminal.commands.map((entry) => JSON.stringify(entry)).join("\n")}\n`,
+ );
+ }
return dir;
}
@@ -109,11 +135,22 @@ async function main(): Promise<void> {
try {
const dir = materialize(root, scenario);
await processSession(dir);
- const analysis: Analysis = await describer.analyze(scenario.id);
+ const { values } = await scanSession(scenario.id);
+ const analysis: Analysis = await describer.analyze(scenario.id, {
+ redactText: buildRedactor(values),
+ frameRedactor: null,
+ });
res.stepCount = analysis.steps.length;
res.intent = analysis.intent;
res.score = scoreAnalysis(analysis, scenario.rubric);
res.ok = res.score.pass;
+ const leaked = scenario.sensitiveValues?.find((value) =>
+ JSON.stringify(analysis).includes(value),
+ );
+ if (leaked) {
+ res.ok = false;
+ res.error = "Sensitive terminal output reached the final analysis.";
+ }
if (flags.judge) {
try {
res.judge = await judgeAnalysis(scenario, analysis, flags.model);
diff --git a/evals/scenario.ts b/evals/scenario.ts
index 2b7a4b0..4ff5cc3 100644
--- a/evals/scenario.ts
+++ b/evals/scenario.ts
@@ -9,6 +9,7 @@
// pages these flows reference).
import { EventType } from "../common/events";
+import type { TerminalCommandIndex } from "../common/terminal";
import type { RecEvent, SessionMeta } from "../common/types";
/** An event as authored in a scenario: just a time offset + type + payload. */
@@ -51,6 +52,13 @@ export interface Scenario {
truth: string;
/** Produce the ordered raw events for this recording. */
build: () => RawEvent[];
+ /** Optional full recorded-terminal artifacts for output-aware describer evals. */
+ terminal?: {
+ commands: TerminalCommandIndex[];
+ output: { atMs: number; text: string }[];
+ };
+ /** Raw values that must not survive local redaction into the final analysis. */
+ sensitiveValues?: string[];
rubric: Rubric;
}
@@ -145,7 +153,13 @@ export const terminal = (
atMs,
type: EventType.TerminalCommand,
source: "terminal",
- payload: { command, cwd, shell: "zsh", ...extra },
+ payload: {
+ commandId: `cmd-${atMs}`,
+ command,
+ cwd,
+ shell: "zsh",
+ ...extra,
+ },
});
export const marker = (atMs: number, note: string): RawEvent => ({
diff --git a/evals/scenarios/index.ts b/evals/scenarios/index.ts
index 71634ff..6b3abf8 100644
--- a/evals/scenarios/index.ts
+++ b/evals/scenarios/index.ts
@@ -8,6 +8,11 @@ import { releaseNotes } from "./release-notes";
import { researchCompile } from "./research-compile";
import { webToSpreadsheet } from "./web-to-spreadsheet";
import { windowsDeploy } from "./windows-deploy";
+import {
+ terminalFailureRecovery,
+ terminalOutputRequired,
+ terminalSensitiveOutput,
+} from "./terminal-output";
/** All eval scenarios, in run order. */
export const scenarios: Scenario[] = [
@@ -23,4 +28,7 @@ export const scenarios: Scenario[] = [
leadToCrm,
// Windows-shaped capture (win32 app names + browser.url + pwsh):
windowsDeploy,
+ terminalOutputRequired,
+ terminalFailureRecovery,
+ terminalSensitiveOutput,
];
diff --git a/evals/scenarios/terminal-output.ts b/evals/scenarios/terminal-output.ts
new file mode 100644
index 0000000..03d9739
--- /dev/null
+++ b/evals/scenarios/terminal-output.ts
@@ -0,0 +1,151 @@
+import type { TerminalCommandIndex } from "../../common/terminal";
+import {
+ recorder,
+ terminal,
+ type Scenario,
+} from "../scenario";
+
+const command = (
+ id: string,
+ text: string,
+ startAtMs: number,
+ endAtMs: number,
+ exitCode: number,
+): TerminalCommandIndex => ({
+ id,
+ command: text,
+ cwd: "/work/checkout",
+ shell: "bash",
+ startAtMs,
+ endAtMs,
+ durationMs: endAtMs - startAtMs,
+ exitCode,
+ interrupted: false,
+ transcriptStartByte: 0,
+ transcriptEndByte: 0,
+});
+
+const OUTPUT_SECRET =
+ "ghp_" + "Z9y8X7w6V5u4T3s2R1q0P9o8N7m6L5k4J3h2";
+
+export const terminalOutputRequired: Scenario = {
+ id: "terminal-output-required",
+ title: "Diagnose Payment Tests",
+ truth:
+ "The user ran the full tests, read the terminal failure identifying payment validation, then ran the focused payment tests successfully.",
+ build: () => [
+ recorder(0),
+ terminal(1_000, "npm test", "/work/checkout", {
+ commandId: "tests-all",
+ exitCode: 1,
+ durationMs: 4_000,
+ }),
+ terminal(6_000, "npm test -- payment", "/work/checkout", {
+ commandId: "tests-payment",
+ exitCode: 0,
+ durationMs: 2_000,
+ }),
+ recorder(9_000),
+ ],
+ terminal: {
+ commands: [
+ command("tests-all", "npm test", 1_000, 5_000, 1),
+ command("tests-payment", "npm test -- payment", 6_000, 8_000, 0),
+ ],
+ output: [
+ { atMs: 1_200, text: "Running 84 tests...\r\n" },
+ {
+ atMs: 4_900,
+ text: "FAIL checkout/payment-validation.test.ts: rejects an expired card\r\n",
+ },
+ { atMs: 6_200, text: "Running payment tests...\r\n" },
+ { atMs: 7_900, text: "PASS 12 tests\r\n" },
+ ],
+ },
+ rubric: {
+ intentKeywordsAll: ["payment", "test"],
+ minSteps: 2,
+ maxSteps: 3,
+ orderedActions: [["run", "test"], ["payment", "focused", "targeted", "pass"]],
+ mustMentionAny: [["validation", "expired card"], ["pass", "12"]],
+ forbidden: ["skill recorder"],
+ },
+};
+
+export const terminalFailureRecovery: Scenario = {
+ id: "terminal-failure-recovery",
+ title: "Recover Azure Deployment",
+ platform: "win32",
+ truth:
+ "The first Azure deployment failed because authentication had expired; the user signed in and reran it successfully.",
+ build: () => [
+ recorder(0),
+ terminal(1_000, "az webapp up", "C:\\work\\site", {
+ commandId: "deploy-failed",
+ shell: "pwsh",
+ exitCode: 1,
+ }),
+ terminal(4_000, "az login", "C:\\work\\site", {
+ commandId: "login",
+ shell: "pwsh",
+ exitCode: 0,
+ }),
+ terminal(7_000, "az webapp up", "C:\\work\\site", {
+ commandId: "deploy-ok",
+ shell: "pwsh",
+ exitCode: 0,
+ }),
+ recorder(11_000),
+ ],
+ terminal: {
+ commands: [
+ { ...command("deploy-failed", "az webapp up", 1_000, 3_000, 1), shell: "pwsh" },
+ { ...command("login", "az login", 4_000, 6_000, 0), shell: "pwsh" },
+ { ...command("deploy-ok", "az webapp up", 7_000, 10_000, 0), shell: "pwsh" },
+ ],
+ output: [
+ { atMs: 2_900, text: "ERROR: AADSTS70043 refresh token has expired\r\n" },
+ { atMs: 5_900, text: "You have logged in.\r\n" },
+ { atMs: 9_900, text: "Webapp deployed to https://atlas-eval.azurewebsites.net\r\n" },
+ ],
+ },
+ rubric: {
+ intentKeywordsAll: ["deploy"],
+ intentKeywordsAny: [["azure", "webapp"]],
+ minSteps: 3,
+ maxSteps: 4,
+ orderedActions: [["deploy", "failed"], ["login", "sign in"], ["deploy", "success"]],
+ mustMentionAny: [["expired", "authentication", "token"], ["atlas-eval", "azurewebsites"]],
+ forbidden: ["skill recorder"],
+ },
+};
+
+export const terminalSensitiveOutput: Scenario = {
+ id: "terminal-sensitive-output",
+ title: "Inspect Deployment Output Safely",
+ truth:
+ "The user inspected deployment output for the Atlas service; a token printed by the command must be redacted before analysis.",
+ build: () => [
+ recorder(0),
+ terminal(1_000, "deploy --service atlas", "/work/atlas", {
+ commandId: "deploy-atlas",
+ exitCode: 0,
+ }),
+ recorder(5_000),
+ ],
+ terminal: {
+ commands: [command("deploy-atlas", "deploy --service atlas", 1_000, 4_000, 0)],
+ output: [
+ { atMs: 2_000, text: `Authorization token: ${OUTPUT_SECRET}\r\n` },
+ { atMs: 3_900, text: "Deployment complete for service atlas in production\r\n" },
+ ],
+ },
+ sensitiveValues: [OUTPUT_SECRET],
+ rubric: {
+ intentKeywordsAll: ["atlas", "deploy"],
+ minSteps: 1,
+ maxSteps: 2,
+ mustMentionAny: [["production", "complete", "successful"]],
+ forbidden: ["ghp_", OUTPUT_SECRET.toLowerCase(), "skill recorder"],
+ },
+};
diff --git a/evals/skillbuilder/run.ts b/evals/skillbuilder/run.ts
index 8f666a1..3bf0c2b 100644
--- a/evals/skillbuilder/run.ts
+++ b/evals/skillbuilder/run.ts
@@ -127,7 +127,7 @@ function printResult(r: Result): void {
console.error(` value · {{${val.id}}} ${val.name}${val.value ? ` = ${val.value}` : ""}`);
}
for (const [i, s] of (r.plan?.steps ?? []).entries()) {
- const tool = s.tool ? ` {${s.tool}}` : "";
+ const tool = s.tools.length ? ` {${s.tools.join(" → ")}}` : "";
console.error(` ${i + 1}. [${s.kind}] ${s.text}${tool}`);
}
console.error(` score: ${Math.round((r.score?.score ?? 0) * 100)}% · ${r.ok ? "PASS" : "FAIL"} · ${(r.durationMs / 1000).toFixed(1)}s`);
diff --git a/evals/skillbuilder/score.ts b/evals/skillbuilder/score.ts
index 824df4a..792f104 100644
--- a/evals/skillbuilder/score.ts
+++ b/evals/skillbuilder/score.ts
@@ -26,9 +26,9 @@ export interface SkillScoreResult {
const has = (haystack: string, needle: string): boolean =>
haystack.toLowerCase().includes(needle.toLowerCase());
-/** All the text a native-tool check looks at: every step's text + tool, plus allowed-tools. */
+/** All the text a native-tool check looks at: every step's text + tools, plus allowed-tools. */
function toolText(plan: SkillPlan): string {
- const steps = plan.steps.map((s) => `${s.text} ${s.tool}`).join("\n");
+ const steps = plan.steps.map((s) => `${s.text} ${s.tools.join(" ")}`).join("\n");
return `${steps}\n${plan.allowedTools.join(" ")}`;
}
diff --git a/package-lock.json b/package-lock.json
index b64c24f..ae68cd8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,8 +14,11 @@
"@secretlint/core": "^13.0.4",
"@secretlint/secretlint-rule-pattern": "^13.0.4",
"@secretlint/secretlint-rule-preset-recommend": "^13.0.4",
+ "@xterm/addon-fit": "0.11.0",
+ "@xterm/xterm": "6.0.0",
"archiver": "^8.0.0",
"koffi": "^3.1.1",
+ "node-pty": "1.1.0",
"react": "^19.2.5",
"react-dom": "^19.2.5",
"sharp": "^0.35.3",
@@ -2633,6 +2636,21 @@
"node": ">=10.0.0"
}
},
+ "node_modules/@xterm/addon-fit": {
+ "version": "0.11.0",
+ "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.11.0.tgz",
+ "integrity": "sha1-ukd4tp/MkESgYMIXa74HdlfXs34=",
+ "license": "MIT"
+ },
+ "node_modules/@xterm/xterm": {
+ "version": "6.0.0",
+ "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz",
+ "integrity": "sha1-k2N7Dy7jpwcYtXRqJ8nFBq8WdFs=",
+ "license": "MIT",
+ "workspaces": [
+ "addons/*"
+ ]
+ },
"node_modules/abort-controller": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz",
@@ -6362,6 +6380,22 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/node-pty": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+ "integrity": "sha1-Fhk21FpHdRwuO2lMNl5zAXQXqIc=",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^7.1.0"
+ }
+ },
+ "node_modules/node-pty/node_modules/node-addon-api": {
+ "version": "7.1.1",
+ "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+ "integrity": "sha1-Grpmk7DyVSWKBJ1iEykykyKq1Vg=",
+ "license": "MIT"
+ },
"node_modules/normalize-path": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
diff --git a/package.json b/package.json
index d1f81ae..160bc23 100644
--- a/package.json
+++ b/package.json
@@ -19,8 +19,9 @@
"check:lockfile": "node scripts/check-lockfile-portability.mjs",
"typecheck": "tsc --noEmit",
"typecheck:evals": "tsc --noEmit -p evals/tsconfig.json",
- "test": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs --test evals/builder-imports.test.ts common/architecture-registry.test.ts electron/architectures/catalogue-registry.test.ts common/audio.test.ts common/microphone.test.ts common/screen.test.ts common/narration.test.ts common/sensitive.test.ts electron/recording-controls-bounds.test.ts electron/recorder-window-sizing.test.ts electron/recording-privacy.test.ts electron/crash-guards.test.ts electron/recorder/controller.test.ts electron/recorder/session-store.test.ts electron/frames/extractor.test.ts electron/narration/audio-analysis.test.ts electron/narration/analyze-gate.test.ts electron/narration/transcribe.test.ts electron/narration/whisper.test.ts electron/sensitive/scanner.test.ts electron/sensitive/secrets.test.ts electron/sensitive/tessdata-source.test.ts electron/sensitive/ocr.test.ts electron/sensitive/frame-redact.test.ts electron/sensitive/frame-heuristics.test.ts electron/sessions.test.ts electron/debug-bundle.test.ts electron/skillbuilder/placement.test.ts src/skill-placement.test.ts scripts/compliance.test.mjs",
+ "test": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs --test evals/builder-imports.test.ts common/architecture-registry.test.ts electron/architectures/catalogue-registry.test.ts common/audio.test.ts common/microphone.test.ts common/screen.test.ts common/narration.test.ts common/sensitive.test.ts common/skill.test.ts electron/recording-controls-bounds.test.ts electron/recorder-window-sizing.test.ts electron/recording-privacy.test.ts electron/crash-guards.test.ts electron/recorder/controller.test.ts electron/recorder/session-store.test.ts electron/frames/extractor.test.ts electron/narration/audio-analysis.test.ts electron/narration/analyze-gate.test.ts electron/narration/transcribe.test.ts electron/narration/whisper.test.ts electron/sensitive/scanner.test.ts electron/sensitive/secrets.test.ts electron/sensitive/tessdata-source.test.ts electron/sensitive/ocr.test.ts electron/sensitive/frame-redact.test.ts electron/sensitive/frame-heuristics.test.ts electron/terminal/terminal.test.ts electron/sessions.test.ts electron/debug-bundle.test.ts electron/skillbuilder/plan-tools.test.ts electron/skillbuilder/placement.test.ts src/skill-placement.test.ts scripts/compliance.test.mjs",
"eval": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/run.ts",
+ "eval:terminal": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/run.ts --only=terminal-output-required,terminal-failure-recovery,terminal-sensitive-output",
"eval:builder": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/builder/run.ts",
"eval:skill": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/skillbuilder/run.ts",
"eval:sensitive": "node --experimental-transform-types --no-warnings --import ./evals/register.mjs evals/sensitive/run.ts",
@@ -45,8 +46,11 @@
"@secretlint/core": "^13.0.4",
"@secretlint/secretlint-rule-pattern": "^13.0.4",
"@secretlint/secretlint-rule-preset-recommend": "^13.0.4",
+ "@xterm/addon-fit": "0.11.0",
+ "@xterm/xterm": "6.0.0",
"archiver": "^8.0.0",
"koffi": "^3.1.1",
+ "node-pty": "1.1.0",
"react": "^19.2.5",
"react-dom": "^19.2.5",
"sharp": "^0.35.3",
@@ -84,6 +88,7 @@
"electron-winstaller": false,
"protobufjs": false,
"tesseract.js": false
@@ -118,6 +123,7 @@
"node_modules/sharp/**",
"node_modules/@img/**",
"node_modules/koffi/**",
+ "node_modules/node-pty/**",
"node_modules/@koromix/**",
"node_modules/@github/copilot-*/**",
"node_modules/@huggingface/transformers/**",
diff --git a/scripts/verify-packaged-compliance.mjs b/scripts/verify-packaged-compliance.mjs
index 4b79862..143008e 100644
--- a/scripts/verify-packaged-compliance.mjs
+++ b/scripts/verify-packaged-compliance.mjs
@@ -1,5 +1,5 @@
import { existsSync } from "node:fs";
-import { copyFile, readFile, readdir } from "node:fs/promises";
+import { chmod, copyFile, readFile, readdir } from "node:fs/promises";
import { createRequire } from "node:module";
import path from "node:path";
@@ -22,6 +22,21 @@ async function listUnpackedFiles(root) {
return files;
}
+async function ensureNodePtyHelpersAreExecutable(resources, platform) {
+ if (platform === "win32") return;
+ const nodePtyRoot = path.join(
+ resources,
+ "app.asar.unpacked",
+ "node_modules",
+ "node-pty",
+ );
+ for (const file of await listUnpackedFiles(nodePtyRoot)) {
+ if (path.basename(file) === "spawn-helper") {
+ await chmod(path.join(nodePtyRoot, file), 0o755);
+ }
+ }
+}
+
export default async function verifyPackagedCompliance(context) {
const platform = context.electronPlatformName;
const productFilename = context.packager.appInfo.productFilename;
@@ -30,6 +45,8 @@ export default async function verifyPackagedCompliance(context) {
? path.join(context.appOutDir, `${productFilename}.app`, "Contents", "Resources")
: path.join(context.appOutDir, "resources");
+ await ensureNodePtyHelpersAreExecutable(resources, platform);
+
const compliance = path.join(resources, "compliance");
const electronNotices = path.join(compliance, "electron");
const noticeManifest = JSON.parse(
diff --git a/src/App.css b/src/App.css
index 7256716..0225851 100644
--- a/src/App.css
+++ b/src/App.css
@@ -98,6 +98,137 @@ body[data-route="recording-controls"] #root {
height: 100%;
}
+body[data-route="terminal"] {
+ width: 100vw;
+ height: 100vh;
+ overflow: hidden;
+ background: #211f1e;
+ color: #f8f5ef;
+ user-select: text;
+}
+
+body[data-route="terminal"] #root {
+ width: 100%;
+ height: 100%;
+}
+
+.terminal-page {
+ width: 100%;
+ height: 100%;
+ display: grid;
+ grid-template-rows: auto auto minmax(0, 1fr);
+ background: #211f1e;
+}
+
+.terminal-toolbar {
+ min-height: 58px;
+ display: flex;
+ align-items: center;
+ gap: 18px;
+ padding: 9px 12px 9px 16px;
+ border-bottom: 1px solid rgba(255, 255, 255, 0.12);
+ background: #292624;
+ user-select: none;
+}
+
+.terminal-recording-state {
+ min-width: 0;
+ display: flex;
+ align-items: center;
+ gap: 9px;
+}
+
+.terminal-recording-state > span:last-child {
+ min-width: 0;
+ display: grid;
+}
+
+.terminal-recording-state strong {
+ font-size: 12px;
+ font-weight: 650;
+}
+
+.terminal-recording-state small {
+ color: #aaa39d;
+ font-size: 10px;
+}
+
+.terminal-state-dot {
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: #8e8883;
+ flex: none;
+}
+
+.terminal-state-dot.running,
+.terminal-state-dot.starting {
+ background: #e7b45f;
+}
+
+.terminal-state-dot.error {
+ background: #f47c68;
+}
+
+.terminal-state-dot.idle {
+ background: #63c59b;
+}
+
+.terminal-shell-picker {
+ margin-left: auto;
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ color: #aaa39d;
+ font-size: 11px;
+ user-select: none;
+}
+
+.terminal-shell-picker select {
+ max-width: 190px;
+ border: 1px solid rgba(255, 255, 255, 0.16);
+ border-radius: 7px;
+ padding: 5px 26px 5px 8px;
+ color: #f8f5ef;
+ background: #35312f;
+ font: 11px var(--sans);
+}
+
+.terminal-hide {
+ padding: 6px 11px;
+ border: 1px solid rgba(255, 255, 255, 0.16);
+ color: #ddd7d1;
+ background: transparent;
+ font-size: 11px;
+}
+
+.terminal-hide:hover {
+ background: rgba(255, 255, 255, 0.06);
+}
+
+.terminal-error {
+ padding: 7px 14px;
+ color: #ffd7cf;
+ background: rgba(244, 124, 104, 0.14);
+ border-bottom: 1px solid rgba(244, 124, 104, 0.35);
+ font-size: 11px;
+}
+
+.terminal-error:empty {
+ display: none;
+}
+
+.terminal-viewport {
+ min-width: 0;
+ min-height: 0;
+ padding: 8px 0 0 10px;
+ overflow: hidden;
+}
+
+.terminal-viewport .xterm {
+ height: 100%;
+}
+
/* --- Shared primitives ---------------------------------------------------- */
.eyebrow {
@@ -990,6 +1121,8 @@ button:focus-visible,
.recording-bar button,
.recording-discard-confirm,
.recording-discard-confirm button,
+ .recording-terminal-confirm,
+ .recording-terminal-confirm button,
.recording-microphone-menu,
.recording-microphone-menu button {
-webkit-app-region: no-drag;
@@ -1091,6 +1224,55 @@ button:focus-visible,
background: var(--hud-hover);
}
+ .recording-terminal {
+ position: relative;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 6px;
+ height: 36px;
+ min-width: 89px;
+ padding: 0 10px;
+ border: 1px solid var(--hud-line);
+ border-radius: 10px;
+ background: var(--hud-surface-2);
+ color: var(--hud-muted);
+ font-size: 10.5px;
+ font-weight: 600;
+ }
+
+ .recording-terminal:not(:disabled):hover,
+ .recording-terminal.active {
+ border-color: var(--hud-line-strong);
+ color: var(--hud-text);
+ background: var(--hud-hover);
+ }
+
+ .recording-terminal.error {
+ border-color: color-mix(in srgb, var(--hud-accent) 55%, transparent);
+ color: var(--hud-accent);
+ }
+
+ .recording-terminal-dot {
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--hud-muted);
+ }
+
+ .recording-terminal-dot.running,
+ .recording-terminal-dot.starting {
+ background: var(--hud-warn);
+ }
+
+ .recording-terminal-dot.idle {
+ background: hsl(158, 62%, 52%);
+ }
+
+ .recording-terminal-dot.error {
+ background: var(--hud-accent);
+ }
+
.recording-discard,
.recording-done {
height: 36px;
@@ -1125,12 +1307,14 @@ button:focus-visible,
}
.recording-bar button:disabled,
- .recording-discard-confirm button:disabled {
+ .recording-discard-confirm button:disabled,
+ .recording-terminal-confirm button:disabled {
opacity: 0.45;
}
.recording-bar button:focus-visible,
.recording-discard-confirm button:focus-visible,
+ .recording-terminal-confirm button:focus-visible,
.recording-microphone-menu button:focus-visible {
outline: 2px solid var(--signal);
outline-offset: 2px;
@@ -1145,7 +1329,8 @@ button:focus-visible,
-webkit-app-region: drag;
}
- .recording-discard-confirm {
+ .recording-discard-confirm,
+ .recording-terminal-confirm {
display: flex;
flex-direction: column;
gap: 13px;
@@ -1252,13 +1437,15 @@ button:focus-visible,
color: var(--hud-accent);
}
- .recording-discard-confirm h2 {
+ .recording-discard-confirm h2,
+ .recording-terminal-confirm h2 {
margin: 0 0 4px;
font-size: 13px;
font-weight: 650;
}
- .recording-discard-confirm p {
+ .recording-discard-confirm p,
+ .recording-terminal-confirm p {
margin: 0;
color: var(--hud-muted);
font-size: 11.5px;
@@ -1272,7 +1459,8 @@ button:focus-visible,
}
.recording-keep,
- .recording-confirm-discard {
+ .recording-confirm-discard,
+ .recording-close-terminal {
min-height: 34px;
padding: 0 12px;
border-radius: 10px;
@@ -1300,6 +1488,15 @@ button:focus-visible,
filter: brightness(0.92);
}
+ .recording-close-terminal {
+ background: var(--signal);
+ color: var(--brand-fg);
+ }
+
+ .recording-close-terminal:hover {
+ background: var(--brand-hover);
+ }
+
.recording-controls-live {
position: absolute;
width: 1px;
@@ -1319,6 +1516,7 @@ button:focus-visible,
@media (prefers-reduced-motion: reduce) {
.recording-live-dot,
.recording-discard-confirm,
+ .recording-terminal-confirm,
.recording-microphone-menu {
animation: none;
}
diff --git a/src/RecordingControls.tsx b/src/RecordingControls.tsx
index c134987..1a979be 100644
--- a/src/RecordingControls.tsx
+++ b/src/RecordingControls.tsx
@@ -4,6 +4,7 @@ import type {
MicrophoneSettingsStatus,
RecorderStatus,
} from "../common/ipc";
+import type { TerminalStatus } from "../common/terminal";
import {
DEFAULT_NARRATION_LANGUAGE,
narrationLanguageLabel,
@@ -20,6 +21,9 @@ export function RecordingControls() {
const [microphonePending, setMicrophonePending] = useState(false);
const [devicePending, setDevicePending] = useState(false);
const [finishPending, setFinishPending] = useState<"done" | "discard" | null>(null);
+ const [terminalStatus, setTerminalStatus] = useState<TerminalStatus | null>(null);
+ const [terminalPending, setTerminalPending] = useState(false);
+ const [terminalConfirm, setTerminalConfirm] = useState<"done" | "discard" | null>(null);
const [actionError, setActionError] = useState<string | null>(null);
const keepRecordingRef = useRef<HTMLButtonElement>(null);
const microphoneControlRef = useRef<HTMLDivElement>(null);
@@ -28,12 +32,23 @@ export function RecordingControls() {
useEffect(() => {
void window.skillRecorder.status().then(setStatus);
void window.skillRecorder.microphoneSettings().then(setMicrophoneSettings);
+ void window.skillRecorder.terminalStatus().then(setTerminalStatus);
const offStatus = window.skillRecorder.onStatusChanged(setStatus);
const offMicrophones =
window.skillRecorder.onMicrophoneSettingsChanged(setMicrophoneSettings);
+ const offTerminal =
+ window.skillRecorder.onTerminalStatusChanged(setTerminalStatus);
+ const offTerminalFinish =
+ window.skillRecorder.onTerminalFinishConfirmationRequested(() => {
+ setConfirmDiscard(false);
+ setShowMicrophoneMenu(false);
+ setTerminalConfirm("done");
+ });
return () => {
offStatus();
offMicrophones();
+ offTerminal();
+ offTerminalFinish();
};
}, []);
@@ -57,13 +72,15 @@ export function RecordingControls() {
setMicrophonePending(false);
setDevicePending(false);
setFinishPending(null);
+ setTerminalConfirm(null);
+ setTerminalPending(false);
}, [confirmDiscard, recording, showMicrophoneMenu]);
useEffect(() => {
void window.skillRecorder.setRecordingControlsExpanded(
- confirmDiscard || showMicrophoneMenu,
+ confirmDiscard || showMicrophoneMenu || terminalConfirm !== null,
);
- }, [confirmDiscard, showMicrophoneMenu]);
+ }, [confirmDiscard, showMicrophoneMenu, terminalConfirm]);
useEffect(() => {
if (!confirmDiscard) return;
@@ -140,20 +157,31 @@ export function RecordingControls() {
setDevicePending(false);
}, []);
- const done = useCallback(async () => {
+ const done = useCallback(async (forceTerminal = false) => {
setFinishPending("done");
setActionError(null);
- const result = await window.skillRecorder.stop();
+ const result = await window.skillRecorder.stop(forceTerminal);
+ if (result.requiresTerminalConfirmation) {
+ setTerminalConfirm("done");
+ setFinishPending(null);
+ return;
+ }
if (!result.ok) {
setActionError(result.error ?? "Could not stop the recording.");
setFinishPending(null);
}
}, []);
- const discard = useCallback(async () => {
+ const discard = useCallback(async (forceTerminal = false) => {
setFinishPending("discard");
setActionError(null);
- const result = await window.skillRecorder.discard();
+ const result = await window.skillRecorder.discard(forceTerminal);
+ if (result.requiresTerminalConfirmation) {
+ setConfirmDiscard(false);
+ setTerminalConfirm("discard");
+ setFinishPending(null);
+ return;
+ }
if (!result.ok) {
const error = result.error ?? "Could not discard the recording.";
setActionError(error);
@@ -162,6 +190,16 @@ export function RecordingControls() {
}
}, []);
+ const openTerminal = useCallback(async () => {
+ setTerminalPending(true);
+ setActionError(null);
+ setConfirmDiscard(false);
+ setShowMicrophoneMenu(false);
+ const result = await window.skillRecorder.openTerminal();
+ if (!result.ok) setActionError(result.error);
+ setTerminalPending(false);
+ }, []);
+
const transitionBusy = status?.transition !== "none";
const microphoneBusy =
microphonePending ||
@@ -205,7 +243,9 @@ export function RecordingControls() {
return (
<div
- className={`recording-controls ${confirmDiscard ? "expanded" : ""}`}
+ className={`recording-controls ${
+ confirmDiscard || showMicrophoneMenu || terminalConfirm ? "expanded" : ""
+ }`}
onMouseDown={(event) => {
if (event.target === event.currentTarget && confirmDiscard) setConfirmDiscard(false);
}}
@@ -221,7 +261,7 @@ export function RecordingControls() {
<div>
<h2 id="recording-discard-title">Discard this recording?</h2>
<p id="recording-discard-description">
- Screen video, activity, and recorded voice segments will be permanently deleted.
+ Screen video, activity, recorded-terminal output, and voice segments will be permanently deleted.
</p>
</div>
<div className="recording-discard-actions">
@@ -244,6 +284,48 @@ export function RecordingControls() {
</section>
)}
+ {terminalConfirm && (
+ <section
+ className="recording-terminal-confirm"
+ role="alertdialog"
+ aria-modal="true"
+ aria-labelledby="recording-terminal-title"
+ aria-describedby="recording-terminal-description"
+ >
+ <div>
+ <h2 id="recording-terminal-title">A terminal command is still running</h2>
+ <p id="recording-terminal-description">
+ Closing the recording will stop the command and save its output as interrupted.
+ </p>
+ </div>
+ <div className="recording-discard-actions">
+ <button
+ className="recording-keep"
+ onClick={() => setTerminalConfirm(null)}
+ >
+ Keep recording
+ </button>
+ <button
+ className={
+ terminalConfirm === "discard"
+ ? "recording-confirm-discard"
+ : "recording-close-terminal"
+ }
+ onClick={() => {
+ const intent = terminalConfirm;
+ setTerminalConfirm(null);
+ if (intent === "discard") void discard(true);
+ else void done(true);
+ }}
+ >
+ {terminalConfirm === "discard"
+ ? "Close terminal and discard"
+ : "Close terminal and save"}
+ </button>
+ </div>
+ </section>
+ )}
+
{showMicrophoneMenu && (
<section
ref={microphoneMenuRef}
@@ -286,6 +368,7 @@ export function RecordingControls() {
);
})}
</div>
+
{error && (
<p
className={
@@ -365,6 +448,31 @@ export function RecordingControls() {
</button>
</div>
+ <button
+ className={`recording-terminal ${
+ terminalStatus?.state !== "closed" ? "active" : ""
+ } ${terminalStatus?.state === "error" ? "error" : ""}`}
+ disabled={lifecycleBusy || terminalPending}
+ aria-label={
+ terminalStatus?.state === "closed"
+ ? "Open recorded terminal"
+ : `Focus recorded terminal. ${terminalStatus?.state ?? ""}`
+ }
+ title="Open a terminal captured only with this recording"
+ onClick={() => void openTerminal()}
+ >
+ <TerminalIcon />
+ <span>{terminalPending ? "Opening" : "Terminal"}</span>
+ {terminalStatus?.state !== "closed" && (
+ <span
+ className={`recording-terminal-dot ${
+ terminalStatus?.state ?? "closed"
+ }`}
+ aria-hidden
+ />
+ )}
+ </button>
+
<button
className="recording-discard"
disabled={lifecycleBusy}
@@ -376,7 +484,7 @@ export function RecordingControls() {
>
Discard
</button>
- <button className="recording-done" disabled={lifecycleBusy} onClick={() => void done()}>
+ <button className="recording-done" disabled={lifecycleBusy} onClick={() => void done(false)}>
{finishPending === "done" || status?.transition === "stopping" ? "Saving..." : "Done"}
</button>
</div>
@@ -410,6 +518,15 @@ function ChevronIcon({ open }: { open: boolean }) {
);
}
+function TerminalIcon() {
+ return (
+ <svg width="17" height="16" viewBox="0 0 18 16" fill="none" aria-hidden>
+ <rect x="1.5" y="2" width="15" height="12" rx="2" stroke="currentColor" strokeWidth="1.4" />
+ <path d="m4.5 6 2 2-2 2M9 10h4" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
+ </svg>
+ );
+}
+
function MicrophoneIcon({ off }: { off: boolean }) {
return (
<svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden>
diff --git a/src/Terminal.tsx b/src/Terminal.tsx
new file mode 100644
index 0000000..3694e1d
--- /dev/null
+++ b/src/Terminal.tsx
@@ -0,0 +1,154 @@
+import { useEffect, useRef, useState } from "react";
+
+import { FitAddon } from "@xterm/addon-fit";
+import { Terminal as Xterm } from "@xterm/xterm";
+import "@xterm/xterm/css/xterm.css";
+
+import type {
+ SupportedShellId,
+ TerminalShellDescriptor,
+ TerminalStatus,
+} from "../common/terminal";
+
+export function Terminal() {
+ const hostRef = useRef<HTMLDivElement>(null);
+ const terminalRef = useRef<Xterm | null>(null);
+ const [status, setStatus] = useState<TerminalStatus | null>(null);
+ const [shells, setShells] = useState<TerminalShellDescriptor[]>([]);
+ const [switching, setSwitching] = useState(false);
+ const [actionError, setActionError] = useState<string | null>(null);
+
+ useEffect(() => {
+ const host = hostRef.current;
+ if (!host) return;
+ const terminal = new Xterm({
+ cursorBlink: true,
+ fontFamily: 'Consolas, "SF Mono", "JetBrains Mono", Menlo, monospace',
+ fontSize: 13,
+ lineHeight: 1.25,
+ screenReaderMode: true,
+ allowTransparency: false,
+ theme: {
+ background: "#211f1e",
+ foreground: "#f8f5ef",
+ cursor: "#f47c68",
+ cursorAccent: "#211f1e",
+ selectionBackground: "#5c4a46",
+ black: "#211f1e",
+ red: "#f47c68",
+ green: "#63c59b",
+ yellow: "#e7b45f",
+ blue: "#7eb7d8",
+ magenta: "#c89bd0",
+ cyan: "#75c7c2",
+ white: "#f8f5ef",
+ },
+ });
+ terminalRef.current = terminal;
+ const fit = new FitAddon();
+ terminal.loadAddon(fit);
+ terminal.open(host);
+ const fitAndReport = () => {
+ try {
+ fit.fit();
+ window.skillRecorder.resizeTerminal(terminal.cols, terminal.rows);
+ } catch {
+ // The window can disappear between ResizeObserver delivery and fit().
+ }
+ };
+ const observer = new ResizeObserver(fitAndReport);
+ observer.observe(host);
+ const input = terminal.onData((data) => window.skillRecorder.writeTerminal(data));
+ const offOutput = window.skillRecorder.onTerminalOutput((data) => terminal.write(data));
+ const frame = requestAnimationFrame(() => {
+ fitAndReport();
+ terminal.focus();
+ void window.skillRecorder.terminalReady().then((result) => {
+ if (!result.ok) setActionError(result.error);
+ });
+ });
+ return () => {
+ cancelAnimationFrame(frame);
+ offOutput();
+ input.dispose();
+ observer.disconnect();
+ terminalRef.current = null;
+ terminal.dispose();
+ };
+ }, []);
+
+ useEffect(() => {
+ void window.skillRecorder.terminalStatus().then(setStatus);
+ void window.skillRecorder.terminalShells().then(setShells);
+ return window.skillRecorder.onTerminalStatusChanged(setStatus);
+ }, []);
+
+ const switchShell = async (shell: SupportedShellId) => {
+ setSwitching(true);
+ setActionError(null);
+ terminalRef.current?.reset();
+ terminalRef.current?.clear();
+ const result = await window.skillRecorder.switchTerminalShell(shell);
+ if (!result.ok) setActionError(result.error);
+ else terminalRef.current?.focus();
+ setSwitching(false);
+ };
+
+ const stateLabel =
+ switching
+ ? "Switching shell"
+ : status?.state === "running"
+ ? "Command running"
+ : status?.state === "idle"
+ ? "Ready"
+ : status?.state === "starting"
+ ? "Starting"
+ : status?.state === "error"
+ ? "Capture error"
+ : status?.state === "exited"
+ ? "Shell exited"
+ : "Recorded terminal";
+
+ return (
+ <main className="terminal-page">
+ <header className="terminal-toolbar">
+ <div className="terminal-recording-state" role="status">
+ <span className={`terminal-state-dot ${status?.state ?? "closed"}`} aria-hidden />
+ <span>
+ <strong>{stateLabel}</strong>
+ <small>Output is saved only with this recording</small>
+ </span>
+ </div>
+ <label className="terminal-shell-picker">
+ <span>Shell</span>
+ <select
+ value={status?.shell?.id ?? ""}
+ disabled={switching || status?.busy || shells.length === 0}
+ onChange={(event) =>
+ void switchShell(event.target.value as SupportedShellId)
+ }
+ >
+ {shells.map((shell) => (
+ <option key={shell.id} value={shell.id}>
+ {shell.displayName}
+ </option>
+ ))}
+ </select>
+ </label>
+ <button
+ type="button"
+ className="terminal-hide"
+ onClick={() => void window.skillRecorder.hideTerminal()}
+ >
+ Hide
+ </button>
+ </header>
+ {(actionError || status?.error) && (
+ <div className="terminal-error" role="alert">
+ {actionError ?? status?.error}
+ </div>
+ )}
+ <div ref={hostRef} className="terminal-viewport" aria-label="Recorded terminal" />
+ </main>
+ );
+}
diff --git a/src/WhatsRecorded.tsx b/src/WhatsRecorded.tsx
index 70bc074..72a0d49 100644
--- a/src/WhatsRecorded.tsx
+++ b/src/WhatsRecorded.tsx
@@ -104,6 +104,10 @@ export function WhatsRecorded({
<li>Web addresses of the pages you open.</li>
<li>A short preview of text you copy, up to 120 characters.</li>
<li>A silent video of the screen you select, at a low frame rate.</li>
+ <li>
+ If you open the recorded terminal from the floating bar: its commands, working
+ folders, exit status, timing, and complete terminal output.
+ </li>
</ul>
<p className="sheet-caution">
Do not type, paste, display, copy, or narrate passwords, access tokens, API keys,
@@ -113,6 +117,21 @@ export function WhatsRecorded({
</p>
</section>
+ <section className="sheet-block">
+ <h3>Recorded terminal (only if you open it)</h3>
+ <ul>
+ <li>Only the terminal opened from the floating recording bar is captured.</li>
+ <li>
+ Its full output stays with this recording and has no app-imposed size limit, so
+ long-running or noisy commands can make the saved recording much larger.
+ </li>
+ <li>
+ Skill Recorder does not edit shell profiles, install global hooks, watch existing
+ terminals, or keep recording commands after this recording ends.
+ </li>
+ </ul>
+ </section>
+
<section className="sheet-block">
<h3>Voice narration (only if you turn it on)</h3>
<p className="sheet-note">
@@ -153,8 +172,9 @@ export function WhatsRecorded({
<li>Nothing leaves your computer while you record.</li>
<li>
When you choose Analyze, the event timeline (window and document titles, URLs, and
- clipboard previews), plus screen images and narration text if recorded, are sent to
- GitHub&apos;s cloud service and processed by GitHub Copilot.
+ clipboard previews and recorded-terminal commands), plus screen images, narration
+ text, and only the bounded terminal-output excerpts needed for analysis, are sent
+ to GitHub&apos;s cloud service and processed by GitHub Copilot.
</li>
<li>
By default, before anything is sent, this computer hides sensitive details like
@@ -193,8 +213,8 @@ export function WhatsRecorded({
<>
<ul>
<li>
- It hides sensitive details like passwords, keys, emails, and card or ID numbers,
- both in the text that is sent (including narration) and in your screen images.
+ It hides sensitive details like passwords, keys, emails, and card or ID numbers, both in the text that is sent
+ (including narration and terminal output) and in your screen images.
</li>
<li>
Turning it off sends your recording as recorded. That can make the analysis more
@@ -223,6 +243,7 @@ export function WhatsRecorded({
<h3>What it never does</h3>
<ul>
<li>It does not log your keystrokes.</li>
+ <li>It does not capture commands from Terminal, PowerShell, or other terminal apps.</li>
<li>It only captures while a recording is running. Nothing runs in the background.</li>
</ul>
</section>
diff --git a/src/main.tsx b/src/main.tsx
index dc51c5b..8d32fa6 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
import { Library } from "./Library";
import { Recorder } from "./Recorder";
import { RecordingControls } from "./RecordingControls";
+import { Terminal } from "./Terminal";
import "./App.css";
const root = document.getElementById("root");
@@ -12,14 +13,25 @@ if (!root) throw new Error("Missing #root");
const route = window.location.hash.replace("#", "");
const isLibrary = route === "library";
const isRecordingControls = route === "recording-controls";
+const isTerminal = route === "terminal";
document.body.dataset.route = isLibrary
? "library"
: isRecordingControls
? "recording-controls"
+ : isTerminal
+ ? "terminal"
: "recorder";
createRoot(root).render(
<React.StrictMode>
- {isLibrary ? <Library /> : isRecordingControls ? <RecordingControls /> : <Recorder />}
+ {isLibrary ? (
+ <Library />
+ ) : isRecordingControls ? (
+ <RecordingControls />
+ ) : isTerminal ? (
+ <Terminal />
+ ) : (
+ <Recorder />
+ )}
</React.StrictMode>,
);
diff --git a/src/plan-edit.tsx b/src/plan-edit.tsx
index 6623131..22e43b7 100644
--- a/src/plan-edit.tsx
+++ b/src/plan-edit.tsx
@@ -16,6 +16,7 @@ import {
type TimeOfDay,
} from "../common/automation";
import type { PlanStep } from "../common/skill";
+import { planToolLabel } from "../common/plan-tools";
import { tokenize, type Value } from "../common/values";
/* --- shared array helpers (pure) ----------------------------------------- */
@@ -638,18 +639,20 @@ export function SkillStepTiles({
placeholder="What happens in this step?"
ariaLabel="Step description"
/>
- {s.tool?.trim() && (
+ {s.tools.length > 0 && (
<div className="tile-foot">
- <span className="step-tool" title="Native tool this step uses">
- {s.tool}
- </span>
+ {s.tools.map((tool) => (
+ <span className="step-tool" title={`Runtime tool: ${tool}`} key={tool}>
+ {planToolLabel(tool)}
+ </span>
+ ))}
</div>
)}
</div>
))}
<AddTile
label="Add step"
- onAdd={() => onChange([...steps, { kind: "action", title: "", text: "", tool: "" }])}
+ onAdd={() => onChange([...steps, { kind: "action", title: "", text: "", tools: [] }])}
/>
</div>
);
diff --git a/vite.config.ts b/vite.config.ts
index 2ad85eb..cefdf0a 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -67,6 +67,7 @@ export default defineConfig({
"archiver",
"get-windows",
"koffi",
+ "node-pty",
"sharp",
"@huggingface/transformers",
"onnxruntime-node",