roe-typescript 0.1.2 → 0.1.3

package/README.md

@@ -37,6 +37,31 @@ export ROE_API_KEY="your-api-key"
 export ROE_ORGANIZATION_ID="your-org-uuid"
 ```
 
+## Job Result Inspection
+
+After waiting for a job, you can inspect its outcome using status helpers:
+
+```typescript
+import { isJobSuccess, isJobFailure, isJobCancelled } from "roe-typescript";
+
+const result = await job.wait();
+
+if (isJobSuccess(result)) {
+  for (const output of result.outputs) {
+    console.log(`${output.key}: ${output.value}`);
+  }
+} else if (isJobCancelled(result)) {
+  console.log("Job was cancelled");
+} else if (isJobFailure(result)) {
+  console.log("Error:", result.error_message);
+}
+
+// Available fields
+result.status        // JobStatus enum value or null
+result.error_message // Error string or null
+result.outputs       // AgentDatum[]
+```
+
 ## Full Example
 
 Create an agent that extracts structured data from websites:

package/dist/api/agents.d.ts

@@ -34,6 +34,8 @@ export declare class AgentJobsAPI {
     retrieveStatusMany(jobIds: string[]): Promise<AgentJobStatusBatch[]>;
     retrieveResultMany(jobIds: string[]): Promise<AgentJobResultBatch[]>;
     downloadReference(jobId: string, resourceId: string, asAttachment?: boolean): Promise<Buffer>;
+    cancel(jobId: string): Promise<void>;
+    cancelAll(agentId: string): Promise<void>;
     deleteData(jobId: string): Promise<JobDataDeleteResponse>;
     private iterChunks;
 }
@@ -69,19 +71,22 @@ export declare class AgentsAPI {
         agentId: string;
         inputs: Record<string, unknown>;
         timeoutSeconds?: number;
+        metadata?: Record<string, unknown>;
     }): Promise<Job>;
     runMany(params: {
         agentId: string;
         batchInputs: Record<string, unknown>[];
         timeoutSeconds?: number;
+        metadata?: Record<string, unknown>;
     }): Promise<JobBatch>;
-    runSync(agentId: string, inputs: Record<string, unknown>): Promise<AgentDatum[]>;
+    runSync(agentId: string, inputs: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<AgentDatum[]>;
     runVersion(params: {
         agentId: string;
         versionId: string;
         inputs: Record<string, unknown>;
         timeoutSeconds?: number;
+        metadata?: Record<string, unknown>;
     }): Promise<Job>;
-    runVersionSync(agentId: string, versionId: string, inputs: Record<string, unknown>): Promise<AgentDatum[]>;
+    runVersionSync(agentId: string, versionId: string, inputs: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<AgentDatum[]>;
     private iterChunks;
 }

package/dist/api/agents.js

@@ -116,10 +116,18 @@ export class AgentJobsAPI {
     }
     async downloadReference(jobId, resourceId, asAttachment = false) {
         validateUuid(jobId, "jobId");
-        validateUuid(resourceId, "resourceId");
+        // resourceId is a filename/identifier, not a UUID — no validation needed
         const params = asAttachment ? { download: "true" } : undefined;
         return this.http.getBytes(`/v1/agents/jobs/${jobId}/references/${resourceId}/`, params);
     }
+    async cancel(jobId) {
+        validateUuid(jobId, "jobId");
+        await this.http.post({ url: `/v1/agents/jobs/${jobId}/cancel/` });
+    }
+    async cancelAll(agentId) {
+        validateUuid(agentId, "agentId");
+        await this.http.post({ url: `/v1/agents/${agentId}/jobs/cancel-all/` });
+    }
     async deleteData(jobId) {
         validateUuid(jobId, "jobId");
         return this.http.post({
@@ -196,7 +204,7 @@ export class AgentsAPI {
     }
     async run(params) {
         validateUuid(params.agentId, "agentId");
-        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/async/`, params.inputs);
+        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/async/`, params.inputs, undefined, params.metadata);
         // Handle both string response and object response formats
         const jobId = typeof response === "string" ? response : response?.job_id;
         if (!jobId || typeof jobId !== "string") {
@@ -213,9 +221,12 @@ export class AgentsAPI {
         for (const chunk of this.iterChunks(params.batchInputs, AgentsAPI.MAX_BATCH_SIZE)) {
             if (!chunk.length)
                 continue;
+            const json = { inputs: chunk };
+            if (params.metadata !== undefined)
+                json.metadata = params.metadata;
             const resp = await this.httpClient.post({
                 url: `/v1/agents/run/${params.agentId}/async/many/`,
-                json: { inputs: chunk },
+                json,
             });
             // Validate each returned job ID
             for (const jobId of resp) {
@@ -230,15 +241,15 @@ export class AgentsAPI {
         }
         return new JobBatch({ agentsApi: this, jobIds: allJobIds, timeoutSeconds: params.timeoutSeconds });
     }
-    async runSync(agentId, inputs) {
+    async runSync(agentId, inputs, metadata) {
         validateUuid(agentId, "agentId");
-        const resp = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/`, inputs);
+        const resp = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/`, inputs, undefined, metadata);
         return resp;
     }
     async runVersion(params) {
         validateUuid(params.agentId, "agentId");
         validateUuid(params.versionId, "versionId");
-        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/versions/${params.versionId}/async/`, params.inputs);
+        const response = await this.httpClient.postWithDynamicInputs(`/v1/agents/run/${params.agentId}/versions/${params.versionId}/async/`, params.inputs, undefined, params.metadata);
         // Handle both string response and object response formats
         const jobId = typeof response === "string" ? response : response?.job_id;
         if (!jobId || typeof jobId !== "string") {
@@ -249,10 +260,10 @@ export class AgentsAPI {
         }
         return new Job({ agentsApi: this, jobId, timeoutSeconds: params.timeoutSeconds });
     }
