@hotmeshio/long-tail 0.1.13 → 0.1.15

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
+  "bin": {
+    "ltc": "./build/bin/ltc.js"
+  },
   "homepage": "https://github.com/hotmeshio/long-tail/",
   "publishConfig": {
     "access": "public"
@@ -44,7 +47,11 @@
     "dashboard:build": "cd dashboard && npm run build",
     "dashboard:test": "cd dashboard && npm test",
     "dashboard:test:watch": "cd dashboard && npm run test:watch",
-    "build:all": "npm run build && npm run dashboard:build"
+    "ltc": "tsx bin/ltc.ts",
+    "build:all": "npm run build && npm run dashboard:build",
+    "release:patch": "npm version patch && git push && git push --tags",
+    "release:minor": "npm version minor && git push && git push --tags",
+    "release:major": "npm version major && git push && git push --tags"
   },
   "keywords": [
     "Long Tail Workflows",
@@ -61,19 +68,24 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.92.0",
     "@aws-sdk/client-s3": "^3.1017.0",
+    "@aws-sdk/s3-request-presigner": "^3.1045.0",
     "@hotmeshio/hotmesh": "^0.14.7",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",
     "@opentelemetry/sdk-node": "^0.215.0",
     "@opentelemetry/semantic-conventions": "^1.39.0",
+    "ajv": "^8.20.0",
     "arctic": "^3.7.0",
     "bcryptjs": "^2.4.3",
+    "commander": "^14.0.3",
     "express": "^5.1.0",
     "jsonwebtoken": "^9.0.3",
     "nats": "^2.28.0",
     "openai": "^5.9.0",
+    "ora": "^9.4.0",
     "pg": "^8.13.0",
+    "picocolors": "^1.1.1",
     "pino": "^9.6.0",
     "playwright": "^1.58.2",
     "sharp": "^0.34.5",
@@ -91,6 +103,7 @@
     "rimraf": "^4.4.1",
     "ts-node": "^10.9.1",
     "ts-node-dev": "^2.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.4",
     "vitest": "^3.2.4"
   }

package/build/api/escalations.d.ts

