super-dsh 0.1.5 → 0.1.9

package/superd-hub/dist/fusion-transport.js

@@ -48,9 +48,9 @@
  * so cordis's FIFO effect order guarantees trust pushes first and fusion
  * pushes last — the non-merging `if(!window.__DSH_TRANSPORT__)` verdict in the
  * trust script is always evaluated before anything could own that global.
- * Flag gate (minimal, Task 5 formalizes the config face): row config
- * `enabled`, defaulting OFF from the `SUPERD_UI_FUSION` env — while the flag
- * is off the component stays dormant and injects no row at all.
+ * Row gate: the row config `enabled`, ON by default — the composite patch
+ * composing this row is the switch. `enabled: false` (or `disabled: true`)
+ * leaves the component dormant: no listener, no script, no flag global.
  *
  * @module @pgmi-builds/superd-hub/fusion-transport
  */
@@ -319,49 +319,19 @@ try {
 } catch { /* the whole install is best-effort: a partial page is still a page */ }
 })()`;
 }
-/** The env name the minimal Task-3 gate reads; Task 5 builds the config face on it. */
-export const FUSION_FLAG_ENV = 'SUPERD_UI_FUSION';
 /**
- * The page global the ctx0 index carries when the gate is on: the client
+ * The page global the ctx0 index carries when this row is on: the client
  * half's fusion-branch discriminator (the Hub UI switch surfaces read its
  * presence to intercept agent clicks into the switch orchestration instead
  * of letting the hyperlinks navigate — the sole switch surface since the T-B
  * RuntimeSeat retirement; world pages never carry it, so they keep the real
- * navigation half — spec §5 双半边). Baked by the SAME gated listener as the
+ * navigation half — spec §5 双半边). Baked by the SAME listener as the
  * transport script, so the two halves can never disagree.
  */
 export const FUSION_FLAG_GLOBAL = '__SUPERD_UI_FUSION__';
-/**
- * The flag's SEMANTICS after the path-separation Part 2 closeout (T-C/T-D
- * landed; this block is the T-E closeout record) — native-ui-only, there is
- * no fallback route anywhere:
- *
- *   - ON: the ctx0 page fuses. The transport script arms the in-place switch
- *     and `/hub` is the sole surface for every runtime. The per-label URL
- *     family (`/<label>/` ctx0 pages, T-C) and the world web UIs (T-D) are
- *     RETIRED from the product, not gated by this flag — there is nothing
- *     navigational behind them to fall back to.
- *   - OFF: NO foreign entry exists AT ALL. The served product is the bare
- *     native UI plus the Hub panel as an information surface: the roster
- *     still lists the runtimes (the control plane is not gated), but the
- *     switch affordances render inert with the degradation hint
- *     (`switchAffordance` in switch-core) instead of dead controls — a row
- *     has no /<label>/ page to reach and the Hub UI ships no hrefs to reach
- *     one with.
- *
- * The shipped default stays OFF (truthy env opt-in). Moving the default ON is
- * the user's 放行 (acceptance/release) round — a two-gate decision per repo
- * §〇.1, never a code-side choice.
- *
- * Derivation: truthy spellings only (`1` / `true` / `yes` / `on`,
- * case-insensitive, trimmed). Anything else — unset included — is OFF.
- */
-export function deriveFusionFlag(env) {
-    return ['1', 'true', 'yes', 'on'].includes((env ?? '').trim().toLowerCase());
-}
-/** Row config (schema-level default derives from the {@link FUSION_FLAG_ENV} env). */
+/** Row config: ON unless a patch layer restates the row with `enabled: false`. */
 export const Config = z.object({
-    enabled: z.boolean().default(deriveFusionFlag(process.env[FUSION_FLAG_ENV])),
+    enabled: z.boolean().default(true),
 });
 /** Cordis plugin name. */
 export const name = 'superd-fusion-transport';
@@ -379,13 +349,15 @@ export const inject = [];
  * the {@link FUSION_FLAG_GLOBAL} baked global row (Task 4): one gate, both
  * halves.
  *
- * Flag off → the component registers nothing: no listener, no row, no script,
+ * Off → the component registers nothing: no listener, no row, no script,
  * no flag global.
  * @param ctx - host plugin context.
- * @param config - the row config.
+ * @param config - the row config (`enabled`, default on).
  */
 export function apply(ctx, config) {
-    if (config?.enabled !== true)
+    // Composed row = on. Only an explicit `enabled: false` turns it off, so a
+    // composition that omits the config key cannot silently disable the surface.
+    if (config?.enabled === false)
         return;
     ctx.inject(['webServer'], () => {
         ctx.on('webserver/index-inject', (table) => {

package/superd-hub/dist/gateway.d.ts

@@ -12,14 +12,36 @@
  * per-world mount registers through `carrier.ts` (AW-B tasks 2-9), which calls
  * the addressed world's own `typertGateway` instance directly — again without
  * any shared selection value.
+ *
+ * Mesh P2 Task 3 adds the federation wiring: mesh-link's machine lifecycle
+ * events drive mesh-federate's registrar (pair/reprobe success → converge the
+ * remote roster into the registries, probe failure → degrade, removal →
+ * defederate), and the `/hub` family's demux gains the federation table ahead
+ * of the local target registry (spec §3.2 dual-key: a6 canonical, label
+ * aliases compatible).
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 /** Stable Cordis plugin name. */
 export declare const name = "superd-hub";
+/** Row config schema (mesh P3 Task 5a): the periodic reprobe sweep's knob —
+ *  seconds between sweeps, default the user mandate's 5 minutes, floored at
+ *  60 by the schema AND clamped again in `startReprobeSweep` (a bare-library
+ *  caller cannot bypass the floor). Patch rows restate the whole config
+ *  object; schema defaults fill the un-configured one. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    reprobeIntervalSec: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    reprobeIntervalSec: z<number, number, "defined">;
+}>>, "plain">;
+/** The row config's TypeScript face (the schema-declared knob). */
+export interface HubConfig {
+    reprobeIntervalSec?: number;
+}
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Three CTX0-owned contributions, none carrying any selection value:
+ * CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
  *     every mount path the hub currently serves;
@@ -28,6 +50,21 @@ export declare const name = "superd-hub";
  *     World trees compose this same row, but their `webServer` is the VIRTUAL
  *     per-world translation surface — the `/hub` family belongs to ctx0's
  *     real listener only (one family per process, demuxed by `?agent=`).
+ *   - the mesh federation wiring (mesh P2 Task 3): home resolved HERE at
+ *     registration time (mesh-rpc stays a pure route module; tests inject a
+ *     tmpdir home instead); the one-way seam is mesh-link's federation event
+ *     bus — mesh-federate subscribes, mesh-link never imports it.
+ *   - the periodic reprobe sweep (mesh P3 Task 5a I1-a, user mandate
+ *     "状态更新走单向 API + 5 分钟周期轮询"): every `reprobeIntervalSec`
+ *     (default 300, floor 60) one sweep re-probes every ENABLED remote —
+ *     success converges federation, failure degrades (both via the existing
+ *     mesh-link hooks). CTX0-ONLY, gated by the same WorldWebServer check as
+ *     the `/hub` family: world trees compose this row too (world-mount.ts
+ *     WORLD_HUB_ROW) and must never start their own sweep against the shared
+ *     machines registry.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`reprobeIntervalSec`; schema defaults
+ *   apply when the row is composed without one).
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: HubConfig): void;
 export default apply;

package/superd-hub/dist/gateway.js

@@ -1,14 +1,29 @@
+import z from '@deepseek-ai/schemastery';
 import { registerSelectorRpc, registryTargets } from './rpc.js';
+import { registerMeshRpc } from './mesh-rpc.js';
+import { startReprobeSweep } from './mesh-link.js';
+import { federatedGatewayOf, startMeshFederation } from './mesh-federate.js';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 import { agentRosterRow } from './agent-roster.js';
 import { getTarget } from './targets.js';
 import { registerHubRoute } from './hub-route.js';
 import { WorldWebServer } from './world-web-server.js';
+import { registerPtyExecutor } from './exec-pty-rpc.js';
+import { consoleA2aLog } from './a2a-log.js';
 /** Stable Cordis plugin name. */
 export const name = 'superd-hub';
+/** Row config schema (mesh P3 Task 5a): the periodic reprobe sweep's knob —
+ *  seconds between sweeps, default the user mandate's 5 minutes, floored at
+ *  60 by the schema AND clamped again in `startReprobeSweep` (a bare-library
+ *  caller cannot bypass the floor). Patch rows restate the whole config
+ *  object; schema defaults fill the un-configured one. */
+export const Config = z.object({
+    reprobeIntervalSec: z.number().min(60).default(300),
+});
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Three CTX0-owned contributions, none carrying any selection value:
+ * CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
  *     every mount path the hub currently serves;
@@ -17,9 +32,27 @@ export const name = 'superd-hub';
  *     World trees compose this same row, but their `webServer` is the VIRTUAL
  *     per-world translation surface — the `/hub` family belongs to ctx0's
  *     real listener only (one family per process, demuxed by `?agent=`).
+ *   - the mesh federation wiring (mesh P2 Task 3): home resolved HERE at
+ *     registration time (mesh-rpc stays a pure route module; tests inject a
+ *     tmpdir home instead); the one-way seam is mesh-link's federation event
+ *     bus — mesh-federate subscribes, mesh-link never imports it.
+ *   - the periodic reprobe sweep (mesh P3 Task 5a I1-a, user mandate
+ *     "状态更新走单向 API + 5 分钟周期轮询"): every `reprobeIntervalSec`
+ *     (default 300, floor 60) one sweep re-probes every ENABLED remote —
+ *     success converges federation, failure degrades (both via the existing
+ *     mesh-link hooks). CTX0-ONLY, gated by the same WorldWebServer check as
+ *     the `/hub` family: world trees compose this row too (world-mount.ts
+ *     WORLD_HUB_ROW) and must never start their own sweep against the shared
+ *     machines registry.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`reprobeIntervalSec`; schema defaults
+ *   apply when the row is composed without one).
  */
-export function apply(ctx) {
+export function apply(ctx, config) {
     registerSelectorRpc(ctx, registryTargets);
+    const home = resolveDshHome();
+    registerMeshRpc(ctx, { home });
+    ctx.effect(() => startMeshFederation({ home }), 'superd-hub: mesh federation wiring');
     const on = ctx.on;
     on?.call(ctx, 'webserver/index-inject', (table) => { table.push(agentRosterRow()); });
     ctx.inject(['webServer', 'connection'], (host) => {
@@ -32,13 +65,39 @@ export function apply(ctx) {
         // table — never a shared selection. The requestRejection face is the
         // ctx0 browser-trust fence: auth first, then Host/Origin — the family is
         // never weaker than the neighbors carrying identical traffic.
+        //
+        // Demux (mesh P2 Task 3, spec §3.2 dual-key): the mesh FEDERATION table
+        // first — an exact a6 match is the canonical spelling and beats label
+        // aliases — then the shared local target registry (local runtime keys;
+        // federated a6s are registered there too, so the fallback re-arms a
+        // registration whose memo was cleared independently). Local label aliases
+        // and `?agent=<a6>` therefore both demux; under the astronomically rare
+        // a6↔local-key collision the federation wins deterministically (documented
+        // in mesh-federate's header) instead of last-write-wins in the registry.
+        // I1(a) periodic reprobe sweep — CTX0-ONLY by the same gate as the
+        // `/hub` family below (world trees see a WorldWebServer and returned
+        // early): the machines registry is ctx0-owned, and a per-world timer
+        // would multiply probes against every paired remote. The effect's
+        // disposer IS the sweep disposer — the timer dies with the row
+        // (unref'd, overlap-skipping, per-machine errors swallowed; mesh-link).
+        ctx.effect(() => startReprobeSweep({ home, intervalSec: config?.reprobeIntervalSec, immediate: true }), 'superd-hub: mesh reprobe sweep');
         const dispose = registerHubRoute({
             real: real,
             authorize: (req, res) => connection.authorizeIndex(req, res),
             requestRejection: (req) => connection.requestRejection(req),
-            gatewayOf: (label) => getTarget(label)?.gateway,
+            gatewayOf: (label) => (federatedGatewayOf(label) ?? getTarget(label)?.gateway),
         });
         ctx.effect(() => dispose, 'superd-hub: /hub route family');
+        // P4 §8.2: the PTY executor's upgrade route — same gate as the /hub family
+        // (authorizeIndex cookie auth first, then the browser-trust fence). The
+        // dumb pump lives in exec-pty-rpc.ts; a2a-row owns the initiator half.
+        void registerPtyExecutor(real, {
+            authorize: (req, res) => connection.authorizeIndex(req, res),
+            requestRejection: (req) => connection.requestRejection(req),
+            log: consoleA2aLog(),
+        }).then((disposePty) => {
+            ctx.effect(() => disposePty, 'superd-hub: PTY executor upgrade route');
+        }, () => { });
     });
 }
 export default apply;

package/superd-hub/dist/hub-tool.d.ts

@@ -0,0 +1,174 @@
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { A2aDeliveryCtx } from './a2a-delivery.js';
+import type { AgentLink } from './agent-roster.js';
+import type { AgentStatusFile } from './agent-status.js';
+import { type OneShotExecInput, type OneShotExecResult } from './exec.js';
+/** P4 exec face (spec §8.1): the executing side + the wire leg, closed over the hub home by a2a-row. */
+export interface HubToolExecFace {
+    /** This machine's m4 (the default exec target). */
+    selfM4(): string;
+    /** Run one command on THIS machine. */
+    run(input: OneShotExecInput): Promise<OneShotExecResult>;
+    /** Run one command on a paired machine over the wire. Throws typed Errors: unknown machine / exec disabled / peer unreachable. */
+    post(machineId: string, input: OneShotExecInput): Promise<OneShotExecResult>;
+    /**
+     * P4 §8.2 persistent PTY: dispatch one command into a per-(session,
+     * machine) shell that KEEPS its cwd/env across dispatches. Throws typed
+     * Errors: unknown machine / exec disabled / transport failure.
+     */
+    pty(sessionKey: string, machine: string, cmd: string, opts?: {
+        timeoutSec?: number;
+    }): Promise<import('./exec-pty-session.js').PtyDispatchResult>;
+}
+import type { A2aAddress, A2aInitiator, A2aService } from './a2a-service.js';
+/** The service face the tool consumes (structural subset of T2/T3's A2aService). */
+export type HubToolService = Pick<A2aService, 'send' | 'subscribeCompletion' | 'stop' | 'read' | 'listConversations'>;
+/** Per-agent recent-conversation bound (spec §7.2: alive-first, ≤5). */
+/** R6: retired from the agents listing (the strip); kept exported for compat — agent_status windows AGENT_STATUS_WINDOW_MAX rows instead. */
+export declare const RECENT_CONVERSATIONS_MAX = 5;
+/** The exec placeholder note (P4 owns the leg; spec §9 placeholder discipline). */
+export declare const EXEC_PLACEHOLDER_NOTE = "not yet implemented: exec (P4)";
+/** One addressable agent row in the listing (R6: THIN — the conversations embedding is retired; per-agent session state lives on the agent_status leg). */
+export type HubAgentEntry = {
+    /** Agent id (a6). */
+    id: string;
+    /** Chip label (`DSH`, `Codex · dev3`, …). */
+    label: string;
+    /** Full tool address `<m4>-<a6>` — what the `agent` parameter wants. */
+    address: string;
+    /** Whether the agent's data plane is up. */
+    ready: boolean;
+    /** Whether the agent's spawn rejected (row stays for diagnosis). */
+    failed: boolean;
+};
+/** One machine block: its agents grouped under it. */
+export type HubMachineEntry = {
+    /** Machine id (m4). */
+    machine: string;
+    /** Machine display label. */
+    label: string;
+    /** Agents running on this machine (self's machine first, roster order). */
+    agents: HubAgentEntry[];
+};
+/**
+ * The roster view the `agents` listing renders — the `/api/agent-runtime`
+ * family of facts (rpc.ts + agent-roster.ts), injected so the factory stays
+ * filesystem-free.
+ */
+export interface HubRosterView {
+    /** THIS machine: owner-minted m4 + display label (machines.ts `ensureSelf`). */
+    self: {
+        id: string;
+        label: string;
+    };
+    /** Paired remote machines in pairing order (machines.ts `listRemotes`). */
+    remotes: {
+        id: string;
+        label: string;
+    }[];
+    /** `agentLinks(home)` output: local rows carry `machine: 'local'`, federated rows the owning m4. */
+    agents: AgentLink[];
+}
+/** Everything the factory needs, all injected (pure module — see header). */
+export interface HubToolDeps {
+    /** The A2A conversation service (T2 core behind T3's host assembly). */
+    service: HubToolService;
+    /** T3's delivery face: live-agent routing + the bounded unread buffer. */
+    delivery: A2aDeliveryCtx;
+    /** Roster snapshot for the `agents` listing (row: the real hub home view). */
+    roster(): HubRosterView;
+    /**
+     * P4 exec face (spec §8.1): the local executing side + the cross-machine
+     * wire leg, closed over the hub home by a2a-row (self id, remote rows,
+     * pairing cookies, journal). `post` throws typed Errors (unknown machine,
+     * exec disabled on the row, peer unreachable).
+     */
+    exec: HubToolExecFace;
+    /**
+     * Initiator identity for the calling session — the row closes this over
+     * T3's `localA2aInitiator(home, 'native', sessionId)`. Called exactly once
+     * per session-bound action, with `exec.agent.id`.
+     */
+    initiatorOf(sessionId: string): A2aInitiator;
+    /**
+     * Owns one completion-watch disposer per successful send (the row parks it
+     * in a fiber `ctx.effect`; requestId-armed watches self-dispose after
+     * their turn fires). Absent = disposers dropped (happy path still leaks
+     * nothing — the subscription auto-disposes on fire).
+     */
+    onWatch?(dispose: () => void): void;
+    /**
+     * R6: the R5 information-status cache reader (the row wires
+     * `() => loadAgentStatus(home)`); absent = agent_status answers honestly
+     * empty with collectedAt 0.
+     */
+    status?(): AgentStatusFile;
+}
+/**
+ * Parse the `agent` parameter: `<m4>-<a6>`. Both halves are minted over
+ * `[a-z0-9]` (machines.ts `ID_ALPHABET`) at fixed lengths (m4 = 4, a6 = 6), so
+ * a malformed address is refused HERE (0.1.8 T4) instead of being mis-split
+ * into a bogus machine and reported downstream as "unknown machine" — the
+ * `no-such-agent-zzz` → machine `no` is not paired trap the 0.1.7 surface
+ * analysis flagged.
+ * @param agent - the raw `agent` parameter.
+ * @returns the address the service consumes.
+ * @throws `[E_BAD_ADDRESS]` when the value is not a well-formed `<m4>-<a6>`.
+ */
+export declare function parseAgentAddress(agent: unknown): A2aAddress;
+/** The agent_status window size (Orchestra semantics — not-in-window implies nothing). */
+export declare const AGENT_STATUS_WINDOW_MAX = 5;
+/** D18 marker appended to registry-joined titles. */
+export declare const HUB_A2A_TITLE_MARKER = "[hub A2A]";
+/** The honest fallback when neither the registry nor a workspace names the session. */
+export declare const UNHOSTED_TITLE = "[unhosted]";
+/** One shaped agent_status row. */
+export interface AgentStatusEntryRow {
+    conversationId?: string;
+    /** Display-truncated session id (uuid head; the full id stays in the cache). */
+    sessionId: string;
+    title: string;
+    status: 'busy' | 'idle' | 'unknown';
+    agentAvailable: boolean;
+    mtime: number;
+    /** D30: the peer's last delivered output — present ONLY when the caller is this conversation's initiator (ownership gate). */
+    lastOutput?: string;
+    /** D30: epoch ms of lastOutput. */
+    lastOutputAt?: number;
+}
+/**
+ * Shape one agent's window from the R5 cache (D18): alive-first (a session
+ * owning a live Agent first), mtime desc within each group, ≤5 rows —
+ * not-in-window implies nothing. Title: registry join (full session id) →
+ * `{conversationTitle} [hub A2A]`; else the owning workspace's title
+ * verbatim; else '[unhosted]'. conversationId rides only on a registry hit.
+ */
+export declare function shapeAgentStatusWindow(entry: {
+    rows: AgentStatusEntrySrcRow[];
+    workspaces?: Array<{
+        title: string;
+        sessionIds: string[];
+    }>;
+}, conversations: ReadonlyArray<{
+    shortId: string;
+    sessionId: string;
+    title?: string;
+    initiatorSession?: string;
+    lastOutput?: string;
+    lastOutputAt?: number;
+}>, 
+/** D30 ownership gate: the caller's session — lastOutput is surfaced only to the conversation's initiator. */
+callerSessionId?: string): AgentStatusEntryRow[];
+/** The cache row face the shaper consumes (structural subset of AgentStatusRow). */
+export interface AgentStatusEntrySrcRow {
+    sessionId: string;
+    mtime: number;
+    status: 'busy' | 'idle' | 'unknown';
+    agentAvailable: boolean;
+}
+/**
+ * Build the one SuperD Hub tool.
+ * @param deps - service, delivery, roster view, initiator factory, watch owner.
+ * @returns the registry-ready `superd-hub` ToolDefinition.
+ */
+export declare function createSuperdHubTool(deps: HubToolDeps): ToolDefinition;