xyne-sdk 1.0.2

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "xyne-sdk",
+  "version": "1.0.2",
+  "description": "TypeScript types for the Xyne AI coding agent SDK — sessions, messages, parts, events, and client interface",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xyne",
+    "sdk",
+    "ai",
+    "agent",
+    "coding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xynehq/xyne.git",
+    "directory": "npm/xyne-sdk"
+  }
+}

package/src/client.ts

@@ -0,0 +1,81 @@
+import type {
+  Session,
+  Message,
+  Part,
+  TodoItem,
+  ModelInfo,
+  AgentInfo,
+  ToolInfo,
+  AuthEntry,
+  SendOptions,
+  PermissionRequest,
+  PermissionReply,
+  QuestionRequest,
+} from "./types"
+import type { ClientEvent, Unsubscribe } from "./events"
+
+export interface Client {
+  session: {
+    create(opts?: { id?: string; title?: string }): Promise<Session>
+    get(id: string): Promise<Session | undefined>
+    list(): Promise<Session[]>
+    delete(id: string): Promise<void>
+    update(id: string, patch: { title?: string }): Promise<Session>
+    send(opts: SendOptions): Promise<Message>
+    cancel(sessionID: string): Promise<string[] | null>
+    isBusy(sessionID: string): boolean
+    compact(sessionID: string): Promise<boolean>
+  }
+
+  message: {
+    list(sessionID: string): Promise<Message[]>
+    get(id: string): Promise<Message | undefined>
+    delete(id: string): Promise<void>
+  }
+
+  part: {
+    list(messageID: string): Promise<Part[]>
+    listBatch(messageIDs: string[]): Promise<Map<string, Part[]>>
+  }
+
+  todo: {
+    list(sessionID: string): Promise<TodoItem[]>
+    set(sessionID: string, todos: TodoItem[]): Promise<void>
+  }
+
+  tool: {
+    list(): ToolInfo[]
+    /** Invalidate the tool cache — call when MCP tools change. */
+    invalidate(): void
+  }
+
+  model: {
+    list(): Promise<ModelInfo[]>
+    get(providerID: string, modelID: string): ModelInfo | undefined
+  }
+
+  agent: {
+    list(): AgentInfo[]
+    get(name: string): AgentInfo | undefined
+  }
+
+  permission: {
+    list(): PermissionRequest[]
+    reply(requestID: string, sessionID: string, reply: PermissionReply): void
+  }
+
+  question: {
+    list(): QuestionRequest[]
+    reply(requestID: string, sessionID: string, answers: string[][]): void
+    reject(requestID: string, sessionID: string): void
+  }
+
+  auth: {
+    get(providerID: string): Promise<AuthEntry | undefined>
+    set(providerID: string, entry: AuthEntry): Promise<void>
+    remove(providerID: string): Promise<void>
+    list(): Promise<Record<string, AuthEntry>>
+  }
+
+  subscribe(callback: (event: ClientEvent) => void): Unsubscribe
+}

package/src/events.ts

