@xenosystem/agent-interface-core 0.1.3

package/dist/sessionBoardProjection.d.ts

@@ -0,0 +1,84 @@
+/**
+ * What a session surface may SHOW — ADE §5.5 attach and takeover.
+ *
+ * `session.list` answers what exists; this decides what a person is told about
+ * their own relationship to each session, and what they may do about it. Pure,
+ * in `core`, for the reason `reviewProjection` and `fleetBoardProjection` are:
+ * an honesty rule written in JSX is enforced by whoever writes the next
+ * component.
+ *
+ * ## 🔴 The lease has THREE states, not two
+ *
+ * "Locked" is not enough. *You* hold it, *another human* holds it, or the
+ * *agent* holds it — and each implies a different action: keep typing, go find a
+ * colleague, or take over. A surface that renders the first two the same way
+ * tells one person their keystrokes are landing when they are being refused.
+ *
+ * ## Taking over is ADVICE here, never the decision
+ *
+ * `canTakeOver` exists so a button can be disabled, and that is all. The host
+ * arbitrates, and a surface that treated this as the gate would be a second
+ * implementation of the arbitration — which is how the two come to disagree,
+ * always in the direction of the optimistic one.
+ */
+/** Mirrors `AgentSessionSummary` on the wire, redeclared so `core` stays free of
+ *  the contract package in the direction that matters. */
+export interface SessionBoardInput {
+    sessionId: string;
+    runId: string;
+    mode: string;
+    switchable: boolean;
+    hasProtocolChannel: boolean;
+    openedAt: number;
+    viewers: string[];
+    lease: {
+        holder: string | null;
+        heldSince: number | null;
+        interventions: number;
+    };
+}
+export type SessionLeaseRelation = 'agent' | 'you' | 'other-human';
+export interface SessionBoardRow {
+    sessionId: string;
+    runId: string;
+    mode: string;
+    /** Who may write, relative to the person looking at this. */
+    lease: SessionLeaseRelation;
+    /** The other human's id, when one holds the lease. Named, never "someone". */
+    heldBy?: string;
+    /** How many times a human has taken this session over, ever. */
+    interventions: number;
+    viewers: number;
+    /** True when the person looking is one of them. */
+    youAreWatching: boolean;
+    /** Someone ELSE is watching. Worth knowing before you type into a terminal. */
+    othersWatching: number;
+    /** Advice for enabling a control — the host still arbitrates. */
+    canTakeOver: boolean;
+    canRelease: boolean;
+    /** One line a person can act on. */
+    headline: string;
+}
+export interface SessionBoard {
+    rows: SessionBoardRow[];
+    notice?: string;
+}
+export declare function projectSessionBoard(sessions: SessionBoardInput[], viewerId: string): SessionBoard;
+/**
+ * What to say about a snapshot of terminal output.
+ *
+ * 🔴 Truncation and emptiness are different, and neither is an error. Output
+ * that begins mid-sentence with no explanation reads as corruption; an empty
+ * terminal for a session that has genuinely printed nothing is just the truth.
+ * Only `available: false` means something went wrong.
+ */
+export declare function describeSessionOutput(snapshot: {
+    available: boolean;
+    output: string;
+    truncated: boolean;
+    reason?: string;
+}): {
+    text: string;
+    notice?: string;
+};
+//# sourceMappingURL=sessionBoardProjection.d.ts.map

package/dist/sessionBoardProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionBoardProjection.d.ts","sourceRoot":"","sources":["../src/sessionBoardProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;0DAC0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,OAAO,CAAA;IACnB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CAClF;AAED,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,KAAK,GAAG,aAAa,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,KAAK,EAAE,oBAAoB,CAAA;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,cAAc,EAAE,OAAO,CAAA;IACvB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,QAAQ,EAAE,MAAM,GACf,YAAY,CAgDd;AAcD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE;IAC9C,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAapC"}

package/dist/sessionBoardProjection.js

