lark-remote 0.5.8 → 0.5.9

package/dist/runner/dsh/goal-view.js

@@ -0,0 +1,106 @@
+/**
+ * DSH `goal` 域 → 卡片用的 {@link GoalView} 解析。
+ *
+ * 两个来源、同一个目标类型：
+ * 1. 投影值：`session/projections` 的 `values.goal` 与 `session/control` 的
+ *    `{key:'goal'}` 帧，宿主状态包一层 `current`（`{current:{goal,roundsStarted
+ *    ,createdAt,updatedAt},seenGoalIds,failure}`）；
+ * 2. 会话事件 `goal/change`：create/edit/pause/resume/complete/block 携带完整
+ *    snapshot + roundsStarted；clear 是墓碑，表示"现在没有 goal"。
+ *
+ * 解析失败返回 `undefined`，表示**读不懂**——它与"没有 goal"（`null`）必须区分：
+ * 把读不懂当成没有 goal，就会在 goal 还在自动续跑时收尾卡片。
+ */
+const PHASES = new Set(['active', 'paused', 'blocked', 'complete']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonNegativeInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function parseSnapshot(value, roundsStarted) {
+    if (!isRecord(value))
+        return undefined;
+    const phase = value.phase;
+    if (typeof phase !== 'string' || !PHASES.has(phase))
+        return undefined;
+    if (typeof value.objective !== 'string')
+        return undefined;
+    if (typeof value.id !== 'string' || value.id.length === 0)
+        return undefined;
+    const max = nonNegativeInt(value.maxGoalRounds);
+    if (max === undefined)
+        return undefined;
+    const reason = value.blockedReason;
+    const blockedReason = isRecord(reason) && typeof reason.code === 'string' && typeof reason.message === 'string'
+        ? { code: reason.code, message: reason.message }
+        : undefined;
+    return {
+        id: value.id,
+        objective: value.objective,
+        // 上面已按白名单校验，这里收窄回联合类型。
+        phase: phase,
+        roundsStarted: nonNegativeInt(roundsStarted) ?? 0,
+        maxGoalRounds: max,
+        ...(blockedReason ? { blockedReason } : {}),
+    };
+}
+/**
+ * 解析投影里的 goal 状态。
+ *
+ * @returns `GoalView` = 有 goal；`null` = 宿主明确没有 goal；`undefined` = 读不懂。
+ */
+export function goalFromProjection(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    // 宿主状态信封：{current:{goal,roundsStarted,...}, seenGoalIds, failure}
+    if ('current' in value) {
+        const current = value.current;
+        if (current === null)
+            return null;
+        if (!isRecord(current))
+            return undefined;
+        if (current.goal === undefined || current.goal === null)
+            return null;
+        return parseSnapshot(current.goal, current.roundsStarted);
+    }
+    // 兼容直接投递 GoalProjection 的形态：{goal, roundsStarted, ...}
+    if (value.goal === undefined || value.goal === null)
+        return null;
+    return parseSnapshot(value.goal, value.roundsStarted);
+}
+/**
+ * 解析 `goal/change` 事件 payload。
+ *
+ * @returns `GoalView` = 变更后的 goal；`null` = clear（现在没有 goal）；
+ *   `undefined` = 读不懂。
+ */
+export function goalFromChange(data) {
+    if (!isRecord(data))
+        return undefined;
+    if (data.operation === 'clear')
+        return null;
+    if (typeof data.operation !== 'string')
+        return undefined;
+    return parseSnapshot(data.goal, data.roundsStarted);
+}
+/** 便利构造：把解析结果包成 runner 事件。 */
+export function goalStateEvent(goal, known) {
+    return { type: 'goal_state', goal, known, timestamp: new Date().toISOString() };
+}
+/** 两次观测是否等价（用于抑制重复帧，不触发重渲染）。 */
+export function sameGoal(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined)
+        return false;
+    return (a.id === b.id &&
+        a.phase === b.phase &&
+        a.roundsStarted === b.roundsStarted &&
+        a.maxGoalRounds === b.maxGoalRounds &&
+        a.objective === b.objective &&
+        a.blockedReason?.code === b.blockedReason?.code);
+}
+//# sourceMappingURL=goal-view.js.map

package/dist/runner/dsh/runner.js

@@ -19,6 +19,7 @@
  */
 import { DshClient, DshError, newPromptRequestId } from './client.js';
 import { DshTranslator } from './translator.js';
+import { goalFromChange, goalFromProjection, goalStateEvent, sameGoal } from './goal-view.js';
 import { DshApprovalTracker } from './approval.js';
 import { mergeAsync } from './merge.js';
 import { getLogger } from '../../logger/index.js';
@@ -81,6 +82,11 @@ function buildQuestionAnswers(questions, response) {
 }
 /** Budget for one session/cancel attempt on stop. */
 const CANCEL_TIMEOUT_MS = 5_000;
