axmap-cli 1.5.0 → 1.7.0

package/src/session-mailbox.mjs

@@ -0,0 +1,190 @@
+// Generated from src/session-mailbox.mts. Edit the .mts source and run npm run build.
+/** Collaboration mail is durable data, not a user instruction or a model turn.
+ * Receivers collect it at explicit safe boundaries; only urgent mail may send now. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest } from './bridge.mjs';
+import { withRepoLock } from './repolock.mjs';
+import { errorMessage } from './session-types.mjs';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const reasons = ['stop', 'data-loss', 'work-invalidated'];
+const boundaries = ['task-complete', 'test-complete', 'experiment-complete', 'checkpoint'];
+function box(to, cwd) {
+    if (!UUID.test(to || '') || !sessions(cwd).some(s => s.id === to))
+        throw new Error('현재 저장소에 등록된 수신 세션 UUID가 필요합니다.');
+    const repo = repoKey(cwd);
+    const dir = path.join(bridgeHome(), 'mailboxes');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = path.join(dir, `${to}.json`);
+    return { repo, target, lock: `${target}.lock` };
+}
+function load(target) {
+    if (!fs.existsSync(target))
+        return { version: 1, messages: [], batches: [] };
+    const b = readJSON(target);
+    if (b.version !== 1 || !Array.isArray(b.messages) || !Array.isArray(b.batches))
+        throw new Error('받은 편지함 형식을 확인하지 못했습니다.');
+    const states = ['queued', 'sending', 'submitted', 'unknown', 'collected', 'expired', 'superseded'];
+    if (b.messages.some(m => !m || !UUID.test(m.id || '') || m.to !== path.basename(target, '.json') ||
+        typeof m.repo !== 'string' || typeof m.from !== 'string' || typeof m.text !== 'string' || m.source !== 'agent' ||
+        !['boundary', 'immediate'].includes(m.priority) || !states.includes(m.state) ||
+        !Number.isFinite(Date.parse(m.createdAt)) || !Number.isFinite(Date.parse(m.expiresAt))) ||
+        b.batches.some(x => !x || !UUID.test(x.id || '') || typeof x.repo !== 'string' || !Array.isArray(x.ids) ||
+            !['sending', 'submitted', 'unknown'].includes(x.state)))
+        throw new Error('받은 편지함 기록이 손상됐습니다. 빈 큐로 바꾸지 않습니다.');
+    return b;
+}
+function expire(b) {
+    for (const m of b.messages)
+        if (m.state === 'queued' && Date.parse(m.expiresAt) <= Date.now())
+            m.state = 'expired';
+}
+function boundary(value) {
+    if (!boundaries.includes(value || ''))
+        throw new Error(`안전한 작업 경계를 명시하세요: ${boundaries.join(', ')}`);
+}
+export function postMail({ to, cwd, text, from = process.env.AXMAP_SESSION || process.env.AXMAP_AGENT || 'axmap', priority = 'boundary', reason, topic, key, ttlSeconds = 3600 }) {
+    if (typeof text !== 'string' || !text.trim() || Buffer.byteLength(text) > 24000)
+        throw new Error('메시지는 1~24000바이트여야 합니다.');
+    if (Buffer.byteLength(JSON.stringify(text)) > 28000)
+        throw new Error('JSON으로 인코딩한 메시지가 묶음 한도를 넘습니다.');
+    if (!['boundary', 'immediate'].includes(priority))
+        throw new Error('priority는 boundary 또는 immediate입니다.');
+    if (priority === 'immediate' ? !reasons.includes(reason || '') : reason !== undefined)
+        throw new Error('즉시 전달 사유는 stop, data-loss, work-invalidated 중 하나입니다. 일반 알림에는 사유를 넣지 마세요.');
+    for (const v of [from, topic, key])
+        if (v !== undefined && (typeof v !== 'string' || !v.trim() || v.length > 200))
+            throw new Error('발신자·topic·key는 1~200자입니다.');
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > 86400)
+        throw new Error('ttl-seconds는 1~86400 정수입니다.');
+    const { repo, target, lock } = box(to, cwd);
+    const saved = withRepoLock(lock, () => {
+        const b = load(target);
+        expire(b);
+        if (key) {
+            const old = b.messages.find(m => m.repo === repo && m.from === from && m.key === key);
+            if (old) {
+                if (old.text !== text || old.priority !== priority || old.reason !== reason || old.topic !== topic)
+                    throw new Error('같은 메시지 key에 다른 내용이 있습니다.');
+                writeJSON(target, b);
+                return { mail: old, replayed: true };
+            }
+        }
+        if (b.messages.filter(m => m.repo === repo && m.state === 'queued').length >= 1000)
+            throw new Error('받은 편지함이 가득 찼습니다. 작업 경계에서 먼저 회수하세요.');
+        const m = { id: randomUUID(), repo, to, from, source: 'agent', text, priority, reason, topic, key,
+            createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(), state: 'queued' };
+        // Coalesce only explicitly related routine updates by the SAME sender.
+        // Urgent messages and messages already handed off remain immutable.
+        if (topic && priority === 'boundary')
+            for (const old of b.messages) {
+                if (old.repo === repo && old.from === from && old.topic === topic && old.priority === 'boundary' && old.state === 'queued') {
+                    old.state = 'superseded';
+                    old.supersededBy = m.id;
+                }
+            }
+        b.messages.push(m);
+        writeJSON(target, b);
+        return { mail: m, replayed: false };
+    });
+    if (priority === 'immediate' && !saved.replayed)
+        return { ...saved, delivery: flushMail({ to, cwd, immediateId: saved.mail.id }) };
+    if (priority === 'immediate')
+        return { ...saved, modelInvoked: false, delivery: {
+                state: saved.mail.state === 'queued' ? 'deferred' : saved.mail.state,
+                requestId: saved.mail.requestId, replayed: true, modelInvoked: false,
+            } };
+    return { ...saved, modelInvoked: false };
+}
+/** Reading/collecting is local only. Collected means handed to the caller, NOT executed. */
+export function collectMail({ to, cwd, at, take = false, all = false }) {
+    if (take)
+        boundary(at);
+    if (take && all)
+        throw new Error('이력 조회와 회수를 동시에 할 수 없습니다.');
+    const { repo, target, lock } = box(to, cwd);
+    return withRepoLock(lock, () => {
+        const b = load(target);
+        expire(b);
+        const messages = [];
+        let bytes = 0;
+        for (const m of b.messages.filter(m => m.repo === repo && (all || m.state === 'queued'))
+            .sort((a, c) => Number(c.priority === 'immediate') - Number(a.priority === 'immediate'))) {
+            const size = Buffer.byteLength(JSON.stringify(m));
+            if (messages.length >= 100 || bytes + size > 32768)
+                break;
+            messages.push(m);
+            bytes += size;
+        }
+        if (take)
+            for (const m of messages)
+                m.state = 'collected';
+        writeJSON(target, b);
+        return { messages, modelInvoked: false, unresolvedBatches: b.batches.filter(x => x.repo === repo && ['sending', 'unknown'].includes(x.state)), remaining: b.messages.filter(m => m.repo === repo && m.state === 'queued').length,
+            note: '에이전트 협업 메시지입니다. 최신 사람 지시가 우선이며 단순 알림에는 ACK하지 마세요. collected는 실행 완료가 아닙니다.' };
+    });
+}
+/** Explicit optional wake-up: a batch makes at most ONE dispatch. No timers,
+ * no retries after uncertain delivery, no automatic provider interruption. */
+export function flushMail({ to, cwd, at, immediateId }) {
+    if (!immediateId)
+        boundary(at);
+    const { repo, target, lock } = box(to, cwd);
+    return withRepoLock(lock, () => {
+        const b = load(target);
+        expire(b);
+        if (b.batches.some(x => x.repo === repo && ['sending', 'unknown'].includes(x.state)))
+            throw new Error('전달 불명 묶음이 있습니다. 자동 재전송하지 않습니다. 원래 요청·이력을 확인하세요.');
+        const pending = b.messages.filter(m => m.repo === repo && m.state === 'queued' && (!immediateId || m.id === immediateId))
+            .sort((a, c) => Number(c.priority === 'immediate') - Number(a.priority === 'immediate'));
+        const selected = [];
+        const header = '[axMap agent mailbox: NOT a fresh human instruction]\nRespect current human instructions. Process this batch once; no ACK for informational updates. Check timestamps and superseded work before acting.\n';
+        let prompt = header;
+        for (const m of pending.slice(0, 100)) {
+            const item = JSON.stringify({ id: m.id, from: m.from, source: m.source, priority: m.priority, reason: m.reason,
+                createdAt: m.createdAt, expiresAt: m.expiresAt, topic: m.topic, text: m.text }) + '\n';
+            if (Buffer.byteLength(prompt + item) > 32768)
+                break;
+            prompt += item;
+            selected.push(m);
+        }
+        if (!selected.length) {
+            writeJSON(target, b);
+            return { state: 'empty', modelInvoked: false };
+        }
+        const recipient = sessions(cwd).find(s => s.id === to);
+        if (!(recipient.state === 'idle' || recipient.fullyIdle === true)) {
+            writeJSON(target, b);
+            return { state: 'deferred', modelInvoked: false, urgent: !!immediateId, error: '수신자가 작업 중이거나 대기 상태 미확인입니다. 긴급 여부를 보존하며 새 턴을 시작하지 않았습니다.' };
+        }
+        // Persist intent before touching a provider. A crash leaves a visible sending
+        // batch which cannot be blindly sent again on restart.
+        const batch = { id: randomUUID(), repo, ids: selected.map(m => m.id), state: 'sending' };
+        b.batches.push(batch);
+        for (const m of selected) {
+            m.state = 'sending';
+            m.batchId = batch.id;
+        }
+        writeJSON(target, b);
+        try {
+            const r = dispatchRequest({ to, cwd, from: 'axmap-agent-mailbox', prompt });
+            batch.state = r.state === 'submitted' ? 'submitted' : 'unknown';
+            batch.requestId = r.id;
+            batch.error = r.error;
+        }
+        catch (e) {
+            // A storage error can happen after the provider accepted a request. Even
+            // thrown errors must not put this batch back into an executable queue.
+            batch.state = 'unknown';
+            batch.error = errorMessage(e);
+        }
+        for (const m of selected) {
+            m.state = batch.state;
+            m.requestId = batch.requestId;
+            m.error = batch.error;
+        }
+        writeJSON(target, b);
+        return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null };
+    });
+}

