@butlerbot/sdk 0.0.34 → 0.0.35

package/dist/config.d.ts

@@ -59,6 +59,16 @@ export declare const CONFIG: {
                 };
             };
         };
+        jobs: {
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            base: string;
+            /** The owner's job settings, which live on the user rather than on a job. */
+            settings: string;
+        };
+        outreach: {
+            /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
+            base: string;
+        };
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;

package/dist/config.js

@@ -50,6 +50,16 @@ exports.CONFIG = {
             policy: {
                 v3: { base: "/api/user/usage/v3/policy" },
             }
+        },
+        jobs: {
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            base: "/api/jobs",
+            /** The owner's job settings, which live on the user rather than on a job. */
+            settings: "/api/user/jobs-settings",
+        },
+        outreach: {
+            /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
+            base: "/api/outreach",
         }
     }
 };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { APIPath } from "./config";
 import { Link, LinkOptions } from "./link";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
+import { type CancelJobOptions, type GetJobOptions, type ListJobsOptions, 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 */
     apiKey?: string;
@@ -42,6 +44,22 @@ export declare class ButlerBotClient {
     createLink(config: OptionalApiKey<LinkOptions>): Link;
     /** Get current usage policy data */
     getUsagePolicyData(config: OptionalApiKey<UsagePolicyDataOptions>): Promise<import("./types/usage/policy").UsagePolicyData>;
+    /** A page of this user's jobs, with what their jobs may spend today */
+    listJobs(config?: OptionalApiKey<ListJobsOptions>): Promise<import("./types/type_registry").JobListResponse>;
+    /** One job, with its plan, its journal and the questions waiting on the user */
+    getJob(config: OptionalApiKey<GetJobOptions>): Promise<import("./types/type_registry").JobDetailResponse>;
+    /** 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 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 this user's job settings: their daily allowance and what new jobs start with */
+    updateJobSettings(config?: OptionalApiKey<UpdateJobSettingsOptions>): Promise<import("./types/type_registry").JobSettingsResponse>;
+    /** A page of the inbox: what Alfred has told or asked this user outside a chat */
+    listDeliveries(config?: OptionalApiKey<ListDeliveriesOptions>): Promise<import("./types/type_registry").DeliveryListResponse>;
+    /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
+    answerDelivery(config: OptionalApiKey<AnswerDeliveryOptions>): Promise<import("./types/type_registry").DeliveryAnswerResponse>;
+    /** The client's own server and key underneath whatever the call named itself. */
+    private forRequest;
 }
 export * from "./types/type_registry";
 export * from "./link";
@@ -49,6 +67,11 @@ export { Conversation };
 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 { listDeliveries, answerDelivery } from "./modules/outreach";
+export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptions, } from "./modules/outreach";
 export { LinkConversationTransport } from "./modules/transport_link";
 export { SSEConversationTransport } from "./modules/transport_sse";
 export type { SteerResult, TurnStopMode, TurnStopped } from "./modules/transport";

package/dist/index.js

@@ -14,12 +14,14 @@ 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.Conversation = exports.ButlerBotClient = void 0;
+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;
 const config_1 = require("./config");
 const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
 const usage_1 = require("./modules/usage");
