1/**

2 * Types for the TypeScript SDK client: launch options, notification shapes,

3 * and owned activity results.

4 *

5 * @module @deepseek-ai/dsh-sdk-client/types

6 */

7

8import type { ContentBlock, ReasoningEffortId } from '@deepseek-ai/dsh-llm'

9import type { SdkPromptContentBlock } from '@deepseek-ai/dsh-sdk-protocol'

10import type { SessionEvent } from '@deepseek-ai/dsh-session'

11

12/** One server-to-client notification as received off the wire. */

13export interface HarnessNotification {

14 /** The JSON-RPC notification method name. */

15 method: string

16 /** The raw params object; see `HarnessSdkNotificationMap` for the shapes per method. */

17 params: Record<string, unknown>

18}

19

20/** Predicate deciding whether a subscription receives a notification. */

21export type NotificationFilter = (notification: HarnessNotification) => boolean

22

23/** Launch and timeout options for {@link HarnessClient}. */

24export interface HarnessClientOptions {

25 /** Absolute or caller-relative dsh CLI module; omitted resolves this package's same-version dependency. */

26 dshBin?: string

27 /** Named profile serving the SDK protocol (default `sdk`). */

28 profile?: string

29 /** Ordered per-launch profile patches; relative paths resolve before spawn. */

30 patches?: string[]

31 /** Explicit Harness home for this child; relative paths resolve before spawn. */

32 dshHome?: string

33 /** Working directory for the dsh process itself. */

34 processCwd?: string

35 /**

36 * The complete child environment, read when {@link HarnessClient.start}

37 * spawns. `undefined` reads the parent env at that time; passing an object

38 * reads that object at spawn and replaces the parent environment entirely, so callers own

39 * credential policy (see `scrubbedParentEnv` in `@deepseek-ai/dsh-subprocess`

40 * for the shared scrub-then-merge base).

41 */

42 env?: NodeJS.ProcessEnv

43 /** Bound (ms) on the initial profile handshake (default 10000). */

44 initializeTimeoutMs?: number

45 /** Per-request timeout (ms); `undefined` waits indefinitely (a turn can legitimately run long). */

46 requestTimeoutMs?: number

47 /** Bound (ms) on the protocol `shutdown` exchange inside `close()` (default 1000). */

48 shutdownTimeoutMs?: number

49 /** Grace (ms) for the runtime's stdin-EOF quiesce during `close()` (default 6000). */

50 disposeEofGraceMs?: number

51 /** Termination confirmation window (ms) after SIGTERM/SIGKILL during `close()` (default 3000). */

52 disposeGraceMs?: number

53}

54

55/** Options for the high-level {@link DeepSeekHarness} wrapper. */

56export interface DeepSeekHarnessOptions extends HarnessClientOptions {

57 /** Workspace cwd recorded on every SDK-created session (default: the process cwd, else `process.cwd()`). */

58 cwd?: string

59 /** Provider route for SDK-created agents (default `deepseek-official`). */

60 provider?: string

61 /** Model for SDK-created agents (default `deepseek-v4-flash`). */

62 model?: string

63 /** Adapter-owned reasoning effort for the selected provider/model route. */

64 reasoningEffort?: ReasoningEffortId

65 /** Maximum output tokens for each conversation-model request. */

66 maxTokens?: number

67}

68

69/** One owned session activity interval, from enqueue receipt through idle. */

70export interface RunResult {

71 /** The session the activity ran on. */

72 sessionId: string

73 /** Concatenated text of the interval's last assistant message (empty when none). */

74 finalResponse: string

75 /** Every `session.event` payload for the root session, in wire order. */

76 events: SessionEvent[]

77 /** Every notification for the root session and discovered descendants, in wire order. */

78 notifications: HarnessNotification[]

79}

80

81/** Re-exported content-block alias so SDK callers need no extra import. */

82export type { ContentBlock }

83export type { SdkPromptContentBlock }