indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/types/insight/sampling.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Sampling — the admission gate that decides which trails are recorded.
+ *
+ * A {@link SampleGate} (declared in the contract) returns a per-trail verdict:
+ * `true` keeps the trail (live handles), `false` collapses the whole trail to
+ * {@link NOOP_HANDLE}. This module supplies the three concrete gates the recorder
+ * draws from:
+ *
+ *   - {@link alwaysGate} — admit every trail (the default when sampling is off);
+ *   - {@link neverGate}  — reject every trail (a disabled recorder);
+ *   - {@link ratioGate}  — admit a deterministic fraction, keyed on the trail id.
+ *
+ * The ratio gate is the interesting one. It must be *sticky per trail* — a probe
+ * may never disagree with its trail about being sampled — so the verdict is a
+ * pure function of the trail id, not a coin flip. We fold the id into a 32-bit
+ * value with an FNV-1a hash, project it onto the unit interval, and compare
+ * against the configured fraction. The same id always yields the same verdict on
+ * any machine, which also makes head-based sampling agree across a distributed
+ * trail without coordination.
+ */
+import { FixedGates, SampleGate, TrailId } from "./contract";
+/** A gate that admits every trail. Shared, frozen, allocation-free. */
+export declare const alwaysGate: SampleGate;
+/** A gate that rejects every trail. Shared, frozen, allocation-free. */
+export declare const neverGate: SampleGate;
+/** The two well-known fixed gates, bundled for the recorder fallback. */
+export declare const FIXED_GATES: FixedGates;
+/**
+ * Fold a string into a 32-bit unsigned hash with FNV-1a.
+ *
+ * Chosen for being tiny, dependency-free, and well-distributed over short hex
+ * ids. The result is forced unsigned with `>>> 0` so the projection onto the
+ * unit interval never sees a negative numerator.
+ *
+ * @param text the string to hash (a trail id, in practice)
+ * @returns a 32-bit unsigned integer
+ */
+export declare function hash32(text: string): number;
+/**
+ * Project a trail id onto the unit interval `[0, 1)`.
+ *
+ * The same id always lands on the same point, which is what makes a
+ * {@link ratioGate} verdict deterministic and sticky.
+ *
+ * @param trailId the trail id to score
+ * @returns a fraction in `[0, 1)`
+ */
+export declare function trailScore(trailId: TrailId): number;
+/**
+ * A sampling gate that admits a deterministic fraction of trails.
+ *
+ * Unlike {@link alwaysGate} / {@link neverGate}, this gate needs the *trail id*
+ * to render a sticky verdict, but {@link SampleGate.admit} is handed only the
+ * root name. The recorder therefore mints the trail id first and consults
+ * {@link verdict} directly; {@link RatioGate.admit} is kept as a name-only
+ * fallback (it folds the name instead) so the type still satisfies
+ * {@link SampleGate}.
+ */
+export interface RatioGate extends SampleGate {
+    /** The admitted fraction, clamped to `[0, 1]`. */
+    readonly fraction: number;
+    /** The sticky, id-keyed verdict the recorder actually consults. */
+    verdict(trailId: TrailId): boolean;
+}
+/**
+ * Build a {@link RatioGate} admitting roughly `fraction` of all trails.
+ *
+ * The verdict is `trailScore(id) < fraction`, so a fraction of `0.1` admits the
+ * trails whose hashed id lands in the lowest tenth of the unit interval — about
+ * a tenth of trails, deterministically. Edge fractions short-circuit to the
+ * fixed gates: `<= 0` is {@link neverGate} behaviour and `>= 1` is
+ * {@link alwaysGate} behaviour, with no hashing.
+ *
+ * @param fraction the admitted share, clamped to `[0, 1]`
+ * @returns a frozen {@link RatioGate}
+ */
+export declare function ratioGate(fraction: number): RatioGate;
+/**
+ * Narrow a {@link SampleGate} to a {@link RatioGate}.
+ *
+ * Lets the recorder prefer the id-keyed {@link RatioGate.verdict} when the gate
+ * exposes it, falling back to the name-only {@link SampleGate.admit} otherwise.
+ */
+export declare function isRatioGate(gate: SampleGate): gate is RatioGate;

