npm - axmap-cli - Versions diffs - 1.6.0 → 1.8.0 - Mend

axmap-cli 1.6.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/.claude/commands/axmap-view.md +9 -0
package/.claude/commands/pipeline.md +9 -0
package/README.ko.md +19 -0
package/README.md +19 -0
package/bin/axmap.mjs +3 -0
package/docs/VIEW.md +19 -0
package/mcp/README.md +3 -0
package/mcp/pipeline.html +34 -7
package/mcp/server.mjs +34 -3
package/package.json +3 -1
package/skills/axmap-view/SKILL.md +8 -0
package/skills/pipeline/SKILL.md +14 -0
package/src/bridge.mjs +1 -0
package/src/bridge.mts +1 -0
package/src/codex-connection.mjs +151 -0
package/src/codex-connection.mts +83 -0
package/src/managed-session.mjs +76 -14
package/src/managed-session.mts +57 -13
package/src/monitor-cli.mjs +8 -4
package/src/monitor-cli.mts +8 -4
package/src/monitor.mjs +5 -0
package/src/monitor.mts +4 -0
package/src/pipeline-graph.mjs +55 -0
package/src/pipeline-graph.mts +51 -0
package/src/pipeline-mcp.mjs +3 -1
package/src/pipeline-mcp.mts +3 -1
package/src/pipeline-web.mjs +56 -0
package/src/pipeline-web.mts +31 -0
package/src/session-mailbox.mjs +190 -0
package/src/session-mailbox.mts +157 -0
package/src/session-types.mts +2 -1
package/src/view.mjs +129 -0
package/src/view.mts +115 -0
package/tools/bridge.mjs +32 -0
package/tools/pipeline.mjs +10 -2
package/tools/run-tests.mjs +3 -1
package/tools/view.mjs +10 -0

package/src/pipeline-web.mjs ADDED Viewed

