@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/faces/nodes.js

@@ -0,0 +1,171 @@
+/** Identity bodies carry layers of up to 3000 CJK characters; the 10 KiB control default is too small. */
+export const NODE_BODY_MAX_BYTES = 32_000;
+/** §8-2: identity writes need the configured apiKey in the header — loopback is not enough, and no key means no identity writes. */
+export function identityVerdict(apiKey, presented, secretEqual) {
+    if (apiKey === '')
+        return { ok: false, status: 403, error: 'identity writes require apiKey (node-identity §8-2): configure apiKey on this host first' };
+    if (typeof presented !== 'string' || !secretEqual(presented, apiKey))
+        return { ok: false, status: 401, error: 'unauthorized: X-API-Key required for identity writes (loopback is not enough)' };
+    return { ok: true };
+}
+const STATUS = { 'bad-request': 400, 'not-found': 404, conflict: 409, quota: 413, cap: 409, unavailable: 503 };
+/** One POST body → status + payload. Pure: the route below only does I/O and the identity gate. */
+export function nodeAction(store, binder, tasks, reviews, raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return { status: 400, payload: { ok: false, error: 'body must be a JSON object' } };
+    const body = raw;
+    const by = typeof body.by === 'string' && body.by.trim() !== '' ? `human:${body.by.trim().slice(0, 64)}` : 'human:owner';
+    const name = typeof body.name === 'string' ? body.name : '';
+    const answer = (result) => result.ok
+        ? { status: 200, payload: { ok: true, value: result.value } }
+        : { status: STATUS[result.code], payload: { ok: false, error: result.error, code: result.code } };
+    switch (body.action) {
+        case 'create': return answer(store.create(body, by));
+        case 'update': return answer(store.update(name, { ...body, name: body.rename }));
+        case 'archive': {
+            const archived = store.archive(name);
+            if (archived.ok) {
+                binder.nodeArchived(name);
+                tasks.dropNode(name);
+                reviews.dropNode(name);
+            }
+            return answer(archived);
+        }
+        case 'write-core': return answer(store.writeLayer(name, 'core', { core: body.text }, { expectedSha: body.expected_sha256, reason: body.reason, by, via: 'host-face' }));
+        case 'write-mutable': return answer(store.writeLayer(name, 'mutable', body.sections, { expectedSha: body.expected_sha256, reason: body.reason, by, via: 'host-face' }));
+        case 'rollback':
+            if (body.layer !== 'core' && body.layer !== 'mutable')
+                return { status: 400, payload: { ok: false, error: "layer must be 'core' or 'mutable'" } };
+            return answer(store.rollback(name, body.layer, body.to, { expectedSha: body.expected_sha256, reason: body.reason, by }));
+        case 'bind': return answer(binder.bind(typeof body.session === 'string' ? body.session : '', name, by));
+        case 'unbind': return answer(binder.unbind(typeof body.session === 'string' ? body.session : ''));
+        case 'track': {
+            // §6 归因: the pointer records the node's versions at the moment it is tracked.
+            const node = store.get(name);
+            if (node === undefined)
+                return { status: 404, payload: { ok: false, error: `no node ${name}` } };
+            return answer(tasks.track(name, body.ref, { core: node.prompt.core_version, mutable: node.prompt.mutable_version }, by));
+        }
+        case 'untrack': return answer(tasks.untrack(name, body.ref));
+        case 'review-approve': {
+            // N4: a human applies a parked self-update. By default its own CAS sha still has to match (409 keeps it
+            // queued); `rebase: true` is the human's explicit choice to apply the proposed section onto the CURRENT
+            // version after reading the diff the GET view shows (current section text beside the proposal).
+            const item = typeof body.id === 'string' ? reviews.get(body.id) : undefined;
+            if (item === undefined)
+                return { status: 404, payload: { ok: false, error: `no review item ${String(body.id)}` } };
+            const expectedSha = body.rebase === true ? store.get(item.node)?.prompt.mutable_sha256 ?? '' : item.expected_sha256;
+            const written = store.writeLayer(item.node, 'mutable', { [item.section]: item.text }, { expectedSha, reason: item.reason, by: `${by} approved${body.rebase === true ? ' (rebased)' : ''} node:${item.session}`, via: 'review-approved' });
+            if (!written.ok)
+                return answer(written);
+            const removed = reviews.remove(item.id);
+            return { status: 200, payload: { ok: true, value: written.value, ...(removed.ok ? {} : { queue_warning: removed.error }) } };
+        }
+        case 'review-reject': return answer(typeof body.id === 'string' ? reviews.remove(body.id) : { ok: false, code: 'bad-request', error: 'id is required' });
+        default: return { status: 400, payload: { ok: false, error: 'action must be create | update | archive | write-core | write-mutable | rollback | bind | unbind | track | untrack | review-approve | review-reject' } };
+    }
+}
+/**
+ * GET view: the roster with the bindings (and what each live session froze at mount), or one node
+ * with its version numbers and current layers. `current` only shows a version that passes the shape
+ * and sha checks (`null` otherwise) — the same reading a mount uses.
+ */
+export function nodeView(store, bindings, binder, tasks, reviews, name, assembled = new Map()) {
+    if (name === null || name === '') {
+        return {
+            status: 200,
+            payload: {
+                ok: true, nodes: store.list(), read_only: store.readOnly, dropped: store.dropped,
+                // #174: `assembled` is what the session's prompt really carries; `sections_missing` flags a mounted
+                // node whose sections a `complete` preset dropped (the workbench hint reads it).
+                bindings: bindings.list().map(b => {
+                    const seen = assembled.get(b.session);
+                    return { ...b, mounted: binder.mounted(b.session) ?? null, ...(seen !== undefined ? { assembled: seen, sections_missing: !seen.core || !seen.mutable } : {}) };
+                }),
+                bindings_read_only: bindings.readOnly,
+                reviews: reviews.list(),
+                reviews_read_only: reviews.readOnly,
+            },
+        };
+    }
+    const node = store.get(name);
+    if (node === undefined)
+        return { status: 404, payload: { ok: false, error: `no node ${name}` } };
+    return {
+        status: 200,
+        payload: {
+            ok: true, node,
+            versions: { core: store.versions(name, 'core'), mutable: store.versions(name, 'mutable') },
+            current: {
+                core: store.current(name, 'core') ?? null,
+                mutable: store.current(name, 'mutable') ?? null,
+            },
+            tasks: tasks.list(name),
+            tasks_read_only: tasks.readOnly,
+            // Each parked write beside the section text it would replace (the diff the human approves).
+            reviews: reviews.list(name).map(r => ({ ...r, current_text: store.current(name, 'mutable')?.sections[r.section] ?? '' })),
+        },
+    };
+}
+export function registerNodeFaces(webServer, d) {
+    const { ctx, nodeStore, bindings, binder, tasks, reviews, controlRoute, readJsonBody } = d;
+    const send = (res, status, payload) => {
+        const text = JSON.stringify(payload);
+        res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(text), 'Cache-Control': 'no-store' });
+        res.end(text);
+    };
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/__dsh_a2a/nodes',
+        handler: (req, res) => {
+            if (req.method === 'GET') {
+                controlRoute((r, s) => {
+                    try {
+                        const name = new URL(r.url ?? '/', 'http://x').searchParams.get('name');
+                        // #174: the roster view assembles each mounted session's prompt (async), then renders.
+                        void (async () => {
+                            const assembled = new Map();
+                            if (name === null || name === '') {
+                                for (const b of bindings.list()) {
+                                    const seen = await binder.assembled(b.session);
+                                    if (seen !== undefined)
+                                        assembled.set(b.session, seen);
+                                }
+                            }
+                            const view = nodeView(nodeStore, bindings, binder, tasks, reviews, name, assembled);
+                            send(s, view.status, view.payload);
+                        })().catch((error) => {
+                            d.logger.warn('nodes face: %s', String(error));
+                            if (!s.headersSent)
+                                send(s, 500, { ok: false, error: 'internal error' });
+                        });
+                    }
+                    catch (error) {
+                        d.logger.warn('nodes face: %s', String(error));
+                        if (!s.headersSent)
+                            send(s, 500, { ok: false, error: 'internal error' });
+                    }
+                })(req, res);
+                return;
+            }
+            if (req.method !== 'POST')
+                return send(res, 405, { ok: false, error: 'GET or POST' });
+            const verdict = identityVerdict(d.apiKey(), req.headers['x-api-key'], d.secretEqual);
+            if (!verdict.ok)
+                return send(res, verdict.status, { ok: false, error: verdict.error });
+            readJsonBody(req, res, (body) => {
+                // This runs in the body reader's 'end' callback, outside the web server's handler guard:
+                // a throw here would be an uncaughtException and take the host down.
+                try {
+                    const out = nodeAction(nodeStore, binder, tasks, reviews, body);
+                    send(res, out.status, out.payload);
+                }
+                catch (error) {
+                    d.logger.warn('nodes face: %s', String(error));
+                    if (!res.headersSent)
+                        send(res, 500, { ok: false, error: 'internal error' });
+                }
+            }, NODE_BODY_MAX_BYTES);
+        },
+    }), 'a2a: nodes route');
+}

