@moxxy/channel-kit 0.27.0

package/dist/pairing/host-code.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Host-issued-code pairing — the pure state machine behind Telegram's QR /
+ * deep-link chat pairing, generic over the peer identifier (a Telegram chat id,
+ * a Discord DM channel, a WhatsApp JID, ...).
+ *
+ * A control surface (desktop Channels panel, `moxxy channels <name> pair` in a
+ * terminal) opens a window with {@link openHostCodeWindow}: the code is minted
+ * UP FRONT by the caller so the surface can embed it in a deep link and render
+ * that as a QR. The user scans / opens the link (the messenger round-trips the
+ * code back to the bot) or simply sends the code as a message; the channel
+ * calls {@link submitPeerCode}, and on match that peer is authorized.
+ *
+ * Security property: "prove you can see the host's screen" — the code only ever
+ * lives on the surface. No TTL by default: the window's lifetime is the channel
+ * process's lifetime while unpaired; a caller may still bound it with `ttlMs`.
+ *
+ * Decisions carry semantic `kind`s only — user-facing messages (and their
+ * channel-specific wording, e.g. "run `moxxy channels telegram pair`") are
+ * mapped by each channel.
+ */
+export type HostCodePhase = 'idle' | 'awaiting-host-code' | 'paired' | 'expired';
+export interface HostCodeState<P> {
+    readonly phase: HostCodePhase;
+    readonly code: string | null;
+    readonly expiresAt: number | null;
+    readonly authorizedPeer: P | null;
+}
+export type HostCodeAction<P> = 
+/** The presented code matched — the peer is now authorized. */
+{
+    readonly kind: 'paired';
+    readonly peer: P;
+}
+/** The already-authorized peer showed up again (idempotent; greet it). */
+ | {
+    readonly kind: 'still-paired';
+    readonly peer: P;
+}
+/** A DIFFERENT peer while one is authorized — access denied. */
+ | {
+    readonly kind: 'rejected-foreign-peer';
+}
+/** Bare hello while a window is open — nudge toward the QR / code. */
+ | {
+    readonly kind: 'window-open-hint';
+}
+/** Bare hello with no window open — nudge toward starting pairing. */
+ | {
+    readonly kind: 'no-window';
+}
+/** A code was presented but no window is open. */
+ | {
+    readonly kind: 'not-pending';
+}
+/** The window's optional TTL elapsed. */
+ | {
+    readonly kind: 'expired';
+}
+/** The presented code didn't match. */
+ | {
+    readonly kind: 'mismatch';
+};
+export interface HostCodeDecision<P> {
+    readonly state: HostCodeState<P>;
+    readonly action: HostCodeAction<P>;
+}
+export declare function createHostCodeState<P>(opts?: {
+    authorizedPeer?: P | null;
+}): HostCodeState<P>;
+/**
+ * Open a host-issued pairing window with a pre-minted code (the caller mints it
+ * so it can embed the code in the deep link / QR it shows the user).
+ */
+export declare function openHostCodeWindow<P>(state: HostCodeState<P>, opts: {
+    code: string;
+    now?: number;
+    ttlMs?: number | null;
+}): {
+    state: HostCodeState<P>;
+    code: string;
+};
+/**
+ * A peer said hello WITHOUT presenting a code (e.g. a bare Telegram `/start` —
+ * the user opened the chat manually rather than via the pairing deep link).
+ */
+export declare function greetPeer<P>(state: HostCodeState<P>, peer: P): HostCodeDecision<P>;
+/**
+ * A peer PRESENTED a code (deep-link payload or a plain message). Whitespace is
+ * stripped before comparing; on match the peer is authorized.
+ */
+export declare function submitPeerCode<P>(state: HostCodeState<P>, peer: P, rawCode: string, now?: number): HostCodeDecision<P>;
+export declare function isPeerAuthorized<P>(state: HostCodeState<P>, peer: P): boolean;
+export declare function clearHostCodePairing<P>(_state: HostCodeState<P>): HostCodeState<P>;
+//# sourceMappingURL=host-code.d.ts.map