@@ -0,0 +1,29 @@
+import type {
+  Session,
+  Message,
+  Part,
+  PartDelta,
+  PermissionRequest,
+  QuestionRequest,
+  FileChange,
+} from "./types"
+
+export type SessionStatus =
+  | { type: "idle" }
+  | { type: "busy" }
+  | { type: "retry"; attempt: number; message: string; next: number }
+
+export type ClientEvent =
+  | { type: "session.status"; sessionID: string; status: SessionStatus }
+  | { type: "session.updated"; session: Session }
+  | { type: "session.compacted"; sessionID: string }
+  | { type: "message.created"; message: Message }
+  | { type: "message.updated"; message: Message }
+  | { type: "part.created"; part: Part }
+  | { type: "part.updated"; part: Part }
+  | { type: "part.delta"; delta: PartDelta }
+  | { type: "permission.asked"; request: PermissionRequest }
+  | { type: "question.asked"; request: QuestionRequest }
+  | { type: "file.changed"; change: FileChange }
+
+export type Unsubscribe = () => void

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * xyne-sdk — TypeScript types for the Xyne AI coding agent.
+ *
+ * This package provides type definitions for sessions, messages, parts,
+ * events, and the client interface. It has zero runtime dependencies —
+ * all exports are TypeScript types.
+ *
+ * @example
+ * ```ts
+ * import type { Client, Session, Message, Part } from "xyne-sdk"
+ * ```
+ */
+
+// SDK types
+export type {
+  Session,
+  TokenUsage,
+  MessageError,
+  Message,
+  TextPart,
+  ReasoningPart,
+  ToolState,
+  ToolPart,
+  StepStartPart,
+  StepFinishPart,
+  RetryPart,
+  CompactionPart,
+  SubtaskPart,
+  PatchPart,
+  MediaPart,
+  AgentPart,
+  Part,
+  PartDelta,
+  ModelInfo,
+  CredentialSource,
+  AgentInfo,
+  ToolInfo,
+  TodoItem,
+  PermissionRequest,
+  PermissionReply,
+  QuestionOption,
+  QuestionInfo,
+  QuestionRequest,
+  SendOptions,
+  SendAttachment,
+  ImageAttachment,
+  FilePathAttachment,
+  FileChange,
+  AuthEntry,
+} from "./types"
+
+// Events
+export type { SessionStatus, ClientEvent, Unsubscribe } from "./events"
+
+// Client interface
+export type { Client } from "./client"

package/src/types.ts