@@ -0,0 +1,103 @@
+/**
+ * What a session surface may SHOW — ADE §5.5 attach and takeover.
+ *
+ * `session.list` answers what exists; this decides what a person is told about
+ * their own relationship to each session, and what they may do about it. Pure,
+ * in `core`, for the reason `reviewProjection` and `fleetBoardProjection` are:
+ * an honesty rule written in JSX is enforced by whoever writes the next
+ * component.
+ *
+ * ## 🔴 The lease has THREE states, not two
+ *
+ * "Locked" is not enough. *You* hold it, *another human* holds it, or the
+ * *agent* holds it — and each implies a different action: keep typing, go find a
+ * colleague, or take over. A surface that renders the first two the same way
+ * tells one person their keystrokes are landing when they are being refused.
+ *
+ * ## Taking over is ADVICE here, never the decision
+ *
+ * `canTakeOver` exists so a button can be disabled, and that is all. The host
+ * arbitrates, and a surface that treated this as the gate would be a second
+ * implementation of the arbitration — which is how the two come to disagree,
+ * always in the direction of the optimistic one.
+ */
+export function projectSessionBoard(sessions, viewerId) {
+    const rows = sessions.map((session) => {
+        const lease = session.lease.holder === null
+            ? 'agent'
+            : session.lease.holder === viewerId
+                ? 'you'
+                : 'other-human';
+        const youAreWatching = session.viewers.includes(viewerId);
+        const othersWatching = session.viewers.filter((viewer) => viewer !== viewerId).length;
+        return {
+            sessionId: session.sessionId,
+            runId: session.runId,
+            mode: session.mode,
+            lease,
+            ...(lease === 'other-human' && session.lease.holder
+                ? { heldBy: session.lease.holder }
+                : {}),
+            interventions: session.lease.interventions,
+            viewers: session.viewers.length,
+            youAreWatching,
+            othersWatching,
+            // 🔴 Refused only when ANOTHER human holds it. The agent holding the lease
+            // is the ordinary case that takeover exists for, and a surface that
+            // disabled the control there would remove the feature.
+            canTakeOver: lease !== 'other-human',
+            canRelease: lease === 'you',
+            headline: headlineFor(lease, session),
+        };
+    });
+    // Newest first. A session list is read to find what is happening NOW, and the
+    // most recently opened session is the one most likely to be it.
+    rows.sort((left, right) => {
+        const leftAt = sessions.find((session) => session.sessionId === left.sessionId)?.openedAt ?? 0;
+        const rightAt = sessions.find((session) => session.sessionId === right.sessionId)?.openedAt ?? 0;
+        return rightAt === leftAt ? left.sessionId.localeCompare(right.sessionId) : rightAt - leftAt;
+    });
+    const contended = rows.filter((row) => row.lease === 'other-human').length;
+    return {
+        rows,
+        ...(contended > 0
+            ? {
+                notice: `${contended} session${contended === 1 ? ' is' : 's are'} being typed into by someone else. Your keystrokes there will be refused.`,
+            }
+            : {}),
+    };
+}
+function headlineFor(lease, session) {
+    if (lease === 'you') {
+        return 'You are typing. The agent cannot write until you hand it back.';
+    }
+    if (lease === 'other-human') {
+        return `${session.lease.holder} is typing in this session.`;
+    }
+    return session.lease.interventions > 0
+        ? `The agent is driving. Taken over ${session.lease.interventions} time${session.lease.interventions === 1 ? '' : 's'} so far.`
+        : 'The agent is driving.';
+}
+/**
+ * What to say about a snapshot of terminal output.
+ *
+ * 🔴 Truncation and emptiness are different, and neither is an error. Output
+ * that begins mid-sentence with no explanation reads as corruption; an empty
+ * terminal for a session that has genuinely printed nothing is just the truth.
+ * Only `available: false` means something went wrong.
+ */
+export function describeSessionOutput(snapshot) {
+    if (!snapshot.available) {
+        return { text: '', notice: snapshot.reason ?? 'This session could not be read.' };
+    }
+    if (snapshot.output.length === 0) {
+        return { text: '', notice: 'This session has printed nothing yet.' };
+    }
+    return {
+        text: snapshot.output,
+        ...(snapshot.truncated
+            ? { notice: 'Earlier output has been dropped — this is the most recent part only.' }
+            : {}),
+    };
+}
+//# sourceMappingURL=sessionBoardProjection.js.map

package/dist/sessionBoardProjection.js.map

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