-    async runVersionSync(agentId, versionId, inputs) {
+    async runVersionSync(agentId, versionId, inputs, metadata) {
         validateUuid(agentId, "agentId");
         validateUuid(versionId, "versionId");
-        return this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/versions/${versionId}/`, inputs);
+        return this.httpClient.postWithDynamicInputs(`/v1/agents/run/${agentId}/versions/${versionId}/`, inputs, undefined, metadata);
     }
     *iterChunks(items, size) {
         for (let i = 0; i < items.length; i += size) {

package/dist/models/job.d.ts

@@ -22,7 +22,7 @@ export declare class JobBatch {
     private readonly jobIds;
     private readonly timeoutSeconds;
     private completed;
-    private statusCache;
+    private statuses;
     constructor(opts: {
         agentsApi: AgentsAPI;
         jobIds: string[];
@@ -33,5 +33,5 @@ export declare class JobBatch {
         intervalSeconds?: number;
         timeoutSeconds?: number;
     }): Promise<AgentJobResult[]>;
-    retrieveStatus(): Promise<Record<string, number>>;
+    retrieveStatus(): Promise<Record<string, AgentJobStatus>>;
 }

package/dist/models/job.js

@@ -20,11 +20,30 @@ export class Job {
         while (true) {
             const status = await this.retrieveStatus();
             const code = status.status;
-            if (code === JobStatus.SUCCESS || code === JobStatus.CACHED) {
-                return this.retrieveResult();
-            }
-            if (code === JobStatus.FAILURE || code === JobStatus.CANCELLED) {
-                throw new Error(`Job ${this.jobId} failed with status ${code}${status.error_message ? `: ${status.error_message}` : ""}`);
+            if (code === JobStatus.SUCCESS ||
+                code === JobStatus.CACHED ||
+                code === JobStatus.FAILURE ||
+                code === JobStatus.CANCELLED) {
+                const isFailed = code === JobStatus.FAILURE || code === JobStatus.CANCELLED;
+                let result;
+                try {
+                    result = await this.retrieveResult();
+                }
+                catch (err) {
+                    if (!isFailed)
+                        throw err;
+                    result = {
+                        agent_id: "",
+                        agent_version_id: "",
+                        inputs: [],
+                        outputs: [],
+                        input_tokens: null,
+                        output_tokens: null,
+                    };
+                }
+                result.status = code;
+                result.error_message = status.error_message ?? null;
+                return result;
             }
             if (Date.now() - start > timeoutSeconds * 1000) {
                 throw new Error(`Job ${this.jobId} did not complete within ${timeoutSeconds} seconds`);
@@ -42,7 +61,7 @@ export class Job {
 export class JobBatch {
     constructor(opts) {
         this.completed = {};
-        this.statusCache = {};
+        this.statuses = {};
         this.agentsApi = opts.agentsApi;
         this.jobIds = opts.jobIds;
         this.timeoutSeconds = opts.timeoutSeconds ?? 7200;
@@ -64,45 +83,86 @@ export class JobBatch {
             if (!pending.length)
                 break;
             const statusBatch = await this.agentsApi.jobs.retrieveStatusMany(pending);
-            const failures = statusBatch.filter((s) => s.status === JobStatus.FAILURE || s.status === JobStatus.CANCELLED);
-            if (failures.length) {
-                const detail = failures.map((f) => `${f.id}:${f.status ?? "unknown"}`).join(', ');
-                throw new Error(`Jobs failed or cancelled: ${detail}`);
-            }
             const completedIds = [];
             for (const status of statusBatch) {
                 const code = status.status;
-                if (code === JobStatus.SUCCESS || code === JobStatus.CACHED) {
+                if (code === JobStatus.SUCCESS ||
+                    code === JobStatus.CACHED ||
+                    code === JobStatus.FAILURE ||
+                    code === JobStatus.CANCELLED) {
                     completedIds.push(status.id);
                 }
                 if (code !== undefined && code !== null) {
-                    this.statusCache[status.id] = code;
+                    this.statuses[status.id] = {
+                        status: code,
+                        timestamp: status.timestamp ?? null,
+                        error_message: status.error_message ?? null,
+                    };
                 }
             }
             if (completedIds.length) {
-                const resultBatch = await this.agentsApi.jobs.retrieveResultMany(completedIds);
+                let resultBatch;
+                try {
+                    resultBatch = await this.agentsApi.jobs.retrieveResultMany(completedIds);
+                }
+                catch (err) {
+                    // Only synthesize for failed/cancelled — can't fake results for success/cached
+                    const failedIds = completedIds.filter((id) => {
+                        const s = this.statuses[id]?.status;
+                        return s === JobStatus.FAILURE || s === JobStatus.CANCELLED;
+                    });
+                    if (failedIds.length < completedIds.length) {
+                        // Some successful jobs had their results lost — must propagate
+                        throw err;
+                    }
+                    resultBatch = failedIds.map((id) => ({
+                        id,
+                        status: this.statuses[id]?.status ?? null,
+                        agent_id: null,
+                        agent_version_id: null,
+                        inputs: null,
+                        result: null,
+                        corrected_outputs: null,
+                        input_tokens: null,
+                        output_tokens: null,
+                    }));
+                }
                 for (const res of resultBatch) {
+                    const jobStatus = res.status ?? this.statuses[res.id]?.status ?? null;
+                    const isFailed = jobStatus === JobStatus.FAILURE || jobStatus === JobStatus.CANCELLED;
                     if (!res.agent_id || !res.agent_version_id) {
-                        const id = res.id ?? 'unknown';
-                        throw new Error(`Job ${id} missing agent identifiers`);
+                        if (!isFailed) {
+                            const id = res.id ?? 'unknown';
+                            throw new Error(`Job ${id} missing agent identifiers`);
+                        }
                     }
                     // Use corrected_outputs as fallback if result is null/undefined
-                    const outputs = res.result ?? res.corrected_outputs;
-                    if (outputs == null) {
-                        // Both result and corrected_outputs are null - this may indicate an error or incomplete job
-                        throw new Error(`Job ${res.id} returned null or undefined result`);
+                    const rawOutputs = res.result ?? res.corrected_outputs;
+                    let outputs;
+                    if (rawOutputs == null) {
+                        if (!isFailed) {
+                            throw new Error(`Job ${res.id} returned null or undefined result`);
+                        }
+                        outputs = [];
                     }
-                    if (!Array.isArray(outputs)) {
-                        // Result exists but is not an array - unexpected format
-                        throw new Error(`Job ${res.id} returned unexpected result format: ${typeof outputs}`);
+                    else if (!Array.isArray(rawOutputs)) {
+                        if (!isFailed) {
+                            throw new Error(`Job ${res.id} returned unexpected result format: ${typeof rawOutputs}`);
+                        }
+                        outputs = [];
+                    }
+                    else {
+                        outputs = rawOutputs;
                     }
                     this.completed[res.id] = {
-                        agent_id: res.agent_id,
-                        agent_version_id: res.agent_version_id,
+                        agent_id: res.agent_id ?? "",
+                        agent_version_id: res.agent_version_id ?? "",
                         inputs: res.inputs ?? [],
                         input_tokens: res.input_tokens,
                         output_tokens: res.output_tokens,
                         outputs,
+                        status: jobStatus,
+                        error_message: this.statuses[res.id]?.error_message ?? null,
                     };
                 }
             }
@@ -117,14 +177,29 @@ export class JobBatch {
         return this.jobIds.map((id) => this.completed[id]);
     }
     async retrieveStatus() {
-        const statusMap = { ...this.statusCache };
-        const toQuery = this.jobIds.filter((id) => statusMap[id] === undefined);
+        const statusMap = {};
+        const toQuery = [];
+        const TERMINAL = new Set([JobStatus.SUCCESS, JobStatus.CACHED, JobStatus.FAILURE, JobStatus.CANCELLED]);
+        for (const id of this.jobIds) {
+            const cached = this.statuses[id];
+            if (cached !== undefined && TERMINAL.has(cached.status)) {
+                statusMap[id] = cached;
+            }
+            else {
+                toQuery.push(id);
+            }
+        }
         if (toQuery.length) {
-            const statuses = await this.agentsApi.jobs.retrieveStatusMany(toQuery);
-            for (const s of statuses) {
+            const batchStatuses = await this.agentsApi.jobs.retrieveStatusMany(toQuery);
+            for (const s of batchStatuses) {
                 if (s.status !== undefined && s.status !== null) {
-                    statusMap[s.id] = s.status;
-                    this.statusCache[s.id] = s.status;
+                    const js = {
+                        status: s.status,
+                        timestamp: s.timestamp ?? null,
+                        error_message: s.error_message ?? null,
+                    };
+                    this.statuses[s.id] = js;
+                    statusMap[s.id] = js;
                 }
             }
         }

package/dist/models/responses.d.ts

@@ -26,7 +26,7 @@ export type PaginatedResponse<T> = {
 };
 export type AgentJobStatus = {
     status: number;
-    timestamp: number;
+    timestamp: number | null;
     error_message?: string | null;
 };
 export type Reference = {
@@ -43,12 +43,22 @@ export type AgentJobResult = {
     input_tokens?: number | null;
     output_tokens?: number | null;
     outputs: AgentDatum[];
+    status?: number | null;
+    error_message?: string | null;
 };
+/** Returns true if the job status is SUCCESS or CACHED. */
+export declare function isJobSuccess(result: AgentJobResult): boolean;
+/** Returns true if the job status is FAILURE or CANCELLED (any non-success terminal state). */
+export declare function isJobFailure(result: AgentJobResult): boolean;
+/** Returns true if the job status is specifically CANCELLED. */
+export declare function isJobCancelled(result: AgentJobResult): boolean;
 export type AgentJobStatusBatch = {
     id: string;
     status?: number | null;
     created_at?: unknown;
     last_updated_at?: unknown;
+    timestamp?: number | null;
+    error_message?: string | null;
 };
 export type AgentJobResultBatch = {
     id: string;

package/dist/models/responses.js

@@ -34,3 +34,15 @@ export function extractReferencesFromOutputs(outputs) {
 export function getJobReferences(result) {
     return extractReferencesFromOutputs(result.outputs ?? []);
 }
+/** Returns true if the job status is SUCCESS or CACHED. */
+export function isJobSuccess(result) {
+    return result.status === JobStatus.SUCCESS || result.status === JobStatus.CACHED;
+}
+/** Returns true if the job status is FAILURE or CANCELLED (any non-success terminal state). */
+export function isJobFailure(result) {
+    return result.status === JobStatus.FAILURE || result.status === JobStatus.CANCELLED;
+}
+/** Returns true if the job status is specifically CANCELLED. */
+export function isJobCancelled(result) {
+    return result.status === JobStatus.CANCELLED;
+}

package/dist/utils/httpClient.d.ts

@@ -26,5 +26,5 @@ export declare class RoeHTTPClient {
     private executeWithFormData;
     put<T>(url: string, json?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
     delete(url: string, params?: Record<string, unknown>): Promise<void>;
-    postWithDynamicInputs<T>(url: string, inputs: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
+    postWithDynamicInputs<T>(url: string, inputs: Record<string, unknown>, params?: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<T>;
 }

package/dist/utils/httpClient.js

@@ -196,7 +196,7 @@ export class RoeHTTPClient {
     delete(url, params) {
         return this.execute(() => this.client.delete(url, { params }));
     }
-    async postWithDynamicInputs(url, inputs, params) {
+    async postWithDynamicInputs(url, inputs, params, metadata) {
         const formData = {};
         const files = {};
         // Process inputs and detect file paths asynchronously
@@ -224,6 +224,9 @@ export class RoeHTTPClient {
                 formData[key] = value;
             }
         }
+        if (metadata !== undefined) {
+            formData.metadata = JSON.stringify(metadata);
+        }
         return this.post({ url, formData, files, params });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roe-typescript",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "TypeScript SDK for the Roe AI API (feature parity with roe-python).",
   "type": "module",
   "main": "dist/index.js",