@demicodes/shell 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,296 @@
+import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-BfjoIvF3.mjs";
+import { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile } from "./host-fs.mjs";
+import { _ as isCommandGroup, a as CommandIO, b as runRegisteredCommand, c as CommandOutputSpec, d as CommandRunResult, f as CommandSpec, g as ParsedCommandInput, h as CommandSubcommandSpec, i as CommandExecutionContext, l as CommandRegistry, m as CommandStorage, n as COMMAND_PROMPT_DEFAULTS, o as CommandInputSpec, p as CommandStdin, r as CommandAsset, s as CommandNode, t as AgentSessionCommandStorage, u as CommandRunContext, v as parseCommandInput, y as renderCommandPrompt } from "./storage-DJxxqyZA.mjs";
+import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
+import { CommandName } from "@demicodes/just-bash/commands";
+import { CommandRegistry as CommandRegistry$1, ExecResult } from "@demicodes/just-bash/types";
+
+//#region src/command-projection.d.ts
+/**
+ * A registered command leaf described as a structured operation: the second
+ * projection of a CommandSpec. The shell invocation (argv + heredoc) and this
+ * form share one implementation — `renderScript` produces a script that runs
+ * through the normal BashEnvironment path, so audit, command records, and
+ * `/@/commands` artifacts behave identically for both projections.
+ */
+interface RegisteredCommandOperation {
+  /** Path segments from root command to leaf, e.g. ['editor', 'create']. */
+  path: string[];
+  description: string;
+  /** JSON Schema for the operation input, derived from the leaf's zod spec. */
+  inputSchema: Record<string, unknown>;
+  /**
+   * Renders a shell script invoking this operation with the given input.
+   * The stdin field (if any) is delivered as a quoted heredoc, which — like
+   * any heredoc — normalizes the body to end with a newline.
+   */
+  renderScript(values: Record<string, unknown>): string;
+}
+declare function listRegisteredCommandOperations(commands: CommandRegistry | CommandSpec[]): RegisteredCommandOperation[];
+//#endregion
+//#region src/environment-state.d.ts
+interface ExecAccumulator {
+  stdout: string;
+  stderr: string;
+  audit: BashAuditEvent[];
+  commandMetadata: CommandMetadataRecord[];
+  assets: CommandAsset[];
+}
+interface ShellSession {
+  id: string;
+  commandScopeId: string;
+  state: InterpreterState;
+  fs: HostBackedFileSystem;
+  interpreter: Interpreter;
+  forkCommands: CommandRegistry$1;
+  accumulator: ExecAccumulator;
+  foreground?: ForegroundProcess;
+  activeCommandId?: string;
+  backgroundJobs: Map<number, BackgroundJob>;
+  nextBackgroundJobId: number;
+  pendingExec?: Promise<ExecResult | Error>;
+  foregroundWaiters: Set<(foreground: ForegroundProcess) => void>;
+  exited: boolean;
+  abortController?: AbortController;
+}
+interface BackgroundJob {
+  id: number;
+  command: string;
+  args: string[];
+  display: string;
+  cwd: string;
+  handle: HostSpawnHandle;
+  stdoutBuffer: string;
+  stderrBuffer: string;
+  stdoutPump: Promise<void>;
+  stderrPump: Promise<void>;
+  exitPromise: Promise<{
+    exitCode: number | null;
+    signal?: string;
+  }>;
+}
+interface ForegroundProcess {
+  commandId: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  handle: HostSpawnHandle;
+  startedAt: number;
+  lastOutputAt: number;
+  /** Everything the process wrote, including redirected output — this is what
+   * the interpreter observes as the command's stdout/stderr. */
+  rawStdoutBuffer: string;
+  rawStderrBuffer: string;
+  /** Output routed to the visible sinks only (redirections excluded) — this is
+   * what command records and model previews show. */
+  stdoutBuffer: string;
+  stderrBuffer: string;
+  /** Interleaved visible chunks with running byte offsets, for merged replay. */
+  outputChunks: ShellOutputRecordChunk[];
+  outputBytes: number;
+  audit: BashAuditEvent[];
+  stdoutPump: Promise<void>;
+  stderrPump: Promise<void>;
+  exitPromise: Promise<{
+    exitCode: number | null;
+    signal?: string;
+  }>;
+  outputSinks: Record<1 | 2, ForegroundSink>;
+  abortController: AbortController;
+}
+interface ForegroundSink {
+  kind: 'visible' | 'file' | 'null';
+  fd?: 1 | 2;
+  path?: string;
+  append?: boolean;
+  bytes: Uint8Array[];
+}
+//#endregion
+//#region src/environment.d.ts
+interface BashEnvironmentOptions {
+  host: Host;
+  commands?: CommandRegistry;
+  shellIdFactory?: () => string;
+  commandIdFactory?: () => string;
+  initialEnv?: Record<string, string>;
+  /**
+   * Per-exec env injection for agent-owned shells. Evaluated on every exec with
+   * the owning agent session id; returned vars are set and exported, so both
+   * registered commands (ctx.env) and spawned external processes observe them.
+   * Lets a product harness expose session-scoped context (identity, routing)
+   * that changes between execs, which static initialEnv cannot express.
+   */
+  execEnv?: (agentSessionId: string) => Record<string, string>;
+  maxOutputBytes?: number;
+}
+interface ShellExecInput {
+  script: string;
+  shellId?: string;
+  agentSessionId?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  signal?: AbortSignal;
+}
+interface ShellStatusInput {
+  commandId: string;
+  stdoutOffset?: number;
+  stderrOffset?: number;
+  outputOffset?: number;
+  maxOutputBytes?: number;
+}
+interface ShellWriteInput {
+  commandId: string;
+  stdin: string | Uint8Array;
+  maxOutputBytes?: number;
+  signal?: AbortSignal;
+}
+interface ShellAbortInput {
+  commandId: string;
+  maxOutputBytes?: number;
+}
+interface StreamArtifact {
+  path: string;
+  offset: number;
+  delta: string;
+  tail: string;
+  bytes: number;
+  truncated: boolean;
+}
+interface ShellOutputChunk {
+  stream: 'stdout' | 'stderr';
+  text: string;
+}
+interface ShellOutputRecordChunk extends ShellOutputChunk {
+  offset: number;
+  bytes: number;
+}
+interface ShellOutputArtifact {
+  path: string;
+  offset: number;
+  text: string;
+  tail: string;
+  chunks: ShellOutputChunk[];
+  bytes: number;
+  truncated: boolean;
+}
+type BashAuditEvent = {
+  kind: 'registered-command';
+  name: string;
+  args: string[];
+  exitCode: number;
+} | {
+  kind: 'portable-command';
+  name: string;
+  args: string[];
+  cwd: string;
+  exitCode: number;
+} | {
+  kind: 'system-command';
+  name: string;
+  args: string[];
+  cwd: string;
+  exitCode: number | null;
+};
+interface CommandMetadataRecord {
+  kind: 'registered-command';
+  name: string;
+  args: string[];
+  metadata: unknown;
+}
+type ShellCommandSnapshot = {
+  status: 'exited';
+  shellId: string;
+  commandId: string;
+  exitCode: number;
+  stdout: StreamArtifact;
+  stderr: StreamArtifact;
+  output: ShellOutputArtifact;
+  runningMs: number;
+  idleMs: number;
+  audit: BashAuditEvent[];
+  commandMetadata?: CommandMetadataRecord[];
+  assets?: CommandAsset[];
+} | {
+  status: 'running';
+  shellId: string;
+  commandId: string;
+  stdout: StreamArtifact;
+  stderr: StreamArtifact;
+  output: ShellOutputArtifact;
+  runningMs: number;
+  idleMs: number;
+} | {
+  status: 'aborted';
+  shellId: string;
+  commandId: string;
+  stdout: StreamArtifact;
+  stderr: StreamArtifact;
+  output: ShellOutputArtifact;
+  runningMs: number;
+  idleMs: number;
+};
+declare class BashEnvironment {
+  private readonly host;
+  private readonly commands;
+  private readonly shellIdFactory;
+  private readonly commandIdFactory;
+  private readonly initialEnv;
+  private readonly execEnv?;
+  private readonly defaultOutputLimitBytes;
+  private readonly shells;
+  private readonly defaultShellByAgentSessionId;
+  private readonly commandsById;
+  private readonly artifacts;
+  constructor(options: BashEnvironmentOptions);
+  getShell(shellId: string): ShellSession | null;
+  registerCommand(spec: CommandSpec): void;
+  registeredCommands(): CommandSpec[];
+  exec(input: ShellExecInput): Promise<ShellCommandSnapshot>;
+  status(input: ShellStatusInput): Promise<ShellCommandSnapshot>;
+  write(input: ShellWriteInput): Promise<ShellCommandSnapshot>;
+  abort(input: ShellAbortInput): Promise<ShellCommandSnapshot>;
+  releaseCommand(commandId: string): Promise<boolean>;
+  disposeShell(shellId: string): Promise<boolean>;
+  disposeAllShells(): Promise<void>;
+  private killShell;
+  private requireShell;
+  private requireCommand;
+  private requireForegroundCommand;
+  private defaultShell;
+  private availableDefaultShell;
+  private createShell;
+  private runScript;
+  private createCommandRecord;
+  private startBackgroundJob;
+  private listBackgroundJobs;
+  private waitForBackgroundJob;
+  private exportedEnv;
+  private raceForeground;
+  private waitForBoundary;
+  private hostSpawn;
+  private collectExited;
+  private finishExited;
+  private collectAborted;
+  private collectAbortedWithoutForeground;
+  private snapshotCommand;
+  private lookupVirtualArtifact;
+  private commandArtifactIds;
+  private commandArtifact;
+  private persistCommandArtifact;
+  private syncRunningRecord;
+}
+//#endregion
+//#region src/portable-commands.d.ts
+/**
+ * Fork portable commands BashEnvironment registers in every shell, so
+ * cat/ls/grep-class tools work without local coreutils on any Host backend.
+ */
+declare const DEMI_PORTABLE_COMMANDS: readonly CommandName[];
+/**
+ * Names registered commands must not shadow, derived from the actual portable
+ * command set plus interpreter builtins and pass-through system tools — not a
+ * hand-maintained parallel list.
+ */
+declare const RESERVED_COMMAND_NAMES: ReadonlySet<string>;
+//#endregion
+export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, COMMAND_PROMPT_DEFAULTS, CommandAsset, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandNode, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandSpec, CommandStdin, CommandStorage, CommandSubcommandSpec, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, ParsedCommandInput, RESERVED_COMMAND_NAMES, RegisteredCommandOperation, ShellAbortInput, ShellCommandSnapshot, ShellExecInput, ShellOutputArtifact, ShellOutputChunk, ShellOutputRecordChunk, ShellStatusInput, ShellWriteInput, StreamArtifact, VirtualFileSystemNode, VirtualFileSystemProvider, isCommandGroup, listRegisteredCommandOperations, parseCommandInput, renderCommandPrompt, runRegisteredCommand, virtualDirectory, virtualFile };