package/dist/types/insight/serialize.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Serialization — the on-disk NDJSON record shape shared by the file sink and
+ * the replay reader.
+ *
+ * A {@link Signal} is already JSON-ish, but persisting it verbatim would bury the
+ * useful fields (phase, ids, timing) inside a nested probe. A {@link TraceRecord}
+ * is the flat, self-describing line we actually write: one JSON object per line,
+ * carrying the phase, the full probe, and the emission clock. The file sink
+ * encodes a record per signal; {@link replay} parses records back into probes.
+ *
+ * Keeping the record format in one module guarantees the writer and the reader
+ * never drift: there is exactly one {@link encodeRecord} and one
+ * {@link decodeRecord}, and both sides import them.
+ */
+import { ClosedProbe, Probe, Signal, SignalPhase } from "./contract";
+/** Schema version stamped on every record, so a future reader can branch. */
+export declare const RECORD_VERSION: 1;
+/**
+ * One persisted trace line.
+ *
+ * Flat and self-describing: a reader needs nothing but the line to reconstruct
+ * the signal. The `probe` is a {@link ClosedProbe} when `phase === "close"`.
+ */
+export interface TraceRecord {
+    /** Record schema version; see {@link RECORD_VERSION}. */
+    readonly v: typeof RECORD_VERSION;
+    /** The signal phase this record carries. */
+    readonly phase: SignalPhase;
+    /** The probe value at the moment the signal fired. */
+    readonly probe: Probe;
+    /** Emission clock, epoch ms. */
+    readonly at: number;
+}
+/** Line feed (U+000A): the one and only record boundary. */
+export declare const LINE_FEED = "\n";
+/** Project a {@link Signal} onto its flat {@link TraceRecord}. */
+export declare function signalToRecord(signal: Signal): TraceRecord;
+/**
+ * Encode a signal as one separator-safe NDJSON line.
+ *
+ * @returns the JSON line terminated by a single line feed
+ */
+export declare function encodeRecord(signal: Signal): string;
+/**
+ * Parse one NDJSON line into a {@link TraceRecord}.
+ *
+ * @throws SyntaxError when the line is not valid JSON
+ * @returns the decoded record (callers validate the shape before trusting it)
+ */
+export declare function decodeRecord(line: string): TraceRecord;
+/** Whether a decoded record's probe is a terminal {@link ClosedProbe}. */
+export declare function recordIsClose(record: TraceRecord): record is TraceRecord & {
+    probe: ClosedProbe;
+};

package/dist/types/insight/sinks/console.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Console sink — drains signals to a writable, one human-readable line each.
+ *
+ * The simplest terminal {@link Sink}: it pulls the {@link SignalStream} and
+ * prints a compact line per signal — phase, kind, name, ids, and (on close) the
+ * outcome and duration. Open and update lines are dimmed; close lines are
+ * coloured by outcome. Colour is opt-in and degrades to plain text when the
+ * target is not a TTY, so piping the output stays clean.
+ *
+ * The writer is injected (defaulting to `process.stdout`) so tests can capture
+ * lines without touching the real terminal.
+ */
+import { Sink } from "../contract";
+/** The minimal writable face the console sink needs. */
+export interface LineWriter {
+    /** Append a chunk; the sink always supplies a newline-terminated line. */
+    write(chunk: string): unknown;
+    /** Whether the target is an interactive terminal (enables colour). */
+    readonly isTTY?: boolean;
+}
+/** Construction options for {@link createConsoleSink}. */
+export interface ConsoleSinkOptions {
+    /** Where lines go; defaults to `process.stdout`. */
+    readonly writer?: LineWriter;
+    /** Force colour on/off; defaults to the writer's TTY state. */
+    readonly color?: boolean;
+    /** Sink id; defaults to `"console"`. */
+    readonly id?: string;
+}
+/**
+ * Build a {@link Sink} that prints each signal as one line.
+ *
+ * @param options see {@link ConsoleSinkOptions}
+ * @returns a console {@link Sink}
+ */
+export declare function createConsoleSink(options?: ConsoleSinkOptions): Sink;

package/dist/types/insight/sinks/file.d.ts

