@butlerbot/sdk 0.0.38 → 0.0.40

package/dist/config.d.ts

@@ -60,7 +60,7 @@ export declare const CONFIG: {
             };
         };
         jobs: {
-            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel` and its resume `${base}/${jobId}/resume`. */
             base: string;
             /** The owner's job settings, which live on the user rather than on a job. */
             settings: string;

package/dist/config.js

@@ -52,7 +52,7 @@ exports.CONFIG = {
             }
         },
         jobs: {
-            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel` and its resume `${base}/${jobId}/resume`. */
             base: "/api/jobs",
             /** The owner's job settings, which live on the user rather than on a job. */
             settings: "/api/user/jobs-settings",

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { APIPath } from "./config";
 import { Link, LinkOptions } from "./link";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
-import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type SetPhaseModelOptions, type ListJobsOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
+import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type SetPhaseModelOptions, type ListJobsOptions, type ResumeJobOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
 import { type AnswerDeliveryOptions, type ListDeliveriesOptions } from "./modules/outreach";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
     /** Optional API key, defaults to API key specified in client */
@@ -52,7 +52,9 @@ export declare class ButlerBotClient {
     getJobJournal(config: OptionalApiKey<GetJobJournalOptions>): Promise<import("./types/type_registry").JobJournalPage>;
     /** Stops a job. Throws a `ButlerBotAPIError` with `isConflict` when it had already finished */
     cancelJob(config: OptionalApiKey<CancelJobOptions>): Promise<import("./types/type_registry").JobCancelResponse>;
-    /** Changes one job's name, and its autonomy: how far it may act, until when, and what it always asks about */
+    /** Continues a job parked waiting for budget. Throws a `ButlerBotAPIError` with `isConflict` when it is in any other status */
+    resumeJob(config: OptionalApiKey<ResumeJobOptions>): Promise<import("./types/type_registry").JobResumeResponse>;
+    /** Changes one job's name, the model it runs on, its spending cap and its autonomy: how far it may act, until when, and what it always asks about */
     updateJob(config: OptionalApiKey<UpdateJobOptions>): Promise<import("./types/type_registry").JobUpdateResponse>;
     /** Changes the model one phase of a job's plan runs on; only a phase that has not started */
     setPhaseModel(config: OptionalApiKey<SetPhaseModelOptions>): Promise<import("./types/type_registry").JobPhaseModelResponse>;
@@ -72,8 +74,8 @@ export type { ConversationOptions };
 export type { APIPath };
 export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
 export { ButlerBotAPIError } from "./util/api_error";
-export { listJobs, getJob, cancelJob, updateJob, updateJobSettings } from "./modules/jobs";
-export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, UpdateJobOptions, UpdateJobSettingsOptions, } from "./modules/jobs";
+export { listJobs, getJob, cancelJob, resumeJob, updateJob, updateJobSettings } from "./modules/jobs";
+export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, ResumeJobOptions, UpdateJobOptions, UpdateJobSettingsOptions, } from "./modules/jobs";
 export { listDeliveries, answerDelivery } from "./modules/outreach";
 export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptions, } from "./modules/outreach";
 export { LinkConversationTransport } from "./modules/transport_link";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
+exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
 const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
