@downcity/agent 1.1.1

package/src/types/session/SessionRun.ts

@@ -0,0 +1,116 @@
+/**
+ * Session 运行结果与输入类型。
+ *
+ * 关键点（中文）
+ * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
+ * - `SessionExecuteInput` 表示 LocalSessionCore 通过 Composer 装配后的中间运行态。
+ * - 输出仅暴露 assistantMessage（UIMessage）。
+ */
+
+import type { Tool } from "ai";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
+
+/**
+ * Assistant step 可见性。
+ *
+ * 说明（中文）
+ * - `visible`：ACP `agent_message_chunk` 或普通模型文本，属于用户可见回复。
+ * - `internal`：ACP `agent_thought_chunk` 等内部过程，应作为 reasoning 保留，但不能混入普通 text。
+ */
+export type SessionAssistantStepVisibility = "visible" | "internal";
+
+/**
+ * Assistant step 回调入参。
+ */
+export interface SessionAssistantStepCallbackInput {
+  /**
+   * 当前 step 生成的文本。
+   */
+  text: string;
+
+  /**
+   * 当前 step 序号（从 1 开始）。
+   */
+  stepIndex: number;
+
+  /**
+   * 当前 step 的可见性。
+   *
+   * 关键点（中文）
+   * - 未声明时按 `visible` 处理，兼容本地模型与旧调用方。
+   * - `internal` 会落盘为 reasoning part，外部渠道不应当成普通回复文本发送。
+   */
+  visibility?: SessionAssistantStepVisibility;
+
+  /**
+   * 当前 step 的原始结果对象。
+   *
+   * 关键点（中文）
+   * - 由运行时直接透传，供持久化层提取 tool call / tool result 顺序事件。
+   * - 外部调用方不应依赖其稳定结构，只能做 best-effort 读取。
+   */
+  stepResult?: unknown;
+}
+
+/**
+ * Assistant step 完成回调。
+ */
+export type SessionAssistantStepCallback = (
+  input: SessionAssistantStepCallbackInput,
+) => Promise<void>;
+
+/**
+ * Session 执行结果。
+ */
+export interface SessionRunResult {
+  /**
+   * 本轮执行是否成功。
+   */
+  success: boolean;
+
+  /**
+   * 失败时的错误信息（成功时为空）。
+   */
+  error?: string;
+
+  /**
+   * 最终 assistant 消息。
+   */
+  assistantMessage: SessionMessageV1;
+}
+
+/**
+ * Session 运行入口输入。
+ */
+export interface SessionRunInput {
+  /**
+   * 本轮用户输入查询文本。
+   */
+  query: string;
+}
+
+/**
+ * LocalSessionCore 通过 Composer 装配后的中间运行态。
+ */
+export interface SessionExecuteInput {
+  /**
+   * 当前轮用户查询文本。
+   */
+  query: string;
+
+  /**
+   * 当前轮 system messages。
+   */
+  system: SessionSystemMessage[];
+
+  /**
+   * 当前轮 context 语义消息历史。
+   */
+  messages: SessionMessageV1[];
+
+  /**
+   * 当前轮可用工具集合。
+   */
+  tools: Record<string, Tool>;
+}

package/src/types/shell/ShellRuntime.ts

@@ -0,0 +1,94 @@
+/**
+ * ShellRuntime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这些类型描述 shell service 的实例级运行态。
+ * - 状态所有权归属于 ShellService 实例，而不是模块级单例。
+ * - 统一归档到 `src/types/shell/`，避免继续停留在 `shared/types/`。
+ */
+
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ShellSessionSnapshot } from "@services/shell/types/ShellService.js";
+
+/**
+ * 单个 shell wait 调用挂起时注册的 waiter。
+ */
+export type ShellSessionWaiter = {
+  /**
+   * 当前等待完成后的唤醒回调。
+   */
+  resolve: () => void;
+  /**
+   * 当前 waiter 对应的超时定时器。
+   */
+  timer: NodeJS.Timeout;
+};
+
+/**
+ * 单个 shell session 的内存运行态。
+ */
+export type ShellSessionRuntimeState = {
+  /**
+   * 当前 shell session 的对外快照。
+   */
+  snapshot: ShellSessionSnapshot;
+  /**
+   * 当前 shell session 对应的子进程句柄。
+   */
+  child: ChildProcessWithoutNullStreams;
+  /**
+   * 当前已缓存的标准输出与标准错误文本。
+   */
+  outputText: string;
+  /**
+   * 当前输出持久化文件路径。
+   */
+  outputFilePath: string;
+  /**
+   * 当前快照持久化文件路径。
+   */
+  snapshotFilePath: string;
+  /**
+   * 串行化文件写入链，避免并发 append 乱序。
+   */
+  writeChain: Promise<void>;
+  /**
+   * 终态后的延迟清理定时器。
+   */
+  cleanupTimer: NodeJS.Timeout | null;
+  /**
+   * 当前挂起等待该 session 状态变化的 waiter 集合。
+   */
+  waiters: Set<ShellSessionWaiter>;
+  /**
+   * 当前 shell 进入终态后的完成 promise。
+   *
+   * 关键点（中文）
+   * - 供 `shell.exec` 这类 one-shot 路径直接等待进程结束。
+   * - 这样可以减少对版本轮询的依赖，降低瞬时命令的竞态超时。
+   */
+  completionPromise: Promise<void>;
+  /**
+   * 当前 shell 进入终态时触发的完成回调。
+   */
+  resolveCompletion: () => void;
+};
+
+/**
+ * ShellService 实例级状态。
+ */
+export type ShellServiceState = {
+  /**
+   * 当前实例持有的全部 in-memory shell session。
+   */
+  sessions: Map<string, ShellSessionRuntimeState>;
+  /**
+   * 当前实例最近一次绑定的 execution runtime。
+   *
+   * 关键点（中文）
+   * - 仅用于 shell 自动通知 chat 的回调路径。
+   * - 这是实例字段，不再是模块级全局变量。
+   */
+  boundRuntime: AgentContext | null;
+};