@@ -0,0 +1,37 @@
+/**
+ * File sink — drains signals to an append-only NDJSON trace file.
+ *
+ * Each signal becomes one {@link TraceRecord} line via {@link encodeRecord}; the
+ * file is opened for append (created if absent) and every record is flushed to
+ * the OS write buffer as it arrives, so a crash mid-trail still leaves a readable
+ * prefix that {@link replay} can parse. The handle is closed when the stream is
+ * exhausted.
+ *
+ * The file is the durable counterpart to the ephemeral stream sink: what the
+ * file sink writes, the replay reader reads back, with the record format pinned
+ * in `serialize.ts` so the two never disagree.
+ */
+import { Sink } from "../contract";
+/** Construction options for {@link createFileSink}. */
+export interface FileSinkOptions {
+    /** Filesystem path the NDJSON trace is appended to. */
+    readonly path: string;
+    /** Sink id; defaults to `"file"`. */
+    readonly id?: string;
+    /** Create the parent directory if missing; defaults to `true`. */
+    readonly mkdirp?: boolean;
+    /** Truncate the file on open instead of appending; defaults to `false`. */
+    readonly truncate?: boolean;
+}
+/**
+ * Build a {@link Sink} that appends one NDJSON record per signal to a file.
+ *
+ * The file is opened lazily on the first drained signal (so constructing a sink
+ * that is never used touches no disk), then closed when the stream ends or
+ * throws. `mkdirp` ensures the parent directory exists; `truncate` starts a
+ * fresh file rather than appending.
+ *
+ * @param options see {@link FileSinkOptions}
+ * @returns a file {@link Sink}
+ */
+export declare function createFileSink(options: FileSinkOptions): Sink;

package/dist/types/insight/sinks/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sinks barrel — the terminal consumers of a {@link Signal} stream.
+ *
+ * Three concrete {@link Sink} factories, each of which drains an independent
+ * {@link SignalStream} obtained from the recorder's channel:
+ *
+ *   - {@link createConsoleSink} — one human line per signal to a TTY / writer;
+ *   - {@link createFileSink} — append-only NDJSON to a path (durable);
+ *   - {@link createStreamSink} — NDJSON forwarded to an injected byte writer;
+ *   - {@link createCollectorSink} — an in-memory array (tests / inspection).
+ *
+ * All four are framework-agnostic and share the record format in `serialize.ts`.
+ */
+export { createConsoleSink, type ConsoleSinkOptions, type LineWriter, } from "./console";
+export { createFileSink, type FileSinkOptions, } from "./file";
+export { createStreamSink, createCollectorSink, type StreamSinkOptions, type SignalWriter, type CollectorSink, } from "./stream";

package/dist/types/insight/sinks/stream.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Stream sink — forwards signals to a network/byte stream, or collects them.
+ *
+ * Two shapes share this module because both are "drain into something live":
+ *
+ *   - {@link createStreamSink} writes each signal as an NDJSON line to an
+ *     injected byte/string writer (a socket, a child pipe, an SSE response),
+ *     using the same record format as the file sink;
+ *   - {@link createCollectorSink} appends every signal to an in-memory array, the
+ *     trivial test/inspection sink.
+ *
+ * Neither owns a transport: the byte writer is injected, so the same sink feeds a
+ * TCP socket, an HTTP chunked body, or an in-process pair without code change.
+ */
+import { Signal, Sink } from "../contract";
+/** The minimal push-style writer the stream sink forwards lines to. */
+export interface SignalWriter {
+    /** Append one already-encoded NDJSON line. May be async. */
+    write(line: string): unknown | Promise<unknown>;
+    /** Optional end-of-stream hook, called once the source is exhausted. */
+    end?(): unknown | Promise<unknown>;
+}
+/** Construction options for {@link createStreamSink}. */
+export interface StreamSinkOptions {
+    /** Where encoded lines are forwarded. */
+    readonly writer: SignalWriter;
+    /** Sink id; defaults to `"stream"`. */
+    readonly id?: string;
+    /** Call `writer.end()` when the source stream ends; defaults to `true`. */
+    readonly endOnFinish?: boolean;
+}
+/**
+ * Build a {@link Sink} that forwards each signal as an NDJSON line to a writer.
+ *
+ * @param options see {@link StreamSinkOptions}
+ * @returns a stream {@link Sink}
+ */
+export declare function createStreamSink(options: StreamSinkOptions): Sink;
+/** A collector {@link Sink} plus the live array it fills. */
+export interface CollectorSink extends Sink {
+    /** Every signal drained so far, in arrival order. */
+    readonly signals: readonly Signal[];
+}
+/**
+ * Build an in-memory {@link Sink} that accumulates every drained signal.
+ *
+ * The handiest sink for tests and one-shot inspection: drain a recorder's stream
+ * through it, then read {@link CollectorSink.signals}.
+ *
+ * @param id sink id; defaults to `"collector"`
+ * @returns a {@link CollectorSink}
+ */
+export declare function createCollectorSink(id?: string): CollectorSink;