@@ -0,0 +1,56 @@
+// Generated from src/pipeline-web.mts. Edit the .mts source and run npm run build.
+/** Read-only loopback view for clients that cannot embed MCP Apps. */
+import http from 'node:http';
+import fs from 'node:fs';
+import { createMonitor } from './monitor.mjs';
+import { pipelineView } from './pipeline-mcp.mjs';
+export async function startPipelineWeb(cwd, port = 0) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error('port must be 0..65535');
+    const collect = createMonitor(cwd);
+    const html = fs.readFileSync(new URL('../mcp/pipeline.html', import.meta.url), 'utf8')
+        .replace('<html lang="ko">', '<html lang="ko" data-axmap-local="true">')
+        .replace('<script>', '<script>window.axmapLocalRead=()=>fetch("/api/snapshot",{cache:"no-store"}).then(r=>{if(!r.ok)throw new Error("Local observation failed");return r.json()});</script><script>');
+    let collecting = null, url = '';
+    const server = http.createServer(async (req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.headers.host !== new URL(url).host || req.headers.origin && req.headers.origin !== url || req.headers['sec-fetch-site'] === 'cross-site') {
+            res.writeHead(403);
+            res.end('Local origin required');
+            return;
+        }
+        if (req.method !== 'GET') {
+            res.writeHead(405);
+            res.end('Read-only');
+            return;
+        }
+        if (req.url === '/' || req.url === '/pipeline') {
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.end(html);
+            return;
+        }
+        if (req.url !== '/api/snapshot') {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        try {
+            // Concurrent browser refreshes share observation; none submit a model turn.
+            collecting ??= collect().finally(() => { collecting = null; });
+            const snapshot = await collecting;
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.end(JSON.stringify({ structuredContent: pipelineView(snapshot), isError: false }));
+        }
+        catch {
+            res.writeHead(503);
+            res.end(JSON.stringify({ isError: true, content: [{ type: 'text', text: 'Local observation failed' }] }));
+        }
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Local listener unavailable');
+    url = `http://127.0.0.1:${address.port}`;
+    return { url: `${url}/pipeline`, close: () => new Promise((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeIdleConnections(); }) };
+}

package/src/pipeline-web.mts ADDED Viewed

@@ -0,0 +1,31 @@
+/** Read-only loopback view for clients that cannot embed MCP Apps. */
+import http from 'node:http'
+import fs from 'node:fs'
+import { createMonitor } from './monitor.mjs'
+import { pipelineView } from './pipeline-mcp.mjs'
+export async function startPipelineWeb(cwd: string, port = 0) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('port must be 0..65535')
+  const collect = createMonitor(cwd)
+  const html = fs.readFileSync(new URL('../mcp/pipeline.html', import.meta.url), 'utf8')
+    .replace('<html lang="ko">', '<html lang="ko" data-axmap-local="true">')
+    .replace('<script>', '<script>window.axmapLocalRead=()=>fetch("/api/snapshot",{cache:"no-store"}).then(r=>{if(!r.ok)throw new Error("Local observation failed");return r.json()});</script><script>')
+  let collecting: ReturnType<typeof collect> | null = null, url = ''
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store'); res.setHeader('X-Content-Type-Options', 'nosniff')
+    if (req.headers.host !== new URL(url).host || req.headers.origin && req.headers.origin !== url || req.headers['sec-fetch-site'] === 'cross-site') { res.writeHead(403); res.end('Local origin required'); return }
+    if (req.method !== 'GET') { res.writeHead(405); res.end('Read-only'); return }
+    if (req.url === '/' || req.url === '/pipeline') { res.setHeader('Content-Type', 'text/html; charset=utf-8'); res.end(html); return }
+    if (req.url !== '/api/snapshot') { res.writeHead(404); res.end(); return }
+    try {
+      // Concurrent browser refreshes share observation; none submit a model turn.
+      collecting ??= collect().finally(() => { collecting = null })
+      const snapshot = await collecting
+      res.setHeader('Content-Type', 'application/json; charset=utf-8'); res.end(JSON.stringify({ structuredContent: pipelineView(snapshot), isError: false }))
+    } catch { res.writeHead(503); res.end(JSON.stringify({ isError: true, content: [{ type: 'text', text: 'Local observation failed' }] })) }
+  })
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve) })
+  const address = server.address()
+  if (!address || typeof address === 'string') throw new Error('Local listener unavailable')
+  url = `http://127.0.0.1:${address.port}`
+  return { url: `${url}/pipeline`, close: () => new Promise<void>((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeIdleConnections() }) }
+}

package/src/session-mailbox.mjs ADDED Viewed

@@ -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 ADDED Viewed

@@ -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-types.mts CHANGED Viewed

@@ -40,7 +40,7 @@ export interface SessionRecord {
   token?: string
 }
 export type PublicSession = Pick<SessionRecord, 'id' | 'provider' | 'workspaces' | 'model' | 'transport' |
