@demicodes/shell 0.2.1 → 0.3.1

package/dist/index.d.mts

@@ -137,7 +137,7 @@ interface ShellAbortInput {
   commandId: string;
   maxOutputBytes?: number;
 }
-interface StreamArtifact {
+interface ShellStreamView {
   path: string;
   offset: number;
   delta: string;
@@ -153,7 +153,7 @@ interface ShellOutputRecordChunk extends ShellOutputChunk {
   offset: number;
   bytes: number;
 }
-interface ShellOutputArtifact {
+interface ShellOutputView {
   path: string;
   offset: number;
   text: string;
@@ -194,14 +194,14 @@ interface BinaryStdout {
   /** Total byte count of the un-capped stream. */
   totalBytes: number;
 }
-type ShellCommandSnapshot = {
+type ShellCommandStatus = {
   status: 'exited';
   shellId: string;
   commandId: string;
   exitCode: number;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
   audit: BashAuditEvent[];
@@ -212,18 +212,18 @@ type ShellCommandSnapshot = {
   status: 'running';
   shellId: string;
   commandId: string;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
 } | {
   status: 'aborted';
   shellId: string;
   commandId: string;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
 };
@@ -245,10 +245,10 @@ declare class BashEnvironment {
   getShell(shellId: string): ShellSession | null;
   registerCommand(command: Command): void;
   registeredCommands(): Command[];
-  exec(input: ShellExecInput): Promise<ShellCommandSnapshot>;
-  status(input: ShellStatusInput): Promise<ShellCommandSnapshot>;
-  write(input: ShellWriteInput): Promise<ShellCommandSnapshot>;
-  abort(input: ShellAbortInput): Promise<ShellCommandSnapshot>;
+  exec(input: ShellExecInput): Promise<ShellCommandStatus>;
+  status(input: ShellStatusInput): Promise<ShellCommandStatus>;
+  write(input: ShellWriteInput): Promise<ShellCommandStatus>;
+  abort(input: ShellAbortInput): Promise<ShellCommandStatus>;
   releaseCommand(commandId: string): Promise<boolean>;
   disposeShell(shellId: string): Promise<boolean>;
   disposeAllShells(): Promise<void>;
@@ -272,7 +272,7 @@ declare class BashEnvironment {
   private finishExited;
   private collectAborted;
   private collectAbortedWithoutForeground;
-  private snapshotCommand;
+  private commandStatus;
   private lookupVirtualArtifact;
   private commandArtifactIds;
   private commandArtifact;
@@ -311,4 +311,4 @@ declare function shellQuote(value: string): string;
 /** Picks a heredoc delimiter that does not collide with any line already in `body`. */
 declare function heredocDelimiter(body: string): string;
 //#endregion
-export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandSnapshot, ShellExecInput, ShellOutputArtifact, ShellOutputChunk, ShellOutputRecordChunk, ShellStatusInput, ShellWriteInput, StreamArtifact, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };
+export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };

package/dist/index.mjs

@@ -847,7 +847,7 @@ var BashEnvironment = class {
 	}
 	async status(input) {
 		const record = this.requireCommand(input.commandId);
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async write(input) {
 		const record = this.requireCommand(input.commandId);
@@ -857,11 +857,11 @@ var BashEnvironment = class {
 		const data = typeof input.stdin === "string" ? encodeUtf8(input.stdin) : input.stdin;
 		if (data.byteLength === 0) throw new Error("shell_write field \"stdin\" must not be empty; use shell_status to poll");
 		await foreground.handle.writeStdin(data);
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async abort(input) {
 		const record = this.requireCommand(input.commandId);
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		const session = this.requireShell(record.shellId);
 		const foreground = this.requireForegroundCommand(session, record.id);
 		foreground.abortController.abort();
@@ -1078,7 +1078,7 @@ var BashEnvironment = class {
 				record.exitCode = 2;
 				session.state.lastExitCode = 2;
 				session.activeCommandId = void 0;
-				return this.snapshotCommand(record, input);
+				return this.commandStatus(record, input);
 			}
 			throw error;
 		}
@@ -1243,7 +1243,7 @@ var BashEnvironment = class {
 				foreground = outcome.foreground;
 				continue;
 			}
-			if (outcome.kind === "timeout") return this.snapshotCommand(record, input);
+			if (outcome.kind === "timeout") return this.commandStatus(record, input);
 			if (outcome.kind === "aborted") {
 				const activeForeground = foreground ?? session.foreground;
 				if (!activeForeground) return this.collectAbortedWithoutForeground(session, record, input);
@@ -1389,7 +1389,7 @@ var BashEnvironment = class {
 		};
 	}
 	collectExited(session, record, resultOrError, foreground, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		if (resultOrError instanceof Error) {
 			if (resultOrError instanceof ExitError) {
 				session.exited = true;
@@ -1476,10 +1476,10 @@ var BashEnvironment = class {
 		record.commandMetadata = [...session.accumulator.commandMetadata];
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async collectAborted(session, record, foreground, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		foreground.abortController.abort();
 		foreground.handle.kill("SIGTERM").catch(() => {});
 		await flushForegroundSinks(session, foreground);
@@ -1491,10 +1491,10 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	collectAbortedWithoutForeground(session, record, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		session.abortController?.abort();
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
@@ -1506,9 +1506,9 @@ var BashEnvironment = class {
 		}
 		record.lastOutputAt = Date.now();
 		record.status = "aborted";
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
-	snapshotCommand(record, input = {}) {
+	commandStatus(record, input = {}) {
 		const foreground = this.shells.get(record.shellId)?.foreground;
 		if (record.status === "running" && foreground?.commandId === record.id) {
 			record.stdout = foreground.stdoutBuffer;
@@ -1517,9 +1517,9 @@ var BashEnvironment = class {
 			record.lastOutputAt = foreground.lastOutputAt;
 		}
 		const maxOutputBytes = input.maxOutputBytes ?? this.defaultOutputLimitBytes;
-		const stdout = streamArtifact(record, "stdout", input.stdoutOffset, maxOutputBytes);
-		const stderr = streamArtifact(record, "stderr", input.stderrOffset, maxOutputBytes);
-		const output = streamOutputArtifact(record, input.outputOffset, maxOutputBytes);
+		const stdout = streamView(record, "stdout", input.stdoutOffset, maxOutputBytes);
+		const stderr = streamView(record, "stderr", input.stderrOffset, maxOutputBytes);
+		const output = mergedOutputView(record, input.outputOffset, maxOutputBytes);
 		const base = {
 			shellId: record.shellId,
 			commandId: record.id,
@@ -1590,16 +1590,16 @@ var BashEnvironment = class {
 		const record = this.commandsById.get(commandId);
 		if (record?.commandScopeId === scopeId) {
 			this.syncRunningRecord(record);
-			return persistedArtifactFromRecord(record);
+			return commandArtifactFromRecord(record);
 		}
 		const value = await this.artifacts.storageFor(scopeId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
-		return isPersistedShellCommandArtifact(value) ? value : null;
+		return isCommandArtifact(value) ? value : null;
 	}
 	persistCommandArtifact(record) {
 		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}:${record.binaryStdout?.totalBytes ?? ""}`;
 		if (record.persistedFingerprint === fingerprint) return;
 		record.persistedFingerprint = fingerprint;
-		this.artifacts.persist(record.commandScopeId, record.id, persistedArtifactFromRecord(record));
+		this.artifacts.persist(record.commandScopeId, record.id, commandArtifactFromRecord(record));
 	}
 	syncRunningRecord(record) {
 		const foreground = this.shells.get(record.shellId)?.foreground;
@@ -1636,7 +1636,7 @@ function normalizeTimeoutMs(value) {
 	if (!Number.isFinite(value) || value < 1 || value > 6e5) throw new Error(`timeoutMs must be between 1 and ${MAX_TIMEOUT_MS}`);
 	return Math.floor(value);
 }
-function streamArtifact(record, stream, explicitOffset, maxOutputBytes) {
+function streamView(record, stream, explicitOffset, maxOutputBytes) {
 	const text = stream === "stdout" ? record.stdout : record.stderr;
 	const totalBytes = utf8Bytes(text);
 	const boundedOffset = clampOffset(explicitOffset ?? (stream === "stdout" ? record.stdoutOffset : record.stderrOffset), totalBytes);
@@ -1656,7 +1656,7 @@ function streamArtifact(record, stream, explicitOffset, maxOutputBytes) {
 		truncated
 	};
 }
-function streamOutputArtifact(record, explicitOffset, maxOutputBytes) {
+function mergedOutputView(record, explicitOffset, maxOutputBytes) {
 	const totalBytes = record.outputChunks.reduce((total, chunk) => total + chunk.bytes, 0);
 	const offset = clampOffset(explicitOffset ?? record.outputOffset, totalBytes);
 	const byteLimit = Math.max(0, Math.floor(maxOutputBytes));
@@ -1710,7 +1710,7 @@ function ensureRecordOutputCoverage(record) {
 	appendRecordOutput(record, "stdout", record.stdout);
 	appendRecordOutput(record, "stderr", record.stderr);
 }
-function persistedArtifactFromRecord(record) {
+function commandArtifactFromRecord(record) {
 	return {
 		status: record.status,
 		shellId: record.shellId,
@@ -1754,7 +1754,7 @@ function commandArtifactMeta(artifact) {
 		} } : {}
 	};
 }
-function isPersistedShellCommandArtifact(value) {
+function isCommandArtifact(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
 	const record = value;
 	return (record.status === "running" || record.status === "exited" || record.status === "aborted") && typeof record.shellId === "string" && typeof record.commandId === "string" && typeof record.startedAt === "number" && typeof record.lastOutputAt === "number" && (typeof record.exitCode === "number" || record.exitCode === null) && typeof record.stdout === "string" && typeof record.stderr === "string";

package/dist/storage.mjs

@@ -5,7 +5,7 @@ var AgentSessionCommandStorage = class {
 	constructor(store, agentSessionId) {
 		this.store = store;
 		validateAgentSessionId(agentSessionId);
-		this.agentSessionPrefix = `${agentSessionId}/`;
+		this.agentSessionPrefix = `agent-sessions/${agentSessionId}/`;
 	}
 	readJson(key) {
 		return this.store.readJson(this.key(key));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/shell",
   "description": "Sandboxable bash engine and Host contract for Demi.",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@demicodes/utils": "^0.2.1",
+    "@demicodes/utils": "^0.3.1",
     "@demicodes/just-bash": "^3.0.1-demi.5",
     "zod": "^4.0.0"
   },