+const jobs_1 = require("./modules/jobs");
+const outreach_1 = require("./modules/outreach");
 /**
  * The options a caller actually gave, with the keys they left out removed.
  *
@@ -70,11 +72,54 @@ class ButlerBotClient {
     getUsagePolicyData(config) {
         return (0, usage_1.getUsagePolicyData)({ serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...config });
     }
+    /** A page of this user's jobs, with what their jobs may spend today */
+    listJobs(config = {}) {
+        return (0, jobs_1.listJobs)(this.forRequest(config));
+    }
+    /** One job, with its plan, its journal and the questions waiting on the user */
+    getJob(config) {
+        return (0, jobs_1.getJob)(this.forRequest(config));
+    }
+    /** Stops a job. Throws a `ButlerBotAPIError` with `isConflict` when it had already finished */
+    cancelJob(config) {
+        return (0, jobs_1.cancelJob)(this.forRequest(config));
+    }
+    /** Changes one job's autonomy: how far it may act, until when, and what it always asks about */
+    updateJob(config) {
+        return (0, jobs_1.updateJob)(this.forRequest(config));
+    }
+    /** Changes this user's job settings: their daily allowance and what new jobs start with */
+    updateJobSettings(config = {}) {
+        return (0, jobs_1.updateJobSettings)(this.forRequest(config));
+    }
+    /** A page of the inbox: what Alfred has told or asked this user outside a chat */
+    listDeliveries(config = {}) {
+        return (0, outreach_1.listDeliveries)(this.forRequest(config));
+    }
+    /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
+    answerDelivery(config) {
+        return (0, outreach_1.answerDelivery)(this.forRequest(config));
+    }
+    /** The client's own server and key underneath whatever the call named itself. */
+    forRequest(config) {
+        return { serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...given(config) };
+    }
 }
 exports.ButlerBotClient = ButlerBotClient;
 // Expose types from subsequent modules
 __exportStar(require("./types/type_registry"), exports);
 __exportStar(require("./link"), exports);
+var api_error_1 = require("./util/api_error");
+Object.defineProperty(exports, "ButlerBotAPIError", { enumerable: true, get: function () { return api_error_1.ButlerBotAPIError; } });
+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, "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");
+Object.defineProperty(exports, "listDeliveries", { enumerable: true, get: function () { return outreach_2.listDeliveries; } });
+Object.defineProperty(exports, "answerDelivery", { enumerable: true, get: function () { return outreach_2.answerDelivery; } });
 var transport_link_1 = require("./modules/transport_link");
 Object.defineProperty(exports, "LinkConversationTransport", { enumerable: true, get: function () { return transport_link_1.LinkConversationTransport; } });
 var transport_sse_1 = require("./modules/transport_sse");

package/dist/modules/api_request.d.ts

@@ -0,0 +1,18 @@
+export type APIRequestOptions = {
+    url: string;
+    /** GET when nothing says otherwise. */
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    /** Sent as JSON. A route that takes no body is called without one. */
+    body?: unknown;
+    /** What the caller was trying to do, for the message a failure carries. */
+    action: string;
+};
+/**
+ * One call to a JSON route, with the failure turned into a `ButlerBotAPIError`.
+ *
+ * The body is read as text once and parsed here rather than through `response.json()`, because
+ * a failing route's body has to be readable both as the parsed `error`/`errormessage` and as
+ * whatever else it carries — the job on a rejected cancel, the delivery on a rejected answer —
+ * and a response body can only be consumed once.
+ */
+export declare function requestAPI<T>(options: APIRequestOptions): Promise<T>;

package/dist/modules/api_request.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestAPI = requestAPI;
+const api_error_1 = require("../util/api_error");
+/**
+ * One call to a JSON route, with the failure turned into a `ButlerBotAPIError`.
+ *
+ * The body is read as text once and parsed here rather than through `response.json()`, because
+ * a failing route's body has to be readable both as the parsed `error`/`errormessage` and as
+ * whatever else it carries — the job on a rejected cancel, the delivery on a rejected answer —
+ * and a response body can only be consumed once.
+ */
+async function requestAPI(options) {
+    const init = { method: options.method || "GET" };
+    if (options.body !== undefined) {
+        init.headers = { "Content-Type": "application/json" };
+        init.body = JSON.stringify(options.body);
+    }
+    const response = await fetch(options.url, init);
+    const text = await response.text();
+    const data = parseJSON(text);
+    const envelope = (data && typeof data === "object" ? data : {});
+    if (!response.ok || envelope.success !== true) {
+        throw new api_error_1.ButlerBotAPIError({
+            action: options.action,
+            status: response.status,
+            statusText: response.statusText,
+            error: envelope.error,
+            errormessage: envelope.errormessage,
+            body: data ?? text,
+        });
+    }
+    return data;
+}
+function parseJSON(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/modules/jobs.d.ts

@@ -0,0 +1,48 @@
+import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobListResponse, 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;
+    /** The base path for jobs, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type ListJobsOptions = JobsRequestOptions & {
+    /** 1-based. The first page when it is not given. */
+    page?: number;
+    /** How many jobs per page. */
+    limit?: number;
+    /** Only jobs in this status. */
+    status?: JobStatus;
+};
+export type GetJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
+export type CancelJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
+export type UpdateJobOptions = JobsRequestOptions & {
+    jobId: string;
+    /** How far this job may act outward on its own. */
+    autonomy?: JobAutonomy;
+    /** When that autonomy lapses back to asking. Null clears it. */
+    autonomyUntil?: string | number | null;
+    /** Things this job asks about however free it otherwise is. */
+    alwaysAsk?: string[];
+};
+export type UpdateJobSettingsOptions = JobsRequestOptions & JobSettingsUpdate;
+/** A page of the caller's jobs, newest first, with what their jobs may spend today. */
+export declare function listJobs(options: ListJobsOptions): Promise<JobListResponse>;
+/** One job with its plan, its journal and the questions of its nobody has answered. */
+export declare function getJob(options: GetJobOptions): Promise<JobDetailResponse>;
+/**
+ * Stops a job.
+ *
+ * A job that had already finished 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 cancelJob(options: CancelJobOptions): Promise<JobCancelResponse>;
+/** Changes one job's autonomy: how far it may act, until when, and what it always asks about. */
+export declare function updateJob(options: UpdateJobOptions): Promise<JobUpdateResponse>;
+/** Changes the owner's job settings: their daily allowance and the autonomy new jobs start with. */
+export declare function updateJobSettings(options: UpdateJobSettingsOptions): Promise<JobSettingsResponse>;