package/src/session-mailbox.mts

@@ -0,0 +1,157 @@
+/** Collaboration mail is durable data, not a user instruction or a model turn.
+ * Receivers collect it at explicit safe boundaries; only urgent mail may send now. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest } from './bridge.mjs'
+import { withRepoLock } from './repolock.mjs'
+import { errorMessage } from './session-types.mjs'
+
+type Priority = 'boundary' | 'immediate'
+type State = 'queued' | 'sending' | 'submitted' | 'unknown' | 'collected' | 'expired' | 'superseded'
+export interface Mail {
+  id: string; repo: string; to: string; from: string; source: 'agent'; text: string
+  priority: Priority; reason?: string; topic?: string; key?: string
+  createdAt: string; expiresAt: string; state: State
+  supersededBy?: string; batchId?: string; requestId?: string; error?: string
+}
+interface Batch { id: string; repo: string; ids: string[]; state: 'sending' | 'submitted' | 'unknown'; requestId?: string; error?: string }
+interface Box { version: 1; messages: Mail[]; batches: Batch[] }
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const reasons = ['stop', 'data-loss', 'work-invalidated']
+const boundaries = ['task-complete', 'test-complete', 'experiment-complete', 'checkpoint']
+
+function box(to: string, cwd: string) {
+  if (!UUID.test(to || '') || !sessions(cwd).some(s => s.id === to)) throw new Error('현재 저장소에 등록된 수신 세션 UUID가 필요합니다.')
+  const repo = repoKey(cwd)
+  const dir = path.join(bridgeHome(), 'mailboxes'); fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const target = path.join(dir, `${to}.json`)
+  return { repo, target, lock: `${target}.lock` }
+}
+function load(target: string): Box {
+  if (!fs.existsSync(target)) return { version: 1, messages: [], batches: [] }
+  const b = readJSON<Box>(target)
+  if (b.version !== 1 || !Array.isArray(b.messages) || !Array.isArray(b.batches)) throw new Error('받은 편지함 형식을 확인하지 못했습니다.')
+  const states = ['queued', 'sending', 'submitted', 'unknown', 'collected', 'expired', 'superseded']
+  if (b.messages.some(m => !m || !UUID.test(m.id || '') || m.to !== path.basename(target, '.json') ||
+    typeof m.repo !== 'string' || typeof m.from !== 'string' || typeof m.text !== 'string' || m.source !== 'agent' ||
+    !['boundary', 'immediate'].includes(m.priority) || !states.includes(m.state) ||
+    !Number.isFinite(Date.parse(m.createdAt)) || !Number.isFinite(Date.parse(m.expiresAt))) ||
+    b.batches.some(x => !x || !UUID.test(x.id || '') || typeof x.repo !== 'string' || !Array.isArray(x.ids) ||
+      !['sending', 'submitted', 'unknown'].includes(x.state))) throw new Error('받은 편지함 기록이 손상됐습니다. 빈 큐로 바꾸지 않습니다.')
+  return b
+}
+function expire(b: Box) {
+  for (const m of b.messages) if (m.state === 'queued' && Date.parse(m.expiresAt) <= Date.now()) m.state = 'expired'
+}
+function boundary(value?: string) {
+  if (!boundaries.includes(value || '')) throw new Error(`안전한 작업 경계를 명시하세요: ${boundaries.join(', ')}`)
+}
+
+export function postMail({ to, cwd, text, from = process.env.AXMAP_SESSION || process.env.AXMAP_AGENT || 'axmap',
+  priority = 'boundary', reason, topic, key, ttlSeconds = 3600 }:
+  { to: string; cwd: string; text: string; from?: string; priority?: Priority; reason?: string; topic?: string; key?: string; ttlSeconds?: number }) {
+  if (typeof text !== 'string' || !text.trim() || Buffer.byteLength(text) > 24000) throw new Error('메시지는 1~24000바이트여야 합니다.')
+  if (Buffer.byteLength(JSON.stringify(text)) > 28000) throw new Error('JSON으로 인코딩한 메시지가 묶음 한도를 넘습니다.')
+  if (!['boundary', 'immediate'].includes(priority)) throw new Error('priority는 boundary 또는 immediate입니다.')
+  if (priority === 'immediate' ? !reasons.includes(reason || '') : reason !== undefined) throw new Error('즉시 전달 사유는 stop, data-loss, work-invalidated 중 하나입니다. 일반 알림에는 사유를 넣지 마세요.')
+  for (const v of [from, topic, key]) if (v !== undefined && (typeof v !== 'string' || !v.trim() || v.length > 200)) throw new Error('발신자·topic·key는 1~200자입니다.')
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > 86400) throw new Error('ttl-seconds는 1~86400 정수입니다.')
+  const { repo, target, lock } = box(to, cwd)
+  const saved = withRepoLock(lock, () => {
+    const b = load(target); expire(b)
+    if (key) {
+      const old = b.messages.find(m => m.repo === repo && m.from === from && m.key === key)
+      if (old) {
+        if (old.text !== text || old.priority !== priority || old.reason !== reason || old.topic !== topic) throw new Error('같은 메시지 key에 다른 내용이 있습니다.')
+        writeJSON(target, b); return { mail: old, replayed: true }
+      }
+    }
+    if (b.messages.filter(m => m.repo === repo && m.state === 'queued').length >= 1000) throw new Error('받은 편지함이 가득 찼습니다. 작업 경계에서 먼저 회수하세요.')
+    const m: Mail = { id: randomUUID(), repo, to, from, source: 'agent', text, priority, reason, topic, key,
+      createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(), state: 'queued' }
+    // Coalesce only explicitly related routine updates by the SAME sender.
+    // Urgent messages and messages already handed off remain immutable.
+    if (topic && priority === 'boundary') for (const old of b.messages) {
+      if (old.repo === repo && old.from === from && old.topic === topic && old.priority === 'boundary' && old.state === 'queued') {
+        old.state = 'superseded'; old.supersededBy = m.id
+      }
+    }
+    b.messages.push(m); writeJSON(target, b); return { mail: m, replayed: false }
+  })
+  if (priority === 'immediate' && !saved.replayed) return { ...saved, delivery: flushMail({ to, cwd, immediateId: saved.mail.id }) }
+  if (priority === 'immediate') return { ...saved, modelInvoked: false, delivery: {
+    state: saved.mail.state === 'queued' ? 'deferred' : saved.mail.state,
+    requestId: saved.mail.requestId, replayed: true, modelInvoked: false,
+  } }
+  return { ...saved, modelInvoked: false }
+}
+
+/** Reading/collecting is local only. Collected means handed to the caller, NOT executed. */
+export function collectMail({ to, cwd, at, take = false, all = false }:
+  { to: string; cwd: string; at?: string; take?: boolean; all?: boolean }) {
+  if (take) boundary(at)
+  if (take && all) throw new Error('이력 조회와 회수를 동시에 할 수 없습니다.')
+  const { repo, target, lock } = box(to, cwd)
+  return withRepoLock(lock, () => {
+    const b = load(target); expire(b)
+    const messages: Mail[] = []
+    let bytes = 0
+    for (const m of b.messages.filter(m => m.repo === repo && (all || m.state === 'queued'))
+      .sort((a, c) => Number(c.priority === 'immediate') - Number(a.priority === 'immediate'))) {
+      const size = Buffer.byteLength(JSON.stringify(m))
+      if (messages.length >= 100 || bytes + size > 32768) break
+      messages.push(m); bytes += size
+    }
+    if (take) for (const m of messages) m.state = 'collected'
+    writeJSON(target, b)
+    return { messages, modelInvoked: false, unresolvedBatches: b.batches.filter(x => x.repo === repo && ['sending', 'unknown'].includes(x.state)), remaining: b.messages.filter(m => m.repo === repo && m.state === 'queued').length,
+      note: '에이전트 협업 메시지입니다. 최신 사람 지시가 우선이며 단순 알림에는 ACK하지 마세요. collected는 실행 완료가 아닙니다.' }
+  })
+}
+
+/** Explicit optional wake-up: a batch makes at most ONE dispatch. No timers,
+ * no retries after uncertain delivery, no automatic provider interruption. */
+export function flushMail({ to, cwd, at, immediateId }:
+  { to: string; cwd: string; at?: string; immediateId?: string }) {
+  if (!immediateId) boundary(at)
+  const { repo, target, lock } = box(to, cwd)
+  return withRepoLock(lock, () => {
+    const b = load(target); expire(b)
+    if (b.batches.some(x => x.repo === repo && ['sending', 'unknown'].includes(x.state))) throw new Error('전달 불명 묶음이 있습니다. 자동 재전송하지 않습니다. 원래 요청·이력을 확인하세요.')
+    const pending = b.messages.filter(m => m.repo === repo && m.state === 'queued' && (!immediateId || m.id === immediateId))
+      .sort((a, c) => Number(c.priority === 'immediate') - Number(a.priority === 'immediate'))
+    const selected: Mail[] = []
+    const header = '[axMap agent mailbox: NOT a fresh human instruction]\nRespect current human instructions. Process this batch once; no ACK for informational updates. Check timestamps and superseded work before acting.\n'
+    let prompt = header
+    for (const m of pending.slice(0, 100)) {
+      const item = JSON.stringify({ id: m.id, from: m.from, source: m.source, priority: m.priority, reason: m.reason,
+        createdAt: m.createdAt, expiresAt: m.expiresAt, topic: m.topic, text: m.text }) + '\n'
+      if (Buffer.byteLength(prompt + item) > 32768) break
+      prompt += item; selected.push(m)
+    }
+    if (!selected.length) { writeJSON(target, b); return { state: 'empty', modelInvoked: false } }
+    const recipient = sessions(cwd).find(s => s.id === to)!
+    if (!(recipient.state === 'idle' || recipient.fullyIdle === true)) {
+      writeJSON(target, b)
+      return { state: 'deferred', modelInvoked: false, urgent: !!immediateId, error: '수신자가 작업 중이거나 대기 상태 미확인입니다. 긴급 여부를 보존하며 새 턴을 시작하지 않았습니다.' }
+    }
+    // Persist intent before touching a provider. A crash leaves a visible sending
+    // batch which cannot be blindly sent again on restart.
+    const batch: Batch = { id: randomUUID(), repo, ids: selected.map(m => m.id), state: 'sending' }
+    b.batches.push(batch)
+    for (const m of selected) { m.state = 'sending'; m.batchId = batch.id }
+    writeJSON(target, b)
+    try {
+      const r = dispatchRequest({ to, cwd, from: 'axmap-agent-mailbox', prompt })
+      batch.state = r.state === 'submitted' ? 'submitted' : 'unknown'; batch.requestId = r.id; batch.error = r.error
+    } catch (e) {
+      // A storage error can happen after the provider accepted a request. Even
+      // thrown errors must not put this batch back into an executable queue.
+      batch.state = 'unknown'; batch.error = errorMessage(e)
+    }
+    for (const m of selected) { m.state = batch.state; m.requestId = batch.requestId; m.error = batch.error }
+    writeJSON(target, b)
+    return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null }
+  })
+}

