@downcity/shell 0.1.4

package/bin/sandbox/types/SandboxRuntime.d.ts

@@ -0,0 +1,370 @@
+/**
+ * SandboxRuntime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
+ * - 当前只围绕 agent 级 sandbox spawn 设计，不引入复杂 provider / policy / binding 对象。
+ * - 目标是让 shell、task script 等本地执行入口都能复用同一个 agent sandbox 边界。
+ */
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { SandboxConfig } from "../../sandbox/types/Sandbox.js";
+import type { SandboxNetworkMode } from "../../sandbox/types/Sandbox.js";
+/**
+ * 当前内置支持的 sandbox backend。
+ */
+export type SandboxBackend = "macos-seatbelt" | "linux-bubblewrap" | "unrestricted-host";
+/**
+ * sandbox 会话状态。
+ *
+ * 说明（中文）
+ * - `shell_exec` 这类 one-shot 命令通常会很快走到终态。
+ * - `shell_start` 则会维持一个状态化 sandbox session。
+ */
+export type SandboxSessionStatus = "starting" | "running" | "completed" | "failed" | "killed" | "expired";
+/**
+ * 单个 sandbox session 快照。
+ */
+export interface SandboxSessionSnapshot {
+    /**
+     * sandbox 唯一标识。
+     */
+    sandboxId: string;
+    /**
+     * 原始命令文本。
+     */
+    cmd: string;
+    /**
+     * 当前 sandbox 实际工作目录。
+     */
+    cwd: string;
+    /**
+     * 当前 sandbox 状态。
+     */
+    status: SandboxSessionStatus;
+    /**
+     * 进程 pid。
+     *
+     * 说明（中文）
+     * - 某些 backend 可能拿不到宿主 pid，这时为空。
+     */
+    pid?: number;
+    /**
+     * 创建时间戳（毫秒）。
+     */
+    startedAt: number;
+    /**
+     * 最近更新时间戳（毫秒）。
+     */
+    updatedAt: number;
+    /**
+     * 结束时间戳（毫秒）。
+     */
+    endedAt?: number;
+    /**
+     * 退出码。
+     */
+    exitCode?: number;
+    /**
+     * 最近输出预览。
+     */
+    lastOutputPreview?: string;
+    /**
+     * 累计输出字符数。
+     */
+    outputChars: number;
+    /**
+     * 版本号。
+     *
+     * 说明（中文）
+     * - 任意状态或输出变化都递增，供 wait/read 增量判断使用。
+     */
+    version: number;
+}
+/**
+ * sandbox 输出块。
+ */
+export interface SandboxOutputChunk {
+    /**
+     * 当前输出块所属 sandbox 标识。
+     */
+    sandboxId: string;
+    /**
+     * 输出文本。
+     */
+    output: string;
+    /**
+     * 起始游标。
+     */
+    startCursor: number;
+    /**
+     * 结束游标。
+     */
+    endCursor: number;
+    /**
+     * 原始输出字符数。
+     */
+    originalChars: number;
+    /**
+     * 是否还有更多输出未读。
+     */
+    hasMoreOutput: boolean;
+}
+/**
+ * one-shot 命令执行请求。
+ */
+export interface SandboxExecRequest {
+    /**
+     * 最终使用的 sandbox 配置。
+     */
+    config: SandboxConfig;
+    /**
+     * 要执行的命令文本。
+     */
+    cmd: string;
+    /**
+     * 可选工作目录。
+     */
+    cwd?: string;
+    /**
+     * 可选 shell 可执行文件。
+     */
+    shell?: string;
+    /**
+     * 是否以 login shell 语义执行。
+     */
+    login?: boolean;
+}
+/**
+ * 状态化 sandbox session 启动请求。
+ */
+export interface SandboxStartRequest extends SandboxExecRequest {
+}
+/**
+ * sandbox 会话读取请求。
+ */
+export interface SandboxReadRequest {
+    /**
+     * 目标 sandbox 标识。
+     */
+    sandboxId: string;
+    /**
+     * 从哪个游标开始增量读取。
+     */
+    fromCursor?: number;
+}
+/**
+ * sandbox 会话写入请求。
+ */
+export interface SandboxWriteRequest {
+    /**
+     * 目标 sandbox 标识。
+     */
+    sandboxId: string;
+    /**
+     * 要写入 stdin 的原始文本。
+     */
+    chars: string;
+}
+/**
+ * sandbox 会话等待请求。
+ */
+export interface SandboxWaitRequest {
+    /**
+     * 目标 sandbox 标识。
+     */
+    sandboxId: string;
+    /**
+     * 仅当版本号大于该值时才立即返回。
+     */
+    afterVersion?: number;
+    /**
+     * 最长等待毫秒数。
+     */
+    timeoutMs?: number;
+}
+/**
+ * sandbox 会话关闭请求。
+ */
+export interface SandboxCloseRequest {
+    /**
+     * 目标 sandbox 标识。
+     */
+    sandboxId: string;
+    /**
+     * 是否强制关闭。
+     */
+    force?: boolean;
+}
+/**
+ * `SandboxRunner` 最小接口。
+ *
+ * 说明（中文）
+ * - `exec` 用于 one-shot 命令。
+ * - `start/read/write/wait/close` 用于状态化 shell session。
+ */
+export interface SandboxRunner {
+    /**
+     * 执行一次 one-shot 命令并等待完成。
+     */
+    exec(request: SandboxExecRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+        chunk: SandboxOutputChunk;
+    }>;
+    /**
+     * 启动一个状态化 sandbox session。
+     */
+    start(request: SandboxStartRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+        chunk: SandboxOutputChunk;
+    }>;
+    /**
+     * 读取 sandbox 输出。
+     */
+    read(request: SandboxReadRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+        chunk: SandboxOutputChunk;
+    }>;
+    /**
+     * 向 sandbox stdin 写入内容。
+     */
+    write(request: SandboxWriteRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+    }>;
+    /**
+     * 等待 sandbox 状态变化。
+     */
+    wait(request: SandboxWaitRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+        chunk: SandboxOutputChunk;
+    }>;
+    /**
+     * 关闭 sandbox session。
+     */
+    close(request: SandboxCloseRequest): Promise<{
+        snapshot: SandboxSessionSnapshot;
+    }>;
+}
+/**
+ * 运行时归一化后的 sandbox 配置。
+ *
+ * 说明（中文）
+ * - 这里的路径都已经解析成绝对路径。
+ * - 当前版本强制要求 shell 命令走 sandbox，不再允许回退到宿主机普通子进程执行。
+ */
+export interface ResolvedSandboxConfig extends SandboxConfig {
+    /**
+     * 当前运行时选中的 backend。
+     */
+    backend: SandboxBackend;
+    /**
+     * 当前 Downcity sandbox 模式。
+     */
+    sandboxMode?: "safe" | "unrestricted";
+    /**
+     * 当前 agent 级 sandbox 的持久目录。
+     *
+     * 说明（中文）
+     * - 该目录不属于某个 shellId，而属于当前 agent 项目。
+     * - shell、task script 等所有 sandbox 子进程共享它作为 HOME/cache 根。
+     */
+    sandboxDir: string;
+    /**
+     * sandbox 子进程使用的 HOME。
+     */
+    homeDir: string;
+    /**
+     * sandbox 子进程使用的临时目录。
+     */
+    tmpDir: string;
+    /**
+     * sandbox 子进程使用的 XDG cache 目录。
+     */
+    cacheDir: string;
+}
+/**
+ * 单次 shell 启动时传给 sandbox backend 的归一化参数。
+ */
+export interface SandboxSpawnParams {
+    /**
+     * 当前执行记录标识。
+     *
+     * 说明（中文）
+     * - shell runtime 传入 shellId，task script 可以传入自己的 executionId。
+     * - 它只用于日志与诊断，不参与 sandbox HOME/cache/权限边界的计算。
+     */
+    executionId: string;
+    /**
+     * 当前执行记录目录。
+     */
+    executionDir: string;
+    /**
+     * 要执行的原始命令文本。
+     */
+    cmd: string;
+    /**
+     * 最终工作目录。
+     */
+    cwd: string;
+    /**
+     * shell 可执行文件路径。
+     */
+    shellPath: string;
+    /**
+     * 是否使用 login shell 语义。
+     */
+    login: boolean;
+    /**
+     * sandbox 生效前的基础环境变量。
+     */
+    baseEnv: NodeJS.ProcessEnv;
+    /**
+     * 当前请求最终使用的 sandbox 配置。
+     */
+    config: ResolvedSandboxConfig;
+}
+/**
+ * sandbox backend 返回的进程启动结果。
+ */
+export interface SandboxSpawnResult {
+    /**
+     * 已启动的子进程句柄。
+     */
+    child: ChildProcessWithoutNullStreams;
+    /**
+     * 当前子进程实际使用的工作目录。
+     */
+    cwd: string;
+    /**
+     * 当前进程是否实际运行在 sandbox 中。
+     */
+    sandboxed: boolean;
+    /**
+     * 当前 Downcity sandbox 模式。
+     */
+    sandboxMode?: "safe" | "unrestricted";
+    /**
+     * 当前使用的 backend 名称。
+     */
+    backend: SandboxBackend;
+    /**
+     * 当前实际采用的网络模式。
+     */
+    networkMode: SandboxNetworkMode;
+    /**
+     * 当前 agent 级 sandbox 的持久目录。
+     */
+    sandboxDir: string;
+    /**
+     * 当前子进程使用的 HOME。
+     */
+    homeDir: string;
+    /**
+     * 当前子进程使用的临时目录。
+     */
+    tmpDir: string;
+    /**
+     * 当前子进程使用的 XDG cache 目录。
+     */
+    cacheDir: string;
+}
+//# sourceMappingURL=SandboxRuntime.d.ts.map

