@barryfan2045/dsh-matrix 0.1.0

package/dist/ports/backend.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Backend port: everything the bridge knows about the agent runtime.
+ * The DSH implementation lives in src/dsh/; tests use a scripted fake.
+ */
+import type { PreparedAttachment } from './attachments.ts';
+export interface SessionInfo {
+    readonly id: string;
+    readonly title?: string;
+    readonly cwd: string;
+}
+/** One open room↔session binding, as `/sessions` renders it (T11). */
+export interface SessionListEntry {
+    readonly roomId: string;
+    readonly sessionId: string;
+    /** True while that room's turn is executing. */
+    readonly running: boolean;
+}
+/** One pending inbox item as the bridge displays it (T3 turn commands). */
+export interface QueuedItem {
+    /** 'steer' = next-step injection, 'queue' = next-turn follow-up. */
+    readonly kind: 'steer' | 'queue';
+    readonly text: string;
+}
+export interface SessionHandle {
+    readonly id: string;
+    /** True while a turn is executing (drives steer vs prompt choice). */
+    isRunning(): boolean;
+    /** Queue an ordinary next-turn prompt (idle: runs immediately).
+     *  T6: `files` are the sender's pending ledger attachments - the backend
+     *  admits images into the model natively and files as path-bearing
+     *  attachments. Consumption (ledger clear) happens only after this call
+     *  returned without throwing. */
+    prompt(text: string, files?: PreparedAttachment[]): void;
+    /** Inject into the running turn (TUI Enter while busy). */
+    steer(text: string): void;
+    /** Resolve once the whole agent reaches quiescence. */
+    whenIdle(): Promise<void>;
+    /** Text of the last assistant reply, or undefined when none. */
+    lastReply(): string | undefined;
+    /**
+     * T11(US42):最近一个回合若以失败收尾,返回可读原因;正常结束(或还没有
+     * 回合结束事件)返回 undefined。
+     *
+     * DSH 的回合可能以 `turn/end{ reason.kind: 'error' }` 收尾而**不抛错** ——
+     * 此时 prompt()/whenIdle() 照常 resolve,单靠 try/catch 兜不住,房间会静默。
+     * `aborted`(用户自己 /stop)不算失败,不返回原因。
+     */
+    lastTurnFailure(): string | undefined;
+    /**
+     * Abort the active turn. With `keepInbox` the pending queue survives for a
+     * later turn (pi-courier abort semantics, used by /stop and /interrupt);
+     * by default pending work is discarded too. No-op when nothing runs.
+     */
+    cancel(options?: {
+        keepInbox?: boolean;
+    }): void;
+    /** Pending inbox items for /queue views and /stop warnings. */
+    queuedItems(): QueuedItem[];
+    /** Model-facing context for the next admitted step, without waking. */
+    injectContext(text: string): void;
+}
+/**
+ * The room's durable session is already bound to another live write handle —
+ * in practice the DSH GUI (or a second bridge instance) has that session open.
+ * DSH allows exactly ONE writer per session, so the bridge cannot resume it
+ * until the other holder lets go.
+ *
+ * Transient by nature: the condition clears the moment the other holder
+ * closes the session, so the pipeline retries instead of failing the turn.
+ * Kept as a port-level type so any Backend implementation can report it and
+ * the pipeline never has to string-match a DSH-internal message.
+ */
+export declare class SessionBusyError extends Error {
+    /** Durable session id whose write ownership is taken. */
+    readonly sessionId: string;
+    constructor(sessionId: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Narrow an unknown catch value to the transient session-busy condition. */
+export declare function isSessionBusyError(error: unknown): error is SessionBusyError;
+/** One DSH registry command as advertised to the room (for /help). */
+export interface PassthroughCommandInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly hint?: string;
+}
+/** One catalog entry: a model id served by one registered provider route. */
+export interface ModelInfo {
+    readonly provider: string;
+    readonly model: string;
+    readonly name?: string;
+}
+/** The effective model route of one live session (mirror of AgentOptions). */
+export interface ModelSelection {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly reasoningEffort?: string;
+}
+/** One selectable reasoning level advertised by the model catalog. */
+export interface ThinkingEffort {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+}
+export interface Backend {
+    /**
+     * Run one DSH slash command against the room's agent through the
+     * `commands` service. Returns the settled result text (success or error
+     * kind) verbatim — an empty string for a textless success — or `undefined`
+     * when the registry rejected the line (invalid syntax / unknown name);
+     * a rejected line never becomes a model prompt.
+     * Requires the room session to be open; throws a clear error otherwise.
+     */
+    executeCommand(roomId: string, line: string): Promise<string | undefined>;
+    /** Commands the DSH registry would accept for this room (bridge-local names excluded). */
+    listPassthroughCommands(roomId: string): Promise<PassthroughCommandInfo[]>;
+    /** Model catalog across every registered provider route (ctx.llm). */
+    listModels(): Promise<ModelInfo[]>;
+    /** The room session's live model route; undefined when no session is open. */
+    currentModel(roomId: string): Promise<ModelSelection | undefined>;
+    /**
+     * Re-point the room's session at another route. Without a sessionController
+     * in the base profile this disposes the live agent and resumes the SAME
+     * persisted session under new options (history survives; the switch must not
+     * happen mid-turn). Throws a clear error on unknown routes / running turns.
+     */
+    selectModel(roomId: string, provider: string, model: string, reasoningEffort?: string): Promise<ModelSelection>;
+    /** Reasoning levels one exact route supports (empty = no thinking control). */
+    listThinkingEfforts(provider: string, model: string): Promise<ThinkingEffort[]>;
+    /** Persist a user-chosen title for the room's live session. */
+    renameSession(roomId: string, title: string): Promise<void>;
+    /**
+     * Resolve (lazily create / resume) the session bound to a room.
+     * `cwd` selects the working directory for a fresh session.
+     */
+    getSession(roomId: string, cwd: string): Promise<SessionHandle>;
+    /**
+     * Non-creating lookup: the room's session ONLY if one is already open.
+     * The pipeline uses it for the running→steer fast path, which must not
+     * wait behind the per-room queue (otherwise steering could never fire).
+     */
+    peekSession(roomId: string): SessionHandle | undefined;
+    /**
+     * T11(/sessions):本进程已知的房间↔会话绑定,只读。
+     * 架构上房间与会话是确定性一对一(`sessionIdFor(roomId)`),所以这里没有
+     * pi-courier 那种"可切换的会话池"——列出来的是"哪些房间已经有会话"以及
+     * 各自是否在跑回合。懒恢复,重启后要等那个房间再来消息才重新出现。
+     */
+    listSessions(): Promise<SessionListEntry[]>;
+    /**
+     * T9(/pmctl rm|mv):放掉该房间的会话句柄(dispose + 清映射)。持久会话数据
+     * 不动 —— 同房间再来消息会按新 cwd 重开/resume(US35 换目录语义)。幂等。
+     */
+    dropRoomSession(roomId: string): Promise<void>;
+    /** Tear down everything the backend opened. Idempotent. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/ports/backend.d.ts.map

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

package/dist/ports/backend.js

@@ -0,0 +1,25 @@
+/**
+ * The room's durable session is already bound to another live write handle —
+ * in practice the DSH GUI (or a second bridge instance) has that session open.
+ * DSH allows exactly ONE writer per session, so the bridge cannot resume it
+ * until the other holder lets go.
+ *
+ * Transient by nature: the condition clears the moment the other holder
+ * closes the session, so the pipeline retries instead of failing the turn.
+ * Kept as a port-level type so any Backend implementation can report it and
+ * the pipeline never has to string-match a DSH-internal message.
+ */
+export class SessionBusyError extends Error {
+    /** Durable session id whose write ownership is taken. */
+    sessionId;
+    constructor(sessionId, options) {
+        super(`session "${sessionId}" is already owned by an active write handle`, options);
+        this.name = 'SessionBusyError';
+        this.sessionId = sessionId;
+    }
+}
+/** Narrow an unknown catch value to the transient session-busy condition. */
+export function isSessionBusyError(error) {
+    return error instanceof SessionBusyError;
+}
+//# sourceMappingURL=backend.js.map

package/dist/ports/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/ports/backend.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,yDAAyD;IAChD,SAAS,CAAQ;IAC1B,YAAY,SAAiB,EAAE,OAA6B;QAC1D,KAAK,CAAC,YAAY,SAAS,8CAA8C,EAAE,OAAO,CAAC,CAAA;QACnF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,KAAK,YAAY,gBAAgB,CAAA;AAC1C,CAAC"}

package/dist/ports/interactions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Interactions port: agent 侧的提问(user-questions)与沙箱审批(approval)
+ * 如何进入桥的房间。dsh/interactions.ts 用 Cordis 根 waterfall 监听器实现
+ * 本端口;bridge/interactions.ts 只依赖本端口,用假实现做 seam 测试。
+ *
+ * 字段形状来自对部署包源码的实证读取(spike + lib/index.js):
+ * - user-questions/request 监听器收到 `{ questions, agent?, signal? }`,
+ *   答案对象 `{ answers: [{ id, selected, custom? }] }`,或 next() 交还。
+ * - approval/request 监听器收到 `{ agent, toolName, callId?, reason?, signal? }`,
+ *   返回 'allowed-once' | 'rejected' | 'cancelled',或 next() 交还。
+ * 归属判定用 `agent.session.id`(桥会话 id 形如 matrix-<room>):非桥会话
+ * 必须 next(),与 Web 回答器共存。
+ */
+/** 提问的单个选项(label 即回答值)。 */
+export interface QuestionOption {
+    label: string;
+    description?: string;
+}
+/** 一道问题(与 dsh-user-questions 的 AskUserQuestionRequest.questions 项同构)。 */
+export interface QuestionItem {
+    id: string;
+    question: string;
+    detail?: string;
+    header?: string;
+    options?: QuestionOption[];
+    multiSelect?: boolean;
+}
+/** 一道题的答案:selected 为选中标签;custom 自由文本(单选时覆盖 selected)。 */
+export interface QuestionAnswerItem {
+    id: string;
+    selected: string[];
+    custom?: string;
+}
+/** 一次审批的结果。'cancelled' = 用户取消或超时(服务侧同样视为不放行)。 */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled';
+/** 只读切片:监听器收到的 signal 我们只关心 abort。 */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+}
+/** 归一化后的提问事件(sessionId 为提问 agent 的会话 id,归属判定的钥匙)。 */
+export interface QuestionRequestEvent {
+    sessionId: string;
+    questions: QuestionItem[];
+    signal?: AbortSignalLike;
+}
+/** 归一化后的审批事件。 */
+export interface ApprovalRequestEvent {
+    sessionId: string;
+    toolName: string;
+    reason?: string;
+    callId?: string;
+    signal?: AbortSignalLike;
+}
+/** respond 在答案/结果确定时被调用一次(桥侧编排器持有其时机)。 */
+export type QuestionResponder = (answers: QuestionAnswerItem[]) => void;
+export type ApprovalResponder = (outcome: ApprovalOutcome) => void;
+/** 事件来源:dsh 侧注册根监听器,只把桥自己会话的请求回调进桥。 */
+export interface InteractionSource {
+    /** 订阅桥会话的提问。返回 disposer(ctx.on 随 fiber 自动回收,这里通常 no-op)。 */
+    onRequestQuestion(cb: (event: QuestionRequestEvent, respond: QuestionResponder) => void): () => void;
+    /** 订阅桥会话的沙箱审批。 */
+    onRequestApproval(cb: (event: ApprovalRequestEvent, respond: ApprovalResponder) => void): () => void;
+}
+//# sourceMappingURL=interactions.d.ts.map

package/dist/ports/interactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.d.ts","sourceRoot":"","sources":["../../src/ports/interactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,2BAA2B;AAC3B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,cAAc,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAA;AAEvE,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC5D;AAED,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,YAAY,EAAE,CAAA;IACzB,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAED,iBAAiB;AACjB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAED,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAA;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;AAElE,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACpG,kBAAkB;IAClB,iBAAiB,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACrG"}

package/dist/ports/interactions.js

@@ -0,0 +1,15 @@
+/**
+ * Interactions port: agent 侧的提问(user-questions)与沙箱审批(approval)
+ * 如何进入桥的房间。dsh/interactions.ts 用 Cordis 根 waterfall 监听器实现
+ * 本端口;bridge/interactions.ts 只依赖本端口,用假实现做 seam 测试。
+ *
+ * 字段形状来自对部署包源码的实证读取(spike + lib/index.js):
+ * - user-questions/request 监听器收到 `{ questions, agent?, signal? }`,
+ *   答案对象 `{ answers: [{ id, selected, custom? }] }`,或 next() 交还。
+ * - approval/request 监听器收到 `{ agent, toolName, callId?, reason?, signal? }`,
+ *   返回 'allowed-once' | 'rejected' | 'cancelled',或 next() 交还。
+ * 归属判定用 `agent.session.id`(桥会话 id 形如 matrix-<room>):非桥会话
+ * 必须 next(),与 Web 回答器共存。
+ */
+export {};
+//# sourceMappingURL=interactions.js.map

package/dist/ports/interactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../../src/ports/interactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/ports/streaming.d.ts

@@ -0,0 +1,45 @@
+/**
+ * T7 streaming port: the bridge-side view of DSH live assistant output.
+ *
+ * Ground truth (dsh-agent@0.1.5 `lib/types/runtime-types.d.ts` +
+ * dsh-llm `lib/types/types.d.ts`, spike-measured 15-73 frames/turn):
+ * - root event `agent/assistant-stream`, payload `{ agent, frame }`;
+ * - `frame` is one ordered publication of ONE MODEL ATTEMPT:
+ *   `{type:'start', attemptId, revision, turn, step}` |
+ *   `{type:'chunk', attemptId, revision, index, time, chunk: StreamChunk}`
+ *   (`index` dense from 0) |
+ *   `{type:'end', attemptId, revision, index, outcome:
+ *      {kind:'committed', eventType, seq} | {kind:'abandoned'}}`.
+ * - visible text arrives as `frame.chunk.type === 'text-delta'` with a
+ *   `text: string` field. `reasoning-delta` ALSO carries `text` - never
+ *   forward anything but 'text-delta'.
+ *
+ * One turn contains many attempts (tool loops, retries), so an `end` frame is
+ * NOT the turn end: turn completion stays the pipeline's `whenIdle()`. The
+ * committed/abandoned outcome only decides whether the current attempt's
+ * buffered text survives (abandoned retries must not reach the room).
+ */
+/** Callbacks a TurnStreamSource drives for one session. */
+export interface TurnStreamHandlers {
+    /** One streamed visible-text delta. */
+    onTextDelta(text: string): void;
+    /**
+     * Stream-side "turn is over" hint. Optional in practice: DSH implementations
+     * never fire it (end frame ≠ turn end); fakes may script it to flush edits.
+     */
+    onTurnEnd(): void;
+    /** A new model attempt began: per-attempt buffering restarts. */
+    onAttemptStart?(): void;
+    /**
+     * The current attempt was ABANDONED (model-request retry): everything the
+     * stream forwarded since its start must be dropped - retry content never
+     * belongs in the room.
+     */
+    onAttemptAbandoned?(): void;
+}
+/** Anything the bridge can read streamed assistant text from, per session. */
+export interface TurnStreamSource {
+    /** Subscribe to one DSH session's stream. Returns an unsubscribe disposer. */
+    subscribe(sessionId: string, handlers: TurnStreamHandlers): () => void;
+}
+//# sourceMappingURL=streaming.d.ts.map

package/dist/ports/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/ports/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAA;IACjB,iEAAiE;IACjE,cAAc,CAAC,IAAI,IAAI,CAAA;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,IAAI,CAAA;CAC5B;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;CACvE"}

package/dist/ports/streaming.js

@@ -0,0 +1,23 @@
+/**
+ * T7 streaming port: the bridge-side view of DSH live assistant output.
+ *
+ * Ground truth (dsh-agent@0.1.5 `lib/types/runtime-types.d.ts` +
+ * dsh-llm `lib/types/types.d.ts`, spike-measured 15-73 frames/turn):
+ * - root event `agent/assistant-stream`, payload `{ agent, frame }`;
+ * - `frame` is one ordered publication of ONE MODEL ATTEMPT:
+ *   `{type:'start', attemptId, revision, turn, step}` |
+ *   `{type:'chunk', attemptId, revision, index, time, chunk: StreamChunk}`
+ *   (`index` dense from 0) |
+ *   `{type:'end', attemptId, revision, index, outcome:
+ *      {kind:'committed', eventType, seq} | {kind:'abandoned'}}`.
+ * - visible text arrives as `frame.chunk.type === 'text-delta'` with a
+ *   `text: string` field. `reasoning-delta` ALSO carries `text` - never
+ *   forward anything but 'text-delta'.
+ *
+ * One turn contains many attempts (tool loops, retries), so an `end` frame is
+ * NOT the turn end: turn completion stays the pipeline's `whenIdle()`. The
+ * committed/abandoned outcome only decides whether the current attempt's
+ * buffered text survives (abandoned retries must not reach the room).
+ */
+export {};
+//# sourceMappingURL=streaming.js.map

package/dist/ports/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/ports/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/ports/transport.d.ts

@@ -0,0 +1,68 @@
+import type { IncomingMessage, Logger } from '../types.ts';
+import type { MediaDownload } from './attachments.ts';
+/**
+ * Transport port: everything the bridge knows about the chat side.
+ * The bridge core is tested against a fake of exactly this interface -
+ * the single pre-agreed seam (spec: Testing Decisions).
+ */
+export interface Transport {
+    /** Subscribe to normalized inbound messages. Returns an unsubscribe fn. */
+    onIncoming(handler: (msg: IncomingMessage) => void | Promise<void>): () => void;
+    /**
+     * T8 (optional): subscribe to room joins with the group verdict, used for
+     * the one-time group join hint. Fake transports may omit it.
+     */
+    onRoomJoin?(handler: (roomId: string, isGroup: boolean) => void): () => void;
+    /** Send an m.text message. Returns the Matrix event id (for later edits). */
+    send(roomId: string, text: string): Promise<string>;
+    /** Send an m.notice (bot-to-human meta chatter; other bots should ignore). */
+    notify(roomId: string, text: string): Promise<string>;
+    /** Edit a previously sent event in place. Best-effort; ignore failures. */
+    edit(roomId: string, editId: string, text: string): Promise<void>;
+    /**
+     * T6: fetch one media payload by mxc:// address (E2EE-decrypted when the
+     * transport runs with crypto). Rejects with a room-ready message when the
+     * real bytes exceed `maxSizeBytes` or the download/decrypt fails.
+     */
+    downloadMedia(mxc: string, maxSizeBytes: number): Promise<MediaDownload>;
+    /** Connect and start receiving. */
+    start(logger: Logger): Promise<void>;
+    /** Stop and release all resources. Idempotent. */
+    stop(): Promise<void>;
+    /** 建私有房间,名字 `name`,邀请 `inviteUserId`(邀请者+被邀者都进)。返回房间 ID。 */
+    createRoom?(opts: {
+        name: string;
+        inviteUserId: string;
+    }): Promise<string>;
+    /** 设置房间显示名(m.room.name 状态)。 */
+    setRoomName?(roomId: string, name: string): Promise<void>;
+    /** 设置用户在房间的权限等级(trusted → PL100)。尽力而为。 */
+    setUserPowerLevel?(roomId: string, userId: string, level: number): Promise<void>;
+    /**
+     * T12(US37):读某人在某房间的权限等级(`m.room.power_levels` 的 `users[userId]`,
+     * 回落 `users_default`,再回落 0)。
+     *
+     * 提权前**必须**先读:只有真正发生的"低 → 100"才记账本,否则 `/revoke` 会把
+     * 管理员手工提上去的人一起降掉(误伤人工授权)。
+     */
+    getUserPowerLevel?(roomId: string, userId: string): Promise<number>;
+    /** T12(US38):建 space(`creation_content: {type:'m.space'}` 的私有房)。 */
+    createSpace?(opts: {
+        name: string;
+        inviteUserId?: string;
+    }): Promise<string>;
+    /** T12(US38):读房间头像;没设过 → undefined(自愈据此判断"要不要补挂")。 */
+    getRoomAvatar?(roomId: string): Promise<{
+        url?: string;
+        info?: Record<string, unknown>;
+    } | undefined>;
+    /** T12(US38):上传 PNG 并设为房间头像(先 uploadContent 拿 mxc,再发 m.room.avatar)。 */
+    setRoomAvatar?(roomId: string, png: Buffer, info?: Record<string, unknown>): Promise<void>;
+    /** T12(US38):把房间挂进 space(在 space 里发 `m.space.child`,state_key = 房间 ID)。 */
+    addRoomToSpace?(spaceId: string, roomId: string, via?: string): Promise<void>;
+    /** 邀请用户进房(createRoom 之外的独立邀请;Matrix 建房已带 invite 时可不调)。 */
+    inviteUser?(roomId: string, userId: string): Promise<void>;
+    /** 桥自身账号的 MXID(管理房指南文案用;未连接/未知 → undefined)。 */
+    getBotUserId?(): string | undefined;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/ports/transport.d.ts.map

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

package/dist/ports/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/ports/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/ports/transport.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared bridge vocabulary - transport-independent, DSH-independent.
+ * Ported shapes stay close to pi-courier's `ExternalMessage` so the router
+ *移植 keeps a familiar body.
+ */
+import type { MediaIncoming } from './ports/attachments.ts';
+/** One inbound chat text message, already normalized by a Transport. */
+export interface IncomingMessage {
+    readonly roomId: string;
+    readonly sender: string;
+    readonly text: string;
+    /** True for 1:1 rooms (DM). T8: real judgment (was hardcoded in T1). */
+    readonly isDm: boolean;
+    /**
+     * T8: true for rooms with more than two joined members. Optional so
+     * pre-T8 fakes stay valid; when absent, pipelines derive `!isDm`.
+     */
+    readonly isGroup?: boolean;
+    /** T8: the message @-mentions the bot (m.mentions list or body fallback). */
+    readonly mentionsBot?: boolean;
+    /** T8: reply-to relation target; cache-hit resolution lives in the bridge. */
+    readonly replyTo?: {
+        eventId: string;
+    };
+    readonly eventId: string;
+    readonly timestamp: number;
+    /**
+     * T6: media payloads referenced by this message (m.image/m.file/… and
+     * m.sticker events). Media messages are receipted by the attachment stage
+     * and never reach the prompt path; `text` carries no caption for them.
+     */
+    readonly media?: MediaIncoming[];
+    /**
+     * T6: set when the event is neither text nor media (m.location, …). The
+     * bridge answers politely instead of silently swallowing (US/蓝本票3).
+     */
+    readonly unsupportedMsgtype?: string;
+}
+/** Outbound plain message (m.text). */
+export interface OutboundMessage {
+    roomId: string;
+    text: string;
+    /** Replace an earlier message (streaming edit). Transport assigns the id when absent on first send. */
+    editId?: string;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE3D,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@barryfan2045/dsh-matrix",
+  "version": "0.1.0",
+  "description": "Matrix bridge plugin for DeepSeek Harness: drive in-process agent sessions from chat rooms, with questions and approvals in the room",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hi-Barry/dsh-matrix.git"
+  },
+  "homepage": "https://github.com/Hi-Barry/dsh-matrix#readme",
+  "bugs": {
+    "url": "https://github.com/Hi-Barry/dsh-matrix/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "assets"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "prepack": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "matrix",
+    "bridge",
+    "cordis",
+    "plugin",
+    "chat",
+    "bot"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
+    "matrix-bot-sdk": "^0.8.0",
+    "@deepseek-ai/dsh-tool-ask-user": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-user-questions": "^0.1.5-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "@matrix-org/matrix-sdk-crypto-nodejs@0.4.0": true
+  },
+  "optionalDependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0"
+  },
+  "bin": {
+    "dsh-matrix": "dist/cli/index.js"
+  }
+}