-  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval'>
+  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'>
 export interface SessionSnapshot extends PublicSession {
   lastKnownState: SessionState | null
   state: SessionState
@@ -80,6 +80,7 @@ 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 {

package/src/view.mjs ADDED Viewed

@@ -0,0 +1,129 @@
+// Generated from src/view.mts. Edit the .mts source and run npm run build.
+/** Read-only terminal view of observed sessions, claims, mail and events. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { bridgeHome } from './bridge.mjs';
+import { createMonitor, fitTerminal, terminalText } from './monitor.mjs';
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export function createView(cwd, options = {}) {
+    const collect = createMonitor(cwd, options);
+    return async () => {
+        const snapshot = await collect(), mail = [], mailIssues = [];
+        if (snapshot.issues.some(issue => issue.startsWith('세션 확인:')))
+            mailIssues.push('받은 편지함: 세션 목록을 확인하지 못함');
+        // Reading does not create mailboxes, expire records, collect messages or wake a model.
+        for (const session of snapshot.sessions.slice(0, 100)) {
+            if (!uuid.test(session.id)) {
+                mailIssues.push('받은 편지함: 세션 ID 확인 필요');
+                continue;
+            }
+            const file = path.join(bridgeHome(), 'mailboxes', `${session.id}.json`);
+            try {
+                if (fs.statSync(file).size > 1024 * 1024)
+                    throw new Error('파일 크기 초과');
+                const box = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (!box || typeof box !== 'object' || box.version !== 1 || !Array.isArray(box.messages))
+                    throw new Error('형식 오류');
+                for (const m of box.messages) {
+                    if (!m || typeof m !== 'object')
+                        throw new Error('메시지 형식 오류');
+                    const entry = m;
+                    if (entry.repo !== snapshot.repo || entry.state !== 'queued')
+                        continue;
+                    if (entry.to !== session.id || typeof entry.from !== 'string' || typeof entry.text !== 'string' || typeof entry.expiresAt !== 'string' || !Number.isFinite(Date.parse(entry.expiresAt)))
+                        throw new Error('메시지 형식 오류');
+                    if (Date.parse(entry.expiresAt) <= Date.now())
+                        continue;
+                    mail.push({ to: session.id, from: entry.from, topic: typeof entry.topic === 'string' ? entry.topic : '', text: entry.text });
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    mailIssues.push(`받은 편지함 ${session.id.slice(0, 8)}: 읽기 실패`);
+            }
+        }
+        if (snapshot.sessions.length > 100)
+            mailIssues.push('받은 편지함: 앞의 세션 100개만 확인');
+        return { ...snapshot, mail, mailIssues };
+    };
+}
+const labels = { idle: '대기', running: '작업 중', closed: '종료', awaiting_user: '승인 대기', unknown: '상태 미확인', starting: '시작 중', settling: '대기 전환 중' };
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function cells(value) {
+    return [...segmenter.segment(value)].reduce((n, { segment }) => {
+        const cp = segment.codePointAt(0) || 0;
+        return n + (/\p{Extended_Pictographic}/u.test(segment) || cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x20000) ? 2 : /^\p{Mark}+$/u.test(segment) ? 0 : 1);
+    }, 0);
+}
+function pad(value, width) {
+    const text = fitTerminal(value, Math.max(0, width));
+    return text + ' '.repeat(Math.max(0, width - cells(text)));
+}
+export function renderView(snapshot, { columns = 100, rows = 36, color = false, frame = 0 } = {}) {
+    const width = Math.max(1, Math.floor(columns)), height = Math.max(1, Math.floor(rows)), lines = [];
+    if (width < 20)
+        return [fitTerminal('axMap · 화면이 좁습니다', width), fitTerminal('q 종료', width)].slice(0, height).join('\n');
+    const view = snapshot;
+    const palette = {
+        text: '194;197;205', muted: '137;140;150', border: '78;82;94', accent: '172;158;199',
+        claude: '207;157;134', codex: '143;174;214', agy: '139;187;165', warning: '212;171;125',
+    };
+    const paint = (text, tone) => color ? `\x1b[38;2;${palette[tone]}m${text}\x1b[0m` : text;
+    const line = (text, tone = 'text') => lines.push(paint(fitTerminal(text, width), tone));
+    const paintBoxLine = (text, index, last, tone, colorStatus = false) => {
+        if (index === 0 || index === last)
+            return paint(text, 'border');
+        return paint(text.slice(0, 1), 'border') + paint(text.slice(1, -1), index === 1 || colorStatus && index === 3 ? tone : 'text') + paint(text.slice(-1), 'border');
+    };
+    const box = (title, content, w) => {
+        const n = Math.max(1, w - 2);
+        return [`┌${'─'.repeat(n)}┐`, ...[title, ...content].map(s => `│${pad(' ' + terminalText(s), n)}│`), `└${'─'.repeat(n)}┘`];
+    };
+    line('axMap VIEW · 실제 로컬 관측', 'accent');
+    line(`${snapshot.cwd} · ${snapshot.checkedAt}`, 'muted');
+    const sessions = [...snapshot.sessions].sort((a, b) => Number(b.connection === 'connected') - Number(a.connection === 'connected')).slice(0, 3);
+    const cols = width >= 90 ? 3 : width >= 58 ? 2 : 1;
+    const cardWidth = Math.max(3, Math.floor((width - (cols - 1) * 2) / cols));
+    const cards = sessions.map(s => {
+        const active = snapshot.requests.some(r => r.to === s.id && ['sending', 'submitted'].includes(r.state));
+        const connection = { closed: '연결 종료', unreachable: '연결 불가', unverified: '연결 미확인' };
+        const state = s.connection === 'connected' ? labels[s.state] || '상태 미확인' : connection[s.connection] || '연결 미확인';
+        return box(`${s.provider.toUpperCase()} · ${s.id.slice(0, 8)}`, [s.role || '역할 미확인', `${active ? ['◐', '◓', '◑', '◒'][frame % 4] : '○'} ${state}`, s.model || '모델 미확인'], cardWidth);
+    });
+    for (let start = 0; start < cards.length; start += cols) {
+        const group = cards.slice(start, start + cols);
+        for (let i = 0; i < group[0].length; i++)
+            lines.push(group.map((card, k) => {
+                const provider = sessions[start + k].provider.toLowerCase();
+                const tone = provider === 'codex' ? 'codex' : provider === 'agy' ? 'agy' : provider === 'claude' ? 'claude' : 'accent';
+                return paintBoxLine(card[i], i, card.length - 1, tone, true);
+            }).join('  '));
+    }
+    if (!sessions.length)
+        line('등록된 세션 없음 · bridge 연결 후 표시', 'muted');
+    const claims = snapshot.claims.flatMap(c => c.paths.map(p => `${terminalText(c.agent)} · ${terminalText(p)}`));
+    const mails = view.mail?.map(m => `${terminalText(m.from)} → ${m.to.slice(0, 8)} · ${terminalText(m.topic || m.text)}`) || [];
+    const left = [`LEDGER · 현재 선점 ${snapshot.claims.length}건`, ...(claims.slice(0, 4).length ? claims.slice(0, 4) : ['현재 선점 없음'])];
+    const right = [`MAILBOX · ${view.mailIssues?.length ? '일부 확인 실패' : `대기 ${view.mail?.length ?? 0}건`}`, ...(mails.slice(0, 4).length ? mails.slice(0, 4) : [view.mailIssues?.length ? '대기 건수 미확인' : '대기 메시지 없음'])];
+    if (width >= 58) {
+        const lw = Math.floor((width - 2) / 2), rw = width - lw - 2, count = Math.max(left.length, right.length);
+        const a = box(left[0], Array.from({ length: count - 1 }, (_, i) => left[i + 1] || ''), lw);
+        const b = box(right[0], Array.from({ length: count - 1 }, (_, i) => right[i + 1] || ''), rw);
+        a.forEach((v, i) => lines.push(paintBoxLine(v, i, a.length - 1, 'accent') + '  ' + paintBoxLine(b[i], i, b.length - 1, 'accent')));
+    }
+    else {
+        const a = box(left[0], left.slice(1), Math.max(3, width));
+        const b = box(right[0], right.slice(1), Math.max(3, width));
+        lines.push(...a.map((x, i) => paintBoxLine(x, i, a.length - 1, 'accent')));
+        lines.push(...b.map((x, i) => paintBoxLine(x, i, b.length - 1, 'accent')));
+    }
+    line('── 최근 관측 이벤트 ──', 'muted');
+    for (const e of snapshot.events.slice(0, 4))
+        line(`${terminalText(e.at.slice(11, 19))}  ${terminalText(e.label)}`);
+    if (!snapshot.events.length)
+        line('기록된 이벤트 없음', 'muted');
+    for (const issue of [...snapshot.issues, ...(view.mailIssues || [])].slice(0, 2))
+        line(`확인 필요: ${issue}`, 'warning');
+    const footer = paint(fitTerminal('q / Esc 종료 · 작업은 계속됨 · 모델 호출 없음', width), 'muted');
+    return [...lines.slice(0, Math.max(0, height - 1)), footer].join('\n');
+}