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

axmap-cli 1.6.0 → 1.7.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 (29) hide show

package/.claude/commands/pipeline.md +9 -0
package/README.ko.md +17 -0
package/README.md +17 -0
package/mcp/README.md +3 -0
package/mcp/pipeline.html +34 -7
package/mcp/server.mjs +34 -3
package/package.json +2 -1
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 +5 -3
package/src/monitor-cli.mts +5 -3
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/tools/bridge.mjs +32 -0
package/tools/pipeline.mjs +10 -2

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/tools/bridge.mjs CHANGED Viewed

@@ -8,6 +8,7 @@ import { runDialogue, startBackgroundDialogue, dialogueResult, stopDialogue } fr
 import { sendTerminal } from '../src/terminal-bridge.mjs'
 import { sessionStatus, formatSessionStatus } from '../src/session-status.mjs'
 import { attachConsole } from '../src/external-console.mjs'
+import { postMail, collectMail, flushMail } from '../src/session-mailbox.mjs'
 const args = process.argv.slice(2)
 const [command] = args
@@ -15,14 +16,31 @@ const option = (name) => { const i = args.indexOf(`--${name}`); return i < 0 ? u
 const output = (value) => console.log(JSON.stringify(value, null, 2))
 try {
   switch (command) {
+    case 'message': {
+      const r = postMail({ to: option('to'), cwd: process.cwd(), text: fs.readFileSync(0, 'utf8'),
+        priority: option('priority') || 'boundary', reason: option('reason'), topic: option('topic'), key: option('key'),
+        ttlSeconds: Number(option('ttl-seconds') || 3600) })
+      output(r)
+      if (r.delivery && !['submitted', 'empty'].includes(r.delivery.state)) process.exitCode = 2
+      break
+    }
+    case 'mailbox': output(collectMail({ to: option('to'), cwd: process.cwd(), at: option('at'), take: args.includes('--take'), all: args.includes('--all') })); break
+    case 'flush': {
+      const r = flushMail({ to: option('to'), cwd: process.cwd(), at: option('at') }); output(r)
+      if (['unknown', 'deferred'].includes(r.state)) process.exitCode = 2
+      break
+    }
     case 'attach': output(attachConsole({ pid: Number(option('pid')), cwd: process.cwd() })); break
+    case 'connect':
     case 'serve': {
       const provider = args[1]
       if (!['codex', 'agy'].includes(provider)) throw new Error('axmap bridge serve codex|agy를 사용하세요.')
       const binary = resolveBin(provider)
       if (!binary) throw new Error(`${provider} 실행 파일을 찾지 못했습니다.`)
       const [executable, ...prefix] = provider === 'codex' ? codexInvocation(binary) : [binary]
+      if (command === 'connect' && (!option('thread') || !option('socket'))) throw new Error('bridge connect codex --thread <기존 UUID> --socket <로컬 경로>가 필요합니다.')
       const session = await startManagedSession({ provider, executable, prefix, model: option('model'), role: option('role'),
+        ...(command === 'connect' ? { existingThreadId: option('thread'), socketPath: option('socket'), observeActive: args.includes('--observe') } : {}),
         maxTokens: Number(option('max-tokens') || 100000), onEvent: output })
       output({ event: 'connected', ...session, exited: undefined, close: undefined })
       process.once('SIGINT', session.close); process.once('SIGTERM', session.close)
@@ -41,6 +59,7 @@ try {
       break
     }
     case 'dialogue': output(dialogueResult(args[1])); break
+    case 'notice': output(await sendTerminal(option('to'), { action: 'notice', text: fs.readFileSync(0, 'utf8') })); break
     case 'stop': output(stopDialogue(args[1])); break
     case 'answer': output(await sendTerminal(option('to'), { action: 'answer', id: option('request'), decision: option('decision') })); break
     case 'install':
@@ -78,6 +97,9 @@ try {
       console.log(`axMap 로컬 세션 연결 — 관리형 Codex/agy와 제한된 자동 대화
 axmap bridge serve codex|agy [--model 이름] [--role 역할] [--max-tokens 100000]
     명시적으로 새 관리형 CLI를 시작합니다. 기존 창에 임의로 붙지 않습니다.
+axmap bridge connect codex --thread <기존 UUID> --socket <로컬 socket> [--role 역할] [--observe]
+    실행 중인 공식 Codex daemon의 기존 idle 대화에 연결합니다. 새 모델/대화를 만들지 않습니다.
+    --observe는 active 대화에도 관측만 연결하며 idle 전환 전에는 새 요청을 거절합니다.
 axmap bridge chat --left <UUID> --right <UUID> [--max-turns 4] [--max-tokens 50000]
     stdin 작업을 자동 중계합니다. 기본 메시지 한도 2000자, 대기 중 모델 호출 없음.
 axmap bridge answer --to <UUID> --request <ID> --decision accept|decline|cancel
@@ -88,9 +110,19 @@ axmap bridge stop <대화 UUID>                        추가 중계 중단 (이
 axmap bridge install --experimental --executable <agy 절대 경로>   연결 훅 실험
 axmap bridge uninstall                             추가한 연결 훅 해제
 axmap bridge sessions                              이 repo에 연결된 세션
+axmap bridge notice --to <UUID>                    stdin 안내를 기존 Codex 문맥에 기록 (모델 호출 없음)
 axmap bridge attach --pid <PID>                    이미 실행한 Windows agy 콘솔을 현재 repo에 연결
 axmap bridge status [--json]                        로컬 연결·작업·승인 대기·종료 상태 조회 (모델 호출 없음)
 axmap bridge send --to <세션 UUID> [--wait-ms 30000] 본문은 stdin. 전달 후 지정 시간까지 로컬에서 회신 대기
+    send는 실행용 저수준 명령입니다. 일반 협업 알림에는 message를 사용하세요.
+axmap bridge message --to <UUID> [--topic <갱신 주제>] [--key <중복 방지 키>] [--ttl-seconds 3600]
+    stdin 일반 메시지를 큐에 저장합니다. 모델 호출·새 턴 없음. 같은 발신자의 대기 중 topic만 최신으로 합칩니다.
+axmap bridge message --to <UUID> --priority immediate --reason stop|data-loss|work-invalidated
+    긴급 사유를 보존하고 즉시 전달을 시도합니다. busy면 deferred, unknown이면 재전송 금지.
+axmap bridge mailbox --to <UUID> [--all]
+    읽기만 합니다. --take --at checkpoint로 작업 경계에서 묶음 회수 (모델 호출 없음).
+axmap bridge flush --to <UUID> --at task-complete|test-complete|experiment-complete|checkpoint
+    필요할 때만 idle 수신자에게 큐를 한 요청으로 전달. 자동 감시·중단·재전송 없음.
 axmap bridge result <요청 UUID> [--wait-ms 30000]    제출/완료/불명 상태와 결과. 대기 중 모델 호출 없음
 관리형 stdio: Codex App Server / agy stream-json. PTY와 agentapi는 별도 실험 경로입니다.`)
       break

package/tools/pipeline.mjs CHANGED Viewed

@@ -3,14 +3,22 @@ import fs from 'node:fs'
 import { runPipelineOperation } from '../src/pipeline-mcp.mjs'
 import { errorMessage } from '../src/session-types.mjs'
 import { installPipelineStatusline, pipelineStatusline } from '../src/pipeline-statusline.mjs'
+import { runMonitor } from '../src/monitor-cli.mjs'
+import { startPipelineWeb } from '../src/pipeline-web.mjs'
 const output = value => process.stdout.write(JSON.stringify(value) + '\n')
 let cancelled = false
 process.on('message', message => { if (message?.type === 'cancel-observation') cancelled = true })
 try {
   const action = process.argv[2]
   const option = name => { const at = process.argv.indexOf(`--${name}`); return at < 0 ? undefined : process.argv[at + 1] }
-  if (!action || action === '--help' || action === '-h') {
-    console.log('axmap pipeline install-statusline --provider claude|agy\naxmap pipeline uninstall-statusline --provider claude|agy\n현재 CLI의 상태줄에 axMap 진행을 표시합니다. 기존 명령은 보존하며 새 창은 열지 않습니다.\n대화 안 패널은 MCP ax_pipeline, 진행 알림은 ax_pipeline_watch를 사용하세요.')
+  if (process.argv.includes('--web')) {
+    const web = await startPipelineWeb(option('cwd') || process.cwd(), Number(option('port') || 0))
+    console.log(JSON.stringify({ url: web.url, mode: 'read-only-local-pipeline' }))
+    const close = () => { void web.close() }; process.once('SIGINT', close); process.once('SIGTERM', close)
+  } else if (!action || action === 'view' || action.startsWith('--') && !['--help', '-h'].includes(action)) {
+    await runMonitor(['--graph', ...process.argv.slice(action === 'view' ? 3 : 2)])
+  } else if (action === '--help' || action === '-h') {
+    console.log('axmap pipeline [view] [--cwd <repo>] [--once | --json]\naxmap pipeline --web [--cwd <repo>] [--port <local-port>]\n세션 그래프 · 역할 · 실제 요청/응답 · 토큰 · 이벤트를 표시합니다. TTY에서는 실시간 갱신합니다.\naxmap pipeline install-statusline --provider claude|agy\naxmap pipeline uninstall-statusline --provider claude|agy\n상태줄 설치는 기존 명령을 보존하며 새 창은 열지 않습니다.\n대화 안 패널은 MCP ax_pipeline, 진행 알림은 ax_pipeline_watch를 사용하세요.')
   } else if (action === 'install-statusline' || action === 'uninstall-statusline') {
     console.log(JSON.stringify(installPipelineStatusline(option('provider'), option('home'), action === 'uninstall-statusline'), null, 2))
   } else if (action === 'statusline') {