package/dist/pairing/host-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-code.d.ts","sourceRoot":"","sources":["../../src/pairing/host-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GAEN,oBAAoB,GACpB,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,MAAM,cAAc,CAAC,CAAC;AAC1B,+DAA+D;AAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE;AAC/C,0EAA0E;GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE;AACrD,gEAAgE;GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAA;CAAE;AAC5C,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE;AACvC,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE;AAChC,kDAAkD;GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAClC,yCAAyC;GACvC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,uCAAuC;GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CACpC;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,CAAC,GAAG,IAAI,CAAA;CAAO,GACvC,aAAa,CAAC,CAAC,CAAC,CAOlB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC1D;IAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAY3C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAWlF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAmB,GACvB,gBAAgB,CAAC,CAAC,CAAC,CA6BrB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAE7E;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAOlF"}

package/dist/pairing/host-code.js

@@ -0,0 +1,107 @@
+/**
+ * Host-issued-code pairing — the pure state machine behind Telegram's QR /
+ * deep-link chat pairing, generic over the peer identifier (a Telegram chat id,
+ * a Discord DM channel, a WhatsApp JID, ...).
+ *
+ * A control surface (desktop Channels panel, `moxxy channels <name> pair` in a
+ * terminal) opens a window with {@link openHostCodeWindow}: the code is minted
+ * UP FRONT by the caller so the surface can embed it in a deep link and render
+ * that as a QR. The user scans / opens the link (the messenger round-trips the
+ * code back to the bot) or simply sends the code as a message; the channel
+ * calls {@link submitPeerCode}, and on match that peer is authorized.
+ *
+ * Security property: "prove you can see the host's screen" — the code only ever
+ * lives on the surface. No TTL by default: the window's lifetime is the channel
+ * process's lifetime while unpaired; a caller may still bound it with `ttlMs`.
+ *
+ * Decisions carry semantic `kind`s only — user-facing messages (and their
+ * channel-specific wording, e.g. "run `moxxy channels telegram pair`") are
+ * mapped by each channel.
+ */
+export function createHostCodeState(opts = {}) {
+    return {
+        phase: opts.authorizedPeer != null ? 'paired' : 'idle',
+        code: null,
+        expiresAt: null,
+        authorizedPeer: opts.authorizedPeer ?? null,
+    };
+}
+/**
+ * Open a host-issued pairing window with a pre-minted code (the caller mints it
+ * so it can embed the code in the deep link / QR it shows the user).
+ */
+export function openHostCodeWindow(state, opts) {
+    const ttlMs = opts.ttlMs ?? null;
+    const now = opts.now ?? Date.now();
+    return {
+        state: {
+            ...state,
+            phase: 'awaiting-host-code',
+            code: opts.code,
+            expiresAt: ttlMs == null ? null : now + ttlMs,
+        },
+        code: opts.code,
+    };
+}
+/**
+ * A peer said hello WITHOUT presenting a code (e.g. a bare Telegram `/start` —
+ * the user opened the chat manually rather than via the pairing deep link).
+ */
+export function greetPeer(state, peer) {
+    if (state.authorizedPeer === peer && state.phase === 'paired') {
+        return { state, action: { kind: 'still-paired', peer } };
+    }
+    if (state.authorizedPeer !== null && state.authorizedPeer !== peer) {
+        return { state, action: { kind: 'rejected-foreign-peer' } };
+    }
+    if (state.phase === 'awaiting-host-code') {
+        return { state, action: { kind: 'window-open-hint' } };
+    }
+    return { state, action: { kind: 'no-window' } };
+}
+/**
+ * A peer PRESENTED a code (deep-link payload or a plain message). Whitespace is
+ * stripped before comparing; on match the peer is authorized.
+ */
+export function submitPeerCode(state, peer, rawCode, now = Date.now()) {
+    if (state.phase === 'paired' && state.authorizedPeer === peer) {
+        return { state, action: { kind: 'still-paired', peer } };
+    }
+    if (state.authorizedPeer !== null && state.authorizedPeer !== peer) {
+        return { state, action: { kind: 'rejected-foreign-peer' } };
+    }
+    if (state.phase !== 'awaiting-host-code') {
+        return { state, action: { kind: 'not-pending' } };
+    }
+    if (state.expiresAt !== null && now > state.expiresAt) {
+        return {
+            state: { ...state, phase: 'expired', code: null, expiresAt: null },
+            action: { kind: 'expired' },
+        };
+    }
+    const normalized = rawCode.replace(/\s+/g, '');
+    if (!normalized || normalized !== state.code) {
+        return { state, action: { kind: 'mismatch' } };
+    }
+    return {
+        state: {
+            phase: 'paired',
+            code: null,
+            expiresAt: null,
+            authorizedPeer: peer,
+        },
+        action: { kind: 'paired', peer },
+    };
+}
+export function isPeerAuthorized(state, peer) {
+    return state.phase === 'paired' && state.authorizedPeer === peer;
+}
+export function clearHostCodePairing(_state) {
+    return {
+        phase: 'idle',
+        code: null,
+        expiresAt: null,
+        authorizedPeer: null,
+    };
+}
+//# sourceMappingURL=host-code.js.map