package/dist/modules/jobs.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listJobs = listJobs;
+exports.getJob = getJob;
+exports.cancelJob = cancelJob;
+exports.updateJob = updateJob;
+exports.updateJobSettings = updateJobSettings;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+function jobsBase(options) {
+    return (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.jobs.base);
+}
+/** Only what was actually given: `URLSearchParams` would otherwise send the word "undefined". */
+function query(params) {
+    const given = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            given[key] = String(value);
+    }
+    return given;
+}
+/** Only the keys a caller set, so an omitted field is not sent as an explicit `undefined`. */
+function body(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+/** A page of the caller's jobs, newest first, with what their jobs may spend today. */
+async function listJobs(options) {
+    const url = (0, url_formatter_1.formatURL)(jobsBase(options), query({ page: options.page, limit: options.limit, status: options.status }), { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, action: "list jobs" });
+}
+/** One job with its plan, its journal and the questions of its nobody has answered. */
+async function getJob(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, action: `read job ${options.jobId}` });
+}
+/**
+ * Stops a job.
+ *
+ * A job that had already finished is a 409: the call throws a `ButlerBotAPIError` whose
+ * `isConflict` is true and whose `body` still carries the job as it stands.
+ */
+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 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({ autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk }),
+        action: `update job ${options.jobId}`,
+    });
+}
+/** Changes the owner's job settings: their daily allowance and the autonomy new jobs start with. */
+async function updateJobSettings(options) {
+    const endpoint = (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.jobs.settings);
+    const url = (0, url_formatter_1.formatURL)(endpoint, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "PATCH",
+        body: body({
+            allowanceUsd: options.allowanceUsd,
+            allowancePercent: options.allowancePercent,
+            autonomy: options.autonomy,
+            alwaysAsk: options.alwaysAsk,
+        }),
+        action: "update job settings",
+    });
+}

package/dist/modules/outreach.d.ts

@@ -0,0 +1,31 @@
+import type { DeliveryAnswerResponse, DeliveryListResponse } from "../types/outreach";
+/** What every outreach call needs: where the server is, and who is asking. */
+export type OutreachRequestOptions = {
+    serverURL?: string;
+    /** The base path for outreach, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type ListDeliveriesOptions = OutreachRequestOptions & {
+    /** 1-based. The first page when it is not given. */
+    page?: number;
+    /** How many deliveries per page. */
+    limit?: number;
+};
+export type AnswerDeliveryOptions = OutreachRequestOptions & {
+    deliveryId: string;
+    /** The user's answer, in their own words. */
+    text: string;
+    /** On an approval, what they decided. */
+    decision?: "approve" | "deny";
+};
+/** A page of the inbox: what Alfred has told or asked this user outside a chat. */
+export declare function listDeliveries(options: ListDeliveriesOptions): Promise<DeliveryListResponse>;
+/**
+ * Answers one delivery, which closes it and wakes the job that asked.
+ *
+ * A delivery somebody has already answered is a 409: the call throws a `ButlerBotAPIError`
+ * whose `isConflict` is true and whose `body` still carries the delivery with the answer on it.
+ */
+export declare function answerDelivery(options: AnswerDeliveryOptions): Promise<DeliveryAnswerResponse>;