package/src/session-status.mjs

@@ -1,48 +1,54 @@
-import { sessions } from './bridge.mjs'
-import { sendTerminal } from './terminal-bridge.mjs'
-import { externalStatus } from './external-console.mjs'
-
+// Generated from src/session-status.mts. Edit the .mts source and run npm run build.
+import { sessions } from './bridge.mjs';
+import { sendTerminal } from './terminal-bridge.mjs';
+import { externalStatus } from './external-console.mjs';
 /** Probe only the authenticated local control pipe. A saved idle/running record
  * cannot establish that its host still exists; no model request is submitted. */
 export async function sessionStatus(cwd = process.cwd()) {
-  const listed = sessions(cwd)
-  return Promise.all(listed.map(async session => {
-    const base = { ...session, lastKnownState: session.state ?? null }
-    const snapshot = (state, connection, extra = {}) => ({ ...base, ...extra, state, connection,
-      fullyIdle: connection === 'connected' && state === 'idle', checkedAt: new Date().toISOString() })
-    if (session.state === 'closed') return snapshot('closed', 'closed')
-    if (session.transport === 'console') {
-      try {
-        const live = externalStatus(session)
-        return snapshot(live.state, 'connected')
-      } catch { return snapshot('unknown', 'unreachable') }
-    }
-    if (!['pty', 'stdio'].includes(session.transport)) return snapshot('unknown', 'unverified')
-    try {
-      const live = await sendTerminal(session.id, { action: 'status' }, null, { timeoutMs: 1000 })
-      if (live?.id !== session.id || !['starting', 'running', 'idle', 'awaiting_user', 'settling', 'closed'].includes(live.state)) {
-        return snapshot('unknown', 'unreachable')
-      }
-      return snapshot(live.state, 'connected', {
-        usage: live.usage === undefined ? session.usage : live.usage,
-        pendingApproval: live.pendingApproval,
-      })
-    } catch {
-      // A disconnected host or a timeout is not proof of a completed task.
-      return snapshot('unknown', 'unreachable')
-    }
-  }))
+    const listed = sessions(cwd);
+    return Promise.all(listed.map(async (session) => {
+        const base = { ...session, lastKnownState: session.state ?? null };
+        const snapshot = (state, connection, extra = {}) => ({ ...base, ...extra, state, connection,
+            fullyIdle: connection === 'connected' && state === 'idle', checkedAt: new Date().toISOString() });
+        if (session.state === 'closed')
+            return snapshot('closed', 'closed');
+        if (session.transport === 'console') {
+            try {
+                const live = externalStatus(session);
+                return snapshot(live.state, 'connected');
+            }
+            catch {
+                return snapshot('unknown', 'unreachable');
+            }
+        }
+        if (!['pty', 'stdio'].includes(session.transport || ''))
+            return snapshot('unknown', 'unverified');
+        try {
+            const raw = await sendTerminal(session.id, { action: 'status' }, null, { timeoutMs: 1000 });
+            const live = raw;
+            if (live?.id !== session.id || !live.state || !['starting', 'running', 'idle', 'awaiting_user', 'settling', 'closed'].includes(live.state)) {
+                return snapshot('unknown', 'unreachable');
+            }
+            return snapshot(live.state, 'connected', {
+                usage: live.usage === undefined ? session.usage : live.usage,
+                pendingApproval: live.pendingApproval,
+            });
+        }
+        catch {
+            // A disconnected host or a timeout is not proof of a completed task.
+            return snapshot('unknown', 'unreachable');
+        }
+    }));
 }
