@motrix/mdxp 0.1.0

package/src/schemas/task.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod'
+
+/**
+ * Control-plane task status. Richer than the lossy 4-value
+ * `$/task/progress.phase`; snake_case-aligned with the host's domain
+ * `TaskStatus` so the host-side mapper is near-identity. `metadata_ready` maps
+ * to `queued` and `removed` is filtered out of `task/list` (not a value here).
+ */
+export const MdxpTaskStatusSchema = z.enum([
+  'queued',
+  'fetching_metadata',
+  'downloading',
+  'paused',
+  'seeding',
+  'finalizing',
+  'completed',
+  'error',
+])
+
+export const MdxpTaskTypeSchema = z.enum([
+  'http',
+  'ftp',
+  'bt',
+  'magnet',
+  'metalink',
+])
+
+/** BitTorrent-only public subset (omits swarm/announce/piece internals). */
+export const MdxpBtSchema = z.object({
+  peers: z.number(),
+  seeds: z.number(),
+  ratio: z.number(),
+  trackers: z.array(z.string()),
+})
+
+/**
+ * First-class public task DTO — a deliberate NARROW projection of the host's
+ * ~40-field domain `DownloadTask`. Result/notification payload, so non-strict
+ * (a newer server may add fields older clients ignore). The public id is `id`,
+ * never the volatile engine gid.
+ */
+export const MdxpTaskSchema = z.object({
+  id: z.string(),
+  type: MdxpTaskTypeSchema,
+  name: z.string(),
+  status: MdxpTaskStatusSchema,
+  /** Fraction in [0,1] — identity with the domain (DownloadTask.progress is
+   *  already completed/total). `finalPath`, by contrast, is a conditional
+   *  projection (non-null only once completed), not a blind copy. */
+  progress: z.number(),
+  bytesDone: z.number(),
+  bytesTotal: z.number().nullable(),
+  speedBps: z.number(),
+  etaSec: z.number().nullable(),
+  saveDir: z.string(),
+  error: z.string().nullable(),
+  createdAt: z.number(),
+  finishedAt: z.number().nullable(),
+  finalPath: z.string().nullable(),
+  infoHash: z.string().nullable().optional(),
+  bt: MdxpBtSchema.optional(),
+})
+
+/** Shared result for write methods that only need to ack. */
+export const OkResultSchema = z.object({ ok: z.literal(true) })
+
+// ─── task/list ────────────────────────────────────────────────
+export const TaskListParamsSchema = z.strictObject({
+  status: MdxpTaskStatusSchema.optional(),
+  limit: z.number().int().positive().optional(),
+  offset: z.number().int().nonnegative().optional(),
+})
+export const TaskListResultSchema = z.object({
+  tasks: z.array(MdxpTaskSchema),
+  total: z.number(),
+})
+
+// ─── task/get ─────────────────────────────────────────────────
+export const TaskGetParamsSchema = z.strictObject({
+  taskId: z.string().min(1),
+})
+export const TaskGetResultSchema = z.object({
+  task: MdxpTaskSchema.nullable(),
+})
+
+// ─── task/pause · task/resume ─────────────────────────────────
+export const TaskPauseParamsSchema = z.strictObject({
+  taskId: z.string().min(1),
+})
+export const TaskResumeParamsSchema = z.strictObject({
+  taskId: z.string().min(1),
+})
+
+// ─── task/remove ──────────────────────────────────────────────
+export const TaskRemoveParamsSchema = z.strictObject({
+  taskId: z.string().min(1),
+  deleteFiles: z.boolean().optional(),
+})
+
+export type MdxpTaskStatus = z.infer<typeof MdxpTaskStatusSchema>
+export type MdxpTaskType = z.infer<typeof MdxpTaskTypeSchema>
+export type MdxpTask = z.infer<typeof MdxpTaskSchema>
+export type OkResult = z.infer<typeof OkResultSchema>
+export type TaskListParams = z.infer<typeof TaskListParamsSchema>
+export type TaskListResult = z.infer<typeof TaskListResultSchema>
+export type TaskGetParams = z.infer<typeof TaskGetParamsSchema>
+export type TaskGetResult = z.infer<typeof TaskGetResultSchema>
+export type TaskPauseParams = z.infer<typeof TaskPauseParamsSchema>
+export type TaskPauseResult = OkResult
+export type TaskResumeParams = z.infer<typeof TaskResumeParamsSchema>
+export type TaskResumeResult = OkResult
+export type TaskRemoveParams = z.infer<typeof TaskRemoveParamsSchema>
+export type TaskRemoveResult = OkResult