package/dist/modules/outreach.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listDeliveries = listDeliveries;
+exports.answerDelivery = answerDelivery;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+function outreachBase(options) {
+    return (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.outreach.base);
+}
+/** Only what was actually given: `URLSearchParams` would otherwise send the word "undefined". */
+function query(params) {
+    const given = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            given[key] = String(value);
+    }
+    return given;
+}
+/** A page of the inbox: what Alfred has told or asked this user outside a chat. */
+async function listDeliveries(options) {
+    const url = (0, url_formatter_1.formatURL)(outreachBase(options), query({ page: options.page, limit: options.limit }), { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, action: "list deliveries" });
+}
+/**
+ * Answers one delivery, which closes it and wakes the job that asked.
+ *
+ * A delivery somebody has already answered is a 409: the call throws a `ButlerBotAPIError`
+ * whose `isConflict` is true and whose `body` still carries the delivery with the answer on it.
+ */
+async function answerDelivery(options) {
+    const url = (0, url_formatter_1.formatURL)(`${outreachBase(options)}/${encodeURIComponent(options.deliveryId)}/answer`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "POST",
+        body: options.decision === undefined ? { text: options.text } : { text: options.text, decision: options.decision },
+        action: `answer delivery ${options.deliveryId}`,
+    });
+}

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

@@ -0,0 +1 @@
+export * from "./job";

package/dist/types/jobs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./job"), exports);

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

