Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions apps/docs/src/content/guide/terminal.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -421,7 +421,47 @@ commands for builds, tests and Git. Each command shows its full text and absolut
directory for confirmation, including when `--yes` skips file-write prompts. Without
`--shell`, only the existing emulated file commands are available.

The coding agent calls `local_info` to check which client and workspace it is using.
The terminal reports whether native shell execution is enabled; the browser reports
emulated commands and whether files live in a mounted directory or its virtual workspace.
This check reads no project files and runs no command. Older clients can continue using
the file tools, but do not support this capability check.

Before editing a target file, `code` can use `local_instructions` to read the `AGENTS.md`
and `CLAUDE.md` files in its parent directories, starting at the workspace root. This
also works for new files. Results include truncation offsets when instructions exceed
the response budget; the agent must finish those reads before editing. Both tools
are available in plan mode.

`local_edit` rechecks the original contents after terminal confirmation and before
committing a browser write. If the file changed, it reports a conflict and preserves
the newer work so the agent can reread and reconcile it. This does not lock the file
against other programs.

Delete and rename also recheck the source after terminal confirmation. Terminal
rename creates the destination exclusively before removing the source, so it cannot
replace a file created during approval. It requires a filesystem that supports hard
links and refuses moves across filesystems. If a move fails after creating the
destination, inspect both paths: the source is retained when its removal is uncertain.
Browser rename copies before deleting and retains a source changed during that copy.

Commands start inside the project, but **are not sandboxed**: an approved command has your
account's filesystem and network access. stdin is closed; interactive programs are unsupported.
Output is capped at 200 kB and commands time out after four minutes. Stop cancels the process
group. `local_open` displays text files through `$PAGER`; web URLs appear as links to open manually.


After a `code` turn finishes, **Workspace results** summarizes observed file operations,
completed commands, issues, unconfirmed operations, and unfinished plan steps. It uses
recorded tool results, not the agent's prose. A completed command is not a claim that tests
passed. Failed attempts remain visible even after a successful retry; partial or missing
results are marked unconfirmed. Each group shows up to six entries, with the rest available
in the tool results above.

