devteam-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matwal LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# @devteam/sdk
+
+Orchestrate AI agent swarms with Temporal in 10 lines of code.
+
+`@devteam/sdk` is the official TypeScript SDK for the DevTeam platform. It provides a high-level client for creating tasks, building execution plans (DAGs), running fan-out parallel workloads, managing human-in-the-loop approvals, deploying workflow templates, and monitoring worker nodes -- all backed by Temporal for durability and exactly-once execution guarantees.
+
+## Installation
+
+```bash
+npm install @devteam/sdk
+```
+
+## Quick Start
+
+```typescript
+import { DevTeamClient } from '@devteam/sdk';
+
+const client = new DevTeamClient({
+  serverUrl: 'https://devteam.marsala.dev',
+  apiKey: 'dt_...',
+});
+
+// Simple task
+const result = await client.createTask({
+  prompt: 'Review this contract for risks',
+  model: 'opus',
+  queue: 'general-queue',
+});
+
+console.log(result.output);
+```
+
+## Features
+
+- **Single tasks** -- Send a prompt to any AI model and get a result
+- **Fan-out parallel** -- Run N tasks concurrently with a configurable concurrency limit
+- **DAG execution** -- Create plans with dependencies and execute them as a directed acyclic graph
+- **Human-in-the-loop** -- Require approval before tasks execute; review and approve/reject from code
+- **Templates** -- Deploy pre-built industry workflows with custom inputs
+- **Monitoring** -- Track task status, view worker health, subscribe to completion events
+- **Type safety** -- Full TypeScript types and Zod runtime validation
+- **Durability** -- Built on Temporal: retries, timeouts, and exactly-once semantics
+
+## API Reference
+
+### Constructor
+
+```typescript
+const client = new DevTeamClient({
+  serverUrl: 'https://devteam.marsala.dev', // Required
+  apiKey: 'dt_...',                          // Required
+  namespace: 'default',                      // Optional, default: 'default'
+  timeoutMs: 30000,                          // Optional, default: 30000
+  debug: false,                              // Optional, default: false
+});
+```
+
+### Create a Single Task
+
+```typescript
+const result = await client.createTask({
+  prompt: 'Summarize this quarterly earnings report',
+  model: 'sonnet',                   // 'opus' | 'sonnet' | 'haiku' | 'gpt-4o' | ...
+  queue: 'general-queue',            // Temporal task queue
+  priority: 'high',                  // 'critical' | 'high' | 'normal' | 'low'
+  timeoutSeconds: 120,               // Per-task timeout
+  requireApproval: false,            // Require HITL approval
+  metadata: { source: 'earnings' },  // Arbitrary metadata
+  attachments: ['./report.pdf'],     // Files to include as context
+  retry: {                           // Custom retry policy
+    maxAttempts: 3,
+    initialIntervalMs: 1000,
+    backoffCoefficient: 2,
+  },
+});
+
+console.log(result.taskId);     // 'task-abc123'
+console.log(result.output);     // The AI-generated response
+console.log(result.usage);      // { inputTokens, outputTokens, totalTokens, costUsd }
+```
+
+### Fan-Out Parallel Execution
+
+Run multiple independent tasks concurrently. The second argument controls how many tasks run at the same time.
+
+```typescript
+const results = await client.executeFanOut([
+  { prompt: 'Analyze liability clauses', model: 'sonnet' },
+  { prompt: 'Check IP provisions', model: 'sonnet' },
+  { prompt: 'Review termination terms', model: 'sonnet' },
+  { prompt: 'Assess indemnification risks', model: 'sonnet' },
+  { prompt: 'Evaluate non-compete scope', model: 'sonnet' },
+], 3); // max 3 concurrent
+
+for (const result of results) {
+  console.log(`${result.taskId}: ${result.status}`);
+}
+```
+
+### Plan and Execute a DAG
+
+The planner decomposes a high-level goal into an ordered set of subtasks with dependencies. `executeDAG` then runs them layer by layer, passing results from completed tasks as context to downstream tasks.
+
+```typescript
+// Step 1: Generate a plan
+const plan = await client.createPlan(
+  'Full due diligence on Series A investment',
+  {
+    strategy: 'dag',         // 'sequential' | 'parallel' | 'dag' | 'auto'
+    maxSubtasks: 10,
+    defaultModel: 'sonnet',
+    requireApproval: true,   // Review plan before execution
+  },
+);
+
+console.log(`Plan: ${plan.subtasks.length} steps`);
+console.log(`Est. cost: $${plan.estimatedCostUsd}`);
+console.log(`Est. time: ${plan.estimatedDurationSeconds}s`);
+
+// Step 2: Approve the plan (if requireApproval was set)
+const approvals = await client.getPendingApprovals();
+for (const approval of approvals) {
+  await client.approveTask(approval.taskId, 'approve');
+}
+
+// Step 3: Execute the DAG
+const dagResult = await client.executeDAG(plan);
+
+console.log(`Success: ${dagResult.success}`);
+console.log(`Duration: ${dagResult.totalDurationMs}ms`);
+console.log(`Total tokens: ${dagResult.totalUsage?.totalTokens}`);
+console.log(`Total cost: $${dagResult.totalUsage?.costUsd}`);
+
+// Access individual subtask results
+for (const [subtaskId, result] of Object.entries(dagResult.results)) {
+  console.log(`  ${subtaskId}: ${result.status}`);
+}
+```
+
+### Human-in-the-Loop Approvals
+
+Tasks created with `requireApproval: true` pause before execution and wait for human review.
+
+```typescript
+// Create a task that requires approval
+await client.createTask({
+  prompt: 'Send investor update email to all LPs',
+  model: 'opus',
+  requireApproval: true,
+});
+
+// Review pending approvals
+const approvals = await client.getPendingApprovals();
+
+for (const approval of approvals) {
+  console.log(`Task: ${approval.taskId}`);
+  console.log(`Description: ${approval.description}`);
+  console.log(`Model: ${approval.model}`);
+  console.log(`Priority: ${approval.priority}`);
+  console.log(`Requested at: ${approval.requestedAt}`);
+}
+
+// Approve
+await client.approveTask(approvals[0].taskId, 'approve');
+
+// Reject with feedback
+await client.approveTask(approvals[1].taskId, 'reject', 'Too aggressive tone');
+
+// Modify with instructions
+await client.approveTask(approvals[2].taskId, 'modify', 'Use conservative language');
+```
+
+### Deploy Workflow Templates
+
+Templates are pre-built, parameterized workflows for common use cases.
+
+```typescript
+// List available templates
+const templates = await client.listTemplates({
+  industry: 'legal',
+  category: 'review',
+});
+
+for (const t of templates) {
+  console.log(`${t.templateId}: ${t.name} (${t.version})`);
+  console.log(`  Cost: ~$${t.estimatedCostUsd}`);
+  console.log(`  Duration: ~${t.avgDurationSeconds}s`);
+}
+
+// Deploy a template
+const workflowId = await client.deployTemplate('legal-contract-review-v1', {
+  contract_file: './contract.pdf',
+  jurisdiction: 'US-NY',
+  review_depth: 'comprehensive',
+  output_format: 'structured',
+});
+
+console.log(`Workflow started: ${workflowId}`);
+
+// Track progress
+const status = await client.getTaskStatus(workflowId);
+console.log(`Status: ${status.status}, Progress: ${status.progress}%`);
+```
+
+### Monitor Workers
+
+```typescript
+const workers = await client.getWorkers();
+
+for (const worker of workers) {
+  console.log(`${worker.nodeName} (${worker.workerId})`);
+  console.log(`  Queue: ${worker.taskQueue}`);
+  console.log(`  Online: ${worker.online}`);
+  console.log(`  Active: ${worker.activeTasks}/${worker.maxConcurrency}`);
+  console.log(`  Models: ${worker.availableModels.join(', ')}`);
+  console.log(`  CPU: ${worker.cpuPercent}% | RAM: ${worker.memoryPercent}%`);
+}
+```
+
+### Subscribe to Task Completions
+
+```typescript
+const unsubscribe = client.onTaskComplete((result) => {
+  console.log(`Task ${result.taskId} completed: ${result.status}`);
+  if (result.error) {
+    console.error(`  Error: ${result.error.message}`);
+  } else {
+    console.log(`  Output: ${result.output?.substring(0, 100)}...`);
+  }
+});
+
+// ... later
+unsubscribe();
+
+// Or disconnect everything
+client.disconnect();
+```
+
+## Advanced Usage
+
+### Workflow Utilities
+
+The SDK exports low-level utilities for building custom orchestration logic.
+
+```typescript
+import {
+  topologicalSort,
+  aggregateUsage,
+  parallelLimit,
+  withRetry,
+} from '@devteam/sdk';
+
+// Topological sort for custom DAG execution
+const layers = topologicalSort(plan.subtasks);
+// layers[0] = tasks with no dependencies (can run in parallel)
+// layers[1] = tasks depending only on layer 0, etc.
+
+// Aggregate token usage across results
+const totalUsage = aggregateUsage(results);
+
+// Run async operations with concurrency control
+const outputs = await parallelLimit(urls, 5, async (url) => {
+  return fetch(url).then((r) => r.json());
+});
+
+// Retry with exponential backoff
+const data = await withRetry(
+  () => fetch('https://api.example.com/data').then((r) => r.json()),
+  { maxAttempts: 3, initialIntervalMs: 500 },
+);
+```
+
+### Zod Schemas
+
+Use the exported Zod schemas for runtime validation in your own code.
+
+```typescript
+import { TaskInputSchema, PlanOptionsSchema } from '@devteam/sdk';
+
+// Validate user input
+const parsed = TaskInputSchema.safeParse(userInput);
+if (!parsed.success) {
+  console.error('Validation errors:', parsed.error.issues);
+}
+```
+
+### Error Handling
+
+```typescript
+import { DevTeamError, DevTeamValidationError, DevTeamTimeoutError } from '@devteam/sdk';
+
+try {
+  const result = await client.createTask({ prompt: 'Hello' });
+} catch (err) {
+  if (err instanceof DevTeamValidationError) {
+    console.error('Invalid input:', err.message);
+  } else if (err instanceof DevTeamTimeoutError) {
+    console.error('Request timed out:', err.message);
+  } else if (err instanceof DevTeamError) {
+    console.error(`API error [${err.code}]: ${err.message}`);
+    console.error(`Status: ${err.statusCode}, Request ID: ${err.requestId}`);
+  }
+}
+```
+
+## Type Reference
+
+| Type | Description |
+|------|-------------|
+| `DevTeamClientOptions` | Constructor options (serverUrl, apiKey, namespace, etc.) |
+| `TaskInput` | Input for creating a task (prompt, model, queue, etc.) |
+| `TaskResult` | Result of a completed task (output, usage, error, etc.) |
+| `TaskStatus` | Current status with progress and logs |
+| `Plan` | Generated execution plan with subtasks |
+| `PlanOptions` | Options for plan generation (strategy, maxSubtasks, etc.) |
+| `PlanSubtask` | Individual step within a plan |
+| `DAGResult` | Result of executing a full DAG |
+| `Approval` | Pending human approval request |
+| `Template` | Workflow template metadata |
+| `Worker` | Worker node status and capabilities |
+| `ModelId` | Supported model identifiers |
+| `TaskPriority` | Priority levels: critical, high, normal, low |
+| `TaskState` | Task lifecycle states |
+| `TokenUsage` | Token count and cost breakdown |
+| `RetryPolicy` | Per-task retry configuration |
+
+## Architecture
+
+```
+Your Code
+    |
+    v
+@devteam/sdk (this package)
+    |
+    v  HTTPS + JSON
+DevTeam API Server (devteam.marsala.dev)
+    |
+    v  gRPC
+Temporal Server
+    |
+    v  Task Queues
+Worker Nodes (ASUS GPU, Surface, GR-14, EC2, ...)
+    |
+    v
+AI Models (Claude, GPT, Gemini, Ollama, ...)
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (recommended)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,163 @@
+import type { DevTeamClientOptions, TaskInput, TaskResult, Plan, PlanOptions, DAGResult, Approval, Template, TemplateFilter, Worker, TaskStatus, TaskCompleteCallback } from './types.js';
+export declare class DevTeamError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    readonly requestId?: string | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, requestId?: string | undefined);
+}
+export declare class DevTeamValidationError extends DevTeamError {
+    constructor(message: string);
+}
+export declare class DevTeamTimeoutError extends DevTeamError {
+    constructor(message?: string);
+}
+export declare class DevTeamClient {
+    private readonly serverUrl;
+    private readonly apiKey;
+    private readonly namespace;
+    private readonly timeoutMs;
+    private readonly debug;
+    private pollingIntervals;
+    constructor(options: DevTeamClientOptions);
+    /**
+     * Create and execute a single AI agent task.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.createTask({
+     *   prompt: 'Review this contract for risks',
+     *   model: 'opus',
+     *   queue: 'general-queue',
+     * });
+     * console.log(result.output);
+     * ```
+     */
+    createTask(input: TaskInput): Promise<TaskResult>;
+    /**
+     * Generate an execution plan (DAG of subtasks) for a high-level goal.
+     * The planner uses an AI model to decompose the goal into ordered subtasks.
+     *
+     * @example
+     * ```typescript
+     * const plan = await client.createPlan('Full legal review of Series A docs', {
+     *   strategy: 'dag',
+     *   defaultModel: 'sonnet',
+     * });
+     * console.log(`Plan has ${plan.subtasks.length} steps`);
+     * ```
+     */
+    createPlan(goal: string, options?: PlanOptions): Promise<Plan>;
+    /**
+     * Execute a plan as a directed acyclic graph. Subtasks are run in
+     * topologically-sorted layers, maximizing parallelism while respecting
+     * dependencies.
+     *
+     * @example
+     * ```typescript
+     * const plan = await client.createPlan('Analyze portfolio risk');
+     * const dagResult = await client.executeDAG(plan);
+     * console.log(`Success: ${dagResult.success}, took ${dagResult.totalDurationMs}ms`);
+     * ```
+     */
+    executeDAG(plan: Plan): Promise<DAGResult>;
+    /**
+     * Execute multiple independent tasks in parallel with a concurrency limit.
+     *
+     * @example
+     * ```typescript
+     * const results = await client.executeFanOut([
+     *   { prompt: 'Analyze liability clauses', model: 'sonnet' },
+     *   { prompt: 'Check IP provisions', model: 'sonnet' },
+     *   { prompt: 'Review termination terms', model: 'sonnet' },
+     * ], 3);
+     * ```
+     */
+    executeFanOut(tasks: TaskInput[], maxParallel?: number): Promise<TaskResult[]>;
+    /**
+     * Submit an approval decision for a task awaiting human review.
+     *
+     * @example
+     * ```typescript
+     * await client.approveTask('task-abc123', 'approve');
+     * await client.approveTask('task-def456', 'reject', 'Too aggressive strategy');
+     * await client.approveTask('task-ghi789', 'modify', 'Use conservative approach instead');
+     * ```
+     */
+    approveTask(taskId: string, decision: 'approve' | 'reject' | 'modify', feedback?: string): Promise<void>;
+    /**
+     * Retrieve all tasks currently awaiting human approval.
+     *
+     * @example
+     * ```typescript
+     * const approvals = await client.getPendingApprovals();
+     * for (const approval of approvals) {
+     *   console.log(`${approval.taskId}: ${approval.description}`);
+     * }
+     * ```
+     */
+    getPendingApprovals(): Promise<Approval[]>;
+    /**
+     * Deploy a pre-built workflow template with custom inputs.
+     * Returns the workflow ID for tracking.
+     *
+     * @example
+     * ```typescript
+     * const workflowId = await client.deployTemplate('legal-contract-review-v1', {
+     *   contract_file: './contract.pdf',
+     *   jurisdiction: 'US-NY',
+     * });
+     * ```
+     */
+    deployTemplate(templateId: string, inputs: Record<string, unknown>): Promise<string>;
+    /**
+     * List available workflow templates with optional filtering.
+     *
+     * @example
+     * ```typescript
+     * const templates = await client.listTemplates({ industry: 'legal', category: 'review' });
+     * ```
+     */
+    listTemplates(filter?: TemplateFilter): Promise<Template[]>;
+    /**
+     * Get the current status of a task, including progress and logs.
+     *
+     * @example
+     * ```typescript
+     * const status = await client.getTaskStatus('task-abc123');
+     * console.log(`${status.status} - ${status.progress}%`);
+     * ```
+     */
+    getTaskStatus(taskId: string): Promise<TaskStatus>;
+    /**
+     * List all registered worker nodes and their current state.
+     *
+     * @example
+     * ```typescript
+     * const workers = await client.getWorkers();
+     * const online = workers.filter(w => w.online);
+     * console.log(`${online.length}/${workers.length} workers online`);
+     * ```
+     */
+    getWorkers(): Promise<Worker[]>;
+    /**
+     * Subscribe to task completion events via polling. Returns an unsubscribe
+     * function.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.onTaskComplete((result) => {
+     *   console.log(`Task ${result.taskId} completed: ${result.status}`);
+     * });
+     *
+     * // Later, stop listening
+     * unsubscribe();
+     * ```
+     */
+    onTaskComplete(callback: TaskCompleteCallback): () => void;
+    /**
+     * Disconnect the client and clean up all background polling.
+     */
+    disconnect(): void;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,IAAI,EACJ,WAAW,EACX,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,MAAM,EACN,UAAU,EACV,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAcpB,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,UAAU,CAAC,EAAE,MAAM;aACnB,SAAS,CAAC,EAAE,MAAM;gBAHlC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,GAAE,MAA4B;CAIlD;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,gBAAgB,CAAkD;gBAE9D,OAAO,EAAE,oBAAoB;IAoBzC;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBvD;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBpE;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC;IAwDhD;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,KAAK,EAAE,SAAS,EAAE,EAClB,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,UAAU,EAAE,CAAC;IAqBxB;;;;;;;;;OASG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,EACzC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;;OAUG;IACG,mBAAmB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAUhD;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC;IAqBlB;;;;;;;OAOG;IACG,aAAa,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAejE;;;;;;;;OAQG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAYxD;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQrC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAsC1D;;OAEG;IACH,UAAU,IAAI,IAAI;YAWJ,OAAO;CAqFtB"}