package/bin/sandbox/types/SandboxRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxRuntime.d.ts","sourceRoot":"","sources":["../../../src/sandbox/types/SandboxRuntime.ts"],"names":[],"mappings":"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"}

package/bin/sandbox/types/SandboxRuntime.js

@@ -0,0 +1,10 @@
+/**
+ * SandboxRuntime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
+ * - 当前只围绕 agent 级 sandbox spawn 设计，不引入复杂 provider / policy / binding 对象。
+ * - 目标是让 shell、task script 等本地执行入口都能复用同一个 agent sandbox 边界。
+ */
+export {};
+//# sourceMappingURL=SandboxRuntime.js.map

package/bin/sandbox/types/SandboxRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxRuntime.js","sourceRoot":"","sources":["../../../src/sandbox/types/SandboxRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/session/Paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shell service 路径工具。
+ *
+ * 关键点（中文）
+ * - shell 运行产物统一落在 `.downcity/shell/<shellId>/`。
+ * - 目录结构简单稳定，便于调试与后续恢复。
+ */
+export declare function getShellRootDir(projectRoot: string): string;
+export declare function getShellDir(projectRoot: string, shellId: string): string;
+export declare function getShellSnapshotPath(projectRoot: string, shellId: string): string;
+export declare function getShellOutputPath(projectRoot: string, shellId: string): string;
+//# sourceMappingURL=Paths.d.ts.map

