codsh-cli 0.1.0

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-cli/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-cli/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;
+}

package/lib/types/theme.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Terminal styling and display metrics: SGR sequences that degrade to plain
+ * text off a TTY, and the display-column width a rendered string occupies.
+ * @module codsh-cli/src/theme
+ */
+/** Style roles the renderer asks for, resolved to SGR codes by {@link createTheme}. */
+export interface Theme {
+    /** Whether this theme emits SGR sequences at all. */
+    readonly colored: boolean;
+    dim(text: string): string;
+    bold(text: string): string;
+    /** Failures, denied approvals, and removed diff lines. */
+    error(text: string): string;
+    /** Completed work and added diff lines. */
+    success(text: string): string;
+    /** Pending state and approval prompts. */
+    pending(text: string): string;
+    /** Tool names and card titles. */
+    tool(text: string): string;
+    /** File paths and locations. */
+    path(text: string): string;
+    /** The user's own echoed input. */
+    user(text: string): string;
+    /** Roles used inside a fenced code block. */
+    readonly syntax: SyntaxTheme;
+}
+/** Styling for the token classes a code block is coloured by. */
+export interface SyntaxTheme {
+    keyword(text: string): string;
+    string(text: string): string;
+    number(text: string): string;
+    comment(text: string): string;
+}
+/**
+ * Build the theme for one surface.
+ *
+ * Color is suppressed off a TTY and whenever `NO_COLOR` is set to any value,
+ * following the `no-color.org` convention: a redirected transcript stays
+ * greppable, and a pipe never receives sequences a reader would have to strip.
+ *
+ * Secondary text uses a palette gray on a 256-color terminal rather than the
+ * `dim` attribute: several terminals render `dim` at full brightness, and a
+ * hierarchy nobody can see is no hierarchy — the placeholder, the menu details,
+ * and the status row must sit visibly behind what the person typed.
+ * @param isTty - whether the output stream is a terminal.
+ * @param env - the environment to read `NO_COLOR` and the color depth from.
+ * @returns the styling functions for this surface.
+ */
+export declare function createTheme(isTty: boolean, env: Record<string, string | undefined>): Theme;
+/**
+ * Display columns a string occupies once printed, ignoring styling sequences.
+ *
+ * Combining marks are counted as zero and East Asian Wide/Fullwidth code
+ * points as two, which is what a terminal's own cursor arithmetic does. This
+ * covers the alignment and wrapping this surface needs; it is not a complete
+ * grapheme segmenter, so a ZWJ emoji sequence still counts each joined code
+ * point ({@link ../README.md | Known Limitations}).
+ * @param text - the string to measure, possibly carrying SGR sequences.
+ * @returns the number of display columns.
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * Shorten a string to at most `columns` display columns, marking the cut with
+ * an ellipsis when anything was dropped.
+ *
+ * Styling survives: sequences cost no columns and travel with the text they
+ * style, and a cut that kept any styling closes it with a reset before the
+ * ellipsis so nothing leaks onto the next row. A string that already fits is
+ * returned exactly as it came — a fit is not a licence to restyle it.
+ * @param text - the string to shorten, possibly carrying SGR sequences.
+ * @param columns - the display-column budget; a budget under 2 yields the empty string.
+ * @returns the string, unchanged when it already fits.
+ */
+export declare function truncate(text: string, columns: number): string;

