dsh-ssh-tui 0.5.3 → 0.5.4

package/lib/types/approval-reviewer.d.ts

@@ -7,14 +7,17 @@
  * Injection hardening: everything inside the marked data regions is review
  * MATERIAL, never instructions — the system prompt says so, and material that
  * tries to instruct is treated as an injection attempt and rejected. The
- * caller also enforces its own floor: `high` risk or `authorization: no`
- * is never approved, whatever the model claims.
+ * caller also enforces its own floor: `high` risk or `authorization` other
+ * than `yes` is never approved, whatever the model claims.
  */
 export interface ReviewInput {
     userText: string;
     segments: string[];
     toolName: string;
     command: string;
+    args?: string;
+    reason?: string;
+    sandboxMode?: string;
 }
 export interface ReviewVerdict {
     risk: 'low' | 'medium' | 'high';
@@ -22,7 +25,10 @@ export interface ReviewVerdict {
     approved: boolean;
     reason: string;
 }
+export type ReviewerLocale = 'zh' | 'en';
+/** Default (zh) prompt; tests and callers that do not pass a locale use this. */
 export declare const REVIEW_SYSTEM_PROMPT: string;
+export declare function reviewSystemPrompt(locale?: ReviewerLocale): string;
 /** Assemble the compact, fence-marked user message for the reviewer. */
 export declare function buildReviewUserMessage(input: ReviewInput): string;
 export declare function parseReviewOutput(text: string): ReviewVerdict | undefined;

package/lib/types/auto-approval.d.ts

@@ -11,29 +11,57 @@
  */
 export type AutoApprovalMode = 'off' | 'auto';
 export type ApprovalDecision = 'allow' | 'deny' | 'ask';
+export type AutoApprovalRisk = 'low' | 'medium' | 'high';
+export interface ClassifiedApproval {
+    decision: ApprovalDecision;
+    risk: AutoApprovalRisk;
+    /** Short stable id for i18n / model feedback. */
+    reasonKey: string;
+}
 /**
  * Whole-command danger patterns, checked before anything else. A match
  * auto-rejects. This is a UX heuristic, not a security boundary: obfuscated
  * or interpreter-wrapped damage still has to be contained by the sandbox.
+ *
+ * Interpreter `-c`/`-e` is NOT here: the table cannot see the payload, so
+ * those shapes ask (AI review) instead of a blanket deny.
  */
 export declare const DANGER_PATTERNS: RegExp[];
 /**
  * Segment-level allow patterns: low-risk, high-frequency reads, builds, and
  * tests. A command auto-approves only when EVERY segment matches one of these.
+ * `env`/`printenv` stay off this list — process env often holds keys.
  */
 export declare const ALLOW_SEGMENT_PATTERNS: RegExp[];
+/**
+ * Split a shell command into segments at &&, ||, ; and | boundaries,
+ * skipping those operators when they sit inside quotes or a here-doc
+ * terminator. Nested quoting is best-effort — the sandbox still owns
+ * real damage containment.
+ */
+export declare function segments(command: string): string[];
+export declare function touchesSensitivePath(text: string): boolean;
 /**
  * Classify one shell command line. Danger anywhere auto-rejects; otherwise
  * the command auto-approves only when every segment is a recognized low-risk
  * pattern — unknown shapes ask (and detach to a rejection when unattended).
  */
 export declare function classifyCommand(command: string): ApprovalDecision;
+export declare function classifyCommandDetailed(command: string): ClassifiedApproval;
+export interface ClassifyApprovalInput {
+    toolName: string;
+    command?: string;
+    args?: string;
+    reason?: string;
+    workspaceCwd?: string;
+}
 /**
  * Classify one approval request. `command` is the decoded shell command when
  * the pending call is a shell tool. 'deny' auto-rejects (the model reads the
  * rejection and adapts); 'ask' falls through to the interactive prompt.
  */
 export declare function classifyApproval(toolName: string, command: string | undefined): ApprovalDecision;
+export declare function classifyApprovalDetailed(input: ClassifyApprovalInput): ClassifiedApproval;
 /**
  * Decode the shell command of a streamed tool call from its raw JSON args.
  * Returns undefined for non-shell tools or unparseable args.

package/lib/types/footer.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Footer stats, status identity, context-pressure chips, and `/status` report.
+ */
+import { type QuotaSnapshot } from './quota.js';
+import type { DisconnectPolicyName } from './transcript-types.js';
+export declare const WAIT_INDICATOR_MS = 8000;
+/** Compact token count, matching the web stats line (517 / 12.2K / 1.2M). */
+export declare function formatTokens(n: number): string;
+/**
+ * Prompt occupancy of the next request, from DSH `contextPressure`.
+ * Provider-agnostic: uses the routed model's advertised window, not a
+ * hardcoded xAI size. Compaction-basic still owns in-turn pressure at 80%.
+ */
+export declare const CONTEXT_PRESSURE_WARN_RATIO = 0.8;
+export declare const CONTEXT_PRESSURE_DANGER_RATIO = 0.95;
+/** Idle auto-compact starts here so recovery finishes before the 80% in-turn trigger. */
+export declare const CONTEXT_IDLE_COMPACT_RATIO = 0.72;
+export interface ContextPressureSample {
+    usedTokens: number;
+    contextWindow: number;
+}
+export interface ContextPressureView {
+    usedTokens: number;
+    contextWindow: number;
+    percent: number;
+    level: 'ok' | 'warn' | 'danger';
+}
+/** Prompt-side occupancy of one usage sample: uncached input plus cache traffic. */
+export declare function promptPressureTokens(usage: {
+    inputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}): number;
+/** Prefer the next-request projection; fall back to last-request pressure. */
+export declare function contextPressureUsedTokens(pressure: {
+    projectedTokens?: number;
+    pressureTokens?: number;
+} | undefined): number | undefined;
+export declare function parseContextPressure(value: unknown): ContextPressureSample | undefined;
+export declare function contextPressureView(sample: ContextPressureSample): ContextPressureView;
+/**
+ * 8-segment Braille ring. Empty `⣀`; full `⣿`. Width is always 1 cell.
+ * Index is `ceil(percent / 12.5)` clamped to 0..8.
+ */
+export declare const CONTEXT_RING_EMPTY = "\u28C0";
+export declare const CONTEXT_RING_SEGMENTS: readonly ["⣀", "⠉", "⠋", "⠛", "⠞", "⠟", "⠿", "⡿", "⣿"];
+export declare function formatContextPressureRing(percent: number): string;
+export declare function contextPressureRingColor(level: ContextPressureView['level']): string;
+export declare function formatContextPressureChip(view: ContextPressureView, color?: boolean): string;
+export declare function formatContextPressureStatusLine(view: ContextPressureView | undefined): string;
+export declare function contextPressureAlertText(view: ContextPressureView): string;
+export declare function shouldIdleAutoCompact(view: ContextPressureView | undefined): boolean;
+/** Compact duration, matching the web stats line (45.2s / 2m42s). */
+export declare function formatDuration(ms: number): string;
+export declare function formatTokensPerSecond(tokensPerSecond: number): string;
+export declare function providerShortCode(provider: string): string;
+export interface FooterStatsInput {
+    turns: number;
+    steps: number;
+    llmMs: number;
+    toolMs: number;
+    ttftMs: number;
+    ttftSteps: number;
+    decodeMs: number;
+    decodeTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** Stats groups in drop order (last is dropped first when the row is too wide). */
+export declare function footerStatsGroups(stats: FooterStatsInput): string[];
+export declare function fitFooterStatsLine(chip: string, groups: readonly string[], width: number): string;
+export type FooterActivityKind = 'plan-review' | 'waiting' | 'compacting' | 'retry' | 'subagents' | 'tools' | 'plan-open' | 'plan-pending' | 'goal' | 'waiting-llm' | 'idle';
+export interface FooterStatusInput {
+    running: boolean;
+    planReview: boolean;
+    waitingQuestion: boolean;
+    compacting: boolean;
+    retry?: {
+        retry: number;
+        maxRetries: number;
+    };
+    subagents: number;
+    tools: number;
+    planLeftOpen: boolean;
+    planPending: boolean;
+    planActive: boolean;
+    goalPhase?: 'active' | 'paused' | 'blocked';
+    idleMs: number;
+    model: string;
+    effort?: string;
+    preset?: string;
+    provider: string;
+    parentModel: string;
+    subModel: string;
+    subDiffers: boolean;
+    quotaCode?: string;
+    quotaPercent?: number;
+    contextChip?: string;
+    balanceText?: string;
+    search?: {
+        index: number;
+        total: number;
+    };
+    foldedInput: boolean;
+    multiLineInput: boolean;
+    queued: number;
+    cwdLabel?: string;
+    compactView?: boolean;
+}
+export declare function footerActivity(input: FooterStatusInput): {
+    kind: FooterActivityKind;
+    text: string;
+};
+/** Short remaining-quota bar: 8 pips, filled from the left. */
+export declare function formatQuotaBar(remainingPercent: number, width?: number): string;
+export declare function footerIdentityParts(input: FooterStatusInput): string[];
+/** `SuperGrok ███████░ 82%`, or just the bar + percent when `code` is omitted. */
+export declare function formatFooterQuota(percent: number, code?: string): string;
+/**
+ * Drop the Go / SuperGrok plan name from a quota identity part, keeping the
+ * remaining-percent bar. Returns true when a part was rewritten.
+ */
+export declare function dropFooterQuotaPlanName(parts: string[]): boolean;
+export declare function fitFooterStatusLine(activity: string, identity: readonly string[], width: number): string;
+export interface StatusReportInput {
+    sessionId: string;
+    pluginVersion: string;
+    provider: string;
+    model: string;
+    effort?: string;
+    agentStatus: string;
+    preset: string;
+    activeSubagents: number;
+    plan: 'off' | 'pending' | 'on';
+    paint: string;
+    disconnect?: DisconnectPolicyName;
+    waitingQuestions: number;
+    quota?: QuotaSnapshot;
+    context?: ContextPressureView;
+    parentModel?: string;
+    subProvider?: string;
+    subModel: string;
+    cwd?: string;
+}
+/** Lines printed by `/status` — SSH first-boot diagnostics, no extra command. */
+export declare function formatStatusReport(input: StatusReportInput): string[];
+/** Human-facing kind for a live LLM route. */
+export declare function describeProviderRoute(provider: string): {
+    kind: string;
+    short: string;
+};
+/** Routes that authenticate without a harness API-key credential. */
+export declare function providerUsesLocalOAuth(provider: string): boolean;

package/lib/types/json-args.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Best-effort JSON argument parsing for tool cards and plan payloads.
+ */
+export declare function parseJsonArgs(args: string): Record<string, unknown> | null;
+export declare function firstString(record: Record<string, unknown>, keys: readonly string[]): string;
+/** A short scalar rendering of one argument value, or null for objects/arrays. */
+export declare function scalarText(value: unknown): string | null;

package/lib/types/paint.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Incremental ANSI paint, SSH cadence, hangup signals, and sliding windows.
+ *
+ * Kept off `tui.ts` so the launch picker can dirty-paint without loading
+ * the agent-backed SshTui class.
+ */
+export declare const DSR_PROBE_TIMEOUT_MS = 800;
+/** Give a running turn this long to settle after cancel before we flush anyway. */
+export declare const HANGUP_CANCEL_TIMEOUT_MS = 10000;
+export type PaintLinkKind = 'local' | 'ssh';
+/** In-app dialog / slash-suggestion page size. Launch picker uses 9 of its own. */
+export declare const PICKER_WINDOW = 12;
+/**
+ * Explicit env/config always wins. Otherwise local TTYs stay snappy and SSH
+ * sessions pick a tier from a measured round-trip (CSI 6n), falling back to
+ * 160 ms when the probe is missing.
+ */
+export declare function resolvePaintIntervalMs(configured?: number, env?: NodeJS.ProcessEnv, options?: {
+    ssh?: boolean;
+    rttMs?: number;
+}): number;
+/** True when this process is attached to an SSH session (jump host / proxy). */
+export declare function detectSshSession(env?: NodeJS.ProcessEnv): boolean;
+/** Node errno on a write/close that means the TTY is gone (SSH drop, HUP). */
+export declare function isHangupErrno(error: unknown): boolean;
+/**
+ * Replace launcher SIGTERM/SIGINT/SIGHUP handlers with `handler`. SSH drop
+ * otherwise lets `dsh` dispose the whole tree before this plugin can detach.
+ */
+export declare function captureHangupSignals(handler: () => void): void;
+export declare function releaseHangupSignals(handler: () => void): void;
+/** After detach, extra HUP/TERM from sshd must not kill the leftover Host. */
+export declare function ignoreFurtherHangupSignals(): void;
+/**
+ * Wait until `isIdle` is true or `timeoutMs` elapses. Used after cancel so a
+ * hangup can flush a settled session log instead of tearing a live write.
+ */
+export declare function waitUntilIdleOrTimeout(isIdle: () => boolean, timeoutMs: number, now?: () => number, wait?: (ms: number) => Promise<void>): Promise<'idle' | 'timeout'>;
+/** Map a CSI-6n round-trip to a paint cadence. Unknown RTT uses the SSH default. */
+export declare function paintIntervalForRtt(rttMs: number | undefined): number;
+export declare function paintLinkLabel(kind: PaintLinkKind, intervalMs: number, probed: boolean): string;
+export type LinkQuality = 'local' | 'good' | 'ok' | 'slow' | 'poor' | 'unknown';
+/** Signal-bar quality from a measured SSH round-trip, or local TTY. */
+export declare function linkQualityOf(kind: PaintLinkKind, rttMs: number | undefined): LinkQuality;
+/** How many filled signal pips: 4 local/fast, 3 ok, 2 slow, 1 poor, 0 unknown. */
+export declare function linkSignalPips(quality: LinkQuality): number;
+/** Compact footer chip: `SSH ●●●○ 90ms` — 1 pip red, 2 yellow, 3+ green. */
+export declare function formatLinkQualityChip(kind: PaintLinkKind, intervalMs: number, rttMs: number | undefined, probed: boolean, color?: boolean): string;
+/** One incremental paint as a single stdout write (one SSH packet when corked). */
+export declare function composePaintOutput(options: {
+    width: number;
+    height: number;
+    paintRows: readonly string[];
+    previousRows: readonly string[];
+    sizeChanged: boolean;
+    chromeChanged: boolean;
+    chromeStart: number;
+    previousChromeStart?: number;
+    cursorRow: number;
+    cursorColumn: number;
+    /** Keep the cursor hidden (session picker). Default shows it on the input. */
+    hideCursor?: boolean;
+}): string;
+/** Whether `text` could still grow into a recognized escape sequence. */
+export declare function isEscapePrefix(text: string): boolean;
+/** Parse a Device Status Report cursor reply (`CSI row;col R`). */
+export declare function parseCursorPositionReply(text: string): {
+    row: number;
+    column: number;
+} | undefined;
+/**
+ * Round-trip to the attached terminal via CSI 6n. Returns undefined when the
+ * reply never arrives (dumb pipe, blocked DSR). Does not interpret the
+ * coordinates — only the elapsed milliseconds matter.
+ */
+export declare function probeTerminalRttMs(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream, timeoutMs?: number): Promise<number | undefined>;
+/** Sliding window of `windowSize` items that keeps `cursor` visible. */
+export declare function pickerWindowStart(cursor: number, total: number, windowSize?: number): number;

package/lib/types/picker.d.ts

@@ -1,9 +1,14 @@
 /**
- * Startup history-session picker: a small raw-mode selector shown BEFORE the
- * main TUI mounts, so launching without an explicit session id lands on a
- * choice instead of a fresh main screen.
+ * Startup history-session picker: a raw-mode selector shown BEFORE the main
+ * TUI mounts, so launching without an explicit session id lands on a choice
+ * instead of a fresh main screen.
+ *
+ * The list itself is not capped. The visible page is always nine rows so
+ * digits 1-9 map onto every on-screen item. Arrow keys move a highlight,
+ * typing filters by title / id / cwd, and Enter confirms the focused row.
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { type ResumableSession } from './session-list.js';
 /** What the launch picker decided. */
 export type SessionPickerResult = {
     kind: 'resume';
@@ -16,10 +21,97 @@ export type SessionPickerResult = {
     kind: 'new';
 } | null;
 /**
- * Show the picker and wait for one digit, Enter (new session), or a lone
- * Esc/Ctrl+C (cancel). Incomplete CSI/SS3 sequences are buffered briefly so
- * arrow keys are ignored instead of cancelling. Restores the terminal before
- * resolving; an AbortSignal cancels and restores as well.
+ * Visible rows in the sliding window. Locked to nine so every on-screen
+ * session has a 1-9 shortcut; remaining history is reached with ↑/↓ / filter.
+ */
+export declare const SESSION_PICKER_WINDOW = 9;
+/** Digit shortcuts into the current window when the filter is empty. */
+export declare const PICKER_QUICK_KEYS = "123456789";
+/** Mutable picker UI state. */
+export interface SessionPickerState {
+    sessions: ResumableSession[];
+    query: string;
+    cursor: number;
+    /**
+     * When true, digits type into the filter instead of acting as 1-9 / 0
+     * shortcuts. Set automatically by the first letter, or by `/` / Ctrl+F.
+     */
+    filterActive: boolean;
+}
+/** One key / control action against {@link SessionPickerState}. */
+export type SessionPickerAction = {
+    type: 'move';
+    delta: number;
+} | {
+    type: 'page';
+    delta: number;
+} | {
+    type: 'home';
+} | {
+    type: 'end';
+} | {
+    type: 'type';
+    text: string;
+} | {
+    type: 'backspace';
+} | {
+    type: 'clearQuery';
+} | {
+    type: 'startFilter';
+} | {
+    type: 'quick';
+    key: string;
+} | {
+    type: 'submit';
+} | {
+    type: 'new';
+} | {
+    type: 'escape';
+} | {
+    type: 'cancel';
+};
+/** Result of applying one action: keep going, or the picker is done. */
+export type SessionPickerStep = {
+    kind: 'continue';
+    state: SessionPickerState;
+} | {
+    kind: 'done';
+    result: SessionPickerResult;
+};
+/** Haystack used by the filter: title, id, cwd, and a live pid when attached. */
+export declare function sessionSearchHaystack(session: ResumableSession): string;
+/** Whether one session matches a whitespace-separated query (every token). */
+export declare function sessionMatchesQuery(session: ResumableSession, query: string): boolean;
+/** Sessions still visible under the current filter, in list order. */
+export declare function filterResumableSessions(sessions: readonly ResumableSession[], query: string): ResumableSession[];
+/** Keep `cursor` inside `[0, total)`. Empty lists pin to 0. */
+export declare function clampPickerCursor(cursor: number, total: number): number;
+/**
+ * How many session rows to show. Prefer a full page of nine so 1-9 always
+ * map onto every on-screen item. Shrink only when the tty cannot fit that
+ * page (title + filter + nine items + hints).
+ */
+export declare function pickerCapacity(rows: number): number;
+/** Whether two picker states would paint the same frame. */
+export declare function pickerStateUnchanged(previous: SessionPickerState, next: SessionPickerState): boolean;
+/**
+ * Apply one picker action. Pure: the TTY layer maps keystrokes onto this, and
+ * tests drive it without stdin.
+ */
+export declare function stepPicker(state: SessionPickerState, action: SessionPickerAction, windowSize?: number): SessionPickerStep;
+/** Map one decoded stdin chunk (or a complete CSI sequence) to actions. */
+export declare function actionsForInput(text: string, state?: Pick<SessionPickerState, 'query' | 'filterActive'>): SessionPickerAction[];
+/** Split a decoded stdin chunk into CSI/SS3 sequences and individual characters. */
+export declare function splitPickerInput(text: string): string[];
+/**
+ * Feed a decoded stdin chunk through the picker. CSI / SS3 sequences are one
+ * unit; ordinary text is applied character by character so a pasted "fix 2"
+ * types the digit instead of treating it as a 1-9 shortcut.
+ */
+export declare function feedPicker(state: SessionPickerState, text: string, windowSize?: number): SessionPickerStep;
+/**
+ * Show the picker and wait for a selection, a new-session request, or cancel.
+ * Restores the terminal before resolving; an AbortSignal cancels as well.
  * @param ctx - boot context supplying sessionPersistence.
  * @param color - whether to apply ANSI colors.
  * @param signal - optional abort signal (fiber dispose) to cancel the picker.

package/lib/types/plan.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Plan dock, todo lists, /find, prompt-injection cards, and compact errors.
+ */
+import type { DisplayKind, PlanTodoItem, Row, SubagentLogEntry } from './transcript-types.js';
+export declare const MAX_SUBAGENT_LOGS = 80;
+export declare const TODO_STATUS_MARK: Record<PlanTodoItem['status'], string>;
+/** True while a plan still belongs in the dock (latest incomplete work). */
+export declare function planIsLive(plan: {
+    active: boolean;
+    pending: boolean;
+    todos: readonly PlanTodoItem[];
+    planMarkdown?: string;
+    archived?: boolean;
+}): boolean;
+/** Open todos left behind when a turn ends without a completing todo_write. */
+export declare function planTurnLeftOpen(plan: {
+    todos: readonly PlanTodoItem[];
+}): boolean;
+/** Mark leftover in-progress/pending todos as display-stale after turn/end. */
+export declare function applyTurnEndToPlan<T extends {
+    todos: PlanTodoItem[];
+    turnLeftOpen?: boolean;
+}>(plan: T): T;
+/** Follow-up that asks the model to close leftover todos. One per open list. */
+export declare function planCloseNudgeText(plan: {
+    todos: readonly PlanTodoItem[];
+}): string;
+export type CardCategory = 'thinking' | 'plan' | 'subagent' | 'reply' | 'tool' | 'question' | 'goal' | 'prompt';
+/** Category for jump / search. Assistant replies are not collapsible cards. */
+export declare function cardCategoryOf(row: {
+    kind: string;
+}): CardCategory | undefined;
+export declare function cardCategoryLabel(category: CardCategory): string;
+export declare function parseCardCategoryToken(token: string): CardCategory | undefined;
+/** Split `/find thinking padAnsi` into an optional category and a query. */
+export declare function parseFindQuery(raw: string): {
+    category?: CardCategory;
+    query: string;
+};
+/** Classify one injected prompt blob into display sources. */
+export declare function promptInjectionSources(text: string, plugin?: string): string[];
+export declare function promptInjectionTitle(sources: readonly string[]): string;
+export declare function isPromptInjectionMessage(sourceKind: string, text: string, plugin?: string): boolean;
+/** Official `/compact` idle-only failures, mapped to a local sentence. */
+export declare function formatCompactCommandError(text: string): string;
+export declare function compactionHeaderText(row: {
+    status: 'running' | 'ok' | 'error';
+    pruneCount: number;
+    prunedTokens: number;
+    error?: string;
+}): string;
+/** Transcript rows matching a `/find` query, newest last. */
+export declare function matchTranscriptRows(rows: readonly Row[], raw: string): Row[];
+/** One-line note under an expanded plan strip. */
+export declare function planDockNote(plan: {
+    active: boolean;
+    pending: boolean;
+    todos: readonly PlanTodoItem[];
+    planMarkdown?: string;
+    turnLeftOpen?: boolean;
+}): string;
+/** Compact per-status counts matching the web plan strip. */
+export declare function todoProgressLabel(todos: readonly PlanTodoItem[]): string;
+export declare function todoItemKind(status: PlanTodoItem['status']): DisplayKind;
+export declare function planMarkdownFromArgs(value: unknown): string | undefined;
+/** First markdown heading of an exit_plan_mode plan body. */
+export declare function planTitleFromMarkdown(markdown: string): string | undefined;
+/** Parse a todo_write payload into displayable plan items. */
+export declare function parsePlanTodos(value: unknown): PlanTodoItem[];
+/** Compact todo-list summary: done/total plus the first in-progress task. */
+export declare function todoSummary(value: unknown): string;
+/** Compact ask_user_question summary from tool arguments. */
+export declare function askSummary(value: unknown): string;
+/** One-line subagent card header used while collapsed. */
+export declare function subagentHeaderText(row: Extract<Row, {
+    kind: 'subagent';
+}>, now?: number): string;
+export declare function appendSubagentLog(row: Extract<Row, {
+    kind: 'subagent';
+}>, entry: SubagentLogEntry): void;

package/lib/types/quota.d.ts

@@ -0,0 +1,94 @@
+/**
+ * OpenCode / SuperGrok / DeepSeek quota and prepaid-balance parsers.
+ */
+/** A recognized OpenCode provider route, used by /usage and /quota. */
+export type OpenCodeFlavor = 'zen' | 'go';
+export interface OpenCodeSource {
+    provider: string;
+    flavor: OpenCodeFlavor;
+    label: string;
+    apiKeyEnv: string;
+    baseURL?: string;
+}
+export interface LlmPiAiProviderProfile {
+    displayName?: unknown;
+    apiKeyEnv?: unknown;
+    baseURL?: unknown;
+    api?: unknown;
+    models?: unknown;
+    reasoning?: unknown;
+}
+export interface LlmPiAiSection {
+    providers?: Record<string, LlmPiAiProviderProfile>;
+}
+/** Build per-model reasoningEfforts from a provider-level reasoning default. */
+export declare function reasoningEffortsForDefault(reasoning: unknown): Record<string, string | null> | undefined;
+export declare const OPENCODE_GO_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
+export declare const OPENCODE_ZEN_BASE_URL = "https://opencode.ai/zen/v1";
+export declare const SUPERGROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+export declare const DEEPSEEK_PUBLIC_BASE_URL = "https://api.deepseek.com";
+/** OpenAI-completions gateways: probe these relative to the configured base URL. */
+export declare const OPENAI_COMPAT_BALANCE_PATHS: readonly ["/user/balance", "/dashboard/billing/credit_grants", "/v1/dashboard/billing/credit_grants", "/v1/dashboard/billing/subscription"];
+/**
+ * Classify the currently selected provider as an OpenCode route. Built-in
+ * `opencode`/`opencode-go` ids are recognized directly, and custom llm-pi-ai
+ * routes are recognized by their `opencode.ai` base URL.
+ */
+export declare function openCodeSourceFor(provider: string, llmPiAiSection: unknown): OpenCodeSource | null;
+export type QuotaPeriod = 'hourly' | 'weekly' | 'monthly' | 'unknown';
+export interface QuotaWindow {
+    label: string;
+    period: QuotaPeriod;
+    /** Remaining percent of the window (100 = unused). */
+    remainingPercent: number;
+    resetsAt?: string;
+}
+export interface QuotaSnapshot {
+    provider: string;
+    plan: string;
+    windows: QuotaWindow[];
+}
+export declare function remainingPercentFromUsed(usedPercent: number): number;
+/** Cross a remaining-percent threshold from above (50 / 25 / 10 / 5).
+ *  Only the tightest (lowest) crossed threshold is returned, so one drop
+ *  never paints 50/25/10 as three identical warnings. */
+export declare function crossedQuotaThresholds(previousRemaining: number | undefined, remaining: number): number[];
+export declare function quotaAlertText(snapshot: QuotaSnapshot, window: QuotaWindow): string;
+/**
+ * How often to re-fetch quota or prepaid balance, counted in model steps.
+ * Default is every 10 steps. Near a remaining-percent threshold, hourly
+ * windows refresh every 4 steps.
+ */
+export declare function quotaRefreshEverySteps(window: QuotaWindow | undefined): number;
+/** @deprecated Same cadence as {@link quotaRefreshEverySteps}; the name predates step accounting. */
+export declare const quotaRefreshEveryTurns: typeof quotaRefreshEverySteps;
+export declare function parseSuperGrokBilling(payload: unknown): QuotaSnapshot;
+export declare function parseOpenCodeGoQuota(payload: unknown, provider: string): QuotaSnapshot;
+export declare function formatQuotaSnapshot(snapshot: QuotaSnapshot): string;
+/** Compact `/status` quota line: tightest window first, then the rest. */
+export declare function formatQuotaStatusLine(snapshot: QuotaSnapshot | undefined): string;
+/** Tightest remaining window — used for threshold alerts. */
+export declare function tightestQuotaWindow(snapshot: QuotaSnapshot): QuotaWindow | undefined;
+/** Render the OpenCode Go quota payload as a transcript block. */
+export declare function formatOpenCodeGoUsage(payload: unknown, source: OpenCodeSource): string;
+export interface AccountBalanceLine {
+    label: string;
+    amount: string;
+    currency?: string;
+}
+export interface AccountBalanceSnapshot {
+    provider: string;
+    plan: string;
+    available?: boolean;
+    lines: AccountBalanceLine[];
+    sourcePath?: string;
+}
+export declare function joinUrl(base: string, path: string): string;
+export declare function parseDeepSeekBalance(payload: unknown, provider?: string): AccountBalanceSnapshot;
+/** Best-effort parse of OpenAI-compatible credit/balance JSON. */
+export declare function parseOpenAiCompatibleBalance(payload: unknown, provider: string, path: string): AccountBalanceSnapshot | undefined;
+/** Compact footer chip: `余额 86.42 CNY`. Prefers remaining/available lines. */
+export declare function formatFooterBalance(snapshot: AccountBalanceSnapshot): string | undefined;
+export declare function formatAccountBalance(snapshot: AccountBalanceSnapshot): string;
+/** Extract a safe human-readable message from an OpenCode error payload. */
+export declare function openCodeApiErrorMessage(payload: unknown): string;

package/lib/types/session-list.d.ts

@@ -38,4 +38,17 @@ export interface ResumableSession {
 }
 /** `MM-DD HH:mm` local-time label for session lists. */
 export declare function formatSessionTime(timestamp: number): string;
+/**
+ * List resumable top-level sessions, newest first.
+ *
+ * Subagent-owned sessions and the current session are excluded. Sessions
+ * whose event log cannot be inspected are kept (marked `unreadable`) instead
+ * of silently disappearing from history; readable sessions with user input
+ * sort first. The label is the persisted title, then the user's first input,
+ * then the id.
+ * @param persistence - the session persistence service.
+ * @param currentId - the live session to exclude (empty at launch).
+ * @returns every resumable candidate in display order (attachable live
+ *   hosts first, then readable logs, then unreadable).
+ */
 export declare function listResumableSessions(persistence: SessionPersistence, currentId: string, listHosts?: typeof listAttachableHosts): Promise<ResumableSession[]>;