dsh-deeppilot 0.3.0 → 0.5.0

package/lib/index.d.ts

@@ -1,4 +1,3 @@
-import { IncomingMessage } from "node:http";
 import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/protocol.d.ts
@@ -26,6 +25,51 @@ interface SessionSummary {
   workspaceId?: string | null;
   workspacePath?: string | null;
 }
+type MessageRole = 'user' | 'assistant' | 'tool' | 'system' | 'error';
+type ToolState = 'running' | 'ok' | 'error';
+/** Provenance of host-injected context; present only on `role: "system"` rows.
+ * Mirrors the durable DSH message source (`dsh-llm` MessageSource): `label`
+ * names the producer (plugin name, skill name, instruction paths…), `form` is
+ * the semantic ContextForm vocabulary ('instructions' | 'catalog' | 'snapshot'
+ * | 'notice' | 'relay' | 'recall'). Both degrade gracefully — clients must
+ * tolerate absent fields and unknown values. */
+interface MessageContextInfo {
+  label?: string;
+  form?: string;
+}
+/** One image carried by a user message. `attachmentId` keys the read-back RPC
+ * (c2s.session.attachment); width/height let clients reserve layout space. */
+interface MessageAttachment {
+  kind: 'image';
+  name?: string;
+  mediaType?: string;
+  attachmentId?: string;
+  width?: number;
+  height?: number;
+}
+interface MessageProjection {
+  /** Durable row identity; unique within one session/page. */
+  seq: number;
+  role: MessageRole;
+  text?: string;
+  /** Reasoning ("thinking") text accompanying the answer, when present. */
+  thinking?: string;
+  streaming?: boolean;
+  tool?: {
+    name: string;
+    state: ToolState;
+    summary: string;
+  };
+  attachments?: MessageAttachment[];
+  /** Present only on system rows: provenance of the injected context.
+   * The DSH host logs synthetic agent.inject() content (runtime-context
+   * snapshots, background-job notices, workspace instructions…) as user-role
+   * messages whose `source.kind` is not 'user'; those project here as
+   * `role: "system"` so clients never show them as human prompts. */
+  context?: MessageContextInfo;
+  ts: number;
+  truncated?: boolean;
+}
 type NotifyCategory = 'turn.completed' | 'approval.required' | 'question.asked' | 'session.error';
 /**
  * One offline-push-worthy event (same facts as s2c.notify / pending frames,
@@ -66,7 +110,7 @@ interface PendingSnapshotPayload {
   questions: PendingQuestionPayload[];
 }
 //#endregion
-//#region src/host-bridge.d.ts
+//#region src/host-api.d.ts
 interface RpcOk<T> {
   ok: true;
   value: T;
@@ -250,7 +294,9 @@ interface PhoneSessionRow {
   sessionId: string;
   updatedAt: number;
   running: boolean;
-  blank: boolean;
+  /** Host marks never-prompted sessions as blank; informational only — the
+   * summary projects them as idle (see toSummary) so phones can send. */
+  blank?: boolean;
   cwd?: string;
   origin?: string;
   parentSessionId?: string;
@@ -355,6 +401,8 @@ interface PushOutlet {
    */
   isAvailable(): boolean;
 }
