@gotcos/glasses-server 6.57.1 → 6.58.0

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+## 6.58.0
+
+### Work: did the session finish the task?
+
+- Miles, 2026-09-29: "If a session is responsible for completing multiple tasks and we have evidence of the session receiving the context necessary to complete that task (as well as a confirmation that it has), then we want to be moving those tasks through the Kanban as well automatically."
+  - COS Control 0.5.247 follows each Work handoff until the session reports on it.
+  - Every handoff asks the agent to make its first reply line `COS-WORK <id>: done: <evidence>`. Control reads it from the session's recent messages (`GET /api/agent-sessions/:provider/:id?turns=N`, served since 6.50.0) and moves the card itself, as far as QA and never to Complete.
+- **New `POST /api/work-board/completion-check`**, the fallback when the session's newest reply since the handoff has no status line and the session is idle.
+  - The body is exactly `{domain, id, provider, sessionId}`, plus an optional `after` (an ISO time).
+  - The task comes from the board. The replies come from this server's own transcripts: with `after`, every reply written since then, joined and kept to the newest 4,000 characters (`LATEST_REPLY_MAX`); without it, the newest reply.
+  - The client never sends work or reply text.
+  - Jev answers one choice question (done, not_done or unclear) with a probability.
+  - The task is judged against its Done when, or, when it has none, against its own text. No open task has one today. The answer says which, as `basis: "done_when" | "task"`.
+  - The answer is advice. Control moves a card only on done at 0.8 or more (`done_when`) or 0.85 (`task`). Confidence is not rounded, so 0.795 never reads as 0.8.
+- **Answers:**
+  - `{provider: "jev", verdict, confidence, basis, model, cached}`.
+  - Otherwise `{provider: "none", reason}`:
+    - `no_reply` when there is no reply;
+    - `no_task_text` when the task has no text;
+    - any Jev condition (`jev_not_configured`, `jev_cap_reached`, `jev_breaker_open` and the rest);
+    - `completion_unavailable` for an unexpected failure, which is logged and answered 200.
+  - An unknown task is 404 `task_not_found`, an unknown session 404 `session_not_found`, and any other body 400 `invalid_completion_request`.
+  - Answers are cached for 30 minutes per task text, Done when and reply.
+- **Cost:** Control asks at most twice per handoff, once per new reply, and only while the session is idle. The task text is clipped to 1,200 characters, the Done when to 500 and the replies to 4,000, so one check is at most about 2,500 input tokens, inside the shared daily Jev cap (`COS_JEV_DAILY_TOKENS`). The reply text goes to TypeSafe unredacted, as with every Jev question about Work.
+- **Other changes:**
+  - `server/routes/jev.ts` finds a task through one `findTask` (Work identity first, then row id) for both suggestions and completion checks.
+  - The local Work candidate answers completion checks with no session, so it never reads this Mac's transcripts.
+- **Tests:**
+  - The checker: policy, unrounded confidence, basis, the clipping of task, Done when and reply, cache and reasons.
+  - The replies reader, over a fixture transcript: `after` window, newest kept, unknown session.
+  - The route: board and transcripts as the only sources, `after` passed through and validated, exact bodies, 404s, a failure answered as advice.
+  - The mutation gate adds 16 mutants and runs `work-completion.test.ts`.
+
 ## 6.57.1
 
 ### Session suggestions for meeting reviews

package/docs/work-intake.md