package/bin/session/Paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../src/session/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E"}

package/bin/session/Paths.js

@@ -0,0 +1,21 @@
+/**
+ * Shell service 路径工具。
+ *
+ * 关键点（中文）
+ * - shell 运行产物统一落在 `.downcity/shell/<shellId>/`。
+ * - 目录结构简单稳定，便于调试与后续恢复。
+ */
+import path from "node:path";
+export function getShellRootDir(projectRoot) {
+    return path.join(projectRoot, ".downcity", "shell");
+}
+export function getShellDir(projectRoot, shellId) {
+    return path.join(getShellRootDir(projectRoot), String(shellId || "").trim());
+}
+export function getShellSnapshotPath(projectRoot, shellId) {
+    return path.join(getShellDir(projectRoot, shellId), "snapshot.json");
+}
+export function getShellOutputPath(projectRoot, shellId) {
+    return path.join(getShellDir(projectRoot, shellId), "output.log");
+}
+//# sourceMappingURL=Paths.js.map

package/bin/session/Paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paths.js","sourceRoot":"","sources":["../../src/session/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,OAAe;IACrE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC;AACpE,CAAC"}

package/bin/session/ShellActionResponse.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shell action 返回结构辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理输出游标、token 近似裁剪与标准 action response。
+ * - 这里不读取文件、不修改 session，只基于传入文本构造返回对象。
+ */
+import type { ShellHostContext } from "../types/ShellHostContext.js";
+import type { ShellActionResponse, ShellOutputChunk, ShellSessionSnapshot } from "../types/ShellAction.js";
+/**
+ * 根据游标与 token 限制构造输出块。
+ */
+export declare function createOutputChunk(params: {
+    /**
+     * 当前 shell session 标识。
+     */
+    shellId: string;
+    /**
+     * 当前完整输出文本。
+     */
+    outputText: string;
+    /**
+     * 本次读取起始游标。
+     */
+    fromCursor?: number;
+    /**
+     * 当前 Agent 执行上下文。
+     */
+    context: ShellHostContext;
+    /**
+     * 输出 token 近似上限。
+     */
+    maxOutputTokens?: number;
+}): ShellOutputChunk;
+/**
+ * 构造 shell action 标准返回。
+ */
+export declare function buildActionResponse(params: {
+    /**
+     * 当前 shell 快照。
+     */
+    shell: ShellSessionSnapshot;
+    /**
+     * 可选输出块。
+     */
+    chunk?: ShellOutputChunk;
+    /**
+     * 可选人类可读提示。
+     */
+    note?: string;
+}): ShellActionResponse;
+//# sourceMappingURL=ShellActionResponse.d.ts.map