package/dist/pairing/host-code.js.map

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

package/dist/pairing/tofu.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Trust-on-first-use pairing window — the mechanism behind Slack's pair flow,
+ * generic over the candidate shape (Slack: `{ teamId, channelId }`).
+ *
+ * A pair flow arms the window, then the channel's ingest path `offer`s every
+ * verified inbound event's origin. While armed, the first candidate is captured
+ * (listeners — the interactive pair flow — are notified and ask the operator to
+ * confirm) and CONSUMED, so the very first message just establishes trust
+ * rather than driving a turn. Confirmation + persistence stay with the channel
+ * (it owns the vault key format); it calls `disarm()` once authorized.
+ */
+export interface TofuPairingWindowOptions {
+    /** Observe a listener throwing (channels log it); never propagates. */
+    readonly onListenerError?: (err: unknown) => void;
+}
+export declare class TofuPairingWindow<C> {
+    private armed;
+    private readonly listeners;
+    private readonly opts;
+    constructor(opts?: TofuPairingWindowOptions);
+    get isArmed(): boolean;
+    arm(): void;
+    disarm(): void;
+    /** Subscribe to captured candidates. Returns an unsubscribe function. */
+    onCandidate(listener: (candidate: C) => void): () => void;
+    /**
+     * Present a verified inbound origin. While armed, notifies listeners and
+     * returns true — the event was consumed by pairing and must NOT also drive a
+     * turn. Returns false when no window is armed.
+     */
+    offer(candidate: C): boolean;
+}
+//# sourceMappingURL=tofu.d.ts.map

package/dist/pairing/tofu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tofu.d.ts","sourceRoot":"","sources":["../../src/pairing/tofu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED,qBAAa,iBAAiB,CAAC,CAAC;IAC9B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;gBAEpC,IAAI,GAAE,wBAA6B;IAI/C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,GAAG,IAAI,IAAI;IAIX,MAAM,IAAI,IAAI;IAId,yEAAyE;IACzE,WAAW,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKzD;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,CAAC,GAAG,OAAO;CAW7B"}

package/dist/pairing/tofu.js