@@ -32,3 +32,5 @@ The journal is `work-intake/intake.json` in the server data directory, owned by
 `POST /api/jev-key/set` `{ key }` validates the key against TypeSafe and saves it to `data/jev-key.json`; `GET /api/jev-key/status` returns `{ configured, source, usedToday, dailyCap, breakerOpenUntil, lastError }` and never the key; `DELETE /api/jev-key` removes the saved key. `POST /api/work-board/session-recommendation` `{ domain, id, sessions: [{ id, provider, title, summary? }] }` returns `{ provider: "jev", action: "continue" | "fork" | "new", sessionId, confidence, reason, alternatives }` or `{ provider: "none", reason }`. The COS meeting producer reads the same saved key when its own `.env` has none.
 
 Since 6.57.1 `POST /api/work-board/session-recommendation` also takes exactly `{ reviewId, sessions }` for a meeting review (`reviewId` = `wr_` + 32 hex). The server reads the review's meeting title and reviewed follow-up from its own store; the client never sends work text. Errors: 400 `invalid_review_request` (bad id or session list), 404 `review_not_found`, 404 `reviews_unavailable` (reviews off), 503 `review_store_unavailable` (defensive; the stock lookup reads memory).
+
+Since 6.58.0 `POST /api/work-board/completion-check` takes exactly `{ domain, id, provider, sessionId }` plus an optional `after` (ISO time). It asks Jev whether the session's replies since `after` (or its newest reply) show the task finished, judged against its Done when or, without one, its own text. The server reads the task from the board and the replies from its own transcripts; the client sends names and a time only. It answers `{ provider: "jev", verdict: "done" | "not_done" | "unclear", confidence, basis: "done_when" | "task", model, cached }` or `{ provider: "none", reason }` (`no_reply`, `no_task_text`, a Jev condition, `completion_unavailable`). Errors: 400 `invalid_completion_request`, 404 `task_not_found`, 404 `session_not_found`. COS Control 0.5.247 asks only while the session is idle and its newest reply since the handoff has no `COS-WORK` status line, at most twice per handoff, and moves a card to QA only on done at 0.8 (0.85 without a Done when).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.57.1",
+  "version": "6.58.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -629,7 +629,8 @@ app.use('/api', createWorkBoardRouter())
 // Work intake (6.57.0): meeting-derived suggestions, asks and review items. Optional: a bad journal never blocks boot.
 const workIntakeStore = createOptionalWorkIntakeStore(() => new WorkIntakeStore(dataPath('work-intake')))
 app.use('/api', createWorkIntakeRouter({ store: workIntakeStore }))
-// Jev key (Control Settings) and Continue/Fork/New session recommendations for Work tasks (6.57.0) and meeting reviews (6.57.1).
+// Jev key (Control Settings), Continue/Fork/New session recommendations for Work tasks (6.57.0) and meeting reviews
+// (6.57.1), and the Work completion check (6.58.0).
 app.use('/api', createJevRouter(workReviewRuntime ? { review: async id => workReviewRuntime.peek(id) } : {}))
 app.use('/api', queryRouter)
 // The scheduled start-of-day brief: settings, status, run-now. Same auth as

package/server/lib/work-completion.ts