+//#endregion
+//#region src/host-bridge.d.ts
 declare class HostBridge {
   private readonly apiProxy;
   private readonly historyBufferMax;
@@ -367,7 +415,10 @@ declare class HostBridge {
   private sinks;
   private ring;
   private cursor;
+  private userReceiptSeq;
   private abort;
+  private started;
+  private disposed;
   constructor(apiProxy: ApiProxyLike, historyBufferMax?: number);
   private pushOutlet;
   /**
@@ -381,6 +432,7 @@ declare class HostBridge {
     approvals: boolean;
     questions: boolean;
     pendingSnapshot: boolean;
+    notifyAllCategories: boolean;
     models: boolean;
     sessionManagement: boolean;
     projectSelection: boolean;
@@ -399,6 +451,12 @@ declare class HostBridge {
   markSinkClosed(sink: BridgeSink, sessionId: string): void;
   dropSinkSessions(sink: BridgeSink): void;
   private isViewedBy;
+  /** F-9: when a notification-worthy event fires, mirror it to every
+   *  online device that is not currently viewing the session (the s2c.notify
+   *  frame counts toward the seq cursor and joins the replay ring per
+   *  PROTOCOL §6 + §7), then fan the same payload out to offline devices
+   *  holding an APNs token. */
+  private emitNotify;
   /** F-9: when a turn completes, notify every device not viewing the session. */
   private emitTurnCompletedNotify;
   /**
@@ -438,7 +496,11 @@ declare class HostBridge {
   pendingSnapshot(): PendingSnapshotPayload;
   /** Tail history for an opened session; pushes s2c.session.tail to the sink. */
   openSession(sink: BridgeSink, sessionId: string, tailCount: number): Promise<boolean>;
-  historyPage(sink: BridgeSink, sessionId: string, beforeSeq: number, limit: number): Promise<boolean>;
+  historyPage(sessionId: string, beforeSeq: number, limit: number): Promise<{
+    sessionId: string;
+    messages: MessageProjection[];
+    hasMore: boolean;
+  } | null>;
   /** Result of one attachment read-back for the phone. */
   attachmentData(sessionId: string, attachmentId: string): Promise<{
     mediaType?: string;
@@ -480,29 +542,11 @@ declare class HostBridge {
   respondQuestion(requestId: string, answers: unknown): Promise<PendingResponseOutcome>;
 }
 //#endregion
-//#region src/index.d.ts
-/**
- * dsh-deeppilot — data bridge between the DSH host and DeepPilot
- * clients. Registers exactly one WebSocket upgrade route (/phone) plus an
- * optional health probe (/phone/health) on the existing web server. The web
- * UI is never touched.
- *
- * Data plane: an in-process HostBridge consumes apiProxy.events.mux()/host()
- * streams, mirrors session summaries, tracks pending approvals/questions,
- * and fans projected protocol-v1 pushes out to every connected device.
- *
- * Protocol: src/protocol.ts, v1. The private app repository carries the
- * matching normative document and Swift models.
- */
-declare const name = "deeppilot";
-/** No eager service requirement: profiles without a web stack simply skip. */
-declare const inject: string[];
+//#region src/config.d.ts
 interface Config {
   /** Master switch; when false the plugin activates and does nothing. */
   enabled?: boolean;
-  /** Pairing token file (0600); generated on first boot when missing. */
-  authTokenPath?: string;
-  /** Paired-device registry JSON path. */
+  /** Protocol-v2 device registry JSON path. */
   devicesPath?: string;
   /** Replay ring buffer bound (frames) per deployment. */
   historyBufferMax?: number;
@@ -511,35 +555,32 @@ interface Config {
   /** Optional embedded remote transport. Reconciled when settings change. */
   remote?: {
     enabled?: boolean;
-    provider?: string;
+    provider?: 'tailscale-funnel';
     hostname?: string;
     statePath?: string;
     helperPath?: string;
-    funnelPort?: number;
+    funnelPort?: 443 | 8443 | 10000;
+    /** Concurrent Funnel WebSockets allowed from one public source address. */
+    maxConnectionsPerSource?: number;
   };
   /**
-   * Offline push (F-9). provider 'apns' sends direct Apple Push Notification
-   * deliveries from this Mac — outbound-only, no relay server, requires the
-   * user's own Apple developer credentials. provider 'relay' forwards notify
-   * projections to an operator-run relay (relay/server.js) holding the
-   * distributor's key — used when the App ships via TestFlight/App Store.
-   *
-   * Deliberately NO environment knob here: each device reports its own
-   * environment when registering (derived from its build kind), and
-   * deliveries route per device — mixed dev/TestFlight phones coexist.
+   * Offline push (F-9). `apns` sends directly from the Mac with the user's
+   * Apple credentials. `relay` sends notify projections to an operator-run
+   * relay for distributed builds. The device reports its own APNs environment,
+   * so development and TestFlight/App Store devices may coexist.
    */
   push?: {
-    /** 'none' (default) | 'apns' | 'relay'. */
-    provider?: string;
+    /** `none` (default), `apns`, or `relay`. */
+    provider?: 'none' | 'apns' | 'relay';
     /** Apple Developer team id (JWT iss claim). */
     teamId?: string;
     /** APNs auth key id (JWT kid header). */
     keyId?: string;
-    /** .p8 private key path; generated keys live under the bridge data dir. */
+    /** `.p8` private key path. */
     keyPath?: string;
     /** App bundle id — the apns-topic header. */
     bundleId?: string;
-    /** Relay base URL (https). See relay/README.md. */
+    /** Relay base URL. */
     relayUrl?: string;
     /** Per-user bearer token issued by the relay operator. */
     relayToken?: string;
@@ -547,27 +588,28 @@ interface Config {
 }
 declare const Config: z<Schemastery.ObjectS<{
   enabled: z<boolean, boolean>;
-  authTokenPath: z<string, string>;
   devicesPath: z<string, string>;
   historyBufferMax: z<number, number>;
   debug: z<boolean, boolean>;
   remote: z<Schemastery.ObjectS<{
     enabled: z<boolean, boolean>;
-    provider: z<string, string>;
+    provider: z<"tailscale-funnel", "tailscale-funnel">;
     hostname: z<string, string>;
     statePath: z<string, string>;
     helperPath: z<string, string>;
-    funnelPort: z<number, number>;
+    funnelPort: z<443 | 8443 | 10000, 443 | 8443 | 10000>;
+    maxConnectionsPerSource: z<number, number>;
   }>, Schemastery.ObjectT<{
     enabled: z<boolean, boolean>;
-    provider: z<string, string>;
+    provider: z<"tailscale-funnel", "tailscale-funnel">;
     hostname: z<string, string>;
     statePath: z<string, string>;
     helperPath: z<string, string>;
-    funnelPort: z<number, number>;
+    funnelPort: z<443 | 8443 | 10000, 443 | 8443 | 10000>;
+    maxConnectionsPerSource: z<number, number>;
   }>>;
   push: z<Schemastery.ObjectS<{
-    provider: z<string, string>;
+    provider: z<"none" | "apns" | "relay", "none" | "apns" | "relay">;
     teamId: z<string, string>;
     keyId: z<string, string>;
     keyPath: z<string, string>;
@@ -575,7 +617,7 @@ declare const Config: z<Schemastery.ObjectS<{
     relayUrl: z<string, string>;
     relayToken: z<string, string>;
   }>, Schemastery.ObjectT<{
-    provider: z<string, string>;
+    provider: z<"none" | "apns" | "relay", "none" | "apns" | "relay">;
     teamId: z<string, string>;
     keyId: z<string, string>;
     keyPath: z<string, string>;
@@ -585,27 +627,28 @@ declare const Config: z<Schemastery.ObjectS<{
   }>>;
 }>, Schemastery.ObjectT<{
   enabled: z<boolean, boolean>;
-  authTokenPath: z<string, string>;
   devicesPath: z<string, string>;
   historyBufferMax: z<number, number>;
   debug: z<boolean, boolean>;
   remote: z<Schemastery.ObjectS<{
     enabled: z<boolean, boolean>;
-    provider: z<string, string>;
+    provider: z<"tailscale-funnel", "tailscale-funnel">;
     hostname: z<string, string>;
     statePath: z<string, string>;
     helperPath: z<string, string>;
-    funnelPort: z<number, number>;
+    funnelPort: z<443 | 8443 | 10000, 443 | 8443 | 10000>;
+    maxConnectionsPerSource: z<number, number>;
   }>, Schemastery.ObjectT<{
     enabled: z<boolean, boolean>;
-    provider: z<string, string>;
+    provider: z<"tailscale-funnel", "tailscale-funnel">;
     hostname: z<string, string>;
     statePath: z<string, string>;
     helperPath: z<string, string>;
-    funnelPort: z<number, number>;
+    funnelPort: z<443 | 8443 | 10000, 443 | 8443 | 10000>;
+    maxConnectionsPerSource: z<number, number>;
   }>>;
   push: z<Schemastery.ObjectS<{
-    provider: z<string, string>;
+    provider: z<"none" | "apns" | "relay", "none" | "apns" | "relay">;
     teamId: z<string, string>;
     keyId: z<string, string>;
     keyPath: z<string, string>;
@@ -613,7 +656,7 @@ declare const Config: z<Schemastery.ObjectS<{
     relayUrl: z<string, string>;
     relayToken: z<string, string>;
   }>, Schemastery.ObjectT<{
-    provider: z<string, string>;
+    provider: z<"none" | "apns" | "relay", "none" | "apns" | "relay">;
     teamId: z<string, string>;
     keyId: z<string, string>;
     keyPath: z<string, string>;
@@ -622,9 +665,41 @@ declare const Config: z<Schemastery.ObjectS<{
     relayToken: z<string, string>;
   }>>;
 }>>;
-/** Authorization is preferred; the query form remains for older app builds. */
-declare function requestToken(req: Pick<IncomingMessage, 'url' | 'headers'>): string | null;
+//#endregion
+//#region src/push-policy.d.ts
+/** Prune only when the provider supplies an authoritative token-lifecycle verdict. */
+declare function shouldPrunePushToken(outcome: 'sent' | 'invalid-token' | 'failed', reason?: string): boolean;
+/**
+ * Zero-touch relay self-heal: HTTP 401 means the relay no longer honors the
+ * cached credential. Only auto-enrolled cells with a still-current token may
+ * re-derive it; an explicitly configured relay token remains user-owned
+ * configuration and is never silently rewritten.
+ */
+declare function shouldReEnrollRelayToken(transport: 'apns' | 'relay', outcome: 'sent' | 'invalid-token' | 'failed', reason: string | undefined, opts: {
+  usedCellToken: boolean;
+  hasEnrollKey: boolean;
+  tokenStillCurrent: boolean;
+}): boolean;
+//#endregion
+//#region src/index.d.ts
+/**
+ * dsh-deeppilot — data bridge between the DSH host and DeepPilot
+ * clients. Registers exactly one WebSocket upgrade route (/phone) plus an
+ * optional health probe (/phone/health) on the existing web server. The web
+ * UI is never touched.
+ *
+ * Data plane: an in-process HostBridge consumes a local compatibility façade
+ * over DSH 0.1.2 Session/Workspace controllers, mirrors session summaries,
+ * tracks pending approvals/questions, and fans projected protocol-v2 pushes
+ * out to every connected device.
+ *
+ * Protocol: PROTOCOL.md is normative; src/protocol.ts and the private app's
+ * Swift models mirror that v2 contract.
+ */
+declare const name = "deeppilot";
+/** No eager service requirement: profiles without a web stack simply skip. */
+declare const inject: string[];
 declare function apply(ctx: Context, options: unknown): void;
 //#endregion
-export { Config, HostBridge, apply, inject, name, requestToken };
+export { Config, HostBridge, apply, inject, name, shouldPrunePushToken, shouldReEnrollRelayToken };
 //# sourceMappingURL=index.d.ts.map