@@ -0,0 +1,41 @@
+export class TofuPairingWindow {
+    armed = false;
+    listeners = new Set();
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    get isArmed() {
+        return this.armed;
+    }
+    arm() {
+        this.armed = true;
+    }
+    disarm() {
+        this.armed = false;
+    }
+    /** Subscribe to captured candidates. Returns an unsubscribe function. */
+    onCandidate(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Present a verified inbound origin. While armed, notifies listeners and
+     * returns true — the event was consumed by pairing and must NOT also drive a
+     * turn. Returns false when no window is armed.
+     */
+    offer(candidate) {
+        if (!this.armed)
+            return false;
+        for (const listener of this.listeners) {
+            try {
+                listener(candidate);
+            }
+            catch (err) {
+                this.opts.onListenerError?.(err);
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=tofu.js.map

package/dist/pairing/tofu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tofu.js","sourceRoot":"","sources":["../../src/pairing/tofu.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,iBAAiB;IACpB,KAAK,GAAG,KAAK,CAAC;IACL,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,IAAI,CAA2B;IAEhD,YAAY,OAAiC,EAAE;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,GAAG;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,yEAAyE;IACzE,WAAW,CAAC,QAAgC;QAC1C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAY;QAChB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAC9B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,SAAS,CAAC,CAAC;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/permission.d.ts

@@ -0,0 +1,28 @@
+import type { PendingToolCall, PermissionResolver } from '@moxxy/sdk';
+/**
+ * Autonomous allow-list permission resolver with an audit hook — the shared
+ * wiring for hands-off channels (Slack-style: no human in the loop; the
+ * operator declares trust upfront via an `allowedTools` list).
+ *
+ * Reuses the SDK's {@link createAllowListResolver} (exact-name match →
+ * `allow_session`, else `deny`) rather than re-implementing the trust check,
+ * and adds the two things every autonomous channel needs:
+ *
+ *   - `'*'` expansion — `['*']` means "allow every registered tool", expanded
+ *     against `allToolNames` at channel-start time (mirrors the CLI's
+ *     `--allow-all`). An empty list denies everything (effectively read-only).
+ *   - an audit hook — `onAutoApprove` fires for every non-denied call so an
+ *     autonomous run leaves a trail of what it ran (channels log it).
+ */
+export interface AuditedAllowListOptions {
+    /** Resolver name surfaced in permission events (e.g. 'slack-allow-list'). */
+    readonly name: string;
+    readonly allowedTools: ReadonlyArray<string>;
+    /** Every registered tool name — the expansion target for `'*'`. */
+    readonly allToolNames: ReadonlyArray<string>;
+    readonly onAutoApprove?: (call: PendingToolCall, info: {
+        readonly wildcard: boolean;
+    }) => void;
+}
+export declare function createAuditedAllowListResolver(opts: AuditedAllowListOptions): PermissionResolver;
+//# sourceMappingURL=permission.d.ts.map

package/dist/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7C,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,KACjC,IAAI,CAAC;CACX;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,uBAAuB,GAAG,kBAAkB,CAehG"}

package/dist/permission.js

@@ -0,0 +1,17 @@
+import { createAllowListResolver } from '@moxxy/sdk';
+export function createAuditedAllowListResolver(opts) {
+    const wildcard = opts.allowedTools.includes('*');
+    const effective = wildcard ? [...opts.allToolNames] : [...opts.allowedTools];
+    const inner = createAllowListResolver(effective);
+    return {
+        name: opts.name,
+        async check(call, ctx) {
+            const decision = await inner.check(call, ctx);
+            if (decision.mode !== 'deny') {
+                opts.onAutoApprove?.(call, { wildcard });
+            }
+            return decision;
+        },
+    };
+}
+//# sourceMappingURL=permission.js.map

package/dist/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA8BrD,MAAM,UAAU,8BAA8B,CAAC,IAA6B;IAC1E,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAEjD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG;YACnB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC9C,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC7B,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/plain-turn-renderer.d.ts

@@ -0,0 +1,17 @@
+import type { MoxxyEvent } from '@moxxy/sdk';
+/**
+ * Accumulate streamed assistant text from the event log into a single growing
+ * snapshot — the minimal plain-text turn renderer for channels without a rich
+ * frame format (Slack v1 and future thin adapters). `assistant_chunk` deltas
+ * render live; the final `assistant_message` content (which supersedes the
+ * streamed deltas for the same turn) wins so the last edit always carries the
+ * complete reply.
+ */
+export declare class PlainTurnRenderer {
+    private streamed;
+    private finalText;
+    /** Returns true when the event changed the snapshot (schedule an edit). */
+    accept(event: MoxxyEvent): boolean;
+    snapshot(): string;
+}
+//# sourceMappingURL=plain-turn-renderer.d.ts.map

package/dist/plain-turn-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain-turn-renderer.d.ts","sourceRoot":"","sources":["../src/plain-turn-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAuB;IAExC,2EAA2E;IAC3E,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;IAYlC,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/plain-turn-renderer.js

@@ -0,0 +1,28 @@
+/**
+ * Accumulate streamed assistant text from the event log into a single growing
+ * snapshot — the minimal plain-text turn renderer for channels without a rich
+ * frame format (Slack v1 and future thin adapters). `assistant_chunk` deltas
+ * render live; the final `assistant_message` content (which supersedes the
+ * streamed deltas for the same turn) wins so the last edit always carries the
+ * complete reply.
+ */
+export class PlainTurnRenderer {
+    streamed = '';
+    finalText = null;
+    /** Returns true when the event changed the snapshot (schedule an edit). */
+    accept(event) {
+        if (event.type === 'assistant_chunk') {
+            this.streamed += event.delta;
+            return true;
+        }
+        if (event.type === 'assistant_message') {
+            this.finalText = event.content;
+            return true;
+        }
+        return false;
+    }
+    snapshot() {
+        return (this.finalText ?? this.streamed).trim();
+    }
+}
+//# sourceMappingURL=plain-turn-renderer.js.map

package/dist/plain-turn-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain-turn-renderer.js","sourceRoot":"","sources":["../src/plain-turn-renderer.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACpB,QAAQ,GAAG,EAAE,CAAC;IACd,SAAS,GAAkB,IAAI,CAAC;IAExC,2EAA2E;IAC3E,MAAM,CAAC,KAAiB;QACtB,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YACrC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;YACvC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,CAAC;CACF"}

package/dist/secrets.d.ts

@@ -0,0 +1,18 @@
+/** The read slice of the vault a channel secret lookup needs. */
+export interface SecretReader {
+    get(name: string): Promise<string | null>;
+}
+export interface SecretSpec {
+    /** Env override — beats the vault, matching every channel's precedence. */
+    readonly envVar?: string;
+    /** Vault key the channel stores the secret under. */
+    readonly vaultKey: string;
+}
+/**
+ * Resolve a channel secret: env override first, then the vault. Values are
+ * trimmed and empty strings are treated as unset (an env var set to whitespace
+ * falls through to the vault rather than masking it). Returns null when
+ * neither source has a value.
+ */
+export declare function resolveSecret(vault: SecretReader, spec: SecretSpec): Promise<string | null>;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOjG"}

package/dist/secrets.js

@@ -0,0 +1,16 @@
+/**
+ * Resolve a channel secret: env override first, then the vault. Values are
+ * trimmed and empty strings are treated as unset (an env var set to whitespace
+ * falls through to the vault rather than masking it). Returns null when
+ * neither source has a value.
+ */
+export async function resolveSecret(vault, spec) {
+    if (spec.envVar) {
+        const fromEnv = process.env[spec.envVar]?.trim();
+        if (fromEnv)
+            return fromEnv;
+    }
+    const stored = (await vault.get(spec.vaultKey))?.trim();
+    return stored || null;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAmB,EAAE,IAAgB;IACvE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;QACjD,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACxD,OAAO,MAAM,IAAI,IAAI,CAAC;AACxB,CAAC"}

package/dist/turn.d.ts

@@ -0,0 +1,96 @@
+import type { MoxxyEvent, RunTurnOptions, TurnId } from '@moxxy/sdk';
+/**
+ * Turn machinery shared by messaging channels that multiplex onto ONE shared
+ * Session (AGENTS.md invariant #8: filter event-log subscribers by turnId —
+ * `session.log` fans out to every listener, so concurrent turns on the same
+ * Session cross-contaminate without it).
+ *
+ * Pieces are deliberately composable rather than one monolithic runner so each
+ * channel keeps its exact flush / typing / unwind ordering:
+ *   - {@link TurnCoordinator} — single-flight `busy` guard, per-turn
+ *     AbortController, bounded own-turn-id tracking, foreign-turn mirror gate.
+ *   - {@link subscribeTurn} — turnId-filtered `session.log.subscribe`.
+ *   - {@link driveTurn} — drain `session.runTurn` for a pre-minted turnId.
+ */
+/** The slice of a session a channel turn needs: the live event log. */
+export interface TurnEventSource {
+    readonly log: {
+        subscribe(fn: (event: MoxxyEvent) => void | Promise<void>): () => void;
+    };
+}
+/** The slice of a session `driveTurn` needs. `ClientSession` satisfies it. */
+export interface TurnSession extends TurnEventSource {
+    runTurn(prompt: string, opts?: RunTurnOptions): AsyncIterable<MoxxyEvent>;
+}
+/**
+ * Subscribe to ONLY the given turn's events. Returns the unsubscribe function.
+ * The caller controls unsubscribe placement (channels keep their final flush
+ * inside the subscription window so trailing events still feed the renderer).
+ */
+export declare function subscribeTurn(source: TurnEventSource, turnId: TurnId, onEvent: (event: MoxxyEvent) => void): () => void;
+export interface DriveTurnOptions {
+    readonly turnId: TurnId;
+    readonly prompt: string;
+    readonly model?: string | undefined;
+    readonly signal: AbortSignal;
+}
+/**
+ * Run one turn to completion, draining the `runTurn` iterator. Rendering is
+ * expected to happen via a {@link subscribeTurn} subscription, not the yielded
+ * events (which are identical); errors propagate to the caller.
+ */
+export declare function driveTurn(session: TurnSession, opts: DriveTurnOptions): Promise<void>;
+/** A granted turn slot. Call `end()` in a `finally` to release single-flight. */
+export interface TurnLease {
+    readonly turnId: TurnId;
+    /** Per-turn controller so a /cancel or channel stop aborts ONLY this turn
+     *  without poisoning the session-level signal other channels share. */
+    readonly controller: AbortController;
+    end(): void;
+}
+export interface TurnCoordinatorOptions {
+    /**
+     * Bound on remembered own-turn ids so a long-lived channel can't leak; a
+     * handful of recent ids is enough to dedup late/replayed events. Default 64.
+     */
+    readonly maxOwnTurnIds?: number;
+}
+/**
+ * Single-flight turn state for a channel: one turn at a time, a per-turn
+ * AbortController, and a bounded set of turnIds THIS channel initiated.
+ *
+ * The own-turn-id set is what {@link mirrorText} filters on (invariant #8)
+ * rather than the coarse `busy` flag alone — so an `assistant_message`
+ * dispatched for our own turn AFTER `busy` flips false (async event ordering /
+ * RemoteSession replay) isn't re-mirrored as foreign.
+ */
+export declare class TurnCoordinator {
+    private busyFlag;
+    private active;
+    private readonly ownTurnIds;
+    private readonly maxOwnTurnIds;
+    constructor(opts?: TurnCoordinatorOptions);
+    get busy(): boolean;
+    /** The in-flight turn's controller (null when idle) — for /cancel handlers. */
+    get controller(): AbortController | null;
+    /**
+     * Atomically claim the single turn slot. Synchronous on purpose: set `busy`
+     * BEFORE any await so a concurrently dispatched second turn can't slip past
+     * the guard. Returns null when a turn is already running (the channel replies
+     * "still working"); otherwise a lease whose `end()` releases the slot.
+     */
+    begin(turnId: TurnId): TurnLease | null;
+    /** Abort the in-flight turn (stop / cancel paths). No-op when idle. */
+    abort(reason: string): void;
+    isOwn(turnId: string): boolean;
+    /**
+     * Foreign-turn mirror gate: returns the assistant prose to mirror for a turn
+     * this channel did NOT initiate (e.g. a co-attached surface ran one), or null
+     * when the event must not be mirrored — not an `assistant_message`, one of
+     * our own turnIds (invariant #8), a turn of ours currently rendering via the
+     * frame pump (`busy`), or empty content. The channel adds its own
+     * "have I served a target yet" check and does the send.
+     */
+    mirrorText(event: MoxxyEvent): string | null;
+}
+//# sourceMappingURL=turn.d.ts.map

package/dist/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE;QACZ,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;KACxE,CAAC;CACH;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;CAC3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GACnC,MAAM,IAAI,CAKZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3F;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,GAAG,IAAI,IAAI,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,IAAI,GAAE,sBAA2B;IAI7C,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,+EAA+E;IAC/E,IAAI,UAAU,IAAI,eAAe,GAAG,IAAI,CAEvC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAoBvC,uEAAuE;IACvE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;CAO7C"}