+/**
+ * goal 探测的预算。goal 是"增强信息"：读不到就按没有（known:false）继续跑，
+ * 但绝不允许一次慢投影把整个 run 的启动/收尾拖住。
+ */
+const GOAL_PROBE_TIMEOUT_MS = 5_000;
 /** Total stop budget: withdraw + cancel + verify must not hold the lane forever. */
 const STOP_BUDGET_MS = 5_000;
 /** A prompt request that was still in flight can land after stop's abort. */
@@ -434,6 +440,18 @@ export class DshRunner {
                 cwd: opts.cwd,
                 model: this.configuredModel ?? 'DSH',
             };
+            // Goal seed：卡片从第一帧就知道这个会话有没有长期目标。放在 init 之后、
+            // prompt 之前——用户发消息时若是 queued，卡片会长时间停在「运行中」，
+            // 这期间"目标是什么、第几轮"是唯一能解释"为什么还不停"的信息。
+            const seedGoal = await this.client.goalState(sessionId, {
+                signal: abort.signal,
+                timeoutMs: GOAL_PROBE_TIMEOUT_MS,
+            });
+            const lastGoal = seedGoal.known ? seedGoal.goal : undefined;
+            // 只有确实存在 goal 才产事件：没有 goal 的会话保持事件序列不变（少一次
+            // 渲染，也不让"读不到"变成一张多出来的卡片事件）。
+            if (seedGoal.known && seedGoal.goal)
+                yield goalStateEvent(seedGoal.goal, true);
             try {
                 // Snapshot the pre-prompt high-water mark before mutating the session.
                 // DSH session/page returns the whole session, so starting from seq 0
@@ -476,7 +494,7 @@ export class DshRunner {
                     return;
                 }
                 try {
-                    for await (const ev of this.runTurn(sessionId, opts.cwd, prePromptSeq, promptRequestId, abort)) {
+                    for await (const ev of this.runTurn(sessionId, opts.cwd, prePromptSeq, promptRequestId, abort, { last: lastGoal })) {
                         yield ev;
                         if (ev.type === 'result') {
                             terminalEmitted = true;
@@ -550,7 +568,7 @@ export class DshRunner {
      * events; `$events` owns the answerable approval waterfall. The merged
      * stream keeps either transport from starving the other.
      */
-    async *runTurn(sessionId, cwd, prePromptSeq, promptRequestId, abort) {
+    async *runTurn(sessionId, cwd, prePromptSeq, promptRequestId, abort, goal) {
         const streamAbort = new AbortController();
         const signal = AbortSignal.any([abort.signal, streamAbort.signal]);
         const translator = new DshTranslator();
@@ -577,6 +595,16 @@ export class DshRunner {
                     // 扩展的，不能因为多了个 key 就报错）。
                     if (item.sessionId !== sessionId)
                         continue;
+                    // goal 是会话级长期目标，单独成事件：卡片要在 agent 创建目标的当下
+                    // 就显示它（否则用户只会在一小时后看到「完成」才发现有个 40 轮任务）。
+                    if (item.key === 'goal') {
+                        const parsed = goalFromProjection(item.value);
+                        if (parsed !== undefined && !sameGoal(parsed, goal.last)) {
+                            goal.last = parsed;
+                            yield goalStateEvent(parsed, true);
+                        }
+                        continue;
+                    }
                     // 只在消费字段真的变了时才产出事件：投影帧本身按 key 去重推送，
                     // 这里再挡掉"值没变"的重复帧。不需要时间节流——卡片更新本来就有
                     // 100ms 合批窗口，与正文 delta 共用同一条节流路径。
@@ -654,6 +682,16 @@ export class DshRunner {
                     continue;
                 }
                 const event = item.event;
+                if (event.type === 'goal/change') {
+                    // 权威变更（create/edit/pause/resume/complete/block/clear）：不等投影
+                    // 推送，直接按事件更新——agent 刚 create 的那一刻卡片就该显示目标。
+                    const parsed = goalFromChange(event.data);
+                    if (parsed !== undefined && !sameGoal(parsed, goal.last)) {
+                        goal.last = parsed;
+                        yield goalStateEvent(parsed, true);
+                    }
+                    continue;
+                }
                 if (event.type === 'tool/call') {
                     const data = event.data;
                     if (data.callId && data.name) {
@@ -686,6 +724,17 @@ export class DshRunner {
                             for (const jobsEvent of await this.collectBackgroundJobs(sessionId, abort.signal)) {
                                 yield jobsEvent;
                             }
+                            // 收尾复核：这一轮结束时 goal 是否仍 active，决定卡片能不能收尾。
+                            // 必须现读宿主，不能沿用过程中的最后一次观测——goal 可能在本轮
+                            // 最后一个 step 才被 complete，也可能刚被 driver 置为 blocked。
+                            const finalGoal = await this.client.goalState(sessionId, {
+                                signal,
+                                timeoutMs: GOAL_PROBE_TIMEOUT_MS,
+                            });
+                            if (finalGoal.known && !sameGoal(finalGoal.goal, goal.last)) {
+                                goal.last = finalGoal.goal;
+                                yield goalStateEvent(finalGoal.goal, true);
+                            }
                         }
                         yield attachContextLimit(ev, live.contextLimit);
                         return;

package/dist/runner/index.d.ts

@@ -15,6 +15,6 @@ export { KimiAcpRunner } from './kimi/index.js';
 export { DshRunner } from './dsh/index.js';
 export { BashProcessRunner, type BashRunner } from './bash/index.js';
 export { AgentRegistry } from './registry.js';
-export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentKind, AgentSession, AgentSessionContentEvent, AgentSessionUsage, SessionContent, SessionSummary, AgentSessionReader, AgentRunner, TurnStartedEvent, TurnDiffEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, } from './types.js';
+export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentKind, AgentSession, AgentSessionContentEvent, AgentSessionUsage, SessionContent, SessionSummary, AgentSessionReader, AgentRunner, TurnStartedEvent, TurnDiffEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, GoalView, GoalStateEvent, } from './types.js';
 export { resolveAgentChoices } from './resolve-agent-choices.js';
 export { syncAgentChoices } from './sync-agent-choices.js';

package/dist/runner/types.d.ts

@@ -347,6 +347,45 @@ export interface RunStatusEvent {
     toolMs?: number;
     timestamp?: string;
 }
+/**
+ * 会话级长期目标（DSH `goal` 投影的渲染快照）。
+ *
+ * 为什么卡片需要它：goal 是**跨 turn** 的自动续跑单元。本轮 turn 结束不等于
+ * 任务结束——`goal-round-driver` 会在 quiescence 立刻起下一轮。缺这一维，
+ * 卡片只能在"这一轮结束了"时收尾，于是出现"任务还在跑、卡片却写完成"
+ * （turn/end 后宿主立刻起 goal round 2，用户点 Compact 被拒）。
+ */
+export interface GoalView {
+    id: string;
+    /** 人类写下的目标全文（可能很长，渲染层负责截断/折叠）。 */
+    objective: string;
+    phase: 'active' | 'paused' | 'blocked' | 'complete';
+    /** 已启动的轮次（最高 admitted round）。 */
+    roundsStarted: number;
+    /** 轮次上限；达到后 driver 把 goal 置为 blocked(round-limit)。 */
+    maxGoalRounds: number;
+    /** 仅在 phase='blocked' 时存在：阻断分类与人类可读原因。 */
+    blockedReason?: {
+        code: string;
+        message: string;
+    };
+    updatedAt?: number;
+}
+/**
+ * 一次 goal 状态观测（seed / 变更事件 / 收尾复核共用）。
+ *
+ * `known=false` 表示**读不到**，与"明确没有 goal"（`goal=null`）是两件事。
+ * 把探测失败降级成"没有 goal"会退回旧行为（goal 还在跑、卡片却收尾），
+ * 所以两者必须分开表达。
+ */
+export interface GoalStateEvent {
+    type: 'goal_state';
+    /** null = 宿主明确表示该会话没有 goal。 */
+    goal: GoalView | null;
+    /** false = 探测失败，`goal` 不具权威性，渲染层不得据此断言"已完成"。 */
+    known: boolean;
+    timestamp?: string;
+}
 /**
  * 运行结束后仍在后台运行的任务（终态卡展示 + 逐个停止入口）。
  *
@@ -431,7 +470,7 @@ export interface TurnDiffEvent {
 export type RunnerLifetime = 'turn' | 'workspace';
 /** 工具渲染 hint：runner 自愿声明，渲染层只消费不推断。 */
 export type ToolHint = 'shell' | 'file' | 'search' | 'web' | 'patch';
-export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent | NoticeEvent | SessionInfoEvent | RunStatusEvent | BackgroundJobsEvent;
+export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent | NoticeEvent | SessionInfoEvent | RunStatusEvent | BackgroundJobsEvent | GoalStateEvent;
 export interface SpawnOptions {
     cwd: string;
     sessionId?: string;

package/dist/session/dsh/sessions.js

@@ -364,7 +364,8 @@ function sessionPreset(item) {
  *
  * 全部取自 `session/list` 的 `projections.values`——DSH 0.2.x 已经随列表一起
  * 返回 title 与 turnOutline（每轮的 prompt/response），所以这里不需要再拉
- * `session/page`：那是一次上万条事件的大响应，一页 5 个会话就是 5 次。
+ * `session/page`：它按 `maxMessages=10000` 的上限拉整段历史，一页前 5 行就是
+ * 5 次这种大响应（把每行的 cwd 守卫与 projections 一起算，是 15 次同步请求）。
  *
  * `turnOutline` 的 prompt/response 由 DSH 侧按长度截断（结尾带 `…`），列表卡
  * 只做单行预览，直接复用即可。缺字段 / 类型不对时全部留空，不影响列表。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Feishu (Lark) private-chat bridge to local coding agents — Claude Code / Codex / opencode / pi / kimi, with live-streaming CardKit 2.0 cards",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",