@@ -0,0 +1,179 @@
+import type { Delivery } from "../outreach/delivery";
+/**
+ * A job: long-running work Alfred does on its own, run as a sequence of short shifts.
+ *
+ * These are the shapes the jobs routes answer with. The server flattens a job row into a
+ * `JobView` before it leaves, and this is that view rather than the row.
+ */
+export declare const JOB_STATUSES: readonly ["queued", "running", "blocked", "waiting_user", "waiting_approval", "waiting_child", "waiting_budget", "review", "done", "failed", "cancelled"];
+export type JobStatus = typeof JOB_STATUSES[number];
+/** The statuses a job never leaves. */
+export declare const TERMINAL_JOB_STATUSES: readonly JobStatus[];
+export declare const JOB_AUTONOMY_MODES: readonly ["ask", "free", "auto"];
+/** How far a job may act outward on its own: ask first, act freely, or act and report. */
+export type JobAutonomy = typeof JOB_AUTONOMY_MODES[number];
+/** One job as a listing or a detail read shows it. */
+export type JobView = {
+    jobId: string;
+    /** A short name for listings, derived from the goal when nobody gave one. */
+    title: string;
+    /** The user's words, verbatim: what the job was asked to do. */
+    goal: string;
+    status: JobStatus;
+    /** Why it is where it is, specific enough to act on. */
+    statusDetail: string | null;
+    /** A one-line note the running shift may leave. */
+    progress: string | null;
+    /** The phase being worked, or the last one that was. */
+    currentPhaseId: string | null;
+    shiftsRun: number;
+    /** How many times the job has been reviewed. */
+    reviewRounds: number;
+    /** What the job has spent in total, in USD. */
+    spentUsd: number;
+    /** What the job has spent today, in USD. */
+    spendTodayUsd: number;
+    /** How many questions of this job's are waiting on the user. */
+    openQuestions: number;
+    lastRunAt: number;
+    /** The earliest the runner may pick it up again. */
+    wakeAt: number;
+    created: number;
+    /** `card://…/plan.md`, once a planning shift has written it. */
+    planCardUri: string | null;
+    /** `card://…/journal.md`, appended to as the job runs. */
+    journalCardUri: string | null;
+    /** The chat the job was asked for in, and where it reports back. */
+    originConversationId: 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. */
+    autonomyUntil: number | null;
+    /** Things this job asks about however free it otherwise is. */
+    alwaysAsk: string[];
+    /** What the gate actually reads, with the owner's setting and any lapse applied. */
+    effectiveAutonomy: JobAutonomy;
+};
+/** What the owner's jobs may spend today, and where that figure comes from. */
+export type JobAllowanceGranted = {
+    perDayUsd: number;
+    /** What set the figure: the owner's own allowance, or their tier. */
+    source: string;
+    remainingUsd: number;
+};
+/** Why the owner's jobs may not run at all. */
+export type JobAllowanceRefused = {
+    perDayUsd: 0;
+    source: null;
+    /** The reason in a word, such as a tier that does not include jobs. */
+    refused: string;
+    /** The same thing in a sentence, for showing a user. */
+    message: string;
+};
+export type JobAllowance = JobAllowanceGranted | JobAllowanceRefused;
+/** Whether an allowance is a refusal rather than a grant. */
+export declare function isJobAllowanceRefused(allowance: JobAllowance): allowance is JobAllowanceRefused;
+export type JobPlanPhaseKind = "plan" | "work" | "review";
+export type JobPlanPhaseStatus = "pending" | "running" | "blocked" | "done";
+/** One phase of a job's plan, as the plan card spells it out. */
+export type JobPlanPhase = {
+    id: string;
+    kind: JobPlanPhaseKind;
+    /** The model this phase is run on. */
+    model: string;
+    status: JobPlanPhaseStatus;
+    /** The card this phase has to leave behind before it may be done. */
+    artifact?: string;
+    /** What finishing it means, in the plan's own words. */
+    acceptance?: string;
+    /** Phase ids that have to be done first. */
+    dependsOn?: string[];
+    /** What the shift working this phase is told. */
+    brief?: string;
+};
+/**
+ * What is wrong with a plan card that could not be read.
+ *
+ * The parse issue names the line and what is wrong with it; a plain string is what a server
+ * that only has a sentence about it sends.
+ */
+export type JobPlanIssue = string | {
+    line: number;
+    message: string;
+};
+export type JobPlanRead = {
+    ok: true;
+    raw: string;
+    phases: JobPlanPhase[];
+} | {
+    ok: false;
+    reason: string;
+    issue?: JobPlanIssue;
+};
+/**
+ * One line of a job's journal.
+ *
+ * Loosely typed on purpose: the journal is a card the model writes as well as the runtime, and
+ * a reader that dropped the keys it did not know would hide exactly the entries worth reading.
+ */
+export type JobJournalEntry = {
+    at: number;
+    kind?: string;
+    title?: string;
+    body?: string;
+    [key: string]: unknown;
+};
+/** What may be written to the owner's job settings. */
+export type JobSettingsUpdate = {
+    /** A flat daily allowance, in USD. */
+    allowanceUsd?: number | null;
+    /** A daily allowance as a percentage of the owner's usage limit. */
+    allowancePercent?: number | null;
+    /** The autonomy new jobs start with. */
+    autonomy?: JobAutonomy | null;
+    /** Things every job of theirs asks about. */
+    alwaysAsk?: string[] | null;
+};
+/**
+ * The owner's job settings as they now stand.
+ *
+ * Open on purpose: the settings pipeline owns this document, and a setting it grows is worth
+ * handing back rather than dropping because the SDK has not been rebuilt.
+ */
+export type JobSettings = JobSettingsUpdate & {
+    [key: string]: unknown;
+};
+export type JobListResponse = {
+    success: true;
+    jobs: JobView[];
+    page: number;
+    limit: number;
+    total: number;
+    /** The status the listing was filtered to, when it was. */
+    status?: JobStatus;
+    allowance: JobAllowance;
+    spentTodayUsd: number;
+};
+export type JobDetailResponse = {
+    success: true;
+    job: JobView;
+    /** The job's autonomy in a sentence, ready to show. */
+    autonomyLine: string;
+    plan: JobPlanRead;
+    journal: JobJournalEntry[];
+    /** Questions of this job's nobody has answered yet. */
+    openDeliveries: Delivery[];
+};
+export type JobCancelResponse = {
+    success: true;
+    job: JobView;
+};
+export type JobUpdateResponse = {
+    success: true;
+    job: JobView;
+    autonomyLine: string;
+};
+export type JobSettingsResponse = {
+    success: true;
+    jobs: JobSettings;
+};

