codsh-bundle 0.3.0

package/lib/types/questions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The terminal's user-questions provider: it renders each question as a
+ * numbered menu, reads one line per question, and encodes the answer.
+ *
+ * A question may offer options, free text, or both. Selecting by number
+ * answers with that option's label; typing anything else answers as `custom`,
+ * which is the encoding `ask_user_question` documents for an "Other" reply.
+ * @module codsh-bundle/src/questions
+ */
+import type { AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+import type { SelectOutcome, SelectSpec } from './selector.ts';
+import type { Theme } from './theme.ts';
+/** Puts one selection to the keyboard; absent on a pipe, which types instead. */
+export type SelectAsk = (spec: SelectSpec, signal?: AbortSignal) => Promise<SelectOutcome>;
+/** Reads one answer from the person. */
+export interface LineReader {
+    /**
+     * Read one submission.
+     * @param signal - aborts the read when the owning tool call is cancelled.
+     * @returns the answer, or undefined when input ended or the read aborted.
+     */
+    read(signal?: AbortSignal): Promise<string | undefined>;
+}
+/**
+ * Parse a selection line against one question's options.
+ *
+ * A comma-separated list of numbers selects those options; a multi-select
+ * question accepts several, a single-select takes the first. Anything that is
+ * not a valid index becomes the free-text answer.
+ * @param line - the line the person typed.
+ * @param question - the question being answered.
+ * @returns the encoded answer for this question.
+ */
+export declare function encodeAnswer(line: string, question: AskUserQuestionItem): AskUserQuestionAnswerItem;
+/**
+ * Render one question as the lines shown above its prompt.
+ * @param question - the question to render.
+ * @param theme - styling for the heading and option list.
+ * @returns the lines to print.
+ */
+export declare function questionLines(question: AskUserQuestionItem, theme: Theme): string[];
+/** Answers `ask_user_question` from the terminal. */
+export declare class TerminalQuestions {
+    private readonly reader;
+    private readonly theme;
+    private readonly write;
+    /** The arrow-key selection, offered only where keys can arrive. */
+    private readonly select?;
+    constructor(reader: LineReader, theme: Theme, write: (line: string) => void, 
+    /** The arrow-key selection, offered only where keys can arrive. */
+    select?: SelectAsk | undefined);
+    /**
+     * Put every question in one request to the person, in order.
+     * @param request - the questions, owner agent, and abort signal.
+     * @returns one answer per question, in request order.
+     */
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;
+    /**
+     * Put one question to the person.
+     * @param question - the question.
+     * @param signal - aborts with the owning tool call.
+     * @returns the encoded answer.
+     */
+    private one;
+}

package/lib/types/screen.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The session's own screen: an alternate-screen viewport with its own scrollback.
+ *
+ * This is what makes a session feel like a place rather than a run of output.
+ * The terminal's buffer is left exactly as the person had it — their shell
+ * history is neither scrolled away nor interleaved — and everything this
+ * surface shows lives in a buffer it owns: the transcript scrolls inside the
+ * viewport while the input box stays where it is, at the bottom.
+ *
+ * Owning the viewport means doing three jobs the terminal used to do. Lines are
+ * wrapped here ({@link wrapAll}), because a line that overflows would otherwise
+ * overwrite the row below. Scrolling is ours, because the terminal's scrollback
+ * does not exist on the alternate screen. And every frame is painted as a
+ * whole, diffed against the last one — which is what removes the class of bug
+ * that relative erase arithmetic keeps producing.
+ * @module codsh-bundle/src/screen
+ */
+/** Where the cursor belongs within the chrome rows. */
+export interface ChromeCursor {
+    row: number;
+    column: number;
+}
+/** What the screen writes to and measures itself against. */
+export interface ScreenHost {
+    /** Emit raw bytes to the terminal. */
+    write(data: string): void;
+    /** Display columns currently available. */
+    columns(): number;
+    /** Screen rows currently available. */
+    rows(): number;
+}
+/** An alternate-screen viewport over a scrollback buffer this surface owns. */
+export declare class Screen {
+    private readonly host;
+    /** Logical transcript lines, unwrapped, oldest first. */
+    private logical;
+    /** The same lines wrapped to the current width — what the viewport slices. */
+    private physical;
+    /** The bottom rows: input box, menu, indicator, status. */
+    private chrome;
+    private chromeCursor;
+    /** Whether the chrome holds input focus, which is when the cursor shows. */
+    private chromeFocus;
+    /** Physical rows hidden below the viewport; zero means following the tail. */
+    private offset;
+    /** What to show while scrolled back, drawn over the viewport's top row. */
+    private notice;
+    /** A mouse selection over the transcript, in physical-row coordinates. */
+    private selection;
+    /** Collapsed blocks in the transcript, in order, with both of their forms. */
+    private folds;
+    /** Whether the folds currently show their full form. */
+    private expanded;
+    /** The last painted frame, so a repaint only touches rows that changed. */
+    private painted;
+    /** Width the current frame was painted at, to detect a resize. */
+    private paintedColumns;
+    private active;
+    constructor(host: ScreenHost);
+    /** Whether the alternate screen is currently held. */
+    get entered(): boolean;
+    /** Physical rows scrolled up out of view; zero means the tail is showing. */
+    get scrolledBy(): number;
+    /** Take the alternate screen and start reporting the mouse. */
+    enter(): void;
+    /**
+     * Give the terminal back exactly as it was.
+     *
+     * Idempotent, because every exit path calls it — a normal quit, an
+     * interrupt, and a crash handler all have to leave the terminal usable.
+     */
+    leave(): void;
+    /**
+     * Append finished transcript lines.
+     *
+     * Following the tail is the default; a person who has scrolled up stays
+     * where they are, and the new rows accumulate below them.
+     * @param lines - the lines to keep, already styled.
+     */
+    append(lines: readonly string[]): void;
+    /**
+     * Append one collapsible block: its summary now, its full form on demand.
+     *
+     * This is what makes every long block — not merely the latest — expandable:
+     * the buffer keeps both forms, and toggling rebuilds the transcript in
+     * place, exactly like a details/summary element.
+     * @param summary - the collapsed lines, already styled.
+     * @param full - the expanded lines, already styled.
+     */
+    appendFold(summary: readonly string[], full: readonly string[]): void;
+    /**
+     * Turn the last `count` appended lines into a collapsible block after the
+     * fact.
+     *
+     * This is how a finished answer becomes foldable without ever having been
+     * withheld: it streamed in the open, and only once complete does it grow a
+     * summary form. The block starts expanded — the person is reading it — and
+     * collapses with the rest when the conversation moves on.
+     * @param count - how many trailing lines the block owns.
+     * @param summary - the collapsed lines, already styled.
+     */
+    foldBack(count: number, summary: readonly string[]): void;
+    /** Whether any collapsible block exists. */
+    get hasFolds(): boolean;
+    /** Whether the folds currently show their full form. */
+    get foldsExpanded(): boolean;
+    /**
+     * Swap every fold between its summary and its full form.
+     * @returns false when there is nothing to toggle.
+     */
+    toggleFolds(): boolean;
+    /** Return every fold to its summary, the way moving on reads as dismissal. */
+    collapseFolds(): void;
+    /** Put every fold into one form, whatever mix of states they are in now. */
+    private setFolds;
+    /**
+     * Replace the bottom rows.
+     * @param rows - the chrome, top to bottom.
+     * @param cursor - where the cursor belongs among them.
+     * @param focus - whether to show the cursor there.
+     */
+    setChrome(rows: readonly string[], cursor: ChromeCursor, focus: boolean): void;
+    /**
+     * Set the line shown while the reader is away from the tail.
+     *
+     * Drawn OVER the viewport's top row rather than added to the chrome: a notice
+     * that changed the chrome's height would move the input box as a side effect
+     * of scrolling, and would make a page up and a page down different sizes.
+     * @param text - the styled notice, already fitted.
+     */
+    setScrollNotice(text: string): void;
+    /**
+     * Scroll the transcript.
+     * @param delta - rows to move; negative scrolls back into history.
+     */
+    scrollBy(delta: number): void;
+    /**
+     * Scroll by a whole viewport, which is what the page keys mean.
+     * @param direction - -1 for back into history, 1 towards the tail.
+     */
+    scrollPage(direction: -1 | 1): void;
+    /** Jump back to the tail, which is also what a new submission does. */
+    scrollToBottom(): void;
+    /**
+     * Drop the transcript, keeping the chrome.
+     *
+     * Ctrl-L on a shared terminal clears a viewport the person may want back; on
+     * our own screen the buffer IS the session's history, so this empties it.
+     */
+    clearTranscript(): void;
+    /** Re-wrap and repaint after the terminal changed size. */
+    resize(): void;
+    /**
+     * Anchor a selection where the left button went down.
+     *
+     * The terminal cannot select for us while mouse reporting is on, so the
+     * viewport does it: press anchors, motion extends, release copies — the
+     * shape opencode and Claude give the same gesture.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDown(row: number, column: number): void;
+    /**
+     * Extend the selection to where the pointer moved.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDrag(row: number, column: number): void;
+    /**
+     * Finish the gesture.
+     *
+     * The highlight stays up — the copy already happened, and the marks show
+     * what it took — until the next click or reflow dismisses it.
+     * @returns the selected text, or undefined for a bare click.
+     */
+    mouseUp(): string | undefined;
+    /** The selection's bounds in order, top-left first. */
+    private orderedSelection;
+    /** The plain text under the selection, visual rows joined by newlines. */
+    private selectedText;
+    /**
+     * Map a terminal position to a physical buffer position.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     * @param clamp - pull an outside position to the nearest content row, the
+     * way dragging past an edge keeps selecting, instead of refusing it.
+     * @returns the position, or undefined when it misses the content.
+     */
+    private locate;
+    /** Rows the transcript viewport occupies. */
+    private viewportHeight;
+    /** Columns content is laid out for, one short of the width so no row wraps. */
+    private contentColumns;
+    /** Re-wrap every kept line at the current width. */
+    private rewrap;
+    /**
+     * Compose and paint the frame.
+     *
+     * The viewport is padded at the top when the transcript is shorter than the
+     * screen, which is what puts the chrome at the bottom from the first frame
+     * rather than wherever output happened to reach.
+     */
+    private render;
+}

package/lib/types/selector.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The arrow-key selection widget: approvals, questions, and any other choice a
+ * person makes by moving a marker rather than by typing an answer.
+ *
+ * Pure state, like the editor: keys in, a verdict and rows out. One widget
+ * serves single-select, multi-select, and shortcut keys, because three slightly
+ * different pickers is how the same bug ships three times.
+ * @module codsh-bundle/src/selector
+ */
+import type { Key } from './keys.ts';
+import type { Theme } from './theme.ts';
+/** One choice on offer. */
+export interface SelectOption {
+    /** What the choice is, shown as its row. */
+    label: string;
+    /** Extra context shown dimly beside the label. */
+    detail?: string;
+    /** Single key that picks this option outright (e.g. `y`). */
+    shortcut?: string;
+}
+/** What a selection asks. */
+export interface SelectSpec {
+    /** The question, shown above the options. */
+    title: string;
+    options: readonly SelectOption[];
+    /** Whether several options may be chosen; Space toggles, Enter confirms. */
+    multi?: boolean;
+    /** Label for a trailing "type your own" row; absent offers none. */
+    custom?: string;
+}
+/** How one selection ended. */
+export type SelectOutcome = {
+    kind: 'chosen';
+    indices: number[];
+} | {
+    kind: 'custom';
+} | {
+    kind: 'cancelled';
+};
+/** What a key did to the selection. */
+export type SelectorStep = {
+    kind: 'pending';
+} | {
+    kind: 'done';
+    outcome: SelectOutcome;
+};
+export declare class Selector {
+    private readonly spec;
+    private selected;
+    private readonly checked;
+    constructor(spec: SelectSpec);
+    /** How many rows the widget offers, the custom row included. */
+    private get count();
+    /** Whether a row index is the custom "type your own" row. */
+    private isCustom;
+    /**
+     * Apply one key.
+     * @param key - the decoded keystroke.
+     * @returns whether the selection settled, and how.
+     */
+    handle(key: Key): SelectorStep;
+    /**
+     * Resolve a typed character: a digit jumps, a shortcut picks, Space toggles.
+     * @param text - what was typed.
+     * @returns whether the selection settled.
+     */
+    private typed;
+    /**
+     * Settle on a row.
+     * @param index - the row accepted.
+     * @returns the settled step.
+     */
+    private accept;
+    /**
+     * Render the widget.
+     * @param theme - styling for the marker, shortcuts, and details.
+     * @param columns - display columns available per row.
+     * @returns the rows, title first.
+     */
+    view(theme: Theme, columns: number): string[];
+    /**
+     * One option's label with its number and shortcut.
+     * @param option - the option to label.
+     * @param theme - styling for the shortcut.
+     * @returns the label text.
+     */
+    private label;
+    /**
+     * One rendered row.
+     * @param index - the row's index.
+     * @param label - the row's label, already styled.
+     * @param detail - dim context beside it.
+     * @param theme - styling for the marker and detail.
+     * @param columns - display columns available.
+     * @returns the row text.
+     */
+    private row;
+}

package/lib/types/spinner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The working indicator: one rewritable line saying the agent is busy, how long
+ * it has been, and which key stops it.
+ *
+ * It occupies the console's single live line, so the transcript above it stays
+ * append-only and the indicator never survives into a redirected transcript.
+ * @module codsh-bundle/src/spinner
+ */
+import type { Theme } from './theme.ts';
+/** The console surface a spinner drives. */
+export interface LiveSurface {
+    setLive(text: string | undefined): void;
+    readonly isTty: boolean;
+}
+/** Formats the indicator's text for one tick. */
+export interface SpinnerLabel {
+    /** What the agent is doing, e.g. `working`. */
+    verb: string;
+    /** Key that cancels, named for the surface that can read it. */
+    interrupt: string;
+    /** Live extra segment, read each tick — e.g. tokens spent so far. */
+    detail?: () => string | undefined;
+}
+/**
+ * Render one tick of the indicator.
+ * @param frame - the frame index, taken modulo the frame count.
+ * @param elapsedMs - milliseconds since the work started.
+ * @param label - the verb and interrupt key to name.
+ * @param theme - styling for the frame and the hint.
+ * @returns the line to display.
+ */
+export declare function spinnerText(frame: number, elapsedMs: number, label: SpinnerLabel, theme: Theme): string;
+/** Drives the working indicator for as long as the agent is busy. */
+export declare class Spinner {
+    private readonly surface;
+    private readonly theme;
+    private readonly label;
+    /** Injected so tests advance time without waiting for it. */
+    private readonly now;
+    private timer;
+    private frame;
+    private startedAt;
+    constructor(surface: LiveSurface, theme: Theme, label: SpinnerLabel, 
+    /** Injected so tests advance time without waiting for it. */
+    now?: () => number);
+    /** Whether the indicator is running. */
+    get running(): boolean;
+    /**
+     * Start the indicator, or do nothing when it is already running or the
+     * surface has no cursor to rewrite.
+     *
+     * The clock keeps running across a pause: the elapsed figure is the whole
+     * turn's, and an indicator that restarted from zero at every tool call would
+     * report each step instead.
+     */
+    start(): void;
+    /** Hide the indicator without forgetting when the turn began. */
+    pause(): void;
+    /** Stop the indicator: the turn is over, and the next one starts at zero. */
+    stop(): void;
+    /** Paint the current frame. */
+    private draw;
+}

package/lib/types/startup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The terminal app's command-line provider: it parses the optional task
+ * positional, the session-continuation flags, the preset override, and
+ * `--help`, then publishes {@link CODING_CLI_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
+ * @module codsh-bundle/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "coding-cli-startup";
+/** Services required before the invocation can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the terminal runner. */
+export declare const CODING_CLI_STARTUP_SERVICE = "codingCliStartup";
+/** What the runner row reads from {@link CODING_CLI_STARTUP_SERVICE}. */
+export interface CodingCliStartupValues {
+    /** Opening task text, or the empty string when the session starts at the prompt. */
+    task: string;
+    /** Session to reopen: an explicit id, `'latest'` for `--continue`, or the empty string for a new session. */
+    resume: string;
+    /** Preset id overriding the roster default, or the empty string to accept it. */
+    preset: string;
+    /** Render the answer and exit rather than entering the interactive loop. */
+    print: boolean;
+}
+/**
+ * Parse and provide this invocation as an ordinary Cordis service. On `--help`
+ * and on a usage error nothing is provided, so the runner never mounts.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/status.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The status readout shown with the prompt: what model and composition answer,
+ * where the session is, and how much context is left.
+ *
+ * Every figure is read from a durable projection or a logged fold rather than
+ * tracked here, so a resumed session reports the same numbers it ended with.
+ * @module codsh-bundle/src/status
+ */
+import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client';
+import type { Theme } from './theme.ts';
+/** Everything one status line reports. */
+export interface StatusFacts {
+    /** Model route answering this session. */
+    model: string;
+    /** Composed preset, absent when the deployment composes no roster. */
+    preset?: string | undefined;
+    /** Permission preset name, absent when none is composed. */
+    permission?: string | undefined;
+    /** Whether plan mode is holding. */
+    planMode: boolean;
+    /** Session workspace. */
+    cwd: string;
+    /** Checked-out branch, absent outside a repository. */
+    branch?: string | undefined;
+    /** Cumulative provider usage, absent before the first reported request. */
+    usage?: TokenUsageProjection | undefined;
+    /** Context occupancy, absent before the first reported request. */
+    context?: ContextPressureProjection | undefined;
+}
+/**
+ * Abbreviate a token count the way a status line wants it: exact while small,
+ * one decimal at thousands, whole at millions.
+ * @param tokens - the count to render.
+ * @returns the abbreviated figure.
+ */
+export declare function formatTokens(tokens: number): string;
+/**
+ * Total tokens a session has spent across every bucket.
+ *
+ * The four buckets are disjoint by contract — reasoning already sits inside
+ * output — so a plain sum is the session total.
+ * @param usage - cumulative usage, or undefined before any request.
+ * @returns the total, or undefined when nothing is recorded.
+ */
+export declare function totalTokens(usage: TokenUsageProjection | undefined): number | undefined;
+/**
+ * Percentage of the context window still free for the next request.
+ *
+ * `projectedTokens` is what the NEXT prompt would cost, which is the figure a
+ * person deciding whether to keep going needs; it also moves the instant a
+ * compaction shadows a span, where the raw sample cannot.
+ * @param context - the occupancy projection.
+ * @returns whole percent remaining, or undefined without both figures.
+ */
+export declare function contextLeftPercent(context: ContextPressureProjection | undefined): number | undefined;
+/**
+ * Shorten a path for display, collapsing the home directory to `~`.
+ * @param path - the absolute path.
+ * @param home - the home directory to collapse; defaults to the real one.
+ * @returns the display path.
+ */
+export declare function displayPath(path: string, home?: string): string;
+/**
+ * Read the checked-out branch by walking up to the repository's `HEAD`.
+ *
+ * Read rather than shelled out: `git` may be absent, slow, or blocked by the
+ * sandbox, and a status line must never be the reason a prompt stalls. A
+ * detached head reports no branch rather than a bare revision, which would read
+ * as a branch named after a hash.
+ * @param cwd - directory to start from.
+ * @returns the branch name, or undefined outside a repository or when detached.
+ */
+export declare function gitBranch(cwd: string): Promise<string | undefined>;
+/**
+ * Render the status line.
+ *
+ * Segments that have nothing to report are dropped rather than shown empty, so
+ * a fresh session reads as short rather than as broken.
+ * @param facts - what to report.
+ * @param theme - styling for the segments.
+ * @param columns - display columns available; a longer line is cut, never wrapped.
+ * @returns the line, unstyled when the theme is plain.
+ */
+export declare function statusLine(facts: StatusFacts, theme: Theme, columns: number): string;
+/**
+ * Render the fuller readout `/status` answers with.
+ *
+ * The status line is a glance; this is the place a person looks when the glance
+ * raised a question, so it names each usage bucket rather than one total.
+ * @param facts - what to report.
+ * @param session - the session identity, which `--resume` takes.
+ * @returns the report, one `label: value` per line.
+ */
+export declare function statusReport(facts: StatusFacts, session: string): string;

package/lib/types/streaming.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Assistant text as it arrives.
+ *
+ * Token-level display and Markdown rendering pull against each other: a line
+ * cannot be styled until it is complete, and a terminal cannot restyle a line
+ * that has scrolled. The split is what resolves it — the line being typed lives
+ * in the console's one rewritable region as raw text, and the moment it ends it
+ * is rendered and written permanently.
+ * @module codsh-bundle/src/streaming
+ */
+import type { Theme } from './theme.ts';
+/** What one delta produced: finished lines, and the line still being typed. */
+export interface StreamStep {
+    /** Rendered lines to append to the transcript. */
+    lines: string[];
+    /** The in-progress line for the live region, or undefined when none is open. */
+    live: string | undefined;
+}
+/** Accumulates assistant text deltas into rendered lines. */
+export declare class TextStream {
+    private readonly theme;
+    /** Display columns, so the in-progress line never wraps the live region. */
+    private readonly columns;
+    /**
+     * Render lines as dim plain text instead of Markdown. Reasoning wants
+     * this: it is the model thinking aloud, not an answer to typeset.
+     */
+    private readonly plain;
+    private markdown;
+    private partial;
+    private seen;
+    constructor(theme: Theme, 
+    /** Display columns, so the in-progress line never wraps the live region. */
+    columns: () => number, 
+    /**
+     * Render lines as dim plain text instead of Markdown. Reasoning wants
+     * this: it is the model thinking aloud, not an answer to typeset.
+     */
+    plain?: boolean);
+    /** Whether this message has produced any text yet. */
+    get streamed(): boolean;
+    /**
+     * Take one text delta.
+     * @param delta - the text fragment, which may contain any number of newlines.
+     * @returns the lines to append and the line still open.
+     */
+    push(delta: string): StreamStep;
+    /**
+     * Close the message, rendering whatever line was still open.
+     *
+     * Called when the model finishes and when a turn is cancelled mid-line: the
+     * text already shown has to land in the transcript either way, or the live
+     * region would take it away again.
+     * @returns the remaining lines to append.
+     */
+    flush(): string[];
+    /** Render one complete line in this stream's mode. */
+    private renderLine;
+    /**
+     * The in-progress line as the live region should show it.
+     *
+     * Raw rather than rendered: it is not a line yet, and inside a fenced block it
+     * is code that Markdown must not touch. Truncated because the live region is
+     * one row — a wrapped live line cannot be erased by a single carriage return.
+     * @returns the text, or undefined when no line is open.
+     */
+    private liveText;
+}