-
 const labels = { starting: '시작 중', running: '작업 중', idle: '대기', awaiting_user: '승인 대기',
-  settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' }
-const connections = { connected: '연결됨', closed: '종료됨', unreachable: '연결 확인 불가', unverified: '확인 미지원' }
-const safe = value => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ')
-
+    settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' };
+const connections = { connected: '연결됨', closed: '종료됨', unreachable: '연결 확인 불가', unverified: '확인 미지원' };
+const safe = (value) => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
 export function formatSessionStatus(listed) {
-  if (!listed.length) return '이 저장소에 등록된 로컬 세션이 없습니다.'
-  return ['axMap 세션 상태', ...listed.map(s => {
-    const usage = s.usage?.totalTokens == null ? '미확인' : `${s.usage.totalTokens}${s.maxTokens ? ` / ${s.maxTokens}` : ''}`
-    return `${safe(s.provider)}  ${safe(s.id)}\n  ${connections[s.connection] || '상태 미확인'} · ${labels[s.state] || '상태 미확인'}${s.role ? ` · ${safe(s.role)}` : ''}\n  확인된 누적 처리 토큰: ${usage}`
-  })].join('\n')
+    if (!listed.length)
+        return '이 저장소에 등록된 로컬 세션이 없습니다.';
+    return ['axMap 세션 상태', ...listed.map(s => {
+            const usage = s.usage?.totalTokens == null ? '미확인' : `${s.usage.totalTokens}${s.maxTokens ? ` / ${s.maxTokens}` : ''}`;
+            return `${safe(s.provider)}  ${safe(s.id)}\n  ${connections[s.connection] || '상태 미확인'} · ${labels[s.state] || '상태 미확인'}${s.role ? ` · ${safe(s.role)}` : ''}\n  확인된 누적 처리 토큰: ${usage}`;
+        })].join('\n');
 }

package/src/session-status.mts

@@ -0,0 +1,50 @@
+import { sessions } from './bridge.mjs'
+import { sendTerminal } from './terminal-bridge.mjs'
+import { externalStatus } from './external-console.mjs'
+import type { PublicSession, SessionSnapshot, SessionState, ConnectionState } from './session-types.mjs'
+
+/** Probe only the authenticated local control pipe. A saved idle/running record
+ * cannot establish that its host still exists; no model request is submitted. */
+export async function sessionStatus(cwd = process.cwd()): Promise<SessionSnapshot[]> {
+  const listed = sessions(cwd)
+  return Promise.all(listed.map(async session => {
+    const base = { ...session, lastKnownState: session.state ?? null }
+    const snapshot = (state: SessionState, connection: ConnectionState, extra: Partial<PublicSession> = {}): SessionSnapshot => ({ ...base, ...extra, state, connection,
+      fullyIdle: connection === 'connected' && state === 'idle', checkedAt: new Date().toISOString() })
+    if (session.state === 'closed') return snapshot('closed', 'closed')
+    if (session.transport === 'console') {
+      try {
+        const live = externalStatus(session)
+        return snapshot(live.state, 'connected')
+      } catch { return snapshot('unknown', 'unreachable') }
+    }
+    if (!['pty', 'stdio'].includes(session.transport || '')) return snapshot('unknown', 'unverified')
+    try {
+      const raw: unknown = await sendTerminal(session.id, { action: 'status' }, null, { timeoutMs: 1000 })
+      const live = raw as Partial<PublicSession> | null
+      if (live?.id !== session.id || !live.state || !['starting', 'running', 'idle', 'awaiting_user', 'settling', 'closed'].includes(live.state)) {
+        return snapshot('unknown', 'unreachable')
+      }
+      return snapshot(live.state, 'connected', {
+        usage: live.usage === undefined ? session.usage : live.usage,
+        pendingApproval: live.pendingApproval,
+      })
+    } catch {
+      // A disconnected host or a timeout is not proof of a completed task.
+      return snapshot('unknown', 'unreachable')
+    }
+  }))
+}
+
+const labels = { starting: '시작 중', running: '작업 중', idle: '대기', awaiting_user: '승인 대기',
+  settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' }
+const connections = { connected: '연결됨', closed: '종료됨', unreachable: '연결 확인 불가', unverified: '확인 미지원' }
+const safe = (value: unknown) => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ')
+
+export function formatSessionStatus(listed: readonly SessionSnapshot[]): string {
+  if (!listed.length) return '이 저장소에 등록된 로컬 세션이 없습니다.'
+  return ['axMap 세션 상태', ...listed.map(s => {
+    const usage = s.usage?.totalTokens == null ? '미확인' : `${s.usage.totalTokens}${s.maxTokens ? ` / ${s.maxTokens}` : ''}`
+    return `${safe(s.provider)}  ${safe(s.id)}\n  ${connections[s.connection] || '상태 미확인'} · ${labels[s.state] || '상태 미확인'}${s.role ? ` · ${safe(s.role)}` : ''}\n  확인된 누적 처리 토큰: ${usage}`
+  })].join('\n')
+}

package/src/session-types.mjs

@@ -0,0 +1,7 @@
+// Generated from src/session-types.mts. Edit the .mts source and run npm run build.
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function errorCode(error) {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
+}

package/src/session-types.mts

@@ -0,0 +1,119 @@
+/** Shared contracts for the local bridge. Runtime input checks still guard external data. */
+export type Provider = 'codex' | 'agy'
+export type Transport = 'console' | 'stdio' | 'pty' | 'agentapi'
+export type SessionState = 'starting' | 'running' | 'idle' | 'awaiting_user' | 'settling' | 'closed' | 'unknown'
+export type RequestState = 'sending' | 'submitted' | 'unknown' | 'completed' | 'failed' | 'superseded'
+export type ConnectionState = 'connected' | 'closed' | 'unreachable' | 'unverified'
+export type HookEvent = 'SessionStart' | 'PreInvocation' | 'Stop'
+
+export interface Usage {
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+  reasoningTokens: number
+  totalTokens: number
+  providerTotalTokens: number
+}
+export interface PendingApproval { id: string | number; method?: string; [key: string]: unknown }
+export interface SessionRecord {
+  id: string
+  provider: Provider
+  transport?: Transport
+  workspaces: string[]
+  repos: string[]
+  state?: SessionState
+  pid?: number
+  startedAt?: string
+  registeredAt: string
+  event?: string
+  fullyIdle?: boolean
+  conversationId?: string
+  transcript?: string
+  model?: string | null
+  role?: string
+  usage?: Usage | null
+  usageKnown?: boolean
+  maxTokens?: number
+  pendingApproval?: PendingApproval
+  executable?: string
+  address?: string
+  token?: string
+}
+export type PublicSession = Pick<SessionRecord, 'id' | 'provider' | 'workspaces' | 'model' | 'transport' |
+  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'>
+export interface SessionSnapshot extends PublicSession {
+  lastKnownState: SessionState | null
+  state: SessionState
+  connection: ConnectionState
+  checkedAt: string
+}
+export interface RequestRecord {
+  id: string
+  to: string
+  from: string
+  repo: string
+  prompt: string
+  createdAt: string
+  baseline: number | null
+  state: RequestState
+  receipt?: unknown
+  result?: unknown
+  error?: string
+  completedAt?: string
+  conversationId?: string
+  usage?: Usage | null
+}
+export interface DispatchOptions { to: string; prompt: string; cwd: string; from?: string; dialogueId?: string | null }
+export interface HookInput {
+  conversationId?: string
+  workspacePaths?: string[]
+  transcriptPath?: string
+  modelName?: string
+  fullyIdle?: boolean
+  model?: string
+  session_id?: string
+  prompt?: string
+  last_assistant_message?: unknown
+}
+export type LocalRequest = Pick<RequestRecord, 'id' | 'to' | 'prompt'> & Partial<Pick<RequestRecord, 'from'>>
+export type LocalMessage = { token?: string } & (
+  { action: 'status' } | { action: 'result'; id: string } |
+  { action: 'answer'; id: string | number; decision: string } |
+  { action: 'submit'; request: LocalRequest } |
+  { action: 'notice'; text: string } |
+  { action: 'hook'; event: string; input: HookInput }
+)
+export interface JobRecord {
+  id: string; to: string; state: RequestState; result?: unknown; error?: string; completedAt?: string
+  baseline?: Usage | null; baselineKnown?: boolean; usage?: Usage | null; conversationId?: string
+  turnId?: string; rawUsage?: unknown; observed?: boolean; interrupted?: boolean
+}
+export interface TranscriptEntry { type?: string; source?: string; status?: string; content?: unknown }
+export interface ConsoleSnapshot { pid: number; startedAt: string; screen: string; ignored?: false }
+export interface DialogueTurn {
+  index: number; to: string; from: string; requestId: string; state: RequestState
+  usage?: Usage | null; conversationId?: string; error?: string; message?: string; done?: boolean
+}
+export type DialogueState = 'queued' | 'running' | 'stopping' | 'failed' | 'cancelled' | 'token_limit' |
+  'unknown' | 'usage_unavailable' | 'message_limit' | 'invalid_response' | 'completed' | 'turn_limit'
+export interface DialogueRecord {
+  id: string; repo: string; left?: string; right?: string; state: DialogueState; createdAt?: string
+  limits?: { maxTurns: number; maxTokens: number; maxMessageChars: number; timeoutMs: number }
+  turns: DialogueTurn[]; usage?: Usage | null; knownUsage?: Usage | null; usagePending?: boolean
+  reason?: string; endedAt?: string
+}
+export interface DialogueOptions {
+  id?: string; left: string; right: string; prompt: string; cwd?: string
+  maxTurns?: number; maxTokens?: number; maxMessageChars?: number; timeoutMs?: number
+  onEvent?: (event: Record<string, unknown>) => void
+  dispatch?: (options: DispatchOptions) => RequestRecord
+  result?: (id: string, cwd: string) => RequestRecord
+  inventory?: (cwd: string) => PublicSession[]
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+export function errorCode(error: unknown): string | undefined {
+  return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined
+}