charness 3.6.1 → 3.8.0

package/dist/todos/tools.d.ts

@@ -0,0 +1,26 @@
+import type { SessionKey } from '../sessionKey';
+import type { TodoBoard } from './board';
+import type { TodoUpdateArgs } from './merge';
+import type { TodoReadArgs, TodoRegistry, TodoToolOutcome } from './registry';
+/**
+ * @description What `todo_update` and `todo_read` answer (D4, D5): the registry's own-list answer, followed by what
+ * changed in the project's other topics since this agent last saw them — every update is an overlap check. With the
+ * project scope `todo_read` answers the whole board instead.
+ */
+export interface TodoTools {
+    update(key: SessionKey, args: TodoUpdateArgs): Promise<TodoToolOutcome>;
+    read(key: SessionKey, args: TodoReadArgs): Promise<TodoToolOutcome>;
+}
+/**
+ * @name TodoToolsDeps
+ * @description The registry, the board, and what to do once a result showed the agent the board's changes: a
+ * mid-turn inbox carrying the same changes is withdrawn (`midTurn.ts` `discardInbox`), or the next tool call would
+ * print them a second time.
+ */
+export interface TodoToolsDeps {
+    registry: TodoRegistry;
+    board: TodoBoard;
+    onBoardShown?: (key: SessionKey) => void;
+}
+export declare function createTodoTools(deps: TodoToolsDeps): TodoTools;
+//# sourceMappingURL=tools.d.ts.map

package/dist/todos/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/todos/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACxE,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACrE;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;CAC1C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAsB9D"}

package/dist/todos/tools.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTodoTools = createTodoTools;
+function createTodoTools(deps) {
+    const { registry, board, onBoardShown } = deps;
+    /** The board text a result carries; the agent has seen it now. */
+    async function takeBoard(key, take) {
+        const text = await take(key);
+        onBoardShown?.(key);
+        return text;
+    }
+    /** The own-list answer, then the board's delta; a refusal stays as it is (nothing was seen). */
+    async function withBoard(key, outcome) {
+        if (!outcome.ok)
+            return outcome;
+        return { ok: true, message: `${outcome.message}\n\n${await takeBoard(key, board.takeToolBoard)}` };
+    }
+    return {
+        update: (key, args) => withBoard(key, registry.updateTodos(key, args)),
+        read: async (key, args) => (args.scope === 'project'
+            ? { ok: true, message: await takeBoard(key, board.takeProjectBoard) }
+            : withBoard(key, registry.readTodos(key, args))),
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/todos/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/todos/tools.ts"],"names":[],"mappings":";;AA2BA,0CAsBC;AAtBD,SAAgB,eAAe,CAAC,IAAmB;IACjD,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAE/C,kEAAkE;IAClE,KAAK,UAAU,SAAS,CAAC,GAAe,EAAE,IAA0C;QAClF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gGAAgG;IAChG,KAAK,UAAU,SAAS,CAAC,GAAe,EAAE,OAAwB;QAChE,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,OAAO,MAAM,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;IACrG,CAAC;IAED,OAAO;QACL,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS;YAClD,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,gBAAgB,CAAC,EAAE;YACrE,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/todos/types.d.ts

@@ -0,0 +1,85 @@
+import type { TodoNagState } from './nag';
+/**
+ * @description Shapes of the shared agent todo registry: one published list per conversation (a Telegram topic, a
+ * Jira issue), kept in its own file under `DATA_DIR/todos/` (`store.ts`). A list belongs to the CONVERSATION, never to
+ * a session: `/new`, `/quit`, a backend switch and a restart keep it.
+ */
+/**
+ * @name TodoStatus
+ * @description Where an item stands: `queued` — waiting, in queue order; `inWork` — being worked on now; `done` —
+ * finished; `dropped` — will not be done (the removal: nothing disappears by omission).
+ */
+export declare const todoStatuses: readonly ["queued", "inWork", "done", "dropped"];
+export type TodoStatus = (typeof todoStatuses)[number];
+/** The statuses of an item still to be done. */
+export declare const openTodoStatuses: readonly TodoStatus[];
+/**
+ * @name TodoSource
+ * @description Who put the item on the list: the agent itself, the owner (a tracker), or a tracker item linked to the
+ * conversation. Only `agent` exists until the trackers ship.
+ */
+export declare const todoSources: readonly ["agent", "owner", "link"];
+export type TodoSource = (typeof todoSources)[number];
+/** Where `position` puts an item among the open ones. */
+export declare const todoPositions: readonly ["top", "bottom"];
+export type TodoPosition = (typeof todoPositions)[number];
+/** The longest item title and note accepted. */
+export declare const todoTitleMaxLength = 200;
+export declare const todoNoteMaxLength = 500;
+/** The longest `ref` (a tracker key, id or link). */
+export declare const todoRefMaxLength = 200;
+/**
+ * @name TodoItem
+ * @description One published item. Its queue position is its place in {@link TodoTopicFile.items} among the open
+ * items (the array order IS the queue order — one source of truth). Times are epoch ms.
+ */
+export interface TodoItem {
+    /** `t1`, `t2`, … per conversation, never reused. */
+    id: string;
+    title: string;
+    status: TodoStatus;
+    note?: string;
+    source: TodoSource;
+    /** A tracker id / key / link the item names (a ticket the agent created on the way). */
+    ref?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** When the item last went in work. */
+    startedAt?: number;
+    /** When the item was closed (done or dropped). */
+    closedAt?: number;
+}
+/**
+ * @name TodoTopicFile
+ * @description A conversation's whole todo record, as stored. `revision` counts content changes (what a peer's
+ * board compares); `lastUpdateAt` is the last `todo_update` call of any kind — a call that changes nothing still
+ * says "the list is accurate".
+ */
+export interface TodoTopicFile {
+    version: 1;
+    /** The conversation's serialized `SessionKey`. */
+    conversationKey: string;
+    /** The number the next new item's id takes. */
+    nextItemNumber: number;
+    items: TodoItem[];
+    revision: number;
+    /** When the content last changed (`revision` moved). */
+    changedAt?: number;
+    /** When the agent last called `todo_update`. */
+    lastUpdateAt?: number;
+    /** The staleness reminder's bookkeeping (`nag.ts`); absent = nothing worked or reminded since the last update. */
+    nag?: TodoNagState;
+    /** When a turn of this conversation last ended (a peer's board line says how long ago). */
+    lastTurnEndAt?: number;
+    /**
+     * What this conversation's agent has seen of its project's other lists (D19): each peer's `revision` and when.
+     * Absent = nothing yet, or the agent lost its context — the next board it gets is the whole one.
+     */
+    boardSeen?: TodoBoardSeen;
+}
+/** @name TodoBoardSeen @description The peers' revisions an agent was last shown, and when. */
+export interface TodoBoardSeen {
+    revisions: Record<string, number>;
+    at: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/todos/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/todos/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,kDAAmD,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAAyB,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,yDAAyD;AACzD,eAAO,MAAM,aAAa,4BAA6B,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,wFAAwF;IACxF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kHAAkH;IAClH,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ"}

package/dist/todos/types.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.todoRefMaxLength = exports.todoNoteMaxLength = exports.todoTitleMaxLength = exports.todoPositions = exports.todoSources = exports.openTodoStatuses = exports.todoStatuses = void 0;
+/**
+ * @description Shapes of the shared agent todo registry: one published list per conversation (a Telegram topic, a
+ * Jira issue), kept in its own file under `DATA_DIR/todos/` (`store.ts`). A list belongs to the CONVERSATION, never to
+ * a session: `/new`, `/quit`, a backend switch and a restart keep it.
+ */
+/**
+ * @name TodoStatus
+ * @description Where an item stands: `queued` — waiting, in queue order; `inWork` — being worked on now; `done` —
+ * finished; `dropped` — will not be done (the removal: nothing disappears by omission).
+ */
+exports.todoStatuses = ['queued', 'inWork', 'done', 'dropped'];
+/** The statuses of an item still to be done. */
+exports.openTodoStatuses = ['queued', 'inWork'];
+/**
+ * @name TodoSource
+ * @description Who put the item on the list: the agent itself, the owner (a tracker), or a tracker item linked to the
+ * conversation. Only `agent` exists until the trackers ship.
+ */
+exports.todoSources = ['agent', 'owner', 'link'];
+/** Where `position` puts an item among the open ones. */
+exports.todoPositions = ['top', 'bottom'];
+/** The longest item title and note accepted. */
+exports.todoTitleMaxLength = 200;
+exports.todoNoteMaxLength = 500;
+/** The longest `ref` (a tracker key, id or link). */
+exports.todoRefMaxLength = 200;
+//# sourceMappingURL=types.js.map

package/dist/todos/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/todos/types.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AAEH;;;;GAIG;AACU,QAAA,YAAY,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAG7E,gDAAgD;AACnC,QAAA,gBAAgB,GAA0B,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE5E;;;;GAIG;AACU,QAAA,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAG/D,yDAAyD;AAC5C,QAAA,aAAa,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAU,CAAC;AAGxD,gDAAgD;AACnC,QAAA,kBAAkB,GAAG,GAAG,CAAC;AACzB,QAAA,iBAAiB,GAAG,GAAG,CAAC;AACrC,qDAAqD;AACxC,QAAA,gBAAgB,GAAG,GAAG,CAAC"}

package/dist/trackers/taskAgentLimit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @description The cap on tracker task agents (`/task_agents`): how many tracker conversations may hold an open hand-over
+ * request at once, for the WHOLE bot — every project of every tracker connector. `0` = no limit.
+ *
+ * One value decides it, read in this order — the first that is set wins:
+ *
+ *  1. the General value (`/task_agents` in General, kept in `state.json`),
+ *  2. `settings.json`'s `taskAgents.maxConcurrent` — the way an instance without General (Jira only) sets it,
+ *  3. {@link defaultTaskAgentsMaxConcurrent}.
+ *
+ * Kept free of `instanceSettings.ts` imports: that module needs these constants for its schema.
+ */
+/** What an instance gets when neither General nor `settings.json` says. */
+export declare const defaultTaskAgentsMaxConcurrent = 5;
+/** The stored and typed value for «no limit». */
+export declare const taskAgentsNoLimit = 0;
+/** The most a number typed into `/task_agents` or written in `settings.json` may name: a bot runs far fewer agents than this at once. */
+export declare const taskAgentsMaxConcurrentUpperBound = 100;
+/** The picker's numbers, besides «No limit». */
+export declare const taskAgentsPickerValues: readonly number[];
+/** The word of `/task_agents <word>` that means «no limit», beside `0`. */
+export declare const taskAgentsNoLimitWord = "off";
+/** Where the value in force comes from: General's own choice, `settings.json`'s seed, or the built-in default. */
+export type TaskAgentLimitSource = 'general' | 'settingsFile' | 'builtInDefault';
+/** @name TaskAgentLimit @description The value in force and the layer that gave it. */
+export interface TaskAgentLimit {
+    maxConcurrent: number;
+    source: TaskAgentLimitSource;
+}
+/** Where the layers of the precedence above are read from; the bot wires `state.json` and `settings.json`. */
+export interface TaskAgentLimitSources {
+    /** The General value; `undefined` = General never chose. */
+    getGeneralValue: () => number | undefined;
+    /** `settings.json`'s `taskAgents.maxConcurrent`; `null` = the file does not say. */
+    getSettingsValue: () => number | null;
+}
+/** @description The value in force: General's, else `settings.json`'s (read only when General never chose), else the default. */
+export declare function readTaskAgentLimit(sources: TaskAgentLimitSources): TaskAgentLimit;
+/** @description Whether `value` is a number the setting may hold: a whole number from 0 up to {@link taskAgentsMaxConcurrentUpperBound}. */
+export declare function checkIsTaskAgentsMaxConcurrent(value: number): boolean;
+/**
+ * @name TaskAgentLimitArgument
+ * @description What `/task_agents <argument>` names: `number` — a valid value (`0` = no limit); `invalid` — it is neither a
+ * whole number in range nor the word for «no limit»; `none` — nothing was typed.
+ */
+export type TaskAgentLimitArgument = {
+    kind: 'number';
+    value: number;
+} | {
+    kind: 'invalid';
+} | {
+    kind: 'none';
+};
+/** @description Read the argument of `/task_agents`: digits only (no sign, no decimals), in range; `off` is `0`. */
+export declare function parseTaskAgentLimitArgument(argument: string): TaskAgentLimitArgument;
+/** @description Did the cap go UP between two reads — a bigger number, or «no limit» after a number? Going down, or staying, is not. */
+export declare function checkIsTaskAgentLimitRaised(previousMaxConcurrent: number, currentMaxConcurrent: number): boolean;
+//# sourceMappingURL=taskAgentLimit.d.ts.map

package/dist/trackers/taskAgentLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskAgentLimit.d.ts","sourceRoot":"","sources":["../../src/trackers/taskAgentLimit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,yIAAyI;AACzI,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAE7E,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,kHAAkH;AAClH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEjF,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,8GAA8G;AAC9G,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC1C,oFAAoF;IACpF,gBAAgB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,iIAAiI;AACjI,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAMjF;AAED,4IAA4I;AAC5I,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhH,oHAAoH;AACpH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAOpF;AAED,wIAAwI;AACxI,wBAAgB,2BAA2B,CAAC,qBAAqB,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAGhH"}

package/dist/trackers/taskAgentLimit.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * @description The cap on tracker task agents (`/task_agents`): how many tracker conversations may hold an open hand-over
+ * request at once, for the WHOLE bot — every project of every tracker connector. `0` = no limit.
+ *
+ * One value decides it, read in this order — the first that is set wins:
+ *
+ *  1. the General value (`/task_agents` in General, kept in `state.json`),
+ *  2. `settings.json`'s `taskAgents.maxConcurrent` — the way an instance without General (Jira only) sets it,
+ *  3. {@link defaultTaskAgentsMaxConcurrent}.
+ *
+ * Kept free of `instanceSettings.ts` imports: that module needs these constants for its schema.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskAgentsNoLimitWord = exports.taskAgentsPickerValues = exports.taskAgentsMaxConcurrentUpperBound = exports.taskAgentsNoLimit = exports.defaultTaskAgentsMaxConcurrent = void 0;
+exports.readTaskAgentLimit = readTaskAgentLimit;
+exports.checkIsTaskAgentsMaxConcurrent = checkIsTaskAgentsMaxConcurrent;
+exports.parseTaskAgentLimitArgument = parseTaskAgentLimitArgument;
+exports.checkIsTaskAgentLimitRaised = checkIsTaskAgentLimitRaised;
+/** What an instance gets when neither General nor `settings.json` says. */
+exports.defaultTaskAgentsMaxConcurrent = 5;
+/** The stored and typed value for «no limit». */
+exports.taskAgentsNoLimit = 0;
+/** The most a number typed into `/task_agents` or written in `settings.json` may name: a bot runs far fewer agents than this at once. */
+exports.taskAgentsMaxConcurrentUpperBound = 100;
+/** The picker's numbers, besides «No limit». */
+exports.taskAgentsPickerValues = [5, 10, 15, 20, 30];
+/** The word of `/task_agents <word>` that means «no limit», beside `0`. */
+exports.taskAgentsNoLimitWord = 'off';
+/** @description The value in force: General's, else `settings.json`'s (read only when General never chose), else the default. */
+function readTaskAgentLimit(sources) {
+    const generalValue = sources.getGeneralValue();
+    if (generalValue !== undefined)
+        return { maxConcurrent: generalValue, source: 'general' };
+    const settingsValue = sources.getSettingsValue();
+    if (settingsValue !== null)
+        return { maxConcurrent: settingsValue, source: 'settingsFile' };
+    return { maxConcurrent: exports.defaultTaskAgentsMaxConcurrent, source: 'builtInDefault' };
+}
+/** @description Whether `value` is a number the setting may hold: a whole number from 0 up to {@link taskAgentsMaxConcurrentUpperBound}. */
+function checkIsTaskAgentsMaxConcurrent(value) {
+    return Number.isInteger(value) && value >= exports.taskAgentsNoLimit && value <= exports.taskAgentsMaxConcurrentUpperBound;
+}
+/** @description Read the argument of `/task_agents`: digits only (no sign, no decimals), in range; `off` is `0`. */
+function parseTaskAgentLimitArgument(argument) {
+    const text = argument.trim().toLowerCase();
+    if (text === '')
+        return { kind: 'none' };
+    if (text === exports.taskAgentsNoLimitWord)
+        return { kind: 'number', value: exports.taskAgentsNoLimit };
+    if (!/^\d+$/.test(text))
+        return { kind: 'invalid' };
+    const value = Number.parseInt(text, 10);
+    return checkIsTaskAgentsMaxConcurrent(value) ? { kind: 'number', value } : { kind: 'invalid' };
+}
+/** @description Did the cap go UP between two reads — a bigger number, or «no limit» after a number? Going down, or staying, is not. */
+function checkIsTaskAgentLimitRaised(previousMaxConcurrent, currentMaxConcurrent) {
+    if (previousMaxConcurrent === exports.taskAgentsNoLimit)
+        return false;
+    return currentMaxConcurrent === exports.taskAgentsNoLimit || currentMaxConcurrent > previousMaxConcurrent;
+}
+//# sourceMappingURL=taskAgentLimit.js.map

package/dist/trackers/taskAgentLimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskAgentLimit.js","sourceRoot":"","sources":["../../src/trackers/taskAgentLimit.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAmCH,gDAMC;AAGD,wEAEC;AAUD,kEAOC;AAGD,kEAGC;AAnED,2EAA2E;AAC9D,QAAA,8BAA8B,GAAG,CAAC,CAAC;AAEhD,iDAAiD;AACpC,QAAA,iBAAiB,GAAG,CAAC,CAAC;AAEnC,yIAAyI;AAC5H,QAAA,iCAAiC,GAAG,GAAG,CAAC;AAErD,gDAAgD;AACnC,QAAA,sBAAsB,GAAsB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;AAE7E,2EAA2E;AAC9D,QAAA,qBAAqB,GAAG,KAAK,CAAC;AAmB3C,iIAAiI;AACjI,SAAgB,kBAAkB,CAAC,OAA8B;IAC/D,MAAM,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAC/C,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC1F,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IACjD,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC5F,OAAO,EAAE,aAAa,EAAE,sCAA8B,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACrF,CAAC;AAED,4IAA4I;AAC5I,SAAgB,8BAA8B,CAAC,KAAa;IAC1D,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,yBAAiB,IAAI,KAAK,IAAI,yCAAiC,CAAC;AAC7G,CAAC;AASD,oHAAoH;AACpH,SAAgB,2BAA2B,CAAC,QAAgB;IAC1D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACzC,IAAI,IAAI,KAAK,6BAAqB;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,yBAAiB,EAAE,CAAC;IACxF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,8BAA8B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACjG,CAAC;AAED,wIAAwI;AACxI,SAAgB,2BAA2B,CAAC,qBAA6B,EAAE,oBAA4B;IACrG,IAAI,qBAAqB,KAAK,yBAAiB;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,oBAAoB,KAAK,yBAAiB,IAAI,oBAAoB,GAAG,qBAAqB,CAAC;AACpG,CAAC"}

package/dist/trackers/taskAgentSlots.d.ts

@@ -0,0 +1,109 @@
+import { type PlatformId, type SessionKey } from '../sessionKey';
+import type { RequestLedger } from '../requests/requestLedger';
+import type { ClosedRequestRecord, OpenRequestState } from '../requests/types';
+import type { StateStore } from '../state';
+/** How many starts of one waiting issue may fail in a row before it moves to the end of the wait list. */
+export declare const taskAgentStartFailureLimit = 3;
+/**
+ * @name TaskAgentSlotDecision
+ * @description `granted` — open the request. `queued` — wait: `isNewlyQueued` is true the first time the conversation joins
+ * the list (the moment to say so), `aheadCount` how many conversations were in front of it, `maxConcurrent` the cap that held it.
+ */
+export type TaskAgentSlotDecision = {
+    kind: 'granted';
+} | {
+    kind: 'queued';
+    isNewlyQueued: boolean;
+    aheadCount: number;
+    maxConcurrent: number;
+};
+/** What the screen and the logs say of the slots right now. */
+export interface TaskAgentSlotStatus {
+    /** The cap in force; `0` = no limit. */
+    maxConcurrent: number;
+    /** Tracker conversations working on a hand-over. */
+    runningCount: number;
+    /** Tracker conversations waiting for a slot. */
+    waitingCount: number;
+}
+export interface TaskAgentSlotsDeps {
+    /** The cap in force, read at every question (`taskAgentLimit.ts`); `0` = no limit. */
+    getMaxConcurrent: () => number;
+    ledger: Pick<RequestLedger, 'listOpenRequests'>;
+    /** Where the wait list lives (`state.json`). */
+    store: Pick<StateStore, 'getTaskAgentWaitList' | 'setTaskAgentWaitList' | 'flush'>;
+    now?: () => number;
+}
+export declare class TaskAgentSlots {
+    private readonly deps;
+    private readonly now;
+    /** Conversations a `granted` answer was given to and whose request is not open yet; memory only. */
+    private readonly reservedConversationKeys;
+    /** Per waiting conversation, how many starts failed in a row (absent = none); memory only, so a restart gives every place a fresh start. */
+    private readonly failedStartCounts;
+    /** The cap as the last read saw it; `null` before the first read. */
+    private lastReadMaxConcurrent;
+    private readonly slotFreedListeners;
+    constructor(deps: TaskAgentSlotsDeps);
+    /** The conversations that hold a slot now: an open, not given-up hand-over request, or a reservation. */
+    private getOccupiedConversationKeys;
+    /** The wait list without the conversations that hold a slot already (a start whose entry was not dropped yet). */
+    private getWaitingEntries;
+    /**
+     * @description May `key`'s conversation open a hand-over request now? `triggerId` names the hand-over for the logs. A
+     * conversation that holds a slot already — a newer hand-over of the same issue supersedes its open request — needs no new one.
+     * A `queued` answer that changes the list (a new place, a newer trigger) saves it, flushed: a restart right after keeps the place.
+     */
+    checkIn(key: SessionKey, triggerId: string): Promise<TaskAgentSlotDecision>;
+    /** @description The granted conversation's request is open (and counted by the ledger now): drop the reservation and its place in the list. */
+    noteStarted(key: SessionKey): void;
+    /**
+     * @description The granted conversation could not open its request: the slot goes back and a place in the list (if any) stays, but
+     * the place no longer holds up the ones behind it. The {@link taskAgentStartFailureLimit}th failure in a row moves it to the end
+     * of the list (logged once) and gives it a fresh start there. A conversation with no place has nothing to move: it asks again at its next poll.
+     */
+    noteStartFailed(key: SessionKey): void;
+    /** @description The conversation no longer waits (its hand-over was withdrawn, refused or handled another way): drop its place. */
+    dropWaiting(key: SessionKey): void;
+    /**
+     * @description Drop the places of `platform`'s conversations that `checkIsStillWaiting` no longer vouches for — a connector's
+     * poll calls it after a complete poll with what it found (an issue that left the hand-over statuses is no longer waiting).
+     */
+    pruneWaiting(platform: PlatformId, checkIsStillWaiting: (key: SessionKey) => boolean): void;
+    /** @description Drop the places of conversations nobody in this process serves any more (a connector taken out of `CONNECTORS`): they could never start and would hold up the others. */
+    dropUnserved(checkIsServed: (key: SessionKey) => boolean): void;
+    private removeWaiting;
+    /**
+     * @description The cap, the conversations working and the conversations waiting. Reading the cap here notices a raise like any read
+     * outside a poll (see {@link TaskAgentSlots.noteLimitMayHaveChanged}).
+     */
+    getStatus(): TaskAgentSlotStatus;
+    /**
+     * The cap in force. `isWakingOnRaise`: when it went up since the last read and somebody waits, the listeners are woken — a raise
+     * is room for the waiting issues, found by whoever reads it first (the `/task_agents` screen, a hand edit of `settings.json`).
+     */
+    private readMaxConcurrent;
+    /**
+     * @description The cap may have changed — General's value was just written: read it, and wake the listeners when it went up while
+     * somebody waits. A hand edit of `settings.json` is noticed the same way, by the first read that is not a poll's own check-in.
+     */
+    noteLimitMayHaveChanged(): void;
+    /**
+     * @description Be told when a slot may have freed while someone waits for one (a connector polls again at once, instead of at
+     * its next interval). Returns the function that stops the listening.
+     */
+    onSlotFreed(listener: () => void): () => void;
+    /**
+     * @description The request ledger's word that a request closed: a hand-over that is not merely replaced by a newer one of its
+     * conversation may have freed a slot, which wakes the listeners — only while somebody waits. It runs inside the ledger's own
+     * close, so the listeners get the news, not the state: they act after the close completed.
+     */
+    noteRequestClosed(closed: ClosedRequestRecord): void;
+    /**
+     * @description The request ledger's word that the wake-up engine gave up on a request (it stays open, but holds no slot any more):
+     * the same wake-up as a close.
+     */
+    noteRequestWakeStopped(request: Pick<OpenRequestState, 'origin'>): void;
+    private wakeListenersWhileWaiting;
+}
+//# sourceMappingURL=taskAgentSlots.d.ts.map

package/dist/trackers/taskAgentSlots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskAgentSlots.d.ts","sourceRoot":"","sources":["../../src/trackers/taskAgentSlots.ts"],"names":[],"mappings":"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"}