@sparkelf/dsh-group-chat 0.0.0-stage → 0.2.0

package/lib/index.d.ts

@@ -0,0 +1,357 @@
+import { CredentialRef } from "@deepseek-ai/dsh-credentials";
+import z from "@deepseek-ai/schemastery";
+import { Agent } from "@deepseek-ai/dsh-agent";
+import { Session, SessionEvent } from "@deepseek-ai/dsh-session";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/context.d.ts
+/**
+ * Host services this plugin needs.
+ *
+ * `agents` and `sessions` carry the room subscription, `webServer` exposes the
+ * browser-facing room API, and `credentials` resolves the token this workspace
+ * presents — the secret is never read from configuration or cached in the plugin.
+ */
+interface GroupChatHostServices {
+  readonly agents: {
+    get(id: string): Agent | undefined;
+    list(): readonly Agent[];
+  };
+  readonly sessions: {
+    get(id: string): Session | undefined;
+    list(): readonly Session[];
+    create(id: string, options?: {
+      meta?: {
+        cwd?: string;
+      };
+    }): Session;
+  };
+  readonly credentials: {
+    resolve(ref: CredentialRef): Promise<{
+      value: string;
+      source: string;
+    } | undefined>;
+  };
+  readonly webServer: {
+    register(route: {
+      kind: 'exact' | 'prefix';
+      path: string;
+      handler(req: unknown, res: unknown): void | Promise<void>;
+    }): () => void;
+  };
+  readonly logger?: {
+    error(...args: unknown[]): void;
+    warn?(...args: unknown[]): void;
+    info?(...args: unknown[]): void;
+  };
+}
+type GroupChatContext = Context & GroupChatHostServices;
+//#endregion
+//#region src/identity.d.ts
+/**
+ * How this plugin learns where its server is and who it is.
+ *
+ * The **protocol**, not DataOps, is the contract: any server implementing the
+ * documented room endpoints works, so nothing here is specific to DataOps. A
+ * deployment supplies values through the plugin's own settings, and DataOps
+ * additionally injects environment defaults into its workspace containers so the
+ * first-run experience needs no typing.
+ *
+ * Resolution order is settings first, environment second:
+ *
+ * 1. An explicit setting always wins — that is what an operator edits, and it is
+ *    how a workspace points at any conforming server.
+ * 2. The DataOps environment variables fill whatever the settings leave blank.
+ */
+/** Environment variables DataOps injects into a managed workspace container. */
+declare const MANAGED_ENV: {
+  /** Base URL of the server, e.g. `http://host.docker.internal:3101`. */
+  readonly baseUrl: "DATAOPS_AI_WORKSPACE_BACKEND_BASE_URL";
+  /** Workspace root, used as a room session's `cwd`. */
+  readonly mountPath: "DATAOPS_AI_WORKSPACE_MOUNT_PATH";
+};
+/**
+ * The default credential reference.
+ *
+ * It names the DataOps access token the workspace already holds in the DSH
+ * credential store — the same reference `dataops-managed` and `knowledge-base`
+ * use. That is what makes this work in a managed workspace: the companion
+ * container has no credential in its environment by design, but the credential
+ * store does carry this entry, and a deployment can point the setting at any other
+ * reference for a different server.
+ */
+declare const DEFAULT_CREDENTIAL_REF = "DATAOPS_ACCESS_TOKEN";
+/** What the plugin needs in hand before it can talk to a server. */
+interface ServerTarget {
+  /** Origin with any trailing slash removed. */
+  readonly baseUrl: string;
+  /** Credential reference to resolve per request. */
+  readonly credentialRef: string;
+}
+interface ResolveTargetInput {
+  /** Value from the settings panel, if the operator set one. */
+  readonly baseUrl?: string;
+  readonly credentialRef?: string;
+  /** Environment bag; defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolves the server target, or `undefined` when this workspace is not configured.
+ *
+ * `undefined` means "do not activate": no route, no listener, no timer. A
+ * half-configured workspace is treated as unconfigured rather than failing loudly,
+ * because a plugin that cannot reach a server has nothing useful to do at startup
+ * and must not disturb ordinary sessions.
+ *
+ * The actor is deliberately absent: a bearer credential identifies the account
+ * server-side, so the plugin never states who it is and cannot disagree with the
+ * server about it.
+ */
+declare const resolveServerTarget: (input?: ResolveTargetInput) => ServerTarget | undefined;
+/** The workspace root a room session uses as its `cwd`. */
+declare const resolveWorkspaceRoot: (env?: Readonly<Record<string, string | undefined>>) => string;
+//#endregion
+//#region src/backend.d.ts
+/** One durable room event as the backend stores it. */
+interface RoomEventRecord {
+  /** Global order across every container, as a decimal string. */
+  readonly id: string;
+  /** The complete DSH event envelope, stored without translation. */
+  readonly event: RoomEvent;
+  readonly createdAt?: string;
+}
+/**
+ * The envelope half of a DSH event. `data` is `unknown` on purpose: the backend
+ * stores it verbatim and this plugin re-appends it verbatim, so nothing here needs
+ * to understand content blocks.
+ */
+interface RoomEvent {
+  readonly type: string;
+  readonly seq?: number;
+  readonly time?: number;
+  readonly data: unknown;
+  readonly surfaceOp?: string;
+}
+interface RoomSummary {
+  readonly id: string;
+  readonly name: string;
+  readonly ownerUserId: string;
+  readonly invitePolicy: 'anyone' | 'admin';
+  readonly discoverability: 'discoverable' | 'invite_only';
+  readonly memberCount: number;
+  readonly joined: boolean;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+interface RoomMember {
+  readonly userId: string;
+  readonly displayName: string;
+  readonly owner: boolean;
+  readonly joinedAt: string;
+}
+interface EventPage {
+  readonly events: readonly RoomEventRecord[];
+  /** Cursor to resume from; `null` when the room has no events yet. */
+  readonly nextCursor: string | null;
+  readonly hasMore: boolean;
+}
+/** A backend refusal that carries the HTTP status so callers can distinguish them. */
+declare class BackendError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+/** True when the request never reached the backend, so retrying cannot duplicate state. */
+declare const isTransportFailure: (error: unknown) => boolean;
+interface BackendClientOptions {
+  /** Per-request timeout; a stalled backend must not hold a session append path. */
+  readonly timeoutMs?: number;
+  /** Injected for tests. */
+  readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Resolves the credential for one request.
+ *
+ * The secret is fetched per request rather than captured at activation: a
+ * credential can be rotated or added while the plugin is loaded, and caching it
+ * would keep sending a stale value. Returning `undefined` means "no credential
+ * available", which fails the request instead of sending an anonymous one.
+ */
+type CredentialResolver = () => Promise<string | undefined>;
+/** Thin typed wrapper over the group-chat server protocol. */
+declare class GroupChatBackend {
+  private readonly target;
+  private readonly resolveCredential;
+  private readonly timeoutMs;
+  private readonly fetchImpl;
+  constructor(target: ServerTarget, resolveCredential: CredentialResolver, options?: BackendClientOptions);
+  /**
+   * Builds the headers for one call.
+   *
+   * The credential is a bearer token, so the request carries the deployment's own
+   * identity rather than a plugin-specific one. The room routes are the same ones
+   * a browser uses, which is why the plugin needs no parallel server surface.
+   */
+  private headers;
+  /** Rooms this workspace's member has joined. */
+  listRooms(signal?: AbortSignal): Promise<readonly RoomSummary[]>;
+  /**
+   * The account this workspace acts as, asked of the server rather than configured.
+   *
+   * The bearer credential already identifies the caller, so the server is the only
+   * correct source for "who am I": a configured value could disagree with the
+   * credential and silently change which messages trigger this agent.
+   */
+  whoami(signal?: AbortSignal): Promise<{
+    readonly id: string;
+  } | undefined>;
+  listMembers(roomId: string, signal?: AbortSignal): Promise<readonly RoomMember[]>;
+  /**
+   * Pull events after `cursor`. Omitting the cursor asks for the room from the start,
+   * which is what a fresh container does on its first sync.
+   */
+  listEvents(roomId: string, cursor?: string, limit?: number, signal?: AbortSignal): Promise<EventPage>;
+  /**
+   * Send one human message. `rpcId` is the idempotency key: a retry that reuses it
+   * returns the original row instead of creating a second one, so a timed-out
+   * request is safe to repeat.
+   */
+  sendMessage(roomId: string, input: {
+    readonly content: string;
+    readonly rpcId: string;
+    readonly mentions?: readonly string[];
+  }, signal?: AbortSignal): Promise<{
+    readonly id: string;
+    readonly event: RoomEvent;
+    readonly deduplicated: boolean;
+  }>;
+  /**
+   * Report one agent reply. Only the turn's final `assistant/message` is sent —
+   * intermediate steps stay in this container by construction.
+   */
+  reportAgentEvent(roomId: string, input: {
+    readonly rpcId: string;
+    readonly event: RoomEvent;
+  }, signal?: AbortSignal): Promise<{
+    readonly id: string;
+    readonly event: RoomEvent;
+    readonly deduplicated: boolean;
+  }>;
+  private request;
+}
+//#endregion
+//#region src/routing.d.ts
+/** Identifies a member mentioned by an event. */
+interface MentionTarget {
+  readonly memberId: string;
+  /** `all` is reserved for `@everyone`; it never equals a member id, so it never triggers. */
+  readonly kind: 'member' | 'all';
+}
+/** The DataOps user a message came from, when the event identifies one. */
+declare const senderId: (event: RoomEvent) => string | undefined;
+/** True when the event is a member's agent reply rather than a human message. */
+declare const isAgentReply: (event: RoomEvent) => boolean;
+/** The global backend id carried on the event, used for local deduplication. */
+declare const messageId: (event: RoomEvent) => string | undefined;
+/**
+ * Reads structured mentions off an event.
+ *
+ * Mentions are declared by the sender's client as member ids — never parsed out of
+ * message text. Parsing text would misread a code sample containing `@`, and it
+ * would let any message smuggle itself into an execution path.
+ */
+declare const mentionsOf: (event: RoomEvent) => readonly MentionTarget[];
+/**
+ * The decision the whole design turns on.
+ *
+ * `selfMention` requires the sender to be this workspace's member *and* to have
+ * mentioned that same member, which is the only combination that may start a turn.
+ */
+declare const shouldTriggerAgent: (event: RoomEvent, workspaceUserId: string, roomMembers: readonly RoomMember[]) => boolean;
+/**
+ * Renders the name prefix for a message this workspace did not author.
+ *
+ * DSH's compaction summarizes raw `role` + `content` and carries no speaker field,
+ * so identity must live inside `content` to survive summarization. This mirrors the
+ * shipped `agent-team` plugin, which prefixes `Team message from <name>:`.
+ */
+declare const speakerPrefix: (event: RoomEvent, roomMembers: readonly RoomMember[]) => string;
+/** Prepends the speaker to each text block so the model can attribute the message. */
+declare const withSpeakerPrefix: (event: RoomEvent, prefix: string) => RoomEvent;
+//#endregion
+//#region src/index.d.ts
+declare const name = "group-chat";
+/** Host services this plugin needs beyond the room runtime. */
+declare const inject: string[];
+/**
+ * Plugin configuration, rendered as editable fields in the DSH settings panel.
+ *
+ * Every field is optional: leaving them blank uses the environment defaults a
+ * managed workspace already carries, so the common case needs no editing while a
+ * workspace pointed at any other conforming server can be configured from the UI.
+ */
+interface Config {
+  /** Origin of the room server, e.g. `http://host.docker.internal:3101`. */
+  baseUrl?: string;
+  /** Credential reference resolved per request; never a secret value. */
+  credentialRef?: string;
+}
+declare const Config: z<Config>;
+/** Browser-facing route the sidebar calls to list and read rooms. */
+declare const GROUP_CHAT_ROUTE = "/dsh-group-chat/api";
+/**
+ * Milliseconds between cursor pulls.
+ *
+ * Pulling is the fallback and currently the only downlink: it needs no second
+ * transport, and a cursor is the whole synchronization state, so it survives a
+ * restart without re-appending history. The interval trades a bounded delay for a
+ * request the backend already serves.
+ */
+declare const POLL_INTERVAL_MS = 3000;
+/**
+ * Every room session id starts with this, so a room's session is recognizable
+ * after a restart and an ordinary session never matches.
+ *
+ * The binding lives in the id rather than in `SessionHeader` because the header
+ * carries no free-form metadata field.
+ */
+declare const ROOM_SESSION_PREFIX = "group-room-";
+/** Deterministic session id for a room. */
+declare const roomSessionId: (roomId: string) => string;
+/** Reads the room a session is bound to, or `undefined` for an ordinary session. */
+declare const roomIdOfSession: (session: unknown) => string | undefined;
+/** The most recently appended event belonging to a room. */
+declare const lastRoomEvent: (session: Session, roomId: string) => SessionEvent | undefined;
+/** Narrows the payload `followup` accepts; the check is structural because JSON crossed a boundary. */
+declare const isUserMessageData: (data: unknown) => data is Parameters<Agent["followup"]>[0];
+/**
+ * Tracks which room events this workspace already appended.
+ *
+ * The key is the backend's global id, never the local sequence: the backend owns
+ * cross-container order, and the same event can arrive twice (a broadcast and a
+ * catch-up pull). Without this the model would read one message twice.
+ */
+declare class RoomEventTracker {
+  private readonly seen;
+  /** Records an event and reports whether it was new. */
+  accept(roomId: string, globalId: string): boolean;
+  has(roomId: string, globalId: string): boolean;
+  /** Highest global id seen for a room, as the cursor to resume from. */
+  cursorOf(roomId: string): string | undefined;
+  /**
+   * Rebuilds the tracker from a room's own session log, so a restart resumes from
+   * what this workspace already holds instead of re-appending the whole room.
+   */
+  seedFromSession(roomId: string, events: readonly SessionEvent[]): void;
+}
+/**
+ * Wire the room runtime.
+ *
+ * Returns `undefined` on an unmanaged DSH: no route, no listener, no timer. That is
+ * the mechanism behind "ordinary sessions are byte-identical with and without this
+ * plugin".
+ */
+declare const apply: (ctx: GroupChatContext, config?: Config) => (() => void) | undefined;
+/** The activated runtime; separated so target resolution stays independently testable. */
+declare const activate: (ctx: GroupChatContext, target: ServerTarget) => (() => void);
+//#endregion
+export { BackendError, Config, DEFAULT_CREDENTIAL_REF, type EventPage, GROUP_CHAT_ROUTE, GroupChatBackend, MANAGED_ENV, POLL_INTERVAL_MS, ROOM_SESSION_PREFIX, type RoomEvent, type RoomEventRecord, RoomEventTracker, type RoomMember, type RoomSummary, type ServerTarget, activate, apply, inject, isAgentReply, isTransportFailure, isUserMessageData, lastRoomEvent, mentionsOf, messageId, name, resolveServerTarget, resolveWorkspaceRoot, roomIdOfSession, roomSessionId, senderId, shouldTriggerAgent, speakerPrefix, withSpeakerPrefix };