@xenosystem/agent-interface-host 0.1.3

package/dist/session/AgentSessionService.d.ts

@@ -0,0 +1,285 @@
+/**
+ * The session substrate — ADE spec §2.8, build-order step 0.
+ *
+ * > "The terminal belongs to us, not to the agent. We do not attach to an
+ * >  agent's terminal; we *give* every session a terminal and own both ends of
+ * >  it. That part is unconditional — every session has a PTY, and input
+ * >  routing, attach and takeover work identically regardless of what is running
+ * >  inside."
+ *
+ * §9 calls this "not a step so much as the floor the others stand on", and it is
+ * the floor §5.5's attach and takeover were found to be waiting on: §4.6's two
+ * process worlds — an agent spawned as a stdio JSON-RPC child with no terminal,
+ * and a PTY belonging to the user — meet here or nowhere.
+ *
+ * ## One session, TWO channels — measured, not assumed
+ *
+ * A PTY is **not** a byte-transparent pipe. Measured 2026-08-13 against real
+ * `node-pty` on Windows/ConPTY (`scripts/probe-pty-framing.mjs`): a
+ * `Content-Length` header survives, and the `\r\n\r\n` that separates it from
+ * the body is **re-rendered as a cursor-position escape**. A framed reader never
+ * finds the separator, so it never begins counting. `\n` is rewritten to `\r\n`
+ * as well.
+ *
+ * That is not a bug to harden around — a terminal's job is to render a screen,
+ * so it is free to express the same visual result as different bytes, which is
+ * exactly what breaks a byte-counted protocol.
+ *
+ * So a session owns a PTY **and**, when the agent speaks a protocol, a separate
+ * channel for framed messages. The two are distinct types here with no
+ * conversion between them, so "just send the JSON-RPC through the terminal"
+ * cannot be written by accident.
+ *
+ * ## What renders is a MODE, and the modes are exclusive
+ *
+ * §2.8: *"The two modes are not simultaneous for one process: a CLI in
+ * interactive TUI mode is not also serving ACP."* That is enforced at open time
+ * rather than documented: a `native-tui` session with a protocol channel is a
+ * contradiction, and an `acp` session without one has nothing to render.
+ */
+import { type AgentRenderSupport, type InputDelivery, type InputRouting, type SessionRenderMode, type WriteLeaseState } from '@xenosystem/agent-interface-core';
+/**
+ * The human-facing half of a session. A port: `node-pty` is a native module
+ * that belongs to the composition, and keeping it out of here is what lets the
+ * substrate's rules be tested without spawning a terminal.
+ */
+export interface SessionPty {
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    onData(listener: (chunk: string) => void): () => void;
+    close(): void;
+}
+/**
+ * The framed-message half: INBOUND ONLY — what the agent says.
+ *
+ * Deliberately a DIFFERENT type from `SessionPty`, with no `write(string)`. The
+ * measurement above is the reason, and a shared interface would make the
+ * mistake expressible.
+ *
+ * 🔴 There is no `send`, and its absence is load-bearing.
+ *
+ * It had one for a while and NOTHING ever called it — outside its own test, in
+ * the whole repo. Everything that goes host→agent already has a better path:
+ * a turn is `turn.start`, a correction mid-turn is `turn.steer`, an approval is
+ * the permission bridge. There is no fourth thing.
+ *
+ * Worse, `sendProtocol` returned `true` to mean "delivered", which is precisely
+ * the claim §5.5 measured to be false: steering lands at the agent's NEXT
+ * DECISION POINT, so `turn.steer` is acknowledged rather than instantaneous. A
+ * second, unacknowledged path would have been a worse version of a thing this
+ * codebase already got right.
+ *
+ * And it made an honest implementation IMPOSSIBLE. This channel's real producer
+ * adapts the run's runtime-event stream (`createRuntimeEventSessionChannel`),
+ * and you cannot send a message backwards into an event log — so the producer
+ * would have had to stub `send` and let `sendProtocol` answer `true`. Removing
+ * the verb removes the obligation to lie.
+ */
+export interface SessionProtocolChannel {
+    onMessage(listener: (message: unknown) => void): () => void;
+    close(): void;
+}
+export interface AgentSessionRecord {
+    sessionId: string;
+    runId: string;
+    mode: SessionRenderMode;
+    /** The user may switch modes; §2.8 switching, never simultaneity. */
+    switchable: boolean;
+    /** True when a protocol channel is attached. Never true for `native-tui`. */
+    hasProtocolChannel: boolean;
+    openedAt: number;
+    /** Surfaces currently watching. Attach is live and plural by construction. */
+    viewers: string[];
+    /** Who may write INTO the session — §5.5 takeover. Output is never gated. */
+    lease: WriteLeaseState;
+}
+/**
+ * The outcome of a surface typing into a session.
+ *
+ * A refusal is NAMED rather than a bare false: the two reasons need different
+ * responses from a surface — "no such session" means stop showing this
+ * terminal, "someone else holds it" means show who, and offer takeover.
+ */
+export type SessionInputResult = {
+    ok: true;
+    routing: InputRouting;
+    delivery: InputDelivery;
+} | {
+    ok: false;
+    code: 'no_such_session';
+} | {
+    ok: false;
+    code: 'lease_held';
+    holder: string;
+};
+/**
+ * What a takeover did: who holds the lease now, and where the keystrokes went.
+ *
+ * 🔴 The delivery has to come back from HERE. Its caller would otherwise have
+ * to look at the session's mode and re-derive which sink applies — the same
+ * rule, restated outside the shared callee, free to drift from it.
+ */
+export interface SessionTakeoverOutcome {
+    lease: WriteLeaseState;
+    delivery: InputDelivery;
+}
+export type SessionOpenResult = {
+    ok: true;
+    session: AgentSessionRecord;
+} | {
+    ok: false;
+    code: SessionOpenRefusal;
+    reason: string;
+};
+export type SessionOpenRefusal = 'mode_unavailable' | 'protocol_channel_required' | 'protocol_channel_forbidden' | 'session_exists';
+export interface SessionOpenRequest {
+    sessionId: string;
+    runId: string;
+    support: AgentRenderSupport;
+    pty: SessionPty;
+    /** Required for `acp`, refused for `native-tui`. */
+    protocol?: SessionProtocolChannel;
+    /**
+     * How a framed message becomes the text a person reads.
+     *
+     * 🔴 INJECTED, because it is presentation and this service is the substrate.
+     * A default is supplied so no caller is forced to decide before it has an
+     * opinion, but the decision stays overridable rather than baked in here.
+     */
+    renderProtocolMessage?: (message: unknown) => string;
+    preference?: SessionRenderMode;
+}
+export type SessionEvent = {
+    type: 'session.opened';
+    sessionId: string;
+    runId: string;
+    mode: SessionRenderMode;
+} | {
+    type: 'session.attached';
+    sessionId: string;
+    viewerId: string;
+    viewers: number;
+} | {
+    type: 'session.detached';
+    sessionId: string;
+    viewerId: string;
+    viewers: number;
+} | {
+    type: 'session.input';
+    sessionId: string;
+    disposition: InputRouting['disposition'];
+} | {
+    type: 'session.takeover';
+    sessionId: string;
+    viewerId: string;
+    interventions: number;
+} | {
+    type: 'session.released';
+    sessionId: string;
+    viewerId: string;
+} | {
+    type: 'session.closed';
+    sessionId: string;
+};
+/** One durable transcript entry for a takeover or its return. */
+export interface SessionInterventionRecord {
+    sessionId: string;
+    viewerId: string;
+    kind: 'takeover' | 'released';
+    at: number;
+    /** What the human typed to seize the session. Present on `takeover` only,
+     *  and only on the durable side — the live feed never carries it. */
+    data?: string;
+}
+export interface AgentSessionServiceOptions {
+    now?: () => number;
+    emit?: (event: SessionEvent) => void;
+    /**
+     * Where interventions go to become a durable record.
+     *
+     * Separate from `emit` for the reason coordination needed two sinks: §5.5's
+     * gate is that a reviewer can "see the human intervention in the timeline",
+     * which needs WHAT WAS TYPED, while the live event feed is a notification
+     * every connected client receives and must stay free of session contents.
+     */
+    record?: (entry: SessionInterventionRecord) => void;
+}
+export declare class AgentSessionService {
+    #private;
+    constructor(options?: AgentSessionServiceOptions);
+    /** Where interventions become a durable transcript entry. */
+    setInterventionSink(record: (entry: SessionInterventionRecord) => void): void;
+    /** Takeovers refused because someone else was typing. */
+    refusals(): ReadonlyArray<{
+        sessionId: string;
+        viewerId: string;
+        code: string;
+    }>;
+    /** Mirrors the coordination and observation services — see either for why a
+     *  sink fixed at construction cannot be the host that owns the service. */
+    setEventSink(emit: (event: SessionEvent) => void): void;
+    /**
+     * Gives a run a session: a terminal always, a protocol channel when the mode
+     * needs one.
+     *
+     * Every refusal is NAMED. An unopenable session that reports success would
+     * hand a caller a terminal that renders nothing, which is the failure §7.1
+     * exists to prevent.
+     */
+    open(request: SessionOpenRequest): SessionOpenResult;
+    /**
+     * Adds a live view. §5.5: *"two surfaces can hold the same running session at
+     * once and both see it move"* — so this is plural by construction rather than
+     * a handoff, and it is NOT resume: joining a live session and replaying a
+     * stored one are different operations.
+     */
+    attach(sessionId: string, viewerId: string, onData: (chunk: string) => void): boolean;
+    detach(sessionId: string, viewerId: string): boolean;
+    routeInput(sessionId: string, viewerId: string, data: string, context: {
+        turnInFlight: boolean;
+        acceptsMidTurnSteering: boolean;
+    }): SessionInputResult;
+    /**
+     * Recent terminal output for a session — the READ half of attach.
+     *
+     * A SNAPSHOT, deliberately, not a stream. The host protocol is
+     * request/response and its event feed is a broadcast to every connected
+     * client; PTY bytes must not go on it, because output is per-viewer and can
+     * be large. So a surface polls this, exactly as `workspace.pty.snapshot`
+     * already works in this repo — the mechanism is not new here, only its
+     * application to sessions.
+     *
+     * ⚠️ Returns what is RETAINED, which is bounded. `truncated` says when older
+     * output has already been dropped, so a surface can say "earlier output is
+     * gone" rather than presenting a terminal that appears to start mid-sentence
+     * for no reason.
+     */
+    snapshot(sessionId: string): {
+        output: string;
+        truncated: boolean;
+    } | undefined;
+    /**
+     * A human types into the agent's terminal. **This is the takeover** — §5.5
+     * has no request-and-wait step, because the case it exists for is an agent
+     * going wrong now.
+     *
+     * The input is written to the PTY whether or not this call TOOK the lease,
+     * because a human who already holds it is simply still typing. What changes
+     * on the first keystroke is the arbitration state and the record.
+     */
+    takeOver(sessionId: string, viewerId: string, data: string): SessionTakeoverOutcome | undefined;
+    /** The human hands the session back. Only the holder may. */
+    releaseTakeOver(sessionId: string, viewerId: string): boolean;
+    /**
+     * Whether the host may inject agent-side input right now.
+     *
+     * ⚠️ INPUT only. Agent OUTPUT is never gated: the agent is a running process
+     * we cannot silence, and its output during a takeover is exactly the evidence
+     * a reviewer needs to see what the human interrupted.
+     */
+    agentMayWrite(sessionId: string): boolean;
+    session(sessionId: string): AgentSessionRecord | undefined;
+    sessions(): AgentSessionRecord[];
+    close(sessionId: string): boolean;
+}
+//# sourceMappingURL=AgentSessionService.d.ts.map

package/dist/session/AgentSessionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionService.d.ts","sourceRoot":"","sources":["../../src/session/AgentSessionService.ts"],"names":[],"mappings":"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"}