package/src/schemas/url.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+import { ResourceSchema } from './resource.js'
+
+// url/probe ----------------------------------------------------
+
+export const UrlProbeParamsSchema = z.object({
+  url: z.string().url(),
+  hint: z.object({ siteName: z.string().optional() }).optional(),
+})
+
+export const UrlProbeResultSchema = z.object({
+  handled: z.boolean(),
+  adapterId: z.string().optional(),
+  confidence: z.enum(['high', 'medium', 'low']).optional(),
+})
+
+// url/resolve --------------------------------------------------
+
+const QualityEnum = z.enum(['360p', '720p', '1080p', '1440p', '2160p', 'best'])
+
+const ResolvedSelectionSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('direct'),
+    primary: ResourceSchema,
+    container: z.string().optional(),
+    quality: z.string(),
+    sizeBytes: z.number().nonnegative().optional(),
+  }),
+  z.object({
+    kind: z.literal('hls'),
+    primary: ResourceSchema,
+    container: z.string(),
+    quality: z.string(),
+  }),
+  z.object({
+    kind: z.literal('mux'),
+    video: ResourceSchema,
+    audio: ResourceSchema,
+    container: z.string(),
+    quality: z.string(),
+    sizeBytes: z.number().nonnegative().optional(),
+  }),
+])
+
+const SubtitleSchema = z.object({
+  languageCode: z.string(),
+  languageName: z.string(),
+  url: z.string().url(),
+  format: z.enum(['vtt', 'srt', 'ttml']),
+})
+
+export const UrlResolveParamsSchema = z.object({
+  url: z.string().url(),
+  preferences: z
+    .object({
+      maxQuality: QualityEnum.optional(),
+      preferContainer: z.enum(['mp4', 'mkv', 'webm']).optional(),
+      includeAudio: z.boolean().optional(),
+      includeSubtitles: z.boolean().optional(),
+    })
+    .optional(),
+})
+
+export const UrlResolveResultSchema = z.object({
+  selections: z.array(ResolvedSelectionSchema),
+  meta: z.object({
+    title: z.string(),
+    author: z.string().optional(),
+    durationSec: z.number().nonnegative().optional(),
+    thumbnail: z.string().url().optional(),
+    description: z.string().optional(),
+    publishedAt: z.number().optional(),
+    tags: z.array(z.string()).optional(),
+  }),
+  subtitles: z.array(SubtitleSchema).optional(),
+  extractedBy: z.object({
+    adapterId: z.string(),
+    adapterVersion: z.string(),
+    extractedAt: z.number(),
+  }),
+})
+
+export type UrlProbeParams = z.infer<typeof UrlProbeParamsSchema>
+export type UrlProbeResult = z.infer<typeof UrlProbeResultSchema>
+export type UrlResolveParams = z.infer<typeof UrlResolveParamsSchema>
+export type UrlResolveResult = z.infer<typeof UrlResolveResultSchema>