package/dist/sessionMode.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Session render mode and input routing — ADE spec §2.8.
+ *
+ * ✅ CONSUMED since 2026-08-13 by `host/session/AgentSessionService`, the §2.8
+ * substrate these rules were written for. It carried an `@unwired-by-design`
+ * marker until that consumer existed; wiring it was the point, so the marker is
+ * gone rather than updated.
+ *
+ * ## 1. The modes are not simultaneous
+ *
+ * §2.8: "The two modes are not simultaneous for one process: a CLI in
+ * interactive TUI mode is not also serving ACP. Where an agent supports both,
+ * the user switches."
+ *
+ * So selection returns exactly ONE mode. An agent that supports both is
+ * *switchable*, which is a different statement from *running both* — and a
+ * caller handed `{nativeTui: true, acp: true}` would otherwise be free to
+ * believe the second one.
+ *
+ * ## 2. Typing never falls into a void
+ *
+ * §2.8: "Input is routed by the host: mid-turn steering where the agent accepts
+ * it, queued as the next turn where it does not. Typing never falls into a void,
+ * and human input is always recorded as a human intervention."
+ *
+ * `InputRouting` has no `drop` case. Not "we decided not to drop input" — there
+ * is no value that means it, so a caller cannot silently discard a keystroke and
+ * a future contributor cannot add that path without changing this type. Every
+ * outcome is also `recordedAs: 'human-intervention'`, because §2.8 says human
+ * input is ALWAYS recorded as one, and an unrecorded intervention is a change in
+ * the run that the timeline cannot explain.
+ */
+/** What renders into the session's PTY. */
+export type SessionRenderMode = 'native-tui' | 'acp';
+/** What an agent is capable of, not what it is doing. */
+export interface AgentRenderSupport {
+    /** The agent ships its own interactive TUI (Claude Code, Codex). */
+    nativeTui: boolean;
+    /** The agent can be driven headless over the protocol. */
+    acp: boolean;
+}
+export type SessionModeSelection = {
+    ok: true;
+    mode: SessionRenderMode;
+    /** True when the user may switch; §2.8 switching, never simultaneity. */
+    switchable: boolean;
+    reason: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Chooses the mode a session runs in.
+ *
+ * §2.8: "For a third-party agent with a good TUI, `native-tui` is the default
+ * and the right answer. Their interface is the product they built; reproducing
+ * it from protocol events yields a worse imitation of something a vendor
+ * invested years in, and it rots every time they ship an improvement."
+ *
+ * An agent supporting neither is a REFUSAL, not a fallback. Quietly picking
+ * `acp` for an agent that cannot serve it produces a session that renders
+ * nothing and reports no error — the failure mode where a caller believes it has
+ * a working terminal.
+ */
+export declare function selectSessionRenderMode(support: AgentRenderSupport, preference?: SessionRenderMode): SessionModeSelection;
+/**
+ * Where a keystroke goes.
+ *
+ * There is deliberately no `drop`. §2.8 is unambiguous that typing never falls
+ * into a void, and the strongest way to hold that is to leave no value that
+ * could express it.
+ */
+export type InputRouting = {
+    disposition: 'steer';
+    recordedAs: 'human-intervention';
+} | {
+    disposition: 'queue';
+    recordedAs: 'human-intervention';
+    reason: string;
+};
+export interface InputRoutingContext {
+    /** True while the agent is mid-turn. */
+    turnInFlight: boolean;
+    /** Whether this agent accepts input during a turn. Assumption 3 PROVED this
+     *  is achievable through a PTY we own — see docs/evidence/PTY_STEERING_2026-08-11.md
+     *  — but not every agent accepts it, and claiming otherwise for one that does
+     *  not would lose the input we promised never to lose. */
+    acceptsMidTurnSteering: boolean;
+}
+/**
+ * Where the keystrokes physically GO once routing has decided to steer.
+ *
+ * 🔴 Routing and delivery are different questions, and conflating them put
+ * typing into exactly the void `InputRouting` was shaped to forbid.
+ *
+ * In `native-tui` the PTY is the agent's own terminal: writing to it IS the
+ * steer, and it has happened by the time the call returns. In `acp` there is no
+ * process behind the PTY at all — it is a render target for the structured
+ * stream — so a write there reaches nobody. The steer has to travel the way
+ * every other host→agent instruction travels, through `turn.steer`, which the
+ * caller owns because that is where acknowledgement and idempotency live.
+ *
+ * So a caller cannot act on the disposition alone: doing the right thing for one
+ * mode is either a double-delivery or a dropped keystroke in the other. It has
+ * to be told which sink was used.
+ */
+export type InputSink = 'pty' | 'turn.steer' | 'turn.queue';
+export interface InputDelivery {
+    /** True when the session has ALREADY put the keystrokes in front of the agent. */
+    delivered: boolean;
+    sink: InputSink;
+}
+export declare function deliveryFor(mode: SessionRenderMode, routing: InputRouting): InputDelivery;
+export declare function routeHumanInput(context: InputRoutingContext): InputRouting;
+//# sourceMappingURL=sessionMode.d.ts.map

package/dist/sessionMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionMode.d.ts","sourceRoot":"","sources":["../src/sessionMode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,KAAK,CAAA;AAEpD,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,GAAG,EAAE,OAAO,CAAA;CACb;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,EAAE,EAAE,IAAI,CAAA;IACR,IAAI,EAAE,iBAAiB,CAAA;IACvB,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjC;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,oBAAoB,CAwCtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,WAAW,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,oBAAoB,CAAA;CAAE,GAC1D;IAAE,WAAW,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9E,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,YAAY,EAAE,OAAO,CAAA;IACrB;;;8DAG0D;IAC1D,sBAAsB,EAAE,OAAO,CAAA;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,YAAY,GAAG,YAAY,CAAA;AAE3D,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa,CAKzF;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAS1E"}

package/dist/sessionMode.js

@@ -0,0 +1,98 @@
+/**
+ * Session render mode and input routing — ADE spec §2.8.
+ *
+ * ✅ CONSUMED since 2026-08-13 by `host/session/AgentSessionService`, the §2.8
+ * substrate these rules were written for. It carried an `@unwired-by-design`
+ * marker until that consumer existed; wiring it was the point, so the marker is
+ * gone rather than updated.
+ *
+ * ## 1. The modes are not simultaneous
+ *
+ * §2.8: "The two modes are not simultaneous for one process: a CLI in
+ * interactive TUI mode is not also serving ACP. Where an agent supports both,
+ * the user switches."
+ *
+ * So selection returns exactly ONE mode. An agent that supports both is
+ * *switchable*, which is a different statement from *running both* — and a
+ * caller handed `{nativeTui: true, acp: true}` would otherwise be free to
+ * believe the second one.
+ *
+ * ## 2. Typing never falls into a void
+ *
+ * §2.8: "Input is routed by the host: mid-turn steering where the agent accepts
+ * it, queued as the next turn where it does not. Typing never falls into a void,
+ * and human input is always recorded as a human intervention."
+ *
+ * `InputRouting` has no `drop` case. Not "we decided not to drop input" — there
+ * is no value that means it, so a caller cannot silently discard a keystroke and
+ * a future contributor cannot add that path without changing this type. Every
+ * outcome is also `recordedAs: 'human-intervention'`, because §2.8 says human
+ * input is ALWAYS recorded as one, and an unrecorded intervention is a change in
+ * the run that the timeline cannot explain.
+ */
+/**
+ * Chooses the mode a session runs in.
+ *
+ * §2.8: "For a third-party agent with a good TUI, `native-tui` is the default
+ * and the right answer. Their interface is the product they built; reproducing
+ * it from protocol events yields a worse imitation of something a vendor
+ * invested years in, and it rots every time they ship an improvement."
+ *
+ * An agent supporting neither is a REFUSAL, not a fallback. Quietly picking
+ * `acp` for an agent that cannot serve it produces a session that renders
+ * nothing and reports no error — the failure mode where a caller believes it has
+ * a working terminal.
+ */
+export function selectSessionRenderMode(support, preference) {
+    const switchable = support.nativeTui && support.acp;
+    if (!support.nativeTui && !support.acp) {
+        return {
+            ok: false,
+            reason: 'the agent declares neither a native TUI nor ACP, so nothing can render into its session',
+        };
+    }
+    if (preference) {
+        const supported = preference === 'native-tui' ? support.nativeTui : support.acp;
+        if (!supported) {
+            // Honouring an impossible preference silently would hand back a mode the
+            // agent cannot serve; refusing names which half is missing.
+            return {
+                ok: false,
+                reason: `the agent does not support ${preference}`,
+            };
+        }
+        return {
+            ok: true,
+            mode: preference,
+            switchable,
+            reason: 'explicit user preference',
+        };
+    }
+    if (support.nativeTui) {
+        return {
+            ok: true,
+            mode: 'native-tui',
+            switchable,
+            reason: "the agent's own TUI is the product its vendor built; rendering it from protocol events would be a worse imitation that rots on every upstream release",
+        };
+    }
+    return { ok: true, mode: 'acp', switchable, reason: 'the agent is headless-only' };
+}
+export function deliveryFor(mode, routing) {
+    if (routing.disposition === 'queue')
+        return { delivered: false, sink: 'turn.queue' };
+    return mode === 'native-tui'
+        ? { delivered: true, sink: 'pty' }
+        : { delivered: false, sink: 'turn.steer' };
+}
+export function routeHumanInput(context) {
+    if (context.turnInFlight && !context.acceptsMidTurnSteering) {
+        return {
+            disposition: 'queue',
+            recordedAs: 'human-intervention',
+            reason: 'the agent does not accept input mid-turn; delivered as the next turn',
+        };
+    }
+    return { disposition: 'steer', recordedAs: 'human-intervention' };
+}
+//# sourceMappingURL=sessionMode.js.map

package/dist/sessionMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionMode.js","sourceRoot":"","sources":["../src/sessionMode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAuBH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA2B,EAC3B,UAA8B;IAE9B,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAA;IAEnD,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACvC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,yFAAyF;SAC5F,CAAA;IACH,CAAC;IAED,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,UAAU,KAAK,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA;QAC/E,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,yEAAyE;YACzE,4DAA4D;YAC5D,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,8BAA8B,UAAU,EAAE;aACnD,CAAA;QACH,CAAC;QACD,OAAO;YACL,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,UAAU;YAChB,UAAU;YACV,MAAM,EAAE,0BAA0B;SACnC,CAAA;IACH,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO;YACL,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,YAAY;YAClB,UAAU;YACV,MAAM,EACJ,uJAAuJ;SAC1J,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAA;AACpF,CAAC;AAgDD,MAAM,UAAU,WAAW,CAAC,IAAuB,EAAE,OAAqB;IACxE,IAAI,OAAO,CAAC,WAAW,KAAK,OAAO;QAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,CAAA;IACpF,OAAO,IAAI,KAAK,YAAY;QAC1B,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE;QAClC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAA4B;IAC1D,IAAI,OAAO,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC;QAC5D,OAAO;YACL,WAAW,EAAE,OAAO;YACpB,UAAU,EAAE,oBAAoB;YAChC,MAAM,EAAE,sEAAsE;SAC/E,CAAA;IACH,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAA;AACnE,CAAC"}

package/dist/workspace/workspaceSelectionContinuation.d.ts

@@ -0,0 +1,8 @@
+export type WorkspaceSelectionChoice = 'inbox' | 'reuse' | 'create';
+export interface WorkspaceSelectionContinuationInput {
+    choice: WorkspaceSelectionChoice;
+    directory: string;
+    result: string;
+}
+export declare function buildWorkspaceSelectionContinuationPrompt(input: WorkspaceSelectionContinuationInput): string;
+//# sourceMappingURL=workspaceSelectionContinuation.d.ts.map

package/dist/workspace/workspaceSelectionContinuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceSelectionContinuation.d.ts","sourceRoot":"","sources":["../../src/workspace/workspaceSelectionContinuation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEnE,MAAM,WAAW,mCAAmC;IAClD,MAAM,EAAE,wBAAwB,CAAA;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,yCAAyC,CACvD,KAAK,EAAE,mCAAmC,GACzC,MAAM,CAiBR"}

package/dist/workspace/workspaceSelectionContinuation.js

@@ -0,0 +1,18 @@
+export function buildWorkspaceSelectionContinuationPrompt(input) {
+    const payload = JSON.stringify({
+        type: 'workspace_selection.completed',
+        status: 'completed',
+        choice: input.choice,
+        directory: input.directory,
+        result: input.result,
+    });
+    return [
+        'This is an internal XENO Hub continuation event, not a new user request.',
+        '<xeno_workspace_selection_result>',
+        payload,
+        '</xeno_workspace_selection_result>',
+        'Acknowledge the completed workspace-placement result naturally and briefly.',
+        'Do not call tools, ask the user to choose again, repeat the available choices, or restart the original request.',
+    ].join('\n');
+}
+//# sourceMappingURL=workspaceSelectionContinuation.js.map

package/dist/workspace/workspaceSelectionContinuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceSelectionContinuation.js","sourceRoot":"","sources":["../../src/workspace/workspaceSelectionContinuation.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,yCAAyC,CACvD,KAA0C;IAE1C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,EAAE,+BAA+B;QACrC,MAAM,EAAE,WAAW;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAA;IAEF,OAAO;QACL,0EAA0E;QAC1E,mCAAmC;QACnC,OAAO;QACP,oCAAoC;QACpC,6EAA6E;QAC7E,iHAAiH;KAClH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC"}

package/dist/workspaceKnowledge.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Workspace knowledge — ADE §5.8 LEARN.
+ *
+ * The workspace getting better at *this* codebase over time, without the user
+ * re-explaining it every session.
+ *
+ * ## 🔴 The gate is CROSS-PROVIDER, and that is the whole design
+ *
+ * §5.8: *"a fact established in one run is available to a different provider in
+ * a later run without the user restating it."*
+ *
+ * So provenance is RECORDED and never CONSULTED for selection. A fact learned
+ * by Claude must reach a GPT run, and an implementation that filtered by
+ * provider — even reasonably, even to avoid "contaminating" a lane — would pass
+ * every test written from the inside and fail the one property the pillar
+ * exists for. Selection here does not receive a provider id at all; that is the
+ * simplest way to make the mistake unrepresentable.
+ *
+ * ## Boundary
+ *
+ * This is *workspace* knowledge — conventions, architecture, prior decisions.
+ * Agent-owned earned memory (the Soul model) belongs to `xeno-anima`. A fact
+ * here describes the CODEBASE, not the agent.
+ *
+ * ## Superseded facts are kept, and not injected
+ *
+ * "We use npm" then "we moved to pnpm" must not both reach a prompt: an agent
+ * given both will pick one at random and be right half the time. The later fact
+ * about a subject wins. The earlier one stays in the record, because "when did
+ * this change, and who decided?" is a question people actually ask.
+ */
+export interface KnowledgeProvenance {
+    /** The run that established it — so "why does it think that?" is answerable. */
+    runId: string;
+    /** RECORDED for provenance. Never used to decide what a later run sees. */
+    providerId?: string;
+    at: number;
+}
+export interface WorkspaceKnowledgeEntry {
+    id: string;
+    workspaceId: string;
+    /**
+     * What the fact is ABOUT — `build.package-manager`, `testing.framework`.
+     * Supersession is per subject, so this is what makes "we moved to pnpm"
+     * replace "we use npm" rather than sit beside it.
+     */
+    subject: string;
+    fact: string;
+    /**
+     * Always included, regardless of budget. For foundational conventions that
+     * stop being followed the moment they fall out of a prompt.
+     */
+    pinned?: boolean;
+    provenance: KnowledgeProvenance;
+}
+export interface KnowledgeSelection {
+    /** What should go into the prompt, in the order it should appear. */
+    entries: WorkspaceKnowledgeEntry[];
+    /** Facts left out for budget. Named, never silently dropped. */
+    omitted: Array<{
+        subject: string;
+        reason: string;
+    }>;
+    /** Superseded by a later fact about the same subject. Kept for the record. */
+    superseded: WorkspaceKnowledgeEntry[];
+    /** True when everything current fitted. */
+    complete: boolean;
+}
+export interface KnowledgeSelectionOptions {
+    /**
+     * Rough character budget for the injected block.
+     *
+     * Characters rather than tokens on purpose: a token count needs a tokenizer
+     * per provider, and this must not vary by provider — see the header. Characters
+     * are provider-neutral and wrong by a constant factor, which a caller can size
+     * around.
+     */
+    maxChars?: number;
+}
+/**
+ * Chooses which facts reach a prompt.
+ *
+ * 🔴 Takes NO provider argument. See the header: the gate is that a fact crosses
+ * provider lanes, and a signature that cannot express "filter by provider"
+ * cannot accidentally do it.
+ */
+export declare function selectWorkspaceKnowledge(entries: readonly WorkspaceKnowledgeEntry[], options?: KnowledgeSelectionOptions): KnowledgeSelection;
+/** Renders the selection as the block that goes into a prompt. */
+export declare function renderWorkspaceKnowledge(selection: KnowledgeSelection): string;
+//# sourceMappingURL=workspaceKnowledge.d.ts.map

package/dist/workspaceKnowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceKnowledge.d.ts","sourceRoot":"","sources":["../src/workspaceKnowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAA;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,EAAE,uBAAuB,EAAE,CAAA;IAClC,gEAAgE;IAChE,OAAO,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnD,8EAA8E;IAC9E,UAAU,EAAE,uBAAuB,EAAE,CAAA;IACrC,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,uBAAuB,EAAE,EAC3C,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAsDpB;AAED,kEAAkE;AAClE,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAS9E"}

package/dist/workspaceKnowledge.js

@@ -0,0 +1,103 @@
+/**
+ * Workspace knowledge — ADE §5.8 LEARN.
+ *
+ * The workspace getting better at *this* codebase over time, without the user
+ * re-explaining it every session.
+ *
+ * ## 🔴 The gate is CROSS-PROVIDER, and that is the whole design
+ *
+ * §5.8: *"a fact established in one run is available to a different provider in
+ * a later run without the user restating it."*
+ *
+ * So provenance is RECORDED and never CONSULTED for selection. A fact learned
+ * by Claude must reach a GPT run, and an implementation that filtered by
+ * provider — even reasonably, even to avoid "contaminating" a lane — would pass
+ * every test written from the inside and fail the one property the pillar
+ * exists for. Selection here does not receive a provider id at all; that is the
+ * simplest way to make the mistake unrepresentable.
+ *
+ * ## Boundary
+ *
+ * This is *workspace* knowledge — conventions, architecture, prior decisions.
+ * Agent-owned earned memory (the Soul model) belongs to `xeno-anima`. A fact
+ * here describes the CODEBASE, not the agent.
+ *
+ * ## Superseded facts are kept, and not injected
+ *
+ * "We use npm" then "we moved to pnpm" must not both reach a prompt: an agent
+ * given both will pick one at random and be right half the time. The later fact
+ * about a subject wins. The earlier one stays in the record, because "when did
+ * this change, and who decided?" is a question people actually ask.
+ */
+const DEFAULT_MAX_CHARS = 4_000;
+/**
+ * Chooses which facts reach a prompt.
+ *
+ * 🔴 Takes NO provider argument. See the header: the gate is that a fact crosses
+ * provider lanes, and a signature that cannot express "filter by provider"
+ * cannot accidentally do it.
+ */
+export function selectWorkspaceKnowledge(entries, options = {}) {
+    const maxChars = options.maxChars ?? DEFAULT_MAX_CHARS;
+    // Latest per subject wins. Ties go to the later id so the choice is stable
+    // rather than dependent on input order.
+    const currentBySubject = new Map();
+    const superseded = [];
+    for (const entry of [...entries].sort((left, right) => left.provenance.at === right.provenance.at
+        ? left.id.localeCompare(right.id)
+        : left.provenance.at - right.provenance.at)) {
+        const existing = currentBySubject.get(entry.subject);
+        if (existing)
+            superseded.push(existing);
+        currentBySubject.set(entry.subject, entry);
+    }
+    const current = [...currentBySubject.values()];
+    // Pinned first, then newest. Pinned exists because a foundational convention
+    // is usually the OLDEST fact on record, and a pure recency order drops exactly
+    // those first — the conventions stop being followed and nobody knows why.
+    const ordered = current.sort((left, right) => {
+        if (Boolean(left.pinned) !== Boolean(right.pinned))
+            return left.pinned ? -1 : 1;
+        return right.provenance.at - left.provenance.at;
+    });
+    const selected = [];
+    const omitted = [];
+    let used = 0;
+    for (const entry of ordered) {
+        const cost = entry.subject.length + entry.fact.length + 2;
+        // Pinned bypasses the budget rather than competing for it. A budget that
+        // could drop a pinned convention would make `pinned` a suggestion.
+        if (entry.pinned || used + cost <= maxChars) {
+            selected.push(entry);
+            used += cost;
+            continue;
+        }
+        omitted.push({
+            subject: entry.subject,
+            reason: 'left out of this prompt for space',
+        });
+    }
+    return {
+        entries: selected,
+        omitted,
+        superseded,
+        // 🔴 Complete means every CURRENT fact was included. A prompt missing
+        // knowledge makes an agent look like it forgot, with nothing on screen to
+        // explain why — so the omission is reported rather than inferred from a
+        // shorter block nobody counted.
+        complete: omitted.length === 0,
+    };
+}
+/** Renders the selection as the block that goes into a prompt. */
+export function renderWorkspaceKnowledge(selection) {
+    if (selection.entries.length === 0)
+        return '';
+    const lines = selection.entries.map((entry) => `- ${entry.subject}: ${entry.fact}`);
+    if (!selection.complete) {
+        // Stated IN the prompt, not only to the surface: the agent should know its
+        // context was trimmed, so it can ask rather than assume.
+        lines.push(`- (${selection.omitted.length} further fact(s) omitted for space)`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=workspaceKnowledge.js.map