@@ -0,0 +1,98 @@
+/**
+ * Did an agent session finish a Work task? (6.58.0)
+ *
+ * Control 0.5.247 follows a Work handoff until the session reports on it. Every handoff asks the agent to start its
+ * reply with a status line (`COS-WORK <id>: done: <evidence>`). When the session's newest reply since the handoff
+ * carries none and the session has gone idle, Control asks this (at most twice per handoff, once per reply). Jev reads
+ * the session's replies since the handoff arrived (`after`) against the task's Done when, or, when the task has none
+ * (most do), against the task itself. It answers done, not_done or unclear with a probability. Control moves the card
+ * to QA only on done at 0.8 or more (0.85 without a Done when), and never to Complete: that stays the user's.
+ *
+ * The task comes from the board and the replies from this server's own session transcripts. The client sends names
+ * and a time only.
+ */
+import { createHash } from 'node:crypto'
+import { estimateJevTokens, JevError, type JevClient } from './jev.js'
+import { agentSessionRoots, findAgentSessionFile, LATEST_REPLY_MAX, parseAgentSession, type AgentProvider } from './agent-session-store.js'
+import { readRecentSessionTurns, SESSION_TURNS_MAX, type SessionTurn } from './agent-session-turns.js'
+
+export const COMPLETION_LIMITS = { task: 1200, doneWhen: 500, reply: LATEST_REPLY_MAX, cacheMs: 30 * 60_000, cacheEntries: 200 } as const
+export const COMPLETION_CHOICES = ['done', 'not_done', 'unclear'] as const
+export type CompletionChoice = typeof COMPLETION_CHOICES[number]
+
+export interface CompletionInput { task: { text: string; doneWhen: string }; reply: string }
+/** `basis`: what the reply was read against, the task's Done when or (without one) the task itself. */
+export type CompletionVerdict =
+  | { provider: 'jev'; model: string; verdict: CompletionChoice; confidence: number; basis: 'done_when' | 'task'; cached: boolean }
+  | { provider: 'none'; reason: string }
+
+const AGAINST_DONE_WHEN = "Does the agent's reply in `reply` show that the task in `task` is finished, as `task.doneWhen` defines finished? "
+  + 'Choose done only when the reply reports the work complete and checked against that finish line.'
+const AGAINST_TASK = "Does the agent's reply in `reply` show that the task in `task.text` is finished? "
+  + 'Choose done only when the reply reports that exact work complete and checked, not merely started or planned.'
+const REST = ' A plan, a partial result, a question for the user, a blocker, or a promise to do it next is not_done. '
+  + 'Choose unclear when the reply does not say enough to tell.'
+
+const clip = (text: string, max: number) => text.trim().slice(0, max)
+
+/** Pure policy over Jev's answer: the most probable choice and its probability (unrounded: a threshold decides on it). */
+export function decideCompletion(probabilities: Record<string, number> | undefined): { verdict: CompletionChoice; confidence: number } {
+  const rows = Object.entries(probabilities ?? {})
+  if (!rows.length || rows.some(([k, v]) => !(COMPLETION_CHOICES as readonly string[]).includes(k) || typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1)) {
+    throw new JevError('jev_bad_answer', 'Jev answered outside done, not_done and unclear')
+  }
+  const [verdict, confidence] = rows.sort((a, b) => b[1] - a[1])[0] as [CompletionChoice, number]
+  return { verdict, confidence }
+}
+
+/** The replies among `turns` written at or after `afterMs`, joined oldest first, keeping the newest `max` characters. */
+export function joinRepliesSince(turns: SessionTurn[], afterMs: number, max: number = COMPLETION_LIMITS.reply): string {
+  const joined = turns.filter(t => t.role === 'assistant' && t.at !== undefined && Date.parse(t.at) >= afterMs).map(t => t.text).join('\n\n')
+  return joined.length <= max ? joined : `\u2026${joined.slice(joined.length - (max - 1))}`
+}
+
+export type SessionFileFinder = (provider: AgentProvider, sessionId: string) => Promise<string | null>
+const findInHome: SessionFileFinder = (provider, sessionId) => findAgentSessionFile(provider, sessionId, agentSessionRoots())
+
+/** What a completion check judges: the session's replies since `afterMs`, or its newest reply when no time is given.
+ *  Null when the session is not on this Mac. */
+export async function readRepliesSince(provider: AgentProvider, sessionId: string, afterMs: number | null,
+                                       find: SessionFileFinder = findInHome): Promise<string | null> {
+  const path = await find(provider, sessionId)
+  if (!path) return null
+  if (afterMs === null) return (await parseAgentSession(provider, path)).latest_reply || ''
+  return joinRepliesSince((await readRecentSessionTurns(provider, path, SESSION_TURNS_MAX)).turns, afterMs)
+}
+
+export class CompletionChecker {
+  private cache = new Map<string, { at: number; value: Extract<CompletionVerdict, { provider: 'jev' }> }>()
+  constructor(private readonly jev: JevClient, private readonly now: () => number = () => Date.now()) {}
+
+  async check(input: CompletionInput): Promise<CompletionVerdict> {
+    const state = { task: { text: clip(input.task.text, COMPLETION_LIMITS.task), doneWhen: clip(input.task.doneWhen, COMPLETION_LIMITS.doneWhen) },
+      reply: clip(input.reply, COMPLETION_LIMITS.reply) }
+    const basis = state.task.doneWhen ? 'done_when' as const : 'task' as const
+    if (!state.task.doneWhen && !state.task.text) return { provider: 'none', reason: 'no_task_text' }
+    if (!state.reply) return { provider: 'none', reason: 'no_reply' }
+    const key = createHash('sha256').update(JSON.stringify(state)).digest('hex')
+    const hit = this.cache.get(key)
+    if (hit && this.now() - hit.at < COMPLETION_LIMITS.cacheMs) return { ...hit.value, cached: true }
+    const questions = {
+      finished: { type: 'choice', instructions: (basis === 'done_when' ? AGAINST_DONE_WHEN : AGAINST_TASK) + REST, criteria: {
+        done: basis === 'done_when' ? 'The reply reports the task finished and checked against its Done when.' : 'The reply reports this task finished and checked.',
+        not_done: 'The reply shows work remaining, a plan, a question, a blocker, or a partial result.',
+        unclear: 'The reply does not say enough to tell.',
+      } },
+    }
+    try {
+      const reply = await this.jev.ask(state, questions, estimateJevTokens({ state, questions }))
+      const value = { provider: 'jev' as const, model: reply.model ?? 'jev', cached: false, basis, ...decideCompletion(reply.answers.finished?.probabilities) }
+      if (this.cache.size >= COMPLETION_LIMITS.cacheEntries) this.cache.delete(this.cache.keys().next().value!)
+      this.cache.set(key, { at: this.now(), value })
+      return value
+    } catch (e) {
+      if (e instanceof JevError) return { provider: 'none', reason: e.code }
+      throw e
+    }
+  }
+}