package/src/tools.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod'
+import { type Method, Methods } from './methods.js'
+import {
+  DownloadCancelParamsSchema,
+  DownloadCancelResultSchema,
+  DownloadSubmitParamsSchema,
+  DownloadSubmitResultSchema,
+} from './schemas/download.js'
+import {
+  DownloadAddParamsSchema,
+  DownloadAddResultSchema,
+} from './schemas/download-add.js'
+import {
+  EngineStatusParamsSchema,
+  EngineStatusResultSchema,
+} from './schemas/engine.js'
+import {
+  InitializeParamsSchema,
+  InitializeResultSchema,
+} from './schemas/initialize.js'
+import { StatsGetParamsSchema, StatsResultSchema } from './schemas/stats.js'
+import {
+  SystemPingParamsSchema,
+  SystemPingResultSchema,
+} from './schemas/system.js'
+import {
+  OkResultSchema,
+  TaskGetParamsSchema,
+  TaskGetResultSchema,
+  TaskListParamsSchema,
+  TaskListResultSchema,
+  TaskPauseParamsSchema,
+  TaskRemoveParamsSchema,
+  TaskResumeParamsSchema,
+} from './schemas/task.js'
+
+export interface MdxpToolDef {
+  readonly method: Method
+  readonly description: string
+  readonly paramsSchema: z.ZodType
+  readonly resultSchema: z.ZodType
+  /** True for methods a CLI / AI agent calls directly (vs handshake/meta). */
+  readonly agentFacing: boolean
+}
+
+/**
+ * Methods the SERVER initiates against the client — not agent-callable, so they
+ * are absent from {@link Tools}. Colocated here so the registry's
+ * "client→server only" invariant has a single source of truth (the drift test
+ * derives the expected Tools key set from this).
+ */
+export const SERVER_INITIATED_METHODS: readonly Method[] = [
+  Methods.UrlProbe,
+  Methods.UrlResolve,
+]
+
+/**
+ * Registry of every client→server request method, keyed by wire method name —
+ * the single source of truth tying method ↔ schema ↔ description together. The
+ * `agentFacing` subset is the tool catalog an AI agent sees (consumed by
+ * `motrix describe` in Spec 8). The server-initiated `url/probe` + `url/resolve`
+ * are intentionally absent (the server calls those on the client).
+ */
+export const Tools: Readonly<Record<string, MdxpToolDef>> = {
+  [Methods.MotrixInitialize]: {
+    method: Methods.MotrixInitialize,
+    description:
+      'Handshake: negotiate protocol version, identity, and capabilities.',
+    paramsSchema: InitializeParamsSchema,
+    resultSchema: InitializeResultSchema,
+    agentFacing: false,
+  },
+  [Methods.SystemPing]: {
+    method: Methods.SystemPing,
+    description: 'Liveness probe; echoes sentAt with the server recvAt.',
+    paramsSchema: SystemPingParamsSchema,
+    resultSchema: SystemPingResultSchema,
+    agentFacing: false,
+  },
+  [Methods.DownloadSubmit]: {
+    method: Methods.DownloadSubmit,
+    description:
+      'Submit a browser-detected download (page-shaped; used by the extension).',
+    paramsSchema: DownloadSubmitParamsSchema,
+    resultSchema: DownloadSubmitResultSchema,
+    agentFacing: false,
+  },
+  [Methods.DownloadCancel]: {
+    method: Methods.DownloadCancel,
+    description: 'Cancel a previously submitted download by task id.',
+    paramsSchema: DownloadCancelParamsSchema,
+    resultSchema: DownloadCancelResultSchema,
+    agentFacing: false,
+  },
+  [Methods.DownloadAdd]: {
+    method: Methods.DownloadAdd,
+    description:
+      'Add a download by URL(s), magnet, or torrent; returns the created task.',
+    paramsSchema: DownloadAddParamsSchema,
+    resultSchema: DownloadAddResultSchema,
+    agentFacing: true,
+  },
+  [Methods.TaskList]: {
+    method: Methods.TaskList,
+    description: 'List tasks, optionally filtered by status and paginated.',
+    paramsSchema: TaskListParamsSchema,
+    resultSchema: TaskListResultSchema,
+    agentFacing: true,
+  },
+  [Methods.TaskGet]: {
+    method: Methods.TaskGet,
+    description: 'Get a single task by id (null if not found).',
+    paramsSchema: TaskGetParamsSchema,
+    resultSchema: TaskGetResultSchema,
+    agentFacing: true,
+  },
+  [Methods.TaskPause]: {
+    method: Methods.TaskPause,
+    description: 'Pause a task by id.',
+    paramsSchema: TaskPauseParamsSchema,
+    resultSchema: OkResultSchema,
+    agentFacing: true,
+  },
+  [Methods.TaskResume]: {
+    method: Methods.TaskResume,
+    description: 'Resume a paused task by id.',
+    paramsSchema: TaskResumeParamsSchema,
+    resultSchema: OkResultSchema,
+    agentFacing: true,
+  },
+  [Methods.TaskRemove]: {
+    method: Methods.TaskRemove,
+    description: 'Remove a task by id, optionally deleting its files.',
+    paramsSchema: TaskRemoveParamsSchema,
+    resultSchema: OkResultSchema,
+    agentFacing: true,
+  },
+  [Methods.StatsGet]: {
+    method: Methods.StatsGet,
+    description: 'Get aggregate global stats (speeds + task counts).',
+    paramsSchema: StatsGetParamsSchema,
+    resultSchema: StatsResultSchema,
+    agentFacing: true,
+  },
+  [Methods.EngineStatus]: {
+    method: Methods.EngineStatus,
+    description: 'Get the download engine lifecycle state + feature report.',
+    paramsSchema: EngineStatusParamsSchema,
+    resultSchema: EngineStatusResultSchema,
+    agentFacing: true,
+  },
+}
+
+export interface AgentTool {
+  name: string
+  description: string
+  /** JSON Schema (draft 2020-12) emitted by `z.toJSONSchema`. */
+  inputSchema: Record<string, unknown>
+  outputSchema: Record<string, unknown>
+}
+
+/** The agent-facing tool catalog: JSON-Schema-typed tools for LLM consumption. */
+export function toAgentToolCatalog(): AgentTool[] {
+  return Object.values(Tools)
+    .filter((tool) => tool.agentFacing)
+    .map((tool) => ({
+      name: tool.method,
+      description: tool.description,
+      inputSchema: z.toJSONSchema(tool.paramsSchema) as Record<string, unknown>,
+      outputSchema: z.toJSONSchema(tool.resultSchema) as Record<
+        string,
+        unknown
+      >,
+    }))
+}