package/dist/types/jobs/job.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_AUTONOMY_MODES = exports.TERMINAL_JOB_STATUSES = exports.JOB_STATUSES = void 0;
+exports.isJobAllowanceRefused = isJobAllowanceRefused;
+/**
+ * A job: long-running work Alfred does on its own, run as a sequence of short shifts.
+ *
+ * These are the shapes the jobs routes answer with. The server flattens a job row into a
+ * `JobView` before it leaves, and this is that view rather than the row.
+ */
+exports.JOB_STATUSES = [
+    "queued",
+    "running",
+    "blocked",
+    "waiting_user",
+    "waiting_approval",
+    "waiting_child",
+    "waiting_budget",
+    "review",
+    "done",
+    "failed",
+    "cancelled",
+];
+/** The statuses a job never leaves. */
+exports.TERMINAL_JOB_STATUSES = ["done", "failed", "cancelled"];
+exports.JOB_AUTONOMY_MODES = ["ask", "free", "auto"];
+/** Whether an allowance is a refusal rather than a grant. */
+function isJobAllowanceRefused(allowance) {
+    return allowance.source === null;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Outreach: what Alfred has told or asked this user outside a chat, and their answers.
+ *
+ * A delivery is the record itself, so the inbox listing is the delivery rather than a
+ * notification about one. Answering closes it, and when it belongs to a job the answer is put
+ * on that job's inbox.
+ */
+export declare const DELIVERY_INTENTS: readonly ["question", "update", "approval", "statement"];
+export type DeliveryIntent = typeof DELIVERY_INTENTS[number];
+/** The intents that leave something outstanding until the user answers. */
+export declare const ANSWERABLE_DELIVERY_INTENTS: readonly DeliveryIntent[];
+export declare const DELIVERY_SURFACES: readonly ["web", "discord"];
+/** Where a delivery was put. */
+export type DeliverySurfaceName = typeof DELIVERY_SURFACES[number];
+export declare const DELIVERY_SURFACE_STATUSES: readonly ["pending", "sent", "failed"];
+export type DeliverySurfaceStatus = typeof DELIVERY_SURFACE_STATUSES[number];
+/** How one surface's send went. */
+export type DeliverySurface = {
+    surface: DeliverySurfaceName;
+    status: DeliverySurfaceStatus;
+    /** Where on the surface it went: a Discord channel id, or "DM". */
+    channelId?: string | null;
+    /** What the channel called the message it sent. */
+    messageId?: string | null;
+    /** Why the last attempt failed. */
+    error?: string | null;
+    attempts: number;
+    /** When the last attempt was made, in UTC milliseconds. */
+    lastAt: number;
+};
+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 type DeliveryAnswer = {
+    at: number;
+    text: string;
+    via: DeliveryAnsweredVia;
+    /** On an approval, what the user decided. */
+    decision?: "approve" | "deny";
+};
+/** One delivery, as the inbox reads it. */
+export type Delivery = {
+    deliveryId: string;
+    ownerUserId: string;
+    /** The chat this is about, so answering opens the conversation it belongs to. */
+    originConversationId: string | null;
+    /** The job this is about, when it is about one. */
+    jobId: string | null;
+    intent: DeliveryIntent;
+    message: string;
+    surfaces: DeliverySurface[];
+    /** Null until somebody answers. Only ever set once. */
+    answered: DeliveryAnswer | null;
+    created: number;
+};
+/** Whether a delivery is still waiting on the user. */
+export declare function isDeliveryOpen(delivery: Delivery): boolean;
+export type DeliveryListResponse = {
+    success: true;
+    deliveries: Delivery[];
+    page: number;
+    limit: number;
+    total: number;
+};
+/** What became of the answer once it was handed to the job that asked. */
+export type DeliveryAnswerJobResult = {
+    jobId: string;
+    /** What the job did with it, or "dropped" when it could not take it. */
+    delivered: string;
+    /** Why it could not be delivered, when it could not. */
+    error?: string;
+};
+export type DeliveryAnswerResponse = {
+    success: true;
+    delivery: Delivery;
+    /** Present only when the delivery belonged to a job. */
+    job?: DeliveryAnswerJobResult;
+};

package/dist/types/outreach/delivery.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Outreach: what Alfred has told or asked this user outside a chat, and their answers.
+ *
+ * A delivery is the record itself, so the inbox listing is the delivery rather than a
+ * notification about one. Answering closes it, and when it belongs to a job the answer is put
+ * 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.isDeliveryOpen = isDeliveryOpen;
+exports.DELIVERY_INTENTS = ["question", "update", "approval", "statement"];
+/** The intents that leave something outstanding until the user answers. */
+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. */
+function isDeliveryOpen(delivery) {
+    return exports.ANSWERABLE_DELIVERY_INTENTS.includes(delivery.intent) && !delivery.answered;
+}

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

@@ -0,0 +1 @@
+export * from "./delivery";

package/dist/types/outreach/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./delivery"), exports);

package/dist/types/type_registry.d.ts

@@ -3,4 +3,6 @@ export * from "./response/v4";
 export * from "./response/v5";
 export * from "./state/convo_state_response";
 export * from "./conversation/v4/conversation_v4";
+export * from "./jobs";
+export * from "./outreach";
 export * from "./error";

package/dist/types/type_registry.js

@@ -19,4 +19,6 @@ __exportStar(require("./response/v4"), exports);
 __exportStar(require("./response/v5"), exports);
 __exportStar(require("./state/convo_state_response"), exports);
 __exportStar(require("./conversation/v4/conversation_v4"), exports);
+__exportStar(require("./jobs"), exports);
+__exportStar(require("./outreach"), exports);
 __exportStar(require("./error"), exports);

package/dist/util/api_error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What an API call throws when the server did not answer with a success.
+ *
+ * One error class for every JSON route rather than a result type per method: the status is
+ * what a caller branches on, and it is carried here alongside whatever the server said, so
+ * "the job was already finished" (409) and "no job of yours has that id" (404) are told apart
+ * without parsing a message. `body` is the parsed response when there was one, so a 409 on a
+ * cancel still hands back the job, and a 409 on an answer still hands back the delivery.
+ */
+export declare class ButlerBotAPIError extends Error {
+    /** The HTTP status the server answered with, or 0 when the call never got a response. */
+    readonly status: number;
+    readonly statusText: string;
+    /** The server's short `error`, e.g. "Already finished". */
+    readonly error?: string;
+    /** The server's `errormessage`: the same thing in a sentence. */
+    readonly errormessage?: string;
+    /** The parsed response body, or the raw text when it was not JSON. */
+    readonly body: unknown;
+    constructor(options: {
+        action: string;
+        status: number;
+        statusText?: string;
+        error?: string;
+        errormessage?: string;
+        body?: unknown;
+    });
+    /** The resource is not there, or is not this key's. The two are answered alike on purpose. */
+    get isNotFound(): boolean;
+    /** Somebody got there first: the job had finished, or the delivery was already answered. */
+    get isConflict(): boolean;
+    /** The request itself was refused: a value the server would not take. */
+    get isBadRequest(): boolean;
+}

package/dist/util/api_error.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ButlerBotAPIError = void 0;
+/**
+ * What an API call throws when the server did not answer with a success.
+ *
+ * One error class for every JSON route rather than a result type per method: the status is
+ * what a caller branches on, and it is carried here alongside whatever the server said, so
+ * "the job was already finished" (409) and "no job of yours has that id" (404) are told apart
+ * without parsing a message. `body` is the parsed response when there was one, so a 409 on a
+ * cancel still hands back the job, and a 409 on an answer still hands back the delivery.
+ */
+class ButlerBotAPIError extends Error {
+    constructor(options) {
+        const detail = options.errormessage
+            || options.error
+            // A body that was not JSON at all still says more than "Unknown error" does.
+            || (typeof options.body === "string" && options.body ? options.body.slice(0, 500) : "Unknown error");
+        super(`Failed to ${options.action}: ${options.status} ${options.statusText || ""} - ${detail}`.replace(/\s+-/, " -"));
+        this.name = "ButlerBotAPIError";
+        this.status = options.status;
+        this.statusText = options.statusText || "";
+        this.error = options.error;
+        this.errormessage = options.errormessage;
+        this.body = options.body;
+        // `target: es2020` down-levels the subclass, which breaks `instanceof` without this.
+        Object.setPrototypeOf(this, ButlerBotAPIError.prototype);
+    }
+    /** The resource is not there, or is not this key's. The two are answered alike on purpose. */
+    get isNotFound() {
+        return this.status === 404;
+    }
+    /** Somebody got there first: the job had finished, or the delivery was already answered. */
+    get isConflict() {
+        return this.status === 409;
+    }
+    /** The request itself was refused: a value the server would not take. */
+    get isBadRequest() {
+        return this.status === 400;
+    }
+}
+exports.ButlerBotAPIError = ButlerBotAPIError;

package/package.json

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

package/readme.md

@@ -322,6 +322,71 @@ seen. A conversation with nothing running simply ends the stream.
 Neither transport can cancel a turn: `close()` stops delivery locally, and the reply is
 still generated and stored.
 
+## Jobs
+
+A job is long-running work Alfred does on its own, run as a sequence of short shifts against
+a plan it writes. The client reads them and steers them; it does not run them.
+
+```typescript
+const { jobs, allowance, spentTodayUsd } = await client.listJobs({ status: "running", page: 1, limit: 20 });
+const { job, plan, journal, openDeliveries, autonomyLine } = await client.getJob({ jobId });
+
+await client.updateJob({ jobId, autonomy: "free", autonomyUntil: Date.now() + 86_400_000 });
+await client.cancelJob({ jobId });
+```
+
+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
+`{ perDayUsd: 0, source: null, refused, message }` when their plan does not include jobs.
+
+`autonomy` is how far a job may act outward without asking: `ask`, `free` or `auto`.
+`autonomyUntil` is when a loosened setting lapses back to asking, and `alwaysAsk` is what the
+job asks about however free it otherwise is. `effectiveAutonomy` on a job is what the gate
+actually reads, with the owner's default and any lapse already applied. What new jobs start
+with, and what they may spend, is the user's own setting:
+
+```typescript
+await client.updateJobSettings({ allowanceUsd: 5, autonomy: "ask", alwaysAsk: ["spending money"] });
+```
+
+## Outreach
+
+Outreach is what Alfred has told or asked this user outside a chat. The record is the inbox —
+there is no separate notification — so a question a job is parked on is a delivery with
+`intent: "question"` and no `answered`:
+
+```typescript
+const { deliveries } = await client.listDeliveries({ page: 1, limit: 20 });
+const { delivery, job } = await client.answerDelivery({ deliveryId, text: "The one in Gardens" });
+```
+
+Answering closes the delivery, and when it belongs to a job the answer is put on that job's
+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.
+
+### When a call fails
+
+Every jobs and outreach call throws `ButlerBotAPIError` when the server does not answer with a
+success. The status is on the error, so the cases worth branching on are told apart without
+reading a message, and the parsed body is kept — a rejected cancel still carries the job, a
+rejected answer still carries the delivery:
+
+```typescript
+import { ButlerBotAPIError } from "@butlerbot/sdk";
+
+try {
+    await client.cancelJob({ jobId });
+} catch (error) {
+    if (error instanceof ButlerBotAPIError && error.isConflict) {
+        // 409: it had already finished. `error.body.job` is how it settled.
+    } else throw error;
+}
+```
+
+`isNotFound` (404), `isConflict` (409) and `isBadRequest` (400) are the three; `status`,
+`error` and `errormessage` are the server's own words. A job or delivery that is not this key's
+is answered exactly as one that does not exist, so a 404 means either.
+
 ## Environment
 
 Node 18+. Node 22 and every browser have a built-in WebSocket; on older Node, install