package/src/types/task/TaskRunner.ts

@@ -0,0 +1,199 @@
+/**
+ * TaskRunner 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task runner 在拆分后跨模块共享的内部类型。
+ * - 这些类型服务于 task 运行链路，统一归档到 `src/types/task/`。
+ */
+
+import type { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import type { SessionExecutor } from "@/types/session/SessionExecutor.js";
+import type {
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunProgressPhaseV1,
+  ShipTaskRunProgressStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+} from "@services/task/types/Task.js";
+
+/**
+ * run-progress.json 的当前快照状态。
+ */
+export type RunProgressSnapshot = {
+  /**
+   * 当前进度状态。
+   */
+  status: ShipTaskRunProgressStatusV1;
+  /**
+   * 当前进度阶段。
+   */
+  phase: ShipTaskRunProgressPhaseV1;
+  /**
+   * 当前阶段对人类可读的说明文本。
+   */
+  message: string;
+  /**
+   * 当前对话轮次。
+   */
+  round?: number;
+  /**
+   * 最大允许轮次。
+   */
+  maxRounds?: number;
+  /**
+   * 运行结束时间（毫秒时间戳）。
+   */
+  endedAt?: number;
+  /**
+   * 任务总体运行状态。
+   */
+  runStatus?: ShipTaskRunStatusV1;
+  /**
+   * 执行阶段状态。
+   */
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  /**
+   * 结果校验状态。
+   */
+  resultStatus?: ShipTaskRunResultStatusV1;
+};
+
+/**
+ * 任务结果校验结果。
+ */
+export type TaskResultValidation = {
+  /**
+   * 结果校验后的状态。
+   */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 校验失败时的错误列表。
+   */
+  errors: string[];
+};
+
+/**
+ * 模拟用户的判定结果。
+ */
+export type UserSimulatorDecision = {
+  /**
+   * 模拟用户是否认为当前结果已满足要求。
+   */
+  satisfied: boolean;
+  /**
+   * 模拟用户给出的回复文本。
+   */
+  reply: string;
+  /**
+   * 判定理由。
+   */
+  reason: string;
+  /**
+   * 可选评分，范围通常为 0-10。
+   */
+  score?: number;
+  /**
+   * 原始输出文本快照。
+   */
+  raw: string;
+};
+
+/**
+ * 单轮对话的落盘记录。
+ */
+export type DialogueRoundRecord = {
+  /**
+   * 当前任务是否启用了 review 多轮模式。
+   */
+  reviewEnabled: boolean;
+  /**
+   * 当前轮次编号。
+   */
+  round: number;
+  /**
+   * 本轮执行器收到的 query。
+   */
+  executorQuery: string;
+  /**
+   * 本轮执行器输出文本。
+   */
+  executorOutput: string;
+  /**
+   * 本轮执行器是否通过 `chat_send` 等方式实际送达文本。
+   */
+  executorDelivered: boolean;
+  /**
+   * 执行器 assistantMessage 的调试快照。
+   */
+  executorAssistantMessageSnapshot?: string;
+  /**
+   * 本轮结果校验状态。
+   */
+  validationResultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 本轮规则校验失败项。
+   */
+  ruleErrors: string[];
+  /**
+   * 模拟用户收到的 query。
+   */
+  userSimulatorQuery?: string;
+  /**
+   * 模拟用户输出文本。
+   */
+  userSimulatorOutput?: string;
+  /**
+   * 模拟用户 assistantMessage 的调试快照。
+   */
+  userSimulatorAssistantMessageSnapshot?: string;
+  /**
+   * 模拟用户最终判定结果。
+   */
+  userSimulator: UserSimulatorDecision;
+  /**
+   * 传递给下一轮执行器的反馈文本。
+   */
+  feedbackForNextRound?: string;
+};
+
+/**
+ * script 类型任务的执行结果。
+ */
+export type ScriptExecutionResult = {
+  /**
+   * script 标准输出与标准错误合并后的文本。
+   */
+  outputText: string;
+};
+
+/**
+ * task 运行专用的 session runtime 端口。
+ *
+ * 关键点（中文）
+ * - task runner 不直接依赖具体 `LocalSessionExecutor` 实现。
+ * - 这里暴露的是 task 场景最小可用端口：执行器 + history Composer。
+ */
+export type TaskSessionRuntimePort = {
+  /**
+   * 获取指定 sessionId 对应的 Session 执行端口。
+   */
+  getExecutor(sessionId: string): SessionExecutor;
+  /**
+   * 获取指定 sessionId 对应的 JsonlSessionHistoryComposer。
+   */
+  getHistoryComposer(sessionId: string): JsonlSessionHistoryComposer;
+};
+
+/**
+ * 从 assistant 输出中提取的文本结果。
+ */
+export type ChatSendOutputPick = {
+  /**
+   * 最终提取到的文本内容。
+   */
+  text: string;
+  /**
+   * 该文本是否已经通过 chat_send 等方式送达。
+   */
+  delivered: boolean;
+};

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./bin",
+    "rootDir": "src",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@session/*": ["./src/session/*"],
+      "@services/*": ["./src/services/*"],
+      "@shared/*": ["./src/shared/*"]
+    },
+    "strict": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "bin"]
+}