package/src/types.ts

@@ -0,0 +1,63 @@
+export type {
+  DownloadCancelParams,
+  DownloadCancelResult,
+  DownloadSubmitParams,
+  DownloadSubmitResult,
+} from './schemas/download.js'
+export type {
+  DownloadAddParams,
+  DownloadAddResult,
+} from './schemas/download-add.js'
+export type {
+  EngineFeatureReport,
+  EngineState,
+  EngineStatusParams,
+  EngineStatusResult,
+} from './schemas/engine.js'
+export type {
+  CancelRequestParams,
+  PairRevokedParams,
+  TaskCompletedParams,
+  TaskErrorParams,
+  TaskProgressParams,
+} from './schemas/events.js'
+export type {
+  InitializeParams,
+  InitializeResult,
+} from './schemas/initialize.js'
+export type {
+  Cookie,
+  Resource,
+} from './schemas/resource.js'
+export type { Selection } from './schemas/selection.js'
+export type {
+  StatsGetParams,
+  StatsResult,
+  StatsUpdateParams,
+} from './schemas/stats.js'
+export type {
+  SystemPingParams,
+  SystemPingResult,
+} from './schemas/system.js'
+export type {
+  MdxpTask,
+  MdxpTaskStatus,
+  MdxpTaskType,
+  OkResult,
+  TaskGetParams,
+  TaskGetResult,
+  TaskListParams,
+  TaskListResult,
+  TaskPauseParams,
+  TaskPauseResult,
+  TaskRemoveParams,
+  TaskRemoveResult,
+  TaskResumeParams,
+  TaskResumeResult,
+} from './schemas/task.js'
+export type {
+  UrlProbeParams,
+  UrlProbeResult,
+  UrlResolveParams,
+  UrlResolveResult,
+} from './schemas/url.js'