@@ -0,0 +1,298 @@
+// Xyne SDK types — plain serializable objects, no runtime dependencies
+
+// ─── Session ────────────────────────────────────────────────────────
+
+export interface Session {
+  id: string
+  created: number
+  updated: number
+  title?: string
+  parentID?: string
+  directory: string
+}
+
+// ─── Message ────────────────────────────────────────────────────────
+
+export interface TokenUsage {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  reasoning: number
+}
+
+export type MessageError =
+  | { name: "AuthError"; providerID: string; message: string }
+  | { name: "APIError"; message: string; statusCode?: number; isRetryable: boolean }
+  | { name: "ContextOverflowError"; message: string }
+  | { name: "AbortedError"; message: string }
+  | { name: "OutputLengthError" }
+  | { name: "StructuredOutputError"; message: string; retries: number }
+  | { name: "Unknown"; message: string }
+
+export interface Message {
+  id: string
+  sessionID: string
+  role: "user" | "assistant"
+  created: number
+  completed?: number
+  parentID?: string
+  agentID?: string
+  modelID?: string
+  providerID?: string
+  path?: { cwd: string; root: string }
+  finish?: string
+  error?: MessageError
+  cost?: number
+  tokens?: TokenUsage
+  summary?: string
+}
+
+// ─── Parts ──────────────────────────────────────────────────────────
+
+interface BasePart {
+  id: string
+  messageID: string
+  sessionID: string
+}
+
+export interface TextPart extends BasePart {
+  type: "text"
+  text: string
+  startTime: number
+  endTime?: number
+  synthetic?: boolean
+}
+
+export interface ReasoningPart extends BasePart {
+  type: "reasoning"
+  text: string
+  startTime: number
+  endTime?: number
+}
+
+export type ToolState =
+  | { status: "pending" }
+  | {
+      status: "running"
+      input: unknown
+      startTime: number
+      title?: string
+      metadata?: unknown
+    }
+  | {
+      status: "completed"
+      input: unknown
+      output: string
+      title: string
+      metadata: unknown
+      startTime: number
+      endTime: number
+    }
+  | {
+      status: "error"
+      input: unknown
+      error: string
+      startTime: number
+      endTime: number
+    }
+
+export interface ToolPart extends BasePart {
+  type: "tool"
+  callID: string
+  tool: string
+  state: ToolState
+}
+
+export interface StepStartPart extends BasePart {
+  type: "step-start"
+}
+
+export interface StepFinishPart extends BasePart {
+  type: "step-finish"
+  reason: string
+  tokens?: TokenUsage
+  cost?: number
+}
+
+export interface RetryPart extends BasePart {
+  type: "retry"
+  attempt: number
+  error: MessageError
+  time: { created: number }
+}
+
+export interface CompactionPart extends BasePart {
+  type: "compaction"
+  auto: boolean
+  overflow?: boolean
+}
+
+export interface SubtaskPart extends BasePart {
+  type: "subtask"
+  prompt: string
+  description: string
+  agent: string
+  model?: { providerID: string; modelID: string }
+  command?: string
+}
+
+export interface PatchPart extends BasePart {
+  type: "patch"
+  hash: string
+  files: string[]
+}
+
+export interface MediaPart extends BasePart {
+  type: "media"
+  mime: string
+  filename?: string
+  url: string
+}
+
+export interface AgentPart extends BasePart {
+  type: "agent"
+  name: string
+}
+
+export type Part =
+  | TextPart
+  | ReasoningPart
+  | ToolPart
+  | StepStartPart
+  | StepFinishPart
+  | RetryPart
+  | CompactionPart
+  | SubtaskPart
+  | PatchPart
+  | MediaPart
+  | AgentPart
+
+// ─── Part Delta (streaming) ─────────────────────────────────────────
+
+export interface PartDelta {
+  sessionID: string
+  messageID: string
+  partID: string
+  field: "text" | "reasoning"
+  delta: string
+}
+
+// ─── Model ──────────────────────────────────────────────────────────
+
+/** How a provider's API key was resolved. */
+export type CredentialSource = "config" | "env" | "auth"
+
+export interface ModelInfo {
+  providerID: string
+  modelID: string
+  name: string
+  contextLength: number
+  maxOutputTokens: number
+  supportsVision?: boolean
+  supportsReasoning?: boolean
+  hasCredential: boolean
+  credentialSource?: CredentialSource
+}
+
+// ─── Agent ──────────────────────────────────────────────────────────
+
+export interface AgentInfo {
+  name: string
+  description?: string
+  mode: "primary" | "subagent" | "all"
+  color?: string
+  hidden?: boolean
+  native?: boolean
+}
+
+// ─── Tool ───────────────────────────────────────────────────────────
+
+export interface ToolInfo {
+  id: string
+  description: string
+}
+
+// ─── Todo ───────────────────────────────────────────────────────────
+
+export interface TodoItem {
+  id: string
+  subject: string
+  description?: string
+  status: "pending" | "in_progress" | "completed" | "cancelled"
+  priority?: "low" | "medium" | "high"
+}
+
+// ─── Permission ─────────────────────────────────────────────────────
+
+export interface PermissionRequest {
+  id: string
+  sessionID: string
+  permission: string
+  patterns: string[]
+  metadata: Record<string, unknown>
+  always: string[]
+  tool?: { messageID: string; callID: string }
+}
+
+export type PermissionReply = "once" | "always" | "reject"
+
+// ─── Question ───────────────────────────────────────────────────────
+
+export interface QuestionOption {
+  label: string
+  description: string
+}
+
+export interface QuestionInfo {
+  question: string
+  header: string
+  options: QuestionOption[]
+  multiple?: boolean
+}
+
+export interface QuestionRequest {
+  id: string
+  sessionID: string
+  questions: QuestionInfo[]
+  tool?: { messageID: string; callID: string }
+}
+
+// ─── Auth ──────────────────────────────────────────────────────────
+
+export type AuthEntry =
+  | { type: "api"; key: string }
+  | { type: "oauth"; access: string; refresh: string; expires: number }
+
+// ─── Send Options ───────────────────────────────────────────────────
+
+export interface ImageAttachment {
+  type: "image"
+  data: string  // base64
+  mime: string
+}
+
+export interface FilePathAttachment {
+  type: "file-path"
+  path: string      // absolute filesystem path
+  filename: string
+}
+
+export type SendAttachment = ImageAttachment | FilePathAttachment
+
+export interface SendOptions {
+  sessionID: string
+  text: string
+  attachments?: SendAttachment[]
+  model?: { providerID: string; modelID: string }
+  agentID?: string
+  abort?: AbortSignal
+}
+
+// ─── File Change ────────────────────────────────────────────────────
+
+export interface FileChange {
+  sessionID: string
+  type: "create" | "update"
+  path: string
+}