@cotal-ai/manager 0.16.0 → 0.17.0

package/dist/attach-endpoint.d.ts

@@ -1,13 +1,9 @@
-import type { AgentHandle } from "./runtime/index.js";
 /**
- * The address the attach endpoint binds and advertises: the host of the mesh broker this manager is
- * attached to. Keeping the two in step is the whole point — a client that reached the control plane
- * to request an attach URL demonstrably has a route to that address, whereas a hardcoded
- * `127.0.0.1` resolves to the client's own machine.
+ * The address the console endpoint binds and advertises, derived from a mesh broker URL.
  *
  * With no server URL there is no mesh address to follow, so this is loopback: the conservative
- * default and exactly the endpoint's previous behavior. An unparseable URL is a caller bug and
- * throws rather than quietly binding somewhere the operator did not ask for.
+ * default. An unparseable URL is a caller bug and throws rather than quietly binding somewhere the
+ * operator did not ask for.
  */
 export declare function attachHost(servers: string | undefined): string;
 /** One Server-Sent-Events frame: a named event carrying JSON data. */
@@ -15,81 +11,79 @@ export interface FeedEvent {
     event: string;
     data: unknown;
 }
+/** What `POST /session/<name>` returns: the console's mesh §13.6 session establishment (P2 item 6).
+ *  The `grant` is the holder-bound offer (no ws:// URL, non-bearer); `wsUrl` is the broker's
+ *  localhost websocket listener; `creds` is the per-session, rails-only session-caller credential the
+ *  browser connects with. NO 127.0.0.1 terminal transport — the terminal rides the mesh session. */
+export interface SessionEstablishment {
+    grant: unknown;
+    wsUrl: string;
+    creds: string;
+}
+/** The manager-injected session establisher (P2 item 6): given a managed agent name, mint the offer
+ *  through the ONE {@link import("./session/plane.js").ManagerSessionPlane} + the per-session caller
+ *  credential, and return what the browser needs to connect. INJECTED — the face never constructs a
+ *  plane; the manager wires the single plane + the cred mint at boot (6b-2). Absent ⇒ the route 503s
+ *  (an open mesh with no console session client, or the pre-6b-2 stub). */
+export type SessionEstablisher = (name: string) => Promise<SessionEstablishment>;
 /**
- * The manager's local HTTP + WebSocket face. It hosts the **console** (a
- * lightweight xterm.js page) and bridges each agent's PTY to the browser — and to
- * `cotal attach` — over a direct socket, never the mesh, so owning the terminal
- * keeps the manager off the message hot path.
- *
- * **Where it binds, and why it is credentialed.** A mesh can span machines: the manager that owns an
- * agent's PTY may sit on another host than the operator running `cotal attach`. Hardcoding
- * `127.0.0.1` made every remote attach fail with ECONNREFUSED against the *client's own* loopback.
- * The bind address is therefore an explicit option (default loopback, so nothing is exposed by
- * accident); `cotal up` passes the address it bound the broker to. A broker DIAL address is
- * deliberately NOT used as the bind: a manager may supervise a broker on another host and could not
- * bind that address at all. Where the manager can only name loopback (a wildcard bind), the CLIENT
- * substitutes the broker address its own control connection reached.
+ * The manager's local HTTP face. It serves the **console** (a lightweight xterm.js page + its
+ * assets) and is the browser's credential broker: `POST /session/<name>` mints a mesh §13.6 session
+ * for the console to drive the terminal over the broker's WebSocket listener. The terminal never
+ * rides a manager-hosted socket (P2 item 6 replaced the loopback `ws://.../attach/` transport with
+ * the mesh session, closing the bearer-less-local hole) — `cotal attach` reaches a manager on
+ * another machine over the mesh, not by dialing this face.
  *
- * Reachability is why the surface is credentialed, in two tiers. This face carries terminal READ AND
- * WRITE for every managed agent, plus the roster and the live feed, so once it can leave the box
- * "unauthenticated but loopback-only" stops being a safe position.
+ * **Where it binds, and why it is credentialed.** The bind address is an explicit option (default
+ * loopback, so nothing is exposed by accident); `cotal up` passes the address it bound the broker
+ * to when the operator asked for an exposed console. A broker DIAL address is deliberately NOT used
+ * as the bind: a manager may supervise a broker on another host and could not bind that address at
+ * all. Where the manager can only name loopback (a wildcard bind), it advertises loopback.
  *
- *  - **Attach tickets** are what a mesh caller gets: minted per authorized `attach` request, bound to
- *    the ONE agent the manager just authorized, single-use, short-lived. This is what makes the
- *    per-agent/owner check real — a manager-wide token would let a caller authorized for its own
- *    agent swap the path and take over anyone's terminal.
- *  - **The console token** is the operator's own: it reaches every agent, because the console
- *    legitimately drives all of them, and it is printed solely to this manager process's output
- *    (so it is as sensitive as `.cotal/manager.log`, and never handed to a mesh caller).
+ * Reachability is why the surface is credentialed. It carries the managed roster, the live mesh
+ * feed, and — through `POST /session/<name>` — the mint of a real §13.6 session grant plus its
+ * per-session caller credential. Once the face can leave the box, "unauthenticated but
+ * loopback-only" stops being a safe position, so every DATA route requires the manager's console
+ * token. The console SHELL (its HTML, its script, the vendored xterm assets) is static and carries
+ * nothing about this mesh, so it stays open — that is what lets the page load and then present the
+ * token, held in memory from its own URL, on the requests that do matter.
  *
- * Credentials travel in `?t=` or a bearer header, never a cookie: cookies are host-scoped, not
+ * The credential travels in `?t=` or a bearer header, never a cookie: cookies are host-scoped, not
  * port-scoped, so one set here would be sent to every other HTTP service on this host and would
  * collide between two managers on one box. The console URL carries its token in the FRAGMENT, which
  * a browser never sends to a server.
  *
- * Routes: `GET /` console page, `GET /agents` the managed roster (JSON),
- * `GET /feed` the live mesh feed (SSE: presence roster + comms), static assets
- * under `/assets`, and `WS /attach/<name>` the PTY stream.
- *
- * Attach protocol: server → client sends raw terminal bytes (binary). client →
- * server: binary frames are keystrokes; a text frame `r:<cols>,<rows>` resizes.
+ * Routes: `GET /` console page + `/app.js` + `/session-bundle.js` + `/assets/*`; `GET /agents` the
+ * managed roster (JSON); `GET /feed` the live mesh feed (SSE: presence roster + comms);
+ * `POST /session/<name>` the mesh session establishment.
  */
 export declare class AttachEndpoint {
     #private;
-    private readonly lookup;
     private readonly list;
     /** Events replayed to each console as it connects to `/feed` (e.g. the current roster). */
     private readonly snapshot;
-    /** The endpoint credential. Generated per manager process; required on every route. */
+    /** P2 item 6: the manager-injected mesh-session establisher backing `POST /session/<name>`
+     *  (the console's session-client transport). Absent ⇒ the route 503s. Wired at 6b-2. */
+    private readonly establishSession?;
+    /** The endpoint credential. Generated per manager process; required on every data route. */
     private readonly token;
-    constructor(lookup: (name: string) => AgentHandle | undefined, list: () => unknown, 
+    constructor(list: () => unknown, 
     /** Events replayed to each console as it connects to `/feed` (e.g. the current roster). */
     snapshot: () => FeedEvent[], port?: number, 
-    /** Bind address, and the host advertised in {@link url} / {@link consoleUrl}. Defaults to
-     *  loopback; the manager passes the mesh broker's host so attach is reachable from wherever the
-     *  mesh is. A wildcard bind still advertises loopback, since a wildcard is not a dialable name. */
+    /** P2 item 6: the manager-injected mesh-session establisher backing `POST /session/<name>`
+     *  (the console's session-client transport). Absent ⇒ the route 503s. Wired at 6b-2. */
+    establishSession?: SessionEstablisher | undefined, 
+    /** Bind address, and the host advertised in {@link consoleUrl}. Defaults to loopback; the
+     *  manager passes an operator-chosen address when the console is meant to be reachable from
+     *  another machine. A wildcard bind still advertises loopback, since a wildcard is not a
+     *  dialable name. */
     host?: string, 
-    /** The endpoint credential. Generated per manager process; required on every route. */
+    /** The endpoint credential. Generated per manager process; required on every data route. */
     token?: string);
     start(): Promise<void>;
     stop(): Promise<void>;
     /** Push a named event to every connected console (SSE). */
     publish(event: string, data: unknown): void;
-    /**
-     * The ws URL a client uses to attach to `name`, carrying a capability bound to THAT agent.
-     *
-     * Called once per authorized control-plane `attach` request, so the ticket inherits exactly the
-     * authorization the manager just performed for this caller and this agent. It is single-use and
-     * short-lived: the client redeems it immediately, and a leaked URL (shell history, a log, a
-     * `Referer`) is spent or expired rather than a standing key to someone's terminal.
-     *
-     * `expected` is the handle the caller actually authorized, and it is REQUIRED. A name is a reusable
-     * slot, and authorization is async (a user-mode ledger read), so between the caller resolving the
-     * name and arriving here the slot can have been stopped and refilled by a same-name successor.
-     * Re-resolving the name would then mint a valid ticket for an agent nobody authorized. Binding to
-     * the caller's own handle closes that window: if the slot moved, there is no capability to issue.
-     */
-    url(name: string, expected: AgentHandle): string;
     /** The console page URL. The token rides the FRAGMENT, which a browser never sends to a server:
      *  it stays out of this endpoint's request handling, out of any proxy's logs, and out of the
      *  `Referer` a click on the page would otherwise leak. The page reads it from `location.hash` and

package/dist/attach-endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach-endpoint.d.ts","sourceRoot":"","sources":["../src/attach-endpoint.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAmBtD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAW9D;AAOD,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc;;IAYvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAMzB,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAVL,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,EACjD,IAAI,EAAE,MAAM,OAAO;IACpC,2FAA2F;IAC1E,QAAQ,EAAE,MAAM,SAAS,EAAE,EAC5C,IAAI,SAAI;IACR;;uGAEmG;IACnG,IAAI,SAAc;IAClB,uFAAuF;IACtE,KAAK,GAAE,MAAwC;IA4F5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,2DAA2D;IAC3D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAW3C;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM;IAWhD;;;;sCAIkC;IAClC,UAAU,IAAI,MAAM;CAmKrB"}
+{"version":3,"file":"attach-endpoint.d.ts","sourceRoot":"","sources":["../src/attach-endpoint.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAW9D;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;oGAGoG;AACpG,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;2EAI2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAc;;IAQvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB;4FACwF;IACxF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAMlC,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAbL,IAAI,EAAE,MAAM,OAAO;IACpC,2FAA2F;IAC1E,QAAQ,EAAE,MAAM,SAAS,EAAE,EAC5C,IAAI,SAAI;IACR;4FACwF;IACvE,gBAAgB,CAAC,EAAE,kBAAkB,YAAA;IACtD;;;yBAGqB;IACrB,IAAI,SAAc;IAClB,4FAA4F;IAC3E,KAAK,GAAE,MAAwC;IAsC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,2DAA2D;IAC3D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAW3C;;;;sCAIkC;IAClC,UAAU,IAAI,MAAM;CA8IrB"}