@@ -1,271 +0,0 @@
-import type { LTApiResult, LTApiAuth } from '../types/sdk';
-/**
- * Create a standalone escalation (not tied to a workflow).
- *
- * Useful for manual work items, support tickets, or approval requests
- * that originate outside the durable workflow engine. The caller must
- * hold the target role or be a superadmin.
- *
- * @param input.type — escalation category (e.g. `"support"`, `"approval"`)
- * @param input.subtype — subcategory for finer routing
- * @param input.role — role responsible for resolving this escalation
- * @param input.description — human-readable summary
- * @param input.priority — 1 (critical) through 4 (low), default 2
- * @param input.envelope — serialized context for the resolver
- * @param input.metadata — arbitrary key-value data (e.g. signal_routing)
- * @param input.escalation_payload — serialized payload for the resolver UI
- * @param auth — authenticated user context (must hold target role or be superadmin)
- * @returns `{ status: 201, data: <escalation record> }`
- */
-export declare function createEscalation(input: {
-    type: string;
-    subtype?: string;
-    role: string;
-    description?: string;
-    priority?: number;
-    envelope?: string;
-    metadata?: Record<string, any>;
-    escalation_payload?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * List escalations with optional filters.
- *
- * Results are scoped to the authenticated user's roles unless the user
- * is a superadmin (who sees all roles).
- *
- * @param input.status — filter by `pending`, `resolved`, or `cancelled`
- * @param input.role — filter by assigned role
- * @param input.type — filter by workflow type
- * @param input.subtype — filter by subtype
- * @param input.assigned_to — filter by assigned user ID
- * @param input.priority — filter by priority (1–4)
- * @param input.limit — max results (default: 50)
- * @param input.offset — pagination offset
- * @param input.sort_by — column to sort by (e.g. `created_at`, `priority`)
- * @param input.order — `asc` or `desc`
- * @param auth — authenticated user context (required for role scoping)
- * @returns `{ status: 200, data: { escalations, total } }`
- */
-export declare function listEscalations(input: {
-    status?: string;
-    role?: string;
-    type?: string;
-    subtype?: string;
-    assigned_to?: string;
-    priority?: number;
-    limit?: number;
-    offset?: number;
-    sort_by?: string;
-    order?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * List escalations available for claim (pending and not actively claimed).
- *
- * Similar to `listEscalations` but excludes escalations with active claims.
- * Scoped to the authenticated user's roles.
- *
- * @param input.role — filter by role
- * @param input.type — filter by workflow type
- * @param input.subtype — filter by subtype
- * @param input.priority — filter by priority (1–4)
- * @param input.limit — max results (default: 50)
- * @param input.offset — pagination offset
- * @param input.sort_by — column to sort by
- * @param input.order — `asc` or `desc`
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { escalations, total } }`
- */
-export declare function listAvailableEscalations(input: {
-    role?: string;
-    type?: string;
-    subtype?: string;
-    priority?: number;
-    limit?: number;
-    offset?: number;
-    sort_by?: string;
-    order?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * List all distinct escalation type values.
- *
- * @returns `{ status: 200, data: { types: string[] } }`
- */
-export declare function listDistinctTypes(): Promise<LTApiResult>;
-/**
- * Get aggregate escalation statistics scoped to the user's roles.
- *
- * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { pending, claimed, created, resolved, by_role, by_type } }`
- */
-export declare function getEscalationStats(input: {
-    period?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Get a single escalation by ID.
- *
- * Non-superadmin users must hold the escalation's assigned role.
- *
- * @param input.id — escalation UUID
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: <escalation record> }` or 403/404
- */
-export declare function getEscalation(input: {
-    id: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * List all escalations for a given workflow ID.
- *
- * @param input.workflowId — HotMesh workflow ID
- * @returns `{ status: 200, data: { escalations } }`
- */
-export declare function getEscalationsByWorkflowId(input: {
-    workflowId: string;
-}): Promise<LTApiResult>;
-/**
- * Route a pending escalation to a different role.
- *
- * The user must be authorized to escalate from the current role to the
- * target role (checked via escalation chain configuration).
- *
- * @param input.id — escalation UUID
- * @param input.targetRole — destination role
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: <updated escalation> }` or 403/404/409
- */
-export declare function escalateToRole(input: {
-    id: string;
-    targetRole: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Claim a pending escalation for the authenticated user.
- *
- * Sets `assigned_to` and `assigned_until` on the escalation (soft lock).
- * Non-superadmin users must hold the escalation's role. Publishes a
- * `escalation.claimed` event.
- *
- * @param input.id — escalation UUID
- * @param input.durationMinutes — claim duration (default: 30)
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { escalation, isExtension } }` or 403/404/409
- */
-export declare function claimEscalation(input: {
-    id: string;
-    durationMinutes?: number;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Release a claimed escalation back to the pool.
- *
- * Only the user who holds the claim can release it. Publishes a
- * `escalation.released` event.
- *
- * @param input.id — escalation UUID
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { escalation } }` or 409
- */
-export declare function releaseEscalation(input: {
-    id: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Release all escalation claims past their `assigned_until` deadline.
- *
- * Typically called on a maintenance schedule. Returns the count of
- * released claims.
- *
- * @returns `{ status: 200, data: { released: number } }`
- */
-export declare function releaseExpiredClaims(): Promise<LTApiResult>;
-/**
- * Update priority for one or more escalations.
- *
- * @param input.ids — array of escalation UUIDs
- * @param input.priority — new priority (1=critical, 2=high, 3=medium, 4=low)
- * @param auth — authenticated user context (admin or role-holder required)
- * @returns `{ status: 200, data: { updated: number } }`
- */
-export declare function updatePriority(input: {
-    ids: string[];
-    priority: number;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Claim multiple escalations at once for the authenticated user.
- *
- * @param input.ids — array of escalation UUIDs
- * @param input.durationMinutes — claim duration (default: 30)
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { claimed, skipped } }`
- */
-export declare function bulkClaim(input: {
-    ids: string[];
-    durationMinutes?: number;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Assign multiple escalations to a specific user.
- *
- * Non-superadmin callers must verify the target user holds each
- * escalation's role. Publishes claim events for assigned items.
- *
- * @param input.ids — array of escalation UUIDs
- * @param input.targetUserId — user to assign to
- * @param input.durationMinutes — assignment duration (default: 30)
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { assigned, skipped } }`
- */
-export declare function bulkAssign(input: {
-    ids: string[];
-    targetUserId: string;
-    durationMinutes?: number;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Route multiple escalations to a different role.
- *
- * @param input.ids — array of escalation UUIDs
- * @param input.targetRole — destination role
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { updated: number } }`
- */
-export declare function bulkEscalate(input: {
-    ids: string[];
-    targetRole: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Trigger AI triage for multiple escalations.
- *
- * Resolves each escalation and starts a triage workflow that uses MCP
- * tools to analyze and potentially auto-resolve the issue.
- *
- * @param input.ids — array of escalation UUIDs
- * @param input.hint — optional natural-language guidance for the triage AI
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { triaged, workflows } }`
- */
-export declare function bulkTriage(input: {
-    ids: string[];
-    hint?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
-/**
- * Resolve a pending escalation with a human-provided payload.
- *
- * Handles two resolution paths:
- * 1. **Signal-routed** — if the escalation has `signal_routing` metadata,
- *    the resolver payload is sent directly to the paused workflow via
- *    `handle.signal()`. Supports both Durable and YAML engines.
- * 2. **Re-run** — the original workflow is re-started with the resolver
- *    payload injected into `envelope.resolver`. The interceptor detects
- *    the re-run and skips to the resolution branch.
- *
- * Password fields in the resolver payload are replaced with ephemeral
- * tokens (15-minute TTL) so plaintext never enters the signal store.
- *
- * Supports optional escalation strategy execution after resolution.
- *
- * @param input.id — escalation UUID
- * @param input.resolverPayload — human decision data
- * @param auth — authenticated user context
- * @returns `{ status: 200, data: { signaled, escalationId, workflowId } }` (signal path)
- *          or `{ status: 200, data: { workflowId, resumed, escalationId } }` (re-run path)
- */
-export declare function resolveEscalation(input: {
-    id: string;
-    resolverPayload: Record<string, any>;
-}, auth: LTApiAuth): Promise<LTApiResult>;