Use `/work` to open a coding report for the loaded thread history in `$PAGER`. It
combines operations and command attempts across turns and uses the latest recorded
state of each plan. Failed attempts remain visible after successful retries; only the
latest unfinished plan steps are listed. The report makes no model call, runs no
command against the project, and changes no project file. The pager uses a private
temporary report file. It reports loaded history rather
than fetching a fresh Git diff or checking the current workspace.
1 change: 1 addition & 0 deletions apps/tui/src/app.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -899,6 +899,7 @@ export function App({
<Transcript
turns={turns}
streaming={streaming}
showWorkspaceResults={manifest === 'code'}
scrollRef={scrollRef}
theme={theme}
branches={branches}
Expand Down
9 changes: 9 additions & 0 deletions apps/tui/src/commands.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ import { BINDINGS } from './keys.js';
import { skillReport, skillsOverview } from './skill-report.js';
import { oneLine } from './text.js';
import type { ThreadStore } from './threads.js';
import { workReport } from './work-report.js';

const THINKING: ThinkingLevel[] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];

Expand All @@ -64,6 +65,7 @@ const COMMANDS: ReadonlyArray<[label: string, commands: string]> = [
['agent', '/manifest [name] /start <n>'],
['history', '/rewind [n] /version <n> /search <text> /open <n|thread-id>'],
['$PAGER', '/artifact <n> [file] · /skills /skill <name> (read-only)'],
['coding', '/work · recorded operations and latest plan (read-only)'],
['client', '/refresh the thread list · /quit'],
];

Expand Down Expand Up @@ -163,6 +165,13 @@ export function runCommand(ctx: CommandContext, line: string): void {
const [name, ...rest] = line.slice(1).split(/\s+/);
const arg = rest.join(' ').trim();
switch (name) {
case 'work':
if (arg) {
setNotice('usage: /work');
return;
}
ctx.show(workReport(engine.state.turns, threadIdRef.current), 'Coding work');
return;
case 'new':
newThread();
return;
Expand Down
9 changes: 9 additions & 0 deletions apps/tui/src/ui/transcript.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ import { handlesByTool, type Spill, sizeLabel } from '../artifacts.js';
import { syntaxStyle } from '../syntax.js';
import { oneLine } from '../text.js';
import { DIM, DIM_ITALIC, type Theme } from '../theme.js';
import { WorkspaceResults } from './workspace-summary.js';

/**
* Fenced code, in a frame with its language on it.
Expand Down Expand Up @@ -529,12 +530,14 @@ function AssistantTurn({
live,
theme,
handles,
workspaceResults,
}: {
turn: Turn;
live: boolean;
theme: Theme;
/** Handle numbers are assigned across the whole transcript, not per turn. */
handles: Map<ToolCall, Spill>;
workspaceResults: boolean;
}) {
const segments = interleaveTurn(turn.content, turn.tools, turn.reasoning as ReasoningBlock[]);
// Only the tail of a live turn is still being written. An earlier segment was
Expand Down Expand Up @@ -589,6 +592,9 @@ function AssistantTurn({
pending
</text>
) : null}
{workspaceResults && !live && !turn.runStatus ? (
<WorkspaceResults turn={turn} theme={theme} />
) : null}
{turn.usage ? (
<text attributes={DIM}>
{' '}
Expand Down Expand Up @@ -649,13 +655,15 @@ function UserTurn({ turn, theme, branch }: { turn: Turn; theme: Theme; branch?:
export function Transcript({
turns,
streaming = false,
showWorkspaceResults = false,
scrollRef,
theme,
greeting,
branches,
}: {
turns: Turn[];
streaming?: boolean;
showWorkspaceResults?: boolean;
/**
* Handed to `App` so the page keys can drive the box without taking focus
* from the composer. The alternative — focusing the scrollbox so its own
Expand Down Expand Up @@ -722,6 +730,7 @@ export function Transcript({
live={streaming && turn.id === turns[turns.length - 1]?.id}
theme={theme}
handles={handles}
workspaceResults={showWorkspaceResults}
/>
),
)}
Expand Down
53 changes: 53 additions & 0 deletions apps/tui/src/ui/workspace-summary.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import type { Turn } from '@felix/client';
import { useMemo } from 'react';
import { oneLine } from '../text.js';
import { BOLD, DIM, type Theme } from '../theme.js';
import { summarizeWorkspace } from '../workspace-summary.js';

export function WorkspaceResults({ turn, theme }: { turn: Turn; theme: Theme }) {
const summary = useMemo(() => summarizeWorkspace(turn), [turn]);
if (!summary) return null;
const groups = [
['File operations', summary.files, theme.ready],
['Commands completed', summary.commands, theme.ready],
['Issues', summary.issues, theme.failed],
['Unconfirmed operations', summary.unconfirmed, theme.blocked],
['Plan steps remaining', summary.remaining, theme.blocked],
] as const;
const outcome = summary.issues.length
? theme.failed
: summary.unconfirmed.length || summary.remaining.length
? theme.blocked
: theme.ready;
return (
<box
flexDirection="column"
marginTop={1}
paddingLeft={2}
border={['left']}
borderColor={outcome}
>
<text fg={outcome} attributes={BOLD}>
Workspace results
</text>
{groups.map(([label, entries, color]) =>
entries.length ? (
<box key={label} flexDirection="column">
<text fg={color}>{`${label}: ${entries.length}`}</text>
<text attributes={DIM}>
{entries
.slice(0, 6)
.map((entry) => ` ${oneLine(entry, 160)}`)
.join('\n')}
</text>
{entries.length > 6 ? (
<text
attributes={DIM}
>{` … ${entries.length - 6} more; see tool results above`}</text>
) : null}
</box>
) : null,
)}
</box>
);
}
58 changes: 58 additions & 0 deletions apps/tui/src/work-report.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import { type PlanState, plansInTurn, type Turn } from '@felix/client';
import { oneLine } from './text.js';
import { summarizeWorkspace } from './workspace-summary.js';

const MAX_ROWS = 200;

/** A local report from loaded history; no model, repository command, or file write. */
export function workReport(turns: readonly Turn[], threadId: string): string {
const files: string[] = [];
const commands: string[] = [];
const issues: string[] = [];
const unconfirmed: string[] = [];
const plans = new Map<string, PlanState>();
for (const turn of turns) {
if (turn.role !== 'assistant') continue;
const summary = summarizeWorkspace(turn);
if (summary) {
files.push(...summary.files);
commands.push(...summary.commands);
issues.push(...summary.issues);
unconfirmed.push(...summary.unconfirmed);
}
for (const [id, plan] of plansInTurn(turn.tools).latest) plans.set(id, plan);
}
// Tool arguments and instruction-derived titles are data, including control bytes.
// biome-ignore lint/suspicious/noControlCharactersInRegex: Strip terminal control bytes from tool-derived labels.
const line = (text: string) => oneLine(text.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '), 400);
const lines = [
'Coding work · loaded thread history',
`Thread: ${line(threadId)}`,
'',
'Recorded operations, not a live Git diff. Completed commands do not establish that tests passed.',
'Failed or refused attempts remain in history even when a later retry succeeds.',
];
const section = (title: string, entries: string[]) => {
lines.push('', `${title} (${entries.length})`);
lines.push(...entries.slice(0, MAX_ROWS).map((entry) => ` ${line(entry)}`));
if (!entries.length) lines.push(' None recorded.');
if (entries.length > MAX_ROWS)
lines.push(` … ${entries.length - MAX_ROWS} more; see the transcript.`);
};
section('File operations', files);
section('Commands completed', commands);
section('Failed or refused attempts', issues);
section('Unconfirmed operations', unconfirmed);
const remaining: string[] = [];
for (const plan of plans.values()) {
for (const step of plan.steps) {
if (step.state !== 'done')
remaining.push(
`${plan.title}: ${step.title} [${step.status}]${step.note ? ` · ${step.note}` : ''}`,
);
}
}
section('Unfinished steps in latest recorded plans', remaining);
if (!plans.size) lines.push(' No saved plan was observed in loaded history.');
return lines.join('\n');
}
59 changes: 59 additions & 0 deletions apps/tui/src/workspace-summary.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import { classifyToolResult, fileToolOp, plansInTurn, type Turn } from '@felix/client';

export interface WorkspaceSummary {
files: string[];
commands: string[];
issues: string[];
unconfirmed: string[];
remaining: string[];
}

/** Observed tool outcomes only: prose is never evidence that a check passed. */
export function summarizeWorkspace(turn: Turn): WorkspaceSummary | null {
const summary: WorkspaceSummary = {
files: [],
commands: [],
issues: [],
unconfirmed: [],
remaining: [],
};
let relevant = false;
for (const tool of turn.tools ?? []) {
const name = tool.name.replace(/^client · /, '');
const op = fileToolOp(name);
const mutation = op === 'write' || op === 'edit' || op === 'delete' || op === 'rename';
if (!mutation && name !== 'local_shell') continue;
relevant = true;
const args =
tool.input && typeof tool.input === 'object' ? (tool.input as Record<string, unknown>) : {};
const path = typeof args.path === 'string' ? args.path : '(path unavailable)';
const command = typeof args.command === 'string' ? args.command : '(command unavailable)';
const label = mutation
? `${op} ${path}${op === 'rename' ? ` → ${typeof args.to_path === 'string' ? args.to_path : '(destination unavailable)'}` : ''}`
: command;
if (
!tool.done ||
typeof tool.output !== 'string' ||
!tool.output.trim() ||
tool.output.startsWith('[approval required]')
) {
summary.unconfirmed.push(label);
continue;
}
// Local tools historically returned plain error text. Treat it conservatively
// even for shell calls; current clients additionally emit typed error markers.
const issue =
classifyToolResult(name, tool.output) ?? classifyToolResult('local_read', tool.output);
if (issue) summary.issues.push(`${label}: ${issue.label}`);
else if (mutation) summary.files.push(label);
else summary.commands.push(label);
}
if (!relevant) return null;
for (const plan of plansInTurn(turn.tools).latest.values()) {
for (const step of plan.steps) {
if (step.state !== 'done')
summary.remaining.push(`${step.title}${step.note ? ` · ${step.note}` : ''}`);
}
}
return summary;
}
Loading
Loading