package/bin/session/ShellActionResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellActionResponse.d.ts","sourceRoot":"","sources":["../../src/session/ShellActionResponse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AA+ChC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,gBAAgB,CA0BnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C;;OAEG;IACH,KAAK,EAAE,oBAAoB,CAAC;IAC5B;;OAEG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,mBAAmB,CAMtB"}

package/bin/session/ShellActionResponse.js

@@ -0,0 +1,73 @@
+/**
+ * Shell action 返回结构辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理输出游标、token 近似裁剪与标准 action response。
+ * - 这里不读取文件、不修改 session，只基于传入文本构造返回对象。
+ */
+const DEFAULT_MAX_OUTPUT_CHARS = 12_000;
+const DEFAULT_MAX_OUTPUT_LINES = 200;
+const APPROX_CHARS_PER_TOKEN = 4;
+function resolveOutputLimits(params) {
+    const byTokens = typeof params.maxOutputTokens === "number" &&
+        Number.isFinite(params.maxOutputTokens) &&
+        params.maxOutputTokens > 0
+        ? Math.max(200, Math.floor(params.maxOutputTokens * APPROX_CHARS_PER_TOKEN))
+        : null;
+    return {
+        maxChars: byTokens == null
+            ? DEFAULT_MAX_OUTPUT_CHARS
+            : Math.min(DEFAULT_MAX_OUTPUT_CHARS, byTokens),
+        maxLines: DEFAULT_MAX_OUTPUT_LINES,
+    };
+}
+function splitOutputByLimits(text, maxChars, maxLines) {
+    const limitedByChars = text.slice(0, Math.min(text.length, maxChars));
+    let head = limitedByChars;
+    if (maxLines > 0) {
+        const lines = limitedByChars.split("\n");
+        if (lines.length > maxLines) {
+            head = lines.slice(0, maxLines).join("\n");
+        }
+    }
+    return {
+        head,
+        tail: text.slice(head.length),
+    };
+}
+/**
+ * 根据游标与 token 限制构造输出块。
+ */
+export function createOutputChunk(params) {
+    const fromCursor = typeof params.fromCursor === "number" && params.fromCursor >= 0
+        ? Math.floor(params.fromCursor)
+        : 0;
+    const available = params.outputText.slice(fromCursor);
+    const originalChars = available.length;
+    const originalLines = available ? available.split("\n").length : 0;
+    const limits = resolveOutputLimits({
+        context: params.context,
+        maxOutputTokens: params.maxOutputTokens,
+    });
+    const { head, tail } = splitOutputByLimits(available, limits.maxChars, limits.maxLines);
+    return {
+        shellId: params.shellId,
+        output: head,
+        startCursor: fromCursor,
+        endCursor: fromCursor + head.length,
+        originalChars,
+        originalLines,
+        hasMoreOutput: tail.length > 0,
+    };
+}
+/**
+ * 构造 shell action 标准返回。
+ */
+export function buildActionResponse(params) {
+    return {
+        shell: params.shell,
+        ...(params.chunk ? { chunk: params.chunk } : {}),
+        ...(params.note ? { note: params.note } : {}),
+    };
+}
+//# sourceMappingURL=ShellActionResponse.js.map