package/lib/types/transcript.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Session log to terminal lines. One appended {@link SessionEvent} renders to
+ * zero or more finished lines; the surface never rewrites a line it has
+ * printed, so the transcript scrolls like a shell history.
+ *
+ * Tool cards come from the registered presenters rather than from tool names:
+ * a tool declares its own render intent, and this module switches on the
+ * resulting `card` tag.
+ * @module codsh-cli/src/transcript
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ToolCallView, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools';
+import type { Theme } from './theme.ts';
+/** The registered presenters, resolved against the agent's scope by the caller. */
+export interface ToolPresenters {
+    /**
+     * Render intent for a pending call.
+     * @param name - the tool the model called.
+     * @param args - the parsed call arguments.
+     * @returns the declared view, or undefined for the generic fallback.
+     */
+    call(name: string, args: unknown): ToolCallView | undefined;
+    /**
+     * Render intent for a completed call.
+     * @param name - the tool the model called.
+     * @param args - the parsed call arguments.
+     * @param result - the completed outcome.
+     * @returns the declared view, or undefined for the generic fallback.
+     */
+    result(name: string, args: unknown, result: ToolResult): ToolResultView | undefined;
+}
+/** What the renderer needs to know about the surface it writes to. */
+export interface TranscriptOptions {
+    theme: Theme;
+    /** Display columns available for one line. */
+    columns: number;
+    /** Session workspace, stripped from absolute paths so cards stay short. */
+    cwd: string;
+}
+/** Renders one session's appended events as terminal lines. */
+export declare class Transcript {
+    private readonly options;
+    private readonly presenters;
+    private readonly calls;
+    /** The most recent result whose body the cap clipped, kept in full. */
+    private clipped;
+    constructor(options: TranscriptOptions, presenters: ToolPresenters);
+    /**
+     * Shorten an absolute path inside the workspace to a workspace-relative one.
+     * @param path - the model-facing path a card carries.
+     * @returns the display path.
+     */
+    private relative;
+    /**
+     * Shorten every workspace path a presenter embedded in free text.
+     *
+     * A title is prose the tool composed (`Write /abs/path`), so the path inside
+     * it needs the same shortening as a structured `locations` entry.
+     * @param text - the presenter-supplied line.
+     * @returns the line with workspace-rooted paths made relative.
+     */
+    private relativizeIn;
+    /**
+     * Paths worth appending to a title that may already name them.
+     * @param title - the presenter's title, already relativized.
+     * @param paths - the relativized paths the card covers.
+     * @returns the paths the title does not mention, joined for display.
+     */
+    private extraPaths;
+    /**
+     * Render one appended event.
+     * @param event - the event exactly as recorded.
+     * @returns the lines to append to the transcript, empty when the event shows nothing.
+     */
+    render(event: SessionEvent): string[];
+    /**
+     * Render a pending call as its declared card.
+     * @param callId - correlation id, remembered until the result pairs with it.
+     * @param name - the tool the model called.
+     * @param rawArguments - the unparsed arguments JSON the model produced.
+     * @returns the pending card's lines.
+     */
+    private renderCall;
+    /**
+     * Render a completed call, pairing it with the call this transcript recorded.
+     * @param data - the `tool/result` payload.
+     * @returns the completed card's lines.
+     */
+    private renderResult;
+    /**
+     * The last clipped result, rendered without its cap.
+     *
+     * Ctrl-O's answer. The full body is kept from the render itself because a
+     * tool's own output limits are upstream of the log — this is everything the
+     * model saw, which is everything recoverable.
+     * @returns the header and full body, or undefined when nothing was clipped.
+     */
+    expandLast(): string[] | undefined;
+    /**
+     * Render one completed call's status suffix and body from its declared view.
+     * @param view - the result view, absent when no presenter answered.
+     * @param block - the model-facing result block, used by the generic fallback.
+     * @returns the suffix, the (possibly capped) body, and — when the cap dropped
+     *   lines, or a bodiless card withheld content — the full body for Ctrl-O.
+     */
+    private outcome;
+    /**
+     * Flatten a result's content blocks to displayable text.
+     * @param content - the result content blocks.
+     * @returns the joined text.
+     */
+    private resultText;
+    /**
+     * Ask a call presenter for its view, absorbing a throwing presenter.
+     * @param name - the tool the model called.
+     * @param args - the parsed call arguments.
+     * @returns the view, or undefined to fall back to the generic line.
+     */
+    private safeCall;
+    /**
+     * Ask a result presenter for its view, absorbing a throwing presenter.
+     * @param pending - the recorded call this result pairs with.
+     * @param content - the model-facing result content.
+     * @param isError - whether the executor reported a failure.
+     * @param meta - the tool's private presentation payload, when it attached one.
+     * @returns the view, or undefined to fall back to the generic card.
+     */
+    private safeResult;
+}

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "codsh-cli",
+  "description": "A Claude Code-style coding agent for the terminal, composed on the DeepSeek Harness (dsh): interactive TTY surface, plan mode, approvals, custom commands, and session management over the dsh plugin runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "codsh": "./bin/codsh.mjs"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./agent-presets/*": "./agent-presets/*"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/startup.js",
+    "bin",
+    "cordis.patch.yml",
+    "agent-presets",
+    "lib/types/**/*.d.ts"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-instructions": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-command-compact": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-compaction-basic": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-lsp": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-lsp-stdio": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-persona": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-terminal": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-terminal-bash": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-ask-user": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-bash": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-fs": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-fs-search": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-goal": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-jobs": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-lsp": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-pwsh": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-ralph": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-skill": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-subagent-control": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-terminal": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-todo": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-web": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tool-workflow": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-workflow-worker-thread": "^0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "commander": "^15.0.0",
+    "diff": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session-query": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.0",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session-query": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7",
+    "@types/node": "^24.0.0",
+    "execa": "^9.0.0",
+    "tsdown": "^0.15.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blackman99/codsh.git"
+  },
+  "homepage": "https://github.com/Blackman99/codsh#readme",
+  "bugs": "https://github.com/Blackman99/codsh/issues",
+  "keywords": [
+    "cli",
+    "coding-agent",
+    "terminal",
+    "deepseek",
+    "dsh",
+    "ai",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts",
+    "dev": "node scripts/dev.mjs",
+    "release": "pnpm run build && changeset publish"
+  }
+}