@@ -88,7 +88,11 @@ class ButlerBotClient {
     cancelJob(config) {
         return (0, jobs_1.cancelJob)(this.forRequest(config));
     }
-    /** Changes one job's name, and its autonomy: how far it may act, until when, and what it always asks about */
+    /** Continues a job parked waiting for budget. Throws a `ButlerBotAPIError` with `isConflict` when it is in any other status */
+    resumeJob(config) {
+        return (0, jobs_1.resumeJob)(this.forRequest(config));
+    }
+    /** Changes one job's name, the model it runs on, its spending cap and its autonomy: how far it may act, until when, and what it always asks about */
     updateJob(config) {
         return (0, jobs_1.updateJob)(this.forRequest(config));
     }
@@ -123,6 +127,7 @@ var jobs_2 = require("./modules/jobs");
 Object.defineProperty(exports, "listJobs", { enumerable: true, get: function () { return jobs_2.listJobs; } });
 Object.defineProperty(exports, "getJob", { enumerable: true, get: function () { return jobs_2.getJob; } });
 Object.defineProperty(exports, "cancelJob", { enumerable: true, get: function () { return jobs_2.cancelJob; } });
+Object.defineProperty(exports, "resumeJob", { enumerable: true, get: function () { return jobs_2.resumeJob; } });
 Object.defineProperty(exports, "updateJob", { enumerable: true, get: function () { return jobs_2.updateJob; } });
 Object.defineProperty(exports, "updateJobSettings", { enumerable: true, get: function () { return jobs_2.updateJobSettings; } });
 var outreach_2 = require("./modules/outreach");

package/dist/modules/jobs.d.ts

@@ -1,4 +1,4 @@
-import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobJournalPage, JobListResponse, JobPhaseModelResponse, JobSettingsResponse, JobSettingsUpdate, JobStatus, JobUpdateResponse } from "../types/jobs";
+import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobJournalPage, JobListResponse, JobPhaseModelResponse, JobResumeResponse, JobSettingsResponse, JobSettingsUpdate, JobStatus, JobUpdateResponse } from "../types/jobs";
 /** What every jobs call needs: where the server is, and who is asking. */
 export type JobsRequestOptions = {
     serverURL?: string;
@@ -28,6 +28,9 @@ export type GetJobJournalOptions = JobsRequestOptions & {
 export type CancelJobOptions = JobsRequestOptions & {
     jobId: string;
 };
+export type ResumeJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
 export type UpdateJobOptions = JobsRequestOptions & {
     jobId: string;
     /** A new short name for the job, a few words at most. */
@@ -40,6 +43,13 @@ export type UpdateJobOptions = JobsRequestOptions & {
     alwaysAsk?: string[];
     /** A ceiling on what the job may spend in all, in dollars. Null clears it. */
     capUsd?: number | null;
+    /**
+     * The model or alias the whole job runs on, and the plan's default.
+     *
+     * A name sets it; null clears it, leaving the planner to pick a model per phase. One
+     * phase's model on its own is `setPhaseModel`.
+     */
+    model?: string | null;
 };
 export type SetPhaseModelOptions = JobsRequestOptions & {
     jobId: string;
@@ -62,7 +72,16 @@ export declare function getJobJournal(options: GetJobJournalOptions): Promise<Jo
  * `isConflict` is true and whose `body` still carries the job as it stands.
  */
 export declare function cancelJob(options: CancelJobOptions): Promise<JobCancelResponse>;
-/** Changes one job's name, and its autonomy: how far it may act, until when, and what it always asks about. */
+/**
+ * Continues a job that is parked waiting for budget, when there is room for it again.
+ *
+ * The answer says what happened either way: `resumed` is the job queued again, and otherwise
+ * `reason`, `action` and `message` say why it is still parked and what would change that. A
+ * job in any other status is a 409: the call throws a `ButlerBotAPIError` whose `isConflict`
+ * is true and whose `body` still carries the job as it stands.
+ */
+export declare function resumeJob(options: ResumeJobOptions): Promise<JobResumeResponse>;
+/** Changes one job's name, the model it runs on, its spending cap and its autonomy: how far it may act, until when, and what it always asks about. */
 export declare function updateJob(options: UpdateJobOptions): Promise<JobUpdateResponse>;
 /**
  * Changes the model one phase of a job's plan runs on.

package/dist/modules/jobs.js

@@ -4,6 +4,7 @@ exports.listJobs = listJobs;
 exports.getJob = getJob;
 exports.getJobJournal = getJobJournal;
 exports.cancelJob = cancelJob;
+exports.resumeJob = resumeJob;
 exports.updateJob = updateJob;
 exports.setPhaseModel = setPhaseModel;
 exports.updateJobSettings = updateJobSettings;
@@ -51,13 +52,25 @@ async function cancelJob(options) {
     const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}/cancel`, {}, { apiKey: options.apiKey, debug: options.debug });
     return (0, api_request_1.requestAPI)({ url, method: "POST", action: `cancel job ${options.jobId}` });
 }
-/** Changes one job's name, and its autonomy: how far it may act, until when, and what it always asks about. */
+/**
+ * Continues a job that is parked waiting for budget, when there is room for it again.
+ *
+ * The answer says what happened either way: `resumed` is the job queued again, and otherwise
+ * `reason`, `action` and `message` say why it is still parked and what would change that. A
+ * job in any other status is a 409: the call throws a `ButlerBotAPIError` whose `isConflict`
+ * is true and whose `body` still carries the job as it stands.
+ */
+async function resumeJob(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}/resume`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, method: "POST", action: `resume job ${options.jobId}` });
+}
+/** Changes one job's name, the model it runs on, its spending cap and its autonomy: how far it may act, until when, and what it always asks about. */
 async function updateJob(options) {
     const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}`, {}, { apiKey: options.apiKey, debug: options.debug });
     return (0, api_request_1.requestAPI)({
         url,
         method: "PATCH",
-        body: body({ title: options.title, autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk, capUsd: options.capUsd }),
+        body: body({ title: options.title, autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk, capUsd: options.capUsd, model: options.model }),
         action: `update job ${options.jobId}`,
     });
 }

package/dist/types/jobs/job.d.ts

@@ -52,6 +52,13 @@ export type JobView = {
     journalCardUri: string | null;
     /** The chat the job was asked for in, and where it reports back. */
     originConversationId: string | null;
+    /**
+     * The model or alias the user asked the whole job to run on, and the plan's default.
+     *
+     * Null when nobody chose one, in which case the planner picks a model per phase. A phase's
+     * own `model` is what that phase actually runs on either way.
+     */
+    model: string | null;
     /** What was chosen for this job, or null when nothing was. */
     autonomy: JobAutonomy | null;
     /** When `autonomy` lapses back to asking, in UTC milliseconds. */
@@ -220,3 +227,29 @@ export type JobSettingsResponse = {
     success: true;
     jobs: JobSettings;
 };
+/**
+ * Why a resume answered as it did.
+ *
+ * `resumed` is the job queued again; the rest are why it was left where it is — the owner's
+ * tier does not allow the job to run, today's allowance is spent, or the server refused for a
+ * reason of its own.
+ */
+export type JobResumeReason = "resumed" | "over_tier_limit" | "allowance_spent" | "refused";
+/** What the user can do about a job that was not resumed. */
+export type JobResumeAction = "raise_allowance" | "upgrade_tier" | "wait";
+/**
+ * A job after a resume was asked for.
+ *
+ * `resumed` says whether it is queued again; when it is not, `reason` and `action` say why and
+ * what would change it, and `wakeAt` is the earliest the runner would pick it up on its own,
+ * in epoch milliseconds. `message` is the same thing in a sentence or two, ready to show.
+ */
+export type JobResumeResponse = {
+    success: true;
+    resumed: boolean;
+    reason: JobResumeReason;
+    action?: JobResumeAction;
+    wakeAt?: number;
+    message: string;
+    job: JobView;
+};

package/dist/types/outreach/delivery.d.ts

@@ -31,6 +31,14 @@ export type DeliverySurface = {
 export declare const DELIVERY_ANSWER_VIA: readonly ["web", "discord", "chat", "tool"];
 /** Which surface the answer came back on. */
 export type DeliveryAnsweredVia = typeof DELIVERY_ANSWER_VIA[number];
+export declare const DELIVERY_CLOSED_REASONS: readonly ["job_done", "job_failed", "job_cancelled"];
+/** Why a delivery was closed with nobody having answered it: what became of the job that asked. */
+export type DeliveryClosedReason = typeof DELIVERY_CLOSED_REASONS[number];
+/** A delivery closed unanswered, and when. */
+export type DeliveryClosed = {
+    at: number;
+    reason: DeliveryClosedReason;
+};
 export type DeliveryAnswer = {
     at: number;
     text: string;
@@ -54,9 +62,16 @@ export type Delivery = {
     surfaces: DeliverySurface[];
     /** Null until somebody answers. Only ever set once. */
     answered: DeliveryAnswer | null;
+    /**
+     * Set when the job this belonged to ended before anyone answered, and null otherwise.
+     *
+     * A closed delivery is no longer open, and answering it is refused: the server answers a
+     * 409 the same way it does one already answered.
+     */
+    closed: DeliveryClosed | null;
     created: number;
 };
-/** Whether a delivery is still waiting on the user. */
+/** Whether a delivery is still waiting on the user: unanswered, and not closed under it. */
 export declare function isDeliveryOpen(delivery: Delivery): boolean;
 export type DeliveryListResponse = {
     success: true;

package/dist/types/outreach/delivery.js

@@ -7,7 +7,7 @@
  * on that job's inbox.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DELIVERY_ANSWER_VIA = exports.DELIVERY_SURFACE_STATUSES = exports.DELIVERY_SURFACES = exports.ANSWERABLE_DELIVERY_INTENTS = exports.DELIVERY_INTENTS = void 0;
+exports.DELIVERY_CLOSED_REASONS = exports.DELIVERY_ANSWER_VIA = exports.DELIVERY_SURFACE_STATUSES = exports.DELIVERY_SURFACES = exports.ANSWERABLE_DELIVERY_INTENTS = exports.DELIVERY_INTENTS = void 0;
 exports.isDeliveryOpen = isDeliveryOpen;
 exports.DELIVERY_INTENTS = ["question", "update", "approval", "statement"];
 /** The intents that leave something outstanding until the user answers. */
@@ -15,7 +15,8 @@ exports.ANSWERABLE_DELIVERY_INTENTS = ["question", "approval"];
 exports.DELIVERY_SURFACES = ["web", "discord"];
 exports.DELIVERY_SURFACE_STATUSES = ["pending", "sent", "failed"];
 exports.DELIVERY_ANSWER_VIA = ["web", "discord", "chat", "tool"];
-/** Whether a delivery is still waiting on the user. */
+exports.DELIVERY_CLOSED_REASONS = ["job_done", "job_failed", "job_cancelled"];
+/** Whether a delivery is still waiting on the user: unanswered, and not closed under it. */
 function isDeliveryOpen(delivery) {
-    return exports.ANSWERABLE_DELIVERY_INTENTS.includes(delivery.intent) && !delivery.answered;
+    return exports.ANSWERABLE_DELIVERY_INTENTS.includes(delivery.intent) && !delivery.answered && !delivery.closed;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.38",
+	"version": "0.0.40",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -335,14 +335,22 @@ const { entries, hasMore } = await client.getJobJournal({ jobId, page: 2 });
 await client.updateJob({ jobId, title: "Flat hunt", autonomy: "free", autonomyUntil: Date.now() + 86_400_000, capUsd: 5 });
 await client.setPhaseModel({ jobId, phaseId: "search", model: "Butler-Auto-Smart" });
 await client.cancelJob({ jobId });
+const { resumed, reason, action, message } = await client.resumeJob({ jobId });
 ```
 
 `getJob` carries the newest page of the journal and `journalTotal`; `getJobJournal` pages the rest,
 newest page first, with each page in the order its entries were written and `hasMore` saying whether
 an older page exists. Each entry says which shift wrote it (`shiftIndex`, `shiftKind`) and on which
 model. A job's `title` is a few words of its own, set at start or renamed with `updateJob`, which
-also takes `capUsd`, a ceiling on what the job may spend in all (null clears it). `setPhaseModel`
-changes the model a phase that has not started runs on, to one of the detail's `phaseModels`.
+also takes `capUsd`, a ceiling on what the job may spend in all (null clears it), and `model`, the
+model or alias the whole job runs on and the plan's default — a name sets it, null clears it and
+leaves the planner to pick per phase, and a job's own `model` reads back the same way.
+`setPhaseModel` changes the model one phase that has not started runs on, to one of the detail's
+`phaseModels`.
+`resumeJob` continues a job parked as `waiting_budget` when there is room for it again: it answers
+with `resumed`, a `reason` of `resumed`, `over_tier_limit`, `allowance_spent` or `refused`, an
+`action` of `raise_allowance`, `upgrade_tier` or `wait` when there is one, a `wakeAt` when the job
+would carry on by itself, and a `message` written for the user. A job in any other status is a 409.
 
 Paging is 1-based, and every listing answers with `page`, `limit` and `total`. A listing also
 carries `allowance` — what this user's jobs may spend today and what is left of it, or
@@ -373,6 +381,10 @@ Answering closes the delivery, and when it belongs to a job the answer is put on
 inbox, which wakes a job that was parked waiting for it — `job.delivered` says what became of
 it. An approval takes `decision: "approve" | "deny"` alongside the text.
 
+A delivery whose job ended before anyone answered is closed instead: `closed` carries the time
+and a reason of `job_done`, `job_failed` or `job_cancelled`. `isDeliveryOpen` reads false for
+one, and answering it is refused with a 409 just as one already answered is.
+
 ### When a call fails
 
 Every jobs and outreach call throws `ButlerBotAPIError` when the server does not answer with a