package/server/routes/jev.ts

@@ -9,6 +9,8 @@ import { Router } from 'express'
 import { existsSync, unlinkSync } from 'node:fs'
 import { JEV_KEY_FILE, saveJevKey, sharedJevClient, validateJevKey, type JevClient } from '../lib/jev.js'
 import { SessionRecommender, parseCandidates } from '../lib/session-recommendation.js'
+import { CompletionChecker, readRepliesSince } from '../lib/work-completion.js'
+import { isSafeSessionId, type AgentProvider } from '../lib/agent-session-store.js'
 import { listBoard } from '../lib/task-store.js'
 import { isSafeDomainName } from '../lib/domains.js'
 
@@ -23,13 +25,24 @@ export interface JevRouteDependencies {
   save: typeof saveJevKey
   /** Looks a meeting review up by its `wr_` id; throws or returns null when it does not exist. Absent when reviews are off. */
   review?: (id: string) => Promise<ReviewForAdvice | null>
+  /** 6.58.0: Jev's reading of a reply against a task's Done when. */
+  completion: Pick<CompletionChecker, 'check'>
+  /** 6.58.0: a session's replies since a time (or its newest reply) from this server's transcripts; null when the
+   *  session is not on this Mac. */
+  replies: (provider: AgentProvider, sessionId: string, afterMs: number | null) => Promise<string | null>
+}
+
+/** Work identity first: it survives a rename, while a new card's id could equal an old identity's text hash. */
+function findTask<T extends { id: string; workIdentity?: string }>(rows: T[], id: string): T | undefined {
+  return rows.find(r => r.workIdentity === id) ?? rows.find(r => r.id === id)
 }
 
 export function createJevRouter(overrides: Partial<JevRouteDependencies> = {}): Router {
   const jev = overrides.jev ?? sharedJevClient()
-  const deps: JevRouteDependencies = { jev, recommender: new SessionRecommender(jev), list: listBoard, validate: validateJevKey, save: saveJevKey, ...overrides }
+  const deps: JevRouteDependencies = { jev, recommender: new SessionRecommender(jev), list: listBoard, validate: validateJevKey, save: saveJevKey,
+    completion: new CompletionChecker(jev), replies: (provider, sessionId, afterMs) => readRepliesSince(provider, sessionId, afterMs), ...overrides }
   const router = Router()
-  router.use(['/jev-key', '/work-board/session-recommendation'], (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
+  router.use(['/jev-key', '/work-board/session-recommendation', '/work-board/completion-check'], (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
 
   router.get('/jev-key/status', (_req, res) => res.json(deps.jev.status()))
 
@@ -91,9 +104,8 @@ export function createJevRouter(overrides: Partial<JevRouteDependencies> = {}):
       return res.status(400).json({ error: { code: 'invalid_recommendation_request', message: 'Select an exact task and send at most 80 sessions.' } })
     }
     try {
-      // Work identity first: it survives a rename, while a new card's id could equal an old identity's text hash.
       const rows = (await deps.list()).filter(r => r.domain === body.domain)
-      const row = rows.find(r => r.workIdentity === body.id) ?? rows.find(r => r.id === body.id)
+      const row = findTask(rows, body.id)
       if (!row) return res.status(404).json({ error: { code: 'task_not_found', message: 'That task changed or was removed. Refresh Work.' } })
       const meetings = (row.meetingRefs ?? []).map(ref => ref.title ?? '').filter(Boolean)
       return res.json(await deps.recommender.recommend({ task: { text: row.text || row.title || '', domain: row.domain, meetings }, sessions }))
@@ -102,5 +114,31 @@ export function createJevRouter(overrides: Partial<JevRouteDependencies> = {}):
       return res.json({ provider: 'none', reason: 'recommendation_unavailable' })  // advice only: never block the workspace
     }
   })
+  /** 6.58.0 (Control 0.5.247): did a session finish a board task? Asked when the session's newest reply since the
+   *  handoff has no status line and the session is idle. The task comes from the board and the replies from this
+   *  server's transcripts; the client sends names and, optionally, `after` (judge replies from then on). An answer is
+   *  advice: Control moves a card to QA only on a confident done, never to Complete. */
+  router.post('/work-board/completion-check', async (req, res) => {
+    const body = req.body
+    const keys = body && typeof body === 'object' && !Array.isArray(body) ? Object.keys(body).filter(k => k !== 'after').sort().join(',') : ''
+    const afterMs = body?.after === undefined ? null : typeof body.after === 'string' && body.after.length <= 40 ? Date.parse(body.after) : Number.NaN
+    if (keys !== 'domain,id,provider,sessionId' || Number.isNaN(afterMs)
+      || typeof body.domain !== 'string' || !isSafeDomainName(body.domain) || typeof body.id !== 'string' || !/^[a-f0-9]{12}$/.test(body.id)
+      || !['claude', 'codex', 'cursor'].includes(body.provider) || typeof body.sessionId !== 'string' || !isSafeSessionId(body.sessionId)) {
+      return res.status(400).json({ error: { code: 'invalid_completion_request', message: 'Select an exact task and session.' } })
+    }
+    try {
+      const rows = (await deps.list()).filter(r => r.domain === body.domain)
+      const row = findTask(rows, body.id)
+      if (!row) return res.status(404).json({ error: { code: 'task_not_found', message: 'That task changed or was removed. Refresh Work.' } })
+      const reply = await deps.replies(body.provider as AgentProvider, body.sessionId, afterMs)
+      if (reply === null) return res.status(404).json({ error: { code: 'session_not_found', message: 'That session is not on this Mac.' } })
+      // A task with no Done when (most tasks) is judged against its own text; the answer says which (`basis`).
+      return res.json(await deps.completion.check({ task: { text: row.text || row.title || '', doneWhen: (row.doneWhen ?? '').trim() }, reply }))
+    } catch (e) {
+      console.error('[jev] completion check failed:', e instanceof Error ? e.message : e)
+      return res.json({ provider: 'none', reason: 'completion_unavailable' })  // advice only: tracking goes on without it
+    }
+  })
   return router
 }