package/dist/types/kit/clipboard-image.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Clipboard-image kit — pull a raster image off the OS clipboard and stage it
+ * on disk as a temp PNG, returning the path the composer can splice into a
+ * prompt.
+ *
+ * The terminal can only carry text, so an image on the clipboard cannot ride a
+ * normal paste. Instead this helper shells out to the platform's clipboard
+ * tool, captures the raw bytes, writes them to a temp file, and hands back the
+ * path — the agent then attaches the file by reference.
+ *
+ * Platform strategy (each is the conventional tool for its OS):
+ *   - **macOS** — `pngpaste -` dumps a clipboard image to stdout; when it is not
+ *     installed we fall back to an `osascript` one-liner that asks the clipboard
+ *     for its «class PNGf» data and base64-encodes it.
+ *   - **Linux/Wayland** — `wl-paste --type image/png` writes the image to stdout.
+ *   - **Linux/X11** — `xclip -selection clipboard -t image/png -o` does the same.
+ *
+ * Every spawn is best-effort: a missing tool, a non-zero exit, or an empty
+ * clipboard all collapse to `null` so the caller can warn rather than throw. The
+ * `child_process` / `fs` / `os` builtins are the only dependencies; nothing here
+ * touches the framework or a sibling subsystem.
+ */
+/** Options for {@link readClipboardImage} — injectable so tests stay hermetic. */
+export interface ClipboardImageOptions {
+    /** Override the host platform (defaults to `process.platform`). */
+    readonly platform?: NodeJS.Platform;
+    /** Override the environment consulted for the Wayland probe. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override the temp directory the captured PNG is written to. */
+    readonly dir?: string;
+}
+/**
+ * Pull an image off the OS clipboard, write it to a temp PNG, and return the
+ * file path — or `null` when no image is on the clipboard, the platform's tool
+ * is missing, or the write fails.
+ *
+ * The returned path is unique per call (millisecond + random suffix) so two
+ * pastes never collide. The caller owns the temp file thereafter.
+ */
+export declare function readClipboardImage(options?: ClipboardImageOptions): string | null;

package/dist/types/kit/external-editor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * External-editor kit — hand the composer buffer off to the user's `$EDITOR`,
+ * wait for them to close it, and read the edited text back.
+ *
+ * Composing a long prompt at a single-line terminal caret is painful; this
+ * helper stages the current buffer in a temp file, launches the configured
+ * editor against it with the terminal shared (so vi/nano/etc. take over the
+ * screen), blocks until the editor exits, then reads the file back as the new
+ * buffer.
+ *
+ * The editor is resolved from `$VISUAL`, then `$EDITOR`, then a `vi` fallback —
+ * the conventional precedence. The spawn is synchronous and inherits stdio so
+ * the editor owns the real terminal; on return the temp file is removed. Any
+ * failure (no editor that runs, a non-zero exit, an unreadable file) yields
+ * `null` and the caller keeps the original buffer.
+ *
+ * Only `child_process` / `fs` / `os` builtins are used; nothing here depends on
+ * the framework or a sibling subsystem.
+ */
+/** Options for {@link openInExternalEditor} — injectable so tests stay hermetic. */
+export interface ExternalEditorOptions {
+    /** Override the environment consulted for `$VISUAL` / `$EDITOR`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override the temp directory the scratch file is written to. */
+    readonly dir?: string;
+}
+/**
+ * Stage `buffer` in a temp file, open it in the user's editor sharing this
+ * terminal, block until the editor exits, and return the edited text — or
+ * `null` when the editor could not run or exited non-zero.
+ *
+ * A single trailing newline (most editors add one on save) is stripped so the
+ * round-trip does not silently grow the buffer. The temp file is always removed.
+ */
+export declare function openInExternalEditor(buffer: string, options?: ExternalEditorOptions): string | null;