package/bin/session/ShellActionResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellActionResponse.js","sourceRoot":"","sources":["../../src/session/ShellActionResponse.ts"],"names":[],"mappings":"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"}

package/bin/session/ShellActionRuntime.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shell action 运行时公开入口。
+ *
+ * 关键点（中文）
+ * - 本文件只作为稳定导出门面，保持旧 import 路径不变。
+ * - 具体 action 编排已拆到 `session/actions/*`，避免单模块继续膨胀。
+ */
+export { createShellRuntimeState } from "./ShellActionRuntimeSupport.js";
+export { bindShellRuntime, closeAllShellSessions, } from "./actions/ShellLifecycleActions.js";
+export { startShellSession, } from "./actions/ShellStartActions.js";
+export { closeShellSession, getShellSessionStatus, readShellSession, waitShellSession, } from "./actions/ShellQueryActions.js";
+export { writeShellSession, } from "./actions/ShellWriteActions.js";
+export { execShellCommand, } from "./actions/ShellExecActions.js";
+export { approveShellApproval, denyShellApproval, listShellApprovals, } from "./actions/ShellApprovalActions.js";
+//# sourceMappingURL=ShellActionRuntime.d.ts.map

package/bin/session/ShellActionRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellActionRuntime.d.ts","sourceRoot":"","sources":["../../src/session/ShellActionRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC"}

package/bin/session/ShellActionRuntime.js

@@ -0,0 +1,15 @@
+/**
+ * Shell action 运行时公开入口。
+ *
+ * 关键点（中文）
+ * - 本文件只作为稳定导出门面，保持旧 import 路径不变。
+ * - 具体 action 编排已拆到 `session/actions/*`，避免单模块继续膨胀。
+ */
+export { createShellRuntimeState } from "./ShellActionRuntimeSupport.js";
+export { bindShellRuntime, closeAllShellSessions, } from "./actions/ShellLifecycleActions.js";
+export { startShellSession, } from "./actions/ShellStartActions.js";
+export { closeShellSession, getShellSessionStatus, readShellSession, waitShellSession, } from "./actions/ShellQueryActions.js";
+export { writeShellSession, } from "./actions/ShellWriteActions.js";
+export { execShellCommand, } from "./actions/ShellExecActions.js";
+export { approveShellApproval, denyShellApproval, listShellApprovals, } from "./actions/ShellApprovalActions.js";
+//# sourceMappingURL=ShellActionRuntime.js.map

package/bin/session/ShellActionRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellActionRuntime.js","sourceRoot":"","sources":["../../src/session/ShellActionRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC"}