package/lib/faces/session-log.js

@@ -0,0 +1,162 @@
+import { TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT } from "../session-transcript.js";
+/**
+ * Register the local transcript reader and the remote-log proxy on the shared web server.
+ * @param d - the captures listed on {@link SessionLogFaceDeps}.
+ */
+export function registerSessionLogFaces(webServer, d) {
+    const { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, directoryPeerCandidates, memoizedCardFetch } = d;
+    // Session transcript reader (0.6.11): the workbench inspector shows the
+    // tail of a LOCAL node's own conversation log inline — owner ruling
+    // 2026-10-20 banned navigation, and reading is the need jumps used to
+    // serve. The id gate is artifact existence under this host's sessions
+    // tree — reading is a host-workbench concern, not a network-membership
+    // concern, so archived and never-joined sessions stay readable while the
+    // network faces keep their own visibility rules. Path shape is still
+    // checked (no '/', '\', '..') and the tree never leaves <dshHome>/sessions.
+    // Without an id the same face lists readable sessions (newest activity
+    // first, capped) so the workbench directory can offer log rows even when
+    // the network directory shows none. Caps mirror session-transcript.ts.
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/__dsh_a2a/session-log',
+        handler: controlRoute((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://x');
+            const id = url.searchParams.get('id') ?? '';
+            const limitArg = Number(url.searchParams.get('limit') ?? TRANSCRIPT_DEFAULT_LIMIT);
+            const limit = Number.isFinite(limitArg) ? Math.max(1, Math.min(TRANSCRIPT_MAX_LIMIT, Math.floor(limitArg))) : TRANSCRIPT_DEFAULT_LIMIT;
+            let result;
+            if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+                result = { ok: false, error: 'id is required' };
+            }
+            else if (id === '') {
+                // Listing face: every session directory holding a log artifact.
+                try {
+                    const rows = scanSessionLogList();
+                    result = { ok: true, count: rows.length, sessions: rows.slice(0, 50) };
+                }
+                catch (error) {
+                    result = { ok: false, error: `transcript list failed: ${error instanceof Error ? error.message : String(error)}` };
+                }
+            }
+            else {
+                try {
+                    const tail = readSessionLogTail(id, limit);
+                    if (!tail.ok)
+                        result = { ok: false, error: tail.error };
+                    else
+                        result = { ok: true, id: tail.id, count: tail.messages.length, messages: tail.messages };
+                }
+                catch (error) {
+                    result = { ok: false, error: `transcript failed: ${error instanceof Error ? error.message : String(error)}` };
+                }
+            }
+            const payload = JSON.stringify(result);
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+            res.end(payload);
+        }),
+    }), 'a2a: session-log route');
+    // 0.6.15: the local proxy for REMOTE session logs. The workbench runs
+    // in this host's browser page, so cross-host reads must originate from
+    // this host (no CORS, one trust boundary). ?team=<zone/id8> resolves
+    // directory candidates that publish that team (same walk as routing);
+    // ?peer=<base-url> targets one tracked peer directly and MUST name a
+    // URL already in the peer store — the proxy never fetches an
+    // arbitrary address. The caller label we present is config.team (this
+    // node's own zone handle, the same host face quick-dispatch uses).
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/__dsh_a2a/remote-session-log',
+        handler: controlRoute(async (req, res) => {
+            const url = new URL(req.url ?? '/', 'http://x');
+            const team = url.searchParams.get('team') ?? '';
+            const peer = url.searchParams.get('peer') ?? '';
+            const id = url.searchParams.get('id') ?? '';
+            const limitArg = Number(url.searchParams.get('limit') ?? TRANSCRIPT_DEFAULT_LIMIT);
+            const limit = Number.isFinite(limitArg) ? Math.max(1, Math.min(TRANSCRIPT_MAX_LIMIT, Math.floor(limitArg))) : TRANSCRIPT_DEFAULT_LIMIT;
+            const finish = (body) => {
+                const payload = JSON.stringify(body);
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                res.end(payload);
+            };
+            if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+                finish({ ok: false, error: 'id is required' });
+                return;
+            }
+            const trackedPeers = new Set(peerStore.list().map(entry => entry.replace(/\/+$/, '')));
+            let targets;
+            if (peer !== '') {
+                const normalized = peer.replace(/\/+$/, '');
+                if (!trackedPeers.has(normalized)) {
+                    finish({ ok: false, error: 'unknown peer on this node — the proxy only reads tracked peers' });
+                    return;
+                }
+                targets = [normalized];
+            }
+            else if (team !== '') {
+                const failures = [];
+                targets = await directoryPeerCandidates(memoizedCardFetch(), team, failures);
+                if (targets.length === 0) {
+                    finish({ ok: false, error: `no directory candidate publishes team "${team}"${failures.length > 0 ? ` (${failures.slice(0, 3).join('; ')})` : ''}` });
+                    return;
+                }
+            }
+            else {
+                finish({ ok: false, error: 'team or peer is required' });
+                return;
+            }
+            // 0.6.16: a team-handle read without an explicit id names a NODE, not
+            // a session. The handle suffix (zone/<id8>) is the first 8 hex of the
+            // peer-side session id (sessionTeamOf), so resolve the listing once
+            // and pick that session — bare zone teams fall back to the newest.
+            // An explicit id (peer drill) short-circuits this.
+            let resolvedId = id;
+            if (resolvedId === '' && team !== '') {
+                const suffix = team.includes('/') ? team.slice(team.lastIndexOf('/') + 1) : '';
+                for (const base of targets) {
+                    const listUrl = new URL('/a2a/log', base);
+                    listUrl.searchParams.set('caller_session', config.team);
+                    try {
+                        const listResponse = await peerFetch(listUrl, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } });
+                        const listBody = await listResponse.json().catch(() => ({ ok: false, error: `peer answered HTTP ${listResponse.status}` }));
+                        if (listResponse.ok && listBody.ok === true && Array.isArray(listBody.sessions)) {
+                            const picked = suffix !== '' ? listBody.sessions.find(row => row.id.includes(suffix)) : listBody.sessions[0];
+                            if (picked !== undefined) {
+                                resolvedId = picked.id;
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        // listing failed on this candidate — the tail attempt below
+                        // will surface the honest error for the same base
+                    }
+                }
+                if (resolvedId === '') {
+                    finish({ ok: false, error: `no readable session on this peer matches "${team}"` });
+                    return;
+                }
+            }
+            const attempts = [];
+            for (const base of targets) {
+                const target = new URL('/a2a/log', base);
+                target.searchParams.set('caller_session', config.team);
+                if (resolvedId !== '')
+                    target.searchParams.set('id', resolvedId);
+                target.searchParams.set('limit', String(limit));
+                try {
+                    const response = await peerFetch(target, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } });
+                    const body = await response.json().catch(() => ({ ok: false, error: `peer answered HTTP ${response.status}` }));
+                    if (response.ok && body.ok === true) {
+                        finish({ ...body, via: base });
+                        return;
+                    }
+                    attempts.push(`${base}: ${body.error ?? `HTTP ${response.status}`}`);
+                }
+                catch (error) {
+                    attempts.push(`${base}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            finish({ ok: false, error: `remote log unavailable — ${attempts.join(' | ')}` });
+        }),
+    }), 'a2a: remote-session-log proxy route');
+}