package/dist/types/kit/image.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Image kit — magic-byte sniffing for the two raster formats the agent ships
+ * support for, plus a tiny asset-naming helper.
+ *
+ * This is a leaf utility: framework-agnostic, dependency-free (Node builtins
+ * only), and pure apart from the byte reads it is handed. Two unrelated jobs
+ * live here because both are small and both are about turning opaque bytes /
+ * platform tuples into a stable name:
+ *
+ *   - {@link sniffImageFormat} / {@link detectImageMediaType} classify a byte
+ *     buffer as PNG or JPEG by inspecting its leading signature bytes. The
+ *     signatures are an interface-dictated constant — they are fixed by the PNG
+ *     and JFIF/EXIF container specifications, not a choice we make.
+ *   - {@link resolveAssetName} renders a release-asset file name from a small
+ *     template by substituting platform / architecture / version tokens, so a
+ *     provisioner can locate the right download for the host without a per-tool
+ *     switch.
+ *
+ * Nothing here performs I/O: callers read the bytes (a file head, a clipboard
+ * blob, a fetched body) and pass them in. That keeps the module trivially
+ * testable and usable from any host.
+ */
+/**
+ * The raster image formats this kit can recognise from their leading bytes.
+ *
+ * Deliberately tiny — the agent only ever needs to tell PNG and JPEG apart for
+ * its attachment / clipboard paths; anything else is reported as `unknown`
+ * rather than guessed.
+ */
+export type ImageFormat = "png" | "jpeg";
+/**
+ * The IANA media types {@link ImageFormat} values map to.
+ *
+ * Used when a recognised format must be handed to the framework attachment
+ * model, which speaks media-type strings.
+ */
+export type ImageMediaType = "image/png" | "image/jpeg";
+/** The widest signature checked, so a caller knows the minimum head to read. */
+export declare const IMAGE_SNIFF_BYTES: number;
+/**
+ * A byte source this module can read a leading window from.
+ *
+ * Both a Node `Uint8Array` / `Buffer` and a plain number array satisfy this, so
+ * a caller never has to convert before sniffing.
+ */
+export type ByteSource = ArrayLike<number>;
+/**
+ * Classify a byte buffer as PNG or JPEG by its leading signature.
+ *
+ * Reads at most {@link IMAGE_SNIFF_BYTES} bytes from the front of `bytes` and
+ * returns the matching {@link ImageFormat}, or `null` when neither signature
+ * matches (an empty buffer, a truncated head, or any other format). Pure: it
+ * inspects the buffer and allocates nothing.
+ *
+ * @param bytes the leading bytes of a candidate image (a file head is enough)
+ */
+export declare function sniffImageFormat(bytes: ByteSource): ImageFormat | null;
+/** Map a recognised {@link ImageFormat} to its IANA media type. */
+export declare function mediaTypeForImageFormat(format: ImageFormat): ImageMediaType;
+/**
+ * Detect the media type of a byte buffer, or `null` when unrecognised.
+ *
+ * A convenience over {@link sniffImageFormat} for callers that speak media-type
+ * strings (e.g. the framework attachment model) rather than the internal
+ * {@link ImageFormat} tag.
+ *
+ * @param bytes the leading bytes of a candidate image
+ */
+export declare function detectImageMediaType(bytes: ByteSource): ImageMediaType | null;
+/** Whether `bytes` is a buffer this kit recognises as a supported image. */
+export declare function isSupportedImage(bytes: ByteSource): boolean;
+/**
+ * The platform / architecture / version facts a {@link resolveAssetName}
+ * template can interpolate.
+ *
+ * Field names mirror the substitution tokens; every member is optional so a
+ * template that only references some of them can be rendered from a partial
+ * context (a missing token resolves to an empty string).
+ */
+export interface AssetNameContext {
+    /** The host operating system, e.g. `"darwin"` / `"linux"` / `"win32"`. */
+    readonly platform?: string;
+    /** The host CPU architecture, e.g. `"arm64"` / `"x64"`. */
+    readonly arch?: string;
+    /** The release version, e.g. `"1.2.3"` (with or without a leading `v`). */
+    readonly version?: string;
+    /** The bare tool / binary name, e.g. `"fd"` / `"rg"`. */
+    readonly name?: string;
+}
+/**
+ * Render a release-asset file name from a `{token}` template.
+ *
+ * Replaces each `{platform}` / `{arch}` / `{version}` / `{name}` occurrence with
+ * the matching {@link AssetNameContext} field (an absent field becomes the empty
+ * string), leaving every other character verbatim. This lets a provisioner
+ * declare one template per tool — e.g. `"{name}-{version}-{arch}-{platform}.tar.gz"`
+ * — instead of branching on the host. Pure string work, no I/O.
+ *
+ * @param template the asset-name pattern with `{token}` placeholders
+ * @param context  the platform / arch / version / name facts to substitute
+ */
+export declare function resolveAssetName(template: string, context: AssetNameContext): string;

package/dist/types/kit/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Kit subsystem — public barrel.
+ *
+ * `kit/` holds the agent's framework-agnostic leaf helpers: small, pure, Node-
+ * builtin-only utilities with no dependency on the framework or on any sibling
+ * subsystem. It re-exports three groups:
+ *
+ *   - **tool-fetch** — the managed-binary provisioner stub (fd / rg): managed
+ *     path resolution, regex-driven release-asset selection, and a download-
+ *     request builder stamped with this kit's own {@link KIT_USER_AGENT}. The
+ *     network is injected, never imported.
+ *   - **image** — PNG / JPEG magic-byte sniffing (interface-dictated
+ *     signatures) and the `{token}` asset-name renderer.
+ *   - **shell** — POSIX shell-argument quoting and command assembly.
+ *
+ * Consumers import from `src/kit` rather than reaching into individual modules.
+ * The upstream filler libraries (generic array / string / date / json / etc.
+ * stdlib clones) are intentionally omitted: they had zero consumers, so they
+ * are not rebuilt here.
+ */
+export type { ToolDescriptor, ReleaseAsset, ReleaseInfo, ReleaseLookup, DownloadRequest, ProvisionPlan, } from "./tool-fetch";
+export { KIT_USER_AGENT, resolveManagedBinaryPath, pickReleaseAsset, buildDownloadRequest, planProvision, } from "./tool-fetch";
+export type { ImageFormat, ImageMediaType, ByteSource, AssetNameContext, } from "./image";
+export { IMAGE_SNIFF_BYTES, sniffImageFormat, mediaTypeForImageFormat, detectImageMediaType, isSupportedImage, resolveAssetName, } from "./image";
+export { quoteArg, needsQuoting, buildShellCommand, } from "./shell";
+export type { ClipboardImageOptions, } from "./clipboard-image";
+export { readClipboardImage, } from "./clipboard-image";
+export type { ExternalEditorOptions, } from "./external-editor";
+export { openInExternalEditor, } from "./external-editor";

package/dist/types/kit/kit.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Phase 11 kit — behavioral tests for the leaf helpers.
+ *
+ * Three independent surfaces, all pure and offline:
+ *
+ *   1. image magic-byte detection sniffs PNG and JPEG from their leading bytes
+ *      and rejects non-images;
+ *   2. the tool-fetch provisioner builds a download request stamped with the
+ *      fresh kit User-Agent and resolves a platform-correct managed binary path;
+ *   3. the shell helper quotes arguments that carry metacharacters and passes
+ *      safe ones through.
+ */
+export {};

package/dist/types/kit/shell.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shell kit — POSIX shell-argument quoting and command assembly.
+ *
+ * A leaf utility for safely turning argument strings into a single shell line.
+ * The agent shells out to provisioned binaries (fd / rg) and to user commands;
+ * any argument carrying a space, a glob, a quote, or a metacharacter must be
+ * quoted so the shell passes it through as one literal token rather than
+ * re-parsing it.
+ *
+ * The strategy is the conventional POSIX one: wrap the argument in single
+ * quotes and escape any embedded single quote by closing the quote, emitting an
+ * escaped quote, and reopening — `it's` becomes `'it'\''s'`. Inside single
+ * quotes the shell treats every other character literally, so this is robust
+ * against spaces, `$`, backticks, `*`, `;`, newlines, and the rest. Arguments
+ * that contain only safe characters are passed through unquoted to keep the
+ * rendered line readable.
+ *
+ * Pure and framework-agnostic: no process spawn, no environment, no I/O.
+ */
+/**
+ * Quote a single argument for a POSIX shell.
+ *
+ * Returns the argument unchanged when it is non-empty and made up entirely of
+ * shell-safe characters; otherwise wraps it in single quotes, escaping embedded
+ * single quotes with the `'\''` idiom. An empty string becomes `''` so it
+ * survives as a distinct (empty) argument rather than vanishing.
+ *
+ * @param arg the raw argument value to quote
+ */
+export declare function quoteArg(arg: string): string;
+/**
+ * Whether an argument would need quoting on a POSIX shell line.
+ *
+ * `true` when the value is empty or contains any character outside the
+ * shell-safe class. Useful for diagnostics or for deciding whether to render a
+ * command differently; {@link quoteArg} applies the same test internally.
+ *
+ * @param arg the raw argument value to test
+ */
+export declare function needsQuoting(arg: string): boolean;
+/**
+ * Assemble a list of arguments into a single space-separated shell line.
+ *
+ * Each element is run through {@link quoteArg}, so the result is safe to hand to
+ * a shell as one command string. The argument order is preserved; an empty list
+ * yields an empty string.
+ *
+ * @param args the command and its arguments, in invocation order
+ */
+export declare function buildShellCommand(args: readonly string[]): string;