@borgee/agents-host 0.2.31 → 0.2.32

package/dist/update/package-manager.js

@@ -0,0 +1,137 @@
+import spawn from 'cross-spawn';
+import { dirname, join } from 'node:path';
+import { isSemanticVersion } from './semantic-version.js';
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+export class PackageManagerAbsentError extends Error {
+}
+/**
+ * Runs a package-manager command and returns its stdout. stderr is dropped:
+ * every manager writes advisory noise there (pnpm's npmrc warnings, npm's
+ * update banner), and none of it is part of the answer.
+ *
+ * The deadline kills the child rather than merely rejecting. That is the whole
+ * reason the registry is reached through a subprocess: a resolver that swallows
+ * DNS queries hangs inside `getaddrinfo`, which has no cancellation, so the
+ * same lookup done in-process would keep this process alive long past its
+ * budget. A killed child takes its hung syscall with it.
+ */
+function runCommandProcess(command, args, timeoutMs) {
+    return new Promise((resolveOutput, rejectCommand) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        let bytes = 0;
+        let timedOut = false;
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            bytes += Buffer.byteLength(chunk, 'utf8');
+            if (bytes > MAX_COMMAND_OUTPUT_BYTES) {
+                child.kill('SIGKILL');
+                return;
+            }
+            stdout += chunk;
+        });
+        child.on('error', (error) => {
+            clearTimeout(deadline);
+            if (error.code === 'ENOENT') {
+                rejectCommand(new PackageManagerAbsentError(`${command} is not on PATH`));
+                return;
+            }
+            rejectCommand(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(deadline);
+            if (timedOut) {
+                rejectCommand(new Error(`${command} ${args.join(' ')} exceeded its ${timeoutMs}ms deadline`));
+                return;
+            }
+            if (code !== 0) {
+                rejectCommand(new Error(`${command} ${args.join(' ')} exited with code ${code}`));
+                return;
+            }
+            resolveOutput(stdout.trim());
+        });
+    });
+}
+/**
+ * How each manager reports the directory its global installs land in. Verified
+ * against the real CLIs rather than inferred from paths, because every
+ * path-shaped rule we tried missed at least one layout: pnpm links a dependency
+ * out of a virtual store, yarn v1 capitalises `%LOCALAPPDATA%\Yarn\Data` on
+ * Windows, and bun relocates everything under `BUN_INSTALL`.
+ *
+ * `npm root -g` and `pnpm root -g` already name the `node_modules` directory.
+ * `yarn global dir` names its parent. `bun pm bin -g` names `<BUN_INSTALL>/bin`,
+ * whose sibling `install/global` is the root bun installs into.
+ */
+const GLOBAL_ROOT_QUERIES = {
+    npm: { args: ['root', '-g'], toRootDir: (output) => output },
+    pnpm: { args: ['root', '-g'], toRootDir: (output) => output },
+    yarn: { args: ['global', 'dir'], toRootDir: (output) => join(output, 'node_modules') },
+    bun: {
+        args: ['pm', 'bin', '-g'],
+        toRootDir: (output) => join(dirname(output), 'install', 'global', 'node_modules'),
+    },
+};
+const GLOBAL_INSTALL_ARGV = {
+    npm: ['install', '-g'],
+    pnpm: ['add', '-g'],
+    yarn: ['global', 'add'],
+    bun: ['add', '-g'],
+};
+export function buildGlobalInstallArgv(packageManager, packageSpec) {
+    return { command: packageManager, args: [...GLOBAL_INSTALL_ARGV[packageManager], packageSpec] };
+}
+/**
+ * Where `packageManager` puts its global installs, or `null` when that manager
+ * is not installed on this machine.
+ */
+export async function readGlobalRootDir(packageManager, timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    const query = GLOBAL_ROOT_QUERIES[packageManager];
+    try {
+        const output = await runCommand(packageManager, [...query.args], timeoutMs);
+        return output.length > 0 ? query.toRootDir(output) : null;
+    }
+    catch (error) {
+        if (error instanceof PackageManagerAbsentError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * The registry npm resolves for this working directory. Asking npm rather than
+ * reading `npm_config_registry` ourselves is what makes project-level and user
+ * `.npmrc` files count, which is also where a private registry's credentials
+ * live.
+ */
+export async function readConfiguredRegistry(timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    return runCommand('npm', ['config', 'get', 'registry'], timeoutMs);
+}
+/**
+ * Newest published release of `packageName`, as npm resolves it.
+ *
+ * `npm view` rather than a hand-rolled request to the registry: npm is the
+ * reference implementation of everything around that request — `.npmrc`
+ * discovery, scoped auth tokens, proxies, custom CAs, retries, mirrors — and
+ * all four supported managers publish to and read from the same registry, so
+ * the answer does not depend on which one owns the install.
+ */
+export async function readPublishedVersion(packageName, timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    const output = await runCommand('npm', ['view', packageName, 'version', '--json'], timeoutMs);
+    const parsed = JSON.parse(output);
+    // Whatever comes back here ends up as an npm install spec, so anything that
+    // is not a plain version — a git URL, a tarball URL, a dist-tag — would let a
+    // hostile registry point the install at a source npm never vetted.
+    if (typeof parsed !== 'string' || !isSemanticVersion(parsed)) {
+        throw new Error(`npm view reported no semantic version for ${packageName}`);
+    }
+    return parsed.trim();
+}

package/dist/update/semantic-version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Semantic-version precedence for update decisions. Implemented here rather
+ * than pulled in as a dependency because the published CLI needs exactly one
+ * comparison, and precedence is fully specified by https://semver.org/#spec-item-11.
+ */
+export declare function isSemanticVersion(value: string): boolean;
+export declare function isNewerSemanticVersion(candidate: string, baseline: string): boolean;

package/dist/update/semantic-version.js

@@ -0,0 +1,76 @@
+/**
+ * Semantic-version precedence for update decisions. Implemented here rather
+ * than pulled in as a dependency because the published CLI needs exactly one
+ * comparison, and precedence is fully specified by https://semver.org/#spec-item-11.
+ */
+const SEMANTIC_VERSION_PATTERN = /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:-(?<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/u;
+const NUMERIC_IDENTIFIER_PATTERN = /^(?:0|[1-9]\d*)$/u;
+function parseSemanticVersion(value) {
+    const match = SEMANTIC_VERSION_PATTERN.exec(value.trim());
+    if (!match?.groups) {
+        throw new Error(`Not a semantic version: ${value}`);
+    }
+    const { major, minor, patch, prerelease } = match.groups;
+    return {
+        release: [major, minor, patch],
+        prerelease: prerelease === undefined ? [] : prerelease.split('.'),
+    };
+}
+export function isSemanticVersion(value) {
+    return SEMANTIC_VERSION_PATTERN.test(value.trim());
+}
+/**
+ * Semver puts no upper bound on numeric identifiers, so they are compared as
+ * digit strings: without leading zeroes the longer string is always the larger
+ * number. `parseInt` would silently collapse anything past 2^53.
+ */
+function compareNumericIdentifiers(left, right) {
+    if (left.length !== right.length) {
+        return left.length < right.length ? -1 : 1;
+    }
+    return compareStrings(left, right);
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function comparePrereleaseIdentifier(left, right) {
+    const leftIsNumeric = NUMERIC_IDENTIFIER_PATTERN.test(left);
+    const rightIsNumeric = NUMERIC_IDENTIFIER_PATTERN.test(right);
+    if (leftIsNumeric && rightIsNumeric) {
+        return compareNumericIdentifiers(left, right);
+    }
+    if (leftIsNumeric) {
+        return -1;
+    }
+    if (rightIsNumeric) {
+        return 1;
+    }
+    return compareStrings(left, right);
+}
+function comparePrerelease(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        // A prerelease ranks below the release it leads up to.
+        return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+    }
+    for (let index = 0; index < Math.min(left.length, right.length); index++) {
+        const identifierOrder = comparePrereleaseIdentifier(left[index], right[index]);
+        if (identifierOrder !== 0) {
+            return identifierOrder;
+        }
+    }
+    return Math.sign(left.length - right.length);
+}
+function compareSemanticVersions(left, right) {
+    const parsedLeft = parseSemanticVersion(left);
+    const parsedRight = parseSemanticVersion(right);
+    for (let index = 0; index < parsedLeft.release.length; index++) {
+        const releaseOrder = compareNumericIdentifiers(parsedLeft.release[index], parsedRight.release[index]);
+        if (releaseOrder !== 0) {
+            return releaseOrder;
+        }
+    }
+    return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
+}
+export function isNewerSemanticVersion(candidate, baseline) {
+    return compareSemanticVersions(candidate, baseline) > 0;
+}

package/dist/update/update-command.d.ts

@@ -0,0 +1,9 @@
+import { type PackageInstallation, type PackageLocation } from './package-installation.js';
+export interface RunUpdateCommandDeps {
+    resolveLocation?: () => Promise<PackageLocation>;
+    classifyInstallation?: (location: PackageLocation) => Promise<PackageInstallation>;
+    resolveLatestVersion?: (packageName: string, timeoutMs: number) => Promise<string>;
+    runInstall?: (command: string, args: string[]) => Promise<number>;
+    logger?: Pick<Console, 'log'>;
+}
+export declare function runUpdateCommand(deps?: RunUpdateCommandDeps): Promise<void>;

package/dist/update/update-command.js

@@ -0,0 +1,55 @@
+import spawn from 'cross-spawn';
+import { classifyPackageInstallation, resolvePackageLocation, } from './package-installation.js';
+import { buildGlobalInstallArgv, readPublishedVersion } from './package-manager.js';
+import { isNewerSemanticVersion } from './semantic-version.js';
+const UPDATE_LOOKUP_TIMEOUT_MS = 30000;
+function runInstallProcess(command, args) {
+    return new Promise((resolveExitCode, rejectInstall) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.on('error', rejectInstall);
+        child.on('close', (code, signal) => {
+            if (signal !== null) {
+                rejectInstall(new Error(`${command} ${args.join(' ')} was terminated by ${signal}`));
+                return;
+            }
+            resolveExitCode(code ?? 0);
+        });
+    });
+}
+/**
+ * Only a globally installed CLI owns its own version. A source checkout is
+ * updated with git, and rewriting a project's dependency behind its manifest is
+ * that project's decision, not this command's.
+ */
+function assertSelfUpdatableInstallation(installation) {
+    if (installation.kind === 'source-checkout') {
+        throw new Error(`${installation.packageName} is running from a source checkout at ${installation.packageRootDir}; update that checkout with git instead of the npm registry`);
+    }
+    if (installation.kind === 'project') {
+        throw new Error(`${installation.packageName} is installed as a dependency of ${installation.projectRootDir}; update it through that project's manifest instead of self-updating`);
+    }
+}
+export async function runUpdateCommand(deps = {}) {
+    const logger = deps.logger ?? console;
+    const resolveLocation = deps.resolveLocation ?? (() => resolvePackageLocation());
+    const classifyInstallation = deps.classifyInstallation ?? ((location) => classifyPackageInstallation(location));
+    const resolveLatestVersion = deps.resolveLatestVersion ?? readPublishedVersion;
+    const runInstall = deps.runInstall ?? runInstallProcess;
+    const installation = await classifyInstallation(await resolveLocation());
+    assertSelfUpdatableInstallation(installation);
+    const latestVersion = await resolveLatestVersion(installation.packageName, UPDATE_LOOKUP_TIMEOUT_MS);
+    // Ordering rather than inequality: a machine running ahead of `latest` — a
+    // prerelease, or a release that was unpublished — must not be walked backwards.
+    if (!isNewerSemanticVersion(latestVersion, installation.version)) {
+        logger.log(`[agents-host] already on ${installation.packageName}@${installation.version}`);
+        return;
+    }
+    const { command, args } = buildGlobalInstallArgv(installation.packageManager, `${installation.packageName}@${latestVersion}`);
+    logger.log(`[agents-host] updating ${installation.packageName} ${installation.version} -> ${latestVersion}`);
+    logger.log(`[agents-host] running: ${command} ${args.join(' ')}`);
+    const exitCode = await runInstall(command, args);
+    if (exitCode !== 0) {
+        throw new Error(`${command} ${args.join(' ')} exited with code ${exitCode}`);
+    }
+    logger.log(`[agents-host] updated to ${installation.packageName}@${latestVersion}`);
+}

package/dist/update/update-notice.d.ts

@@ -0,0 +1,39 @@
+import { type LoggerLike } from '../debug.js';
+import { type PackageInstallation, type PackageLocation } from './package-installation.js';
+export declare const DISABLE_UPDATE_CHECK_ENV = "AGENTS_HOST_DISABLE_UPDATE_CHECK";
+export interface AvailableUpdate {
+    installation: PackageInstallation;
+    latestVersion: string;
+}
+export interface UpdateCheckOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export interface UpdateCheckDeps {
+    resolveLocation?: () => Promise<PackageLocation>;
+    classifyInstallation?: (location: PackageLocation) => Promise<PackageInstallation>;
+    readRegistry?: (timeoutMs: number) => Promise<string>;
+    readLatestVersion?: (packageName: string, timeoutMs: number) => Promise<string>;
+    readCache?: (path: string) => Promise<string>;
+    writeCache?: (path: string, contents: string) => Promise<void>;
+    now?: () => number;
+    logger?: LoggerLike;
+}
+export declare function isUpdateCheckDisabled(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolves the newest published release for the running installation, or `null`
+ * when there is nothing worth telling the operator.
+ *
+ * Source checkouts never check: their version is whatever the working tree
+ * says, and `agents-host update` is the wrong advice for a git tree. That is
+ * settled from the path alone, so `pnpm dev` never spawns a package manager.
+ * Which manager owns a real install is only asked once there is a notice to
+ * word, so a start with nothing to report never pays for that either.
+ */
+export declare function resolveAvailableUpdate(options?: UpdateCheckOptions, deps?: UpdateCheckDeps): Promise<AvailableUpdate | null>;
+/**
+ * Startup-path entry point. The notice is advisory, so every failure below it —
+ * offline machine, unreachable registry, unreadable cache — is logged in debug
+ * mode and then dropped: a registry outage must never keep an agent from
+ * starting. It writes to stderr so machine-readable stdout stays clean.
+ */
+export declare function emitUpdateNotice(options?: UpdateCheckOptions, deps?: UpdateCheckDeps): Promise<void>;

package/dist/update/update-notice.js

@@ -0,0 +1,161 @@
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+import { HostLogger, resolveAgentsHostDebugMode } from '../debug.js';
+import { resolveUpdateCheckCachePath } from '../state-paths.js';
+import { classifyPackageInstallation, resolvePackageLocation, } from './package-installation.js';
+import { readConfiguredRegistry, readPublishedVersion } from './package-manager.js';
+import { isNewerSemanticVersion, isSemanticVersion } from './semantic-version.js';
+export const DISABLE_UPDATE_CHECK_ENV = 'AGENTS_HOST_DISABLE_UPDATE_CHECK';
+const UPDATE_CHECK_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 5000;
+/**
+ * Every failure under the update check is swallowed, so `AGENTS_HOST_DEBUG=1`
+ * is the only way an operator can find out why a notice never appeared.
+ */
+function createUpdateCheckLogger(env, deps) {
+    return new HostLogger({ debug: resolveAgentsHostDebugMode(false, env), logger: deps.logger });
+}
+async function readCacheFile(path) {
+    return fs.readFile(path, 'utf8');
+}
+async function writeCacheFile(path, contents) {
+    await fs.mkdir(dirname(path), { recursive: true });
+    // Write-then-rename: a concurrent start never observes a half-written entry,
+    // and a symlink planted at the cache path is replaced rather than followed.
+    const tempPath = `${path}.${process.pid}.tmp`;
+    try {
+        await fs.writeFile(tempPath, contents, { encoding: 'utf8', mode: 0o600 });
+        await fs.rename(tempPath, path);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true });
+        throw error;
+    }
+}
+function parseCacheEntry(contents) {
+    const parsed = JSON.parse(contents);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('Update check cache is not an object');
+    }
+    const { checkedAt, registry, latestVersion } = parsed;
+    if (typeof checkedAt !== 'number' || !Number.isFinite(checkedAt)) {
+        throw new Error('Update check cache carries no checkedAt timestamp');
+    }
+    if (typeof registry !== 'string' || registry.length === 0) {
+        throw new Error('Update check cache carries no registry');
+    }
+    if (latestVersion === null) {
+        return { checkedAt, registry, latestVersion: null };
+    }
+    if (typeof latestVersion !== 'string' || !isSemanticVersion(latestVersion)) {
+        throw new Error('Update check cache carries no semantic latestVersion');
+    }
+    return { checkedAt, registry, latestVersion };
+}
+export function isUpdateCheckDisabled(env) {
+    return env[DISABLE_UPDATE_CHECK_ENV]?.trim() === '1';
+}
+/**
+ * Resolves the newest published release for the running installation, or `null`
+ * when there is nothing worth telling the operator.
+ *
+ * Source checkouts never check: their version is whatever the working tree
+ * says, and `agents-host update` is the wrong advice for a git tree. That is
+ * settled from the path alone, so `pnpm dev` never spawns a package manager.
+ * Which manager owns a real install is only asked once there is a notice to
+ * word, so a start with nothing to report never pays for that either.
+ */
+export async function resolveAvailableUpdate(options = {}, deps = {}) {
+    const env = options.env ?? process.env;
+    if (isUpdateCheckDisabled(env)) {
+        return null;
+    }
+    const resolveLocation = deps.resolveLocation ?? (() => resolvePackageLocation());
+    const location = await resolveLocation();
+    if (location.nodeModulesOwnerDir === null) {
+        return null;
+    }
+    const latestVersion = await resolveLatestPublishedVersion(env, location, deps);
+    if (latestVersion === null || !isNewerSemanticVersion(latestVersion, location.version)) {
+        return null;
+    }
+    const classifyInstallation = deps.classifyInstallation ??
+        ((candidate) => classifyPackageInstallation(candidate));
+    return { installation: await classifyInstallation(location), latestVersion };
+}
+async function resolveLatestPublishedVersion(env, location, deps) {
+    const now = deps.now ?? Date.now;
+    const readCache = deps.readCache ?? readCacheFile;
+    const writeCache = deps.writeCache ?? writeCacheFile;
+    const readRegistry = deps.readRegistry ?? readConfiguredRegistry;
+    const readLatestVersion = deps.readLatestVersion ?? readPublishedVersion;
+    const logger = createUpdateCheckLogger(env, deps);
+    const cachePath = resolveUpdateCheckCachePath(env);
+    const [cached, registry] = await Promise.all([
+        readCache(cachePath)
+            .then(parseCacheEntry)
+            .catch((error) => {
+            // A missing or damaged advisory cache only costs one registry request.
+            logger.debugError('update check cache unreadable', error);
+            return null;
+        }),
+        readRegistry(UPDATE_CHECK_TIMEOUT_MS),
+    ]);
+    const checkedAt = now();
+    if (cached !== null && cached.registry === registry) {
+        // An entry stamped in the future — a clock that has since been corrected,
+        // or a poisoned cache — would otherwise stay "fresh" forever and pin the
+        // operator on a stale release, so only an age inside the window counts.
+        const age = checkedAt - cached.checkedAt;
+        if (age >= 0 && age < UPDATE_CHECK_CACHE_TTL_MS) {
+            return cached.latestVersion;
+        }
+    }
+    const persist = (latestVersion) => writeCache(cachePath, `${JSON.stringify({ checkedAt, registry, latestVersion })}\n`).catch((error) => {
+        logger.debugError('update check cache not persisted', error);
+    });
+    let latestVersion;
+    try {
+        latestVersion = await readLatestVersion(location.packageName, UPDATE_CHECK_TIMEOUT_MS);
+    }
+    catch (error) {
+        // Record the failed attempt: an unreachable registry must cost the deadline
+        // once per TTL, not on every single start.
+        await persist(null);
+        throw error;
+    }
+    await persist(latestVersion);
+    return latestVersion;
+}
+function renderUpdateNotice(update) {
+    const { installation, latestVersion } = update;
+    const headline = `update available: ${installation.version} -> ${latestVersion}`;
+    if (installation.kind === 'project') {
+        return [
+            headline,
+            `update ${installation.packageName} in ${installation.projectRootDir} to pick it up`,
+        ];
+    }
+    return [headline, 'run `agents-host update` to install it'];
+}
+/**
+ * Startup-path entry point. The notice is advisory, so every failure below it —
+ * offline machine, unreachable registry, unreadable cache — is logged in debug
+ * mode and then dropped: a registry outage must never keep an agent from
+ * starting. It writes to stderr so machine-readable stdout stays clean.
+ */
+export async function emitUpdateNotice(options = {}, deps = {}) {
+    const logger = createUpdateCheckLogger(options.env ?? process.env, deps);
+    try {
+        const update = await resolveAvailableUpdate(options, deps);
+        if (update === null) {
+            return;
+        }
+        for (const line of renderUpdateNotice(update)) {
+            logger.error(line);
+        }
+    }
+    catch (error) {
+        logger.debugError('update check failed', error);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -48,6 +48,8 @@
     "typecheck": "tsc --noEmit",
     "pretest": "pnpm --filter @borgee/plugin-sdk build",
     "test": "vitest run --testTimeout=10000",
+    "pretest:e2e": "pnpm --filter @borgee/plugin-sdk build",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts --testTimeout=120000",
     "pretypecheck": "pnpm --filter @borgee/plugin-sdk build"
   }
 }

package/skills/borgee-agent/SKILL.md

@@ -23,10 +23,12 @@ Use one of the packaged local CLIs to inspect the current channel bootstrap payl
 - Python auxiliary mention: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-mention user-id --body "Need review from <@user-id>"`
 - Python auxiliary reply: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-message --body "Following up here" --reply-to message-id`
 
-When the injected `context.json` includes `taskAssignmentContext.active: true`, the same CLIs also expose the task-thread compatibility surface:
+The same CLIs also expose the task commands. Which ones apply depends on where the turn runs, which the injected `context.json` reports through `taskAssignmentContext`:
 
-- In ordinary parent channels: `--create-task`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`
-- In task-assignment threads: `--get-task` and `--update-task` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--create-task` and `--list-tasks` stay disabled there and must be run from the parent channel
+- Parent channel (no `taskAssignmentContext.active`): `--create-task --title ...`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`, `--read-task-history --task-id ...`
+- Task-assignment thread (`taskAssignmentContext.active: true`): `--get-task` and `--update-task` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--read-task-history --task-id ...` still works for that thread's own task, while `--create-task` and `--list-tasks` stay disabled and must be run from the parent channel
+
+`--read-task-history` reads the messages inside a task's thread and always requires an explicit `--task-id`; inside that task's own thread `--read-history` already reads the same messages, so the turn prompt offers the command in the parent channel only. It accepts the same `--limit` / `--before` / `--after` window as `--read-history` and answers the same not-found error for a task outside the current channel as for a task that does not exist.
 
 The private draft snapshot is read-only, collaboration-scoped, and separate from ordinary public channel messages.
 Auxiliary sends are only for short targeted escalation, reply-thread nudges, or mentions. They must not be used for the main final answer body, which still belongs to AgentsHost.

package/skills/borgee-agent/borgee-agent.mjs

@@ -6,6 +6,11 @@ const TASK_THREAD_COLLECTION_COMMAND_ERROR
   = 'Task assignment threads only support --get-task and --update-task. Create/list tasks belong to the parent channel.';
 const TASK_THREAD_MISSING_TASK_ID_ERROR
   = 'Task assignment thread could not resolve the current task from persisted context or local fallback. Pass --task-id explicitly.';
+// A window value outside the IEEE-754 safe integer range does not survive this CLI: it parses
+// the value to a number and re-stringifies it into the query string, so `1000000000000000000000`
+// leaves as `1e+21` and the gateway's `Number.parseInt(value, 10)` reads it back as `1` — a
+// different page, silently. Both packaged CLIs accept exactly this grammar.
+const INTEGER_ARGUMENT_PATTERN = /^[+-]?[0-9]+$/;
 
 function parseArgs(argv) {
   let contextPath;
@@ -36,10 +41,13 @@ function parseArgs(argv) {
     if (value == null) {
       throw new Error(`Missing value after ${flag}`);
     }
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed)) {
+    if (!INTEGER_ARGUMENT_PATTERN.test(value)) {
       throw new Error(`Invalid integer for ${flag}: ${value}`);
     }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+      throw new Error(`Integer out of range for ${flag}: ${value}`);
+    }
     return parsed;
   }
 
@@ -80,6 +88,10 @@ function parseArgs(argv) {
       setAction('read-history');
       continue;
     }
+    if (arg === '--read-task-history') {
+      setAction('read-task-history');
+      continue;
+    }
     if (arg === '--read-draft') {
       setAction('read-draft');
       continue;
@@ -215,16 +227,39 @@ function ensureVisibleMentions(body, participantIds) {
   );
 }
 
-function explicitTaskIdProvided(options) {
-  return typeof options.taskId === 'string' && options.taskId.trim().length > 0;
+function explicitTaskId(options) {
+  const taskId = typeof options.taskId === 'string' ? options.taskId.trim() : '';
+  return taskId.length > 0 ? taskId : null;
+}
+
+function missingTaskIdError(action) {
+  return new Error(`Missing required --task-id <value> for --${action}`);
+}
+
+function requireExplicitTaskId(action, options) {
+  const taskId = explicitTaskId(options);
+  if (taskId === null) {
+    throw missingTaskIdError(action);
+  }
+  return taskId;
+}
+
+function applyHistoryWindow(url, options) {
+  if (options.limit != null) {
+    url.searchParams.set('limit', String(options.limit));
+  }
+  if (options.before != null) {
+    url.searchParams.set('before', String(options.before));
+  }
+  if (options.after != null) {
+    url.searchParams.set('after', String(options.after));
+  }
 }
 
 function resolveTaskId(payload, action, options) {
-  const explicitTaskId = typeof options.taskId === 'string'
-    ? options.taskId.trim()
-    : '';
-  if (explicitTaskId) {
-    return explicitTaskId;
+  const taskId = explicitTaskId(options);
+  if (taskId !== null) {
+    return taskId;
   }
   if (payload.taskAssignmentContext?.active === true) {
     const persistedTaskId = typeof payload.taskAssignmentContext.currentTaskId === 'string'
@@ -235,7 +270,7 @@ function resolveTaskId(payload, action, options) {
     }
     return null;
   }
-  throw new Error(`Missing required --task-id <value> for --${action}`);
+  throw missingTaskIdError(action);
 }
 
 function resolveGatewayRequest(payload, action, options) {
@@ -256,15 +291,13 @@ function resolveGatewayRequest(payload, action, options) {
       return { url: new URL(`/v1/channels/${encodedChannelId}/me`, gateway.baseUrl), method: 'GET' };
     case 'read-history': {
       const url = new URL(`/v1/channels/${encodedChannelId}/history`, gateway.baseUrl);
-      if (options.limit != null) {
-        url.searchParams.set('limit', String(options.limit));
-      }
-      if (options.before != null) {
-        url.searchParams.set('before', String(options.before));
-      }
-      if (options.after != null) {
-        url.searchParams.set('after', String(options.after));
-      }
+      applyHistoryWindow(url, options);
+      return { url, method: 'GET' };
+    }
+    case 'read-task-history': {
+      const taskId = requireExplicitTaskId(action, options);
+      const url = new URL(`/v1/tasks/${encodeURIComponent(taskId)}/history`, gateway.baseUrl);
+      applyHistoryWindow(url, options);
       return { url, method: 'GET' };
     }
     case 'read-draft': {
@@ -298,7 +331,7 @@ function resolveGatewayRequest(payload, action, options) {
       return { url: new URL(`/v1/channels/${encodedChannelId}/tasks`, gateway.baseUrl), method: 'GET' };
     case 'get-task': {
       const taskId = resolveTaskId(payload, action, options);
-      if (payload.taskAssignmentContext?.active === true && !explicitTaskIdProvided(options)) {
+      if (payload.taskAssignmentContext?.active === true && explicitTaskId(options) === null) {
         return {
           url: new URL(`/v1/channels/${encodedChannelId}/current-task`, gateway.baseUrl),
           method: 'GET',
@@ -322,7 +355,7 @@ function resolveGatewayRequest(payload, action, options) {
       if (Object.keys(requestBody).length === 0) {
         throw new Error('At least one of --status, --assignee-id, --title, or --description is required for --update-task');
       }
-      if (payload.taskAssignmentContext?.active === true && !explicitTaskIdProvided(options)) {
+      if (payload.taskAssignmentContext?.active === true && explicitTaskId(options) === null) {
         return {
           url: new URL(`/v1/channels/${encodedChannelId}/current-task`, gateway.baseUrl),
           method: 'PATCH',