@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/channels/send.d.ts

@@ -1,17 +1,6 @@
-/**
- * Delivery envelope for `agents send`.
- *
- * One primitive: resolve a destination (channel + target), compose text + urls +
- * attachments, hand off to a channel provider. `notify` is the same path with
- * destination defaulted from `humans.yaml` — owner is an address
- * alias (`--to owner`), not a separate stack.
- *
- * Agent control (`agents message`, `sessions inject`) stays outside this module.
- */
 import type { Meta } from '../types.js';
 import type { SendResult } from './registry.js';
 import type { SinkMessageFormat } from '../sink-format.js';
-/** Normalized delivery request after CLI/config resolution. */
 interface SendEnvelope {
     text: string;
     channel: string;
@@ -23,31 +12,15 @@ interface SendEnvelope {
     dryRun?: boolean;
 }
 export interface ResolveSendInput {
-    /**
-     * Body text. Prefer `--text`; positional `[text]` is accepted for compat and
-     * folded in when `--text` is omitted.
-     */
     text?: string;
-    /** Positional `[text]` from commander (legacy). */
     positionalText?: string;
-    /**
-     * Recipient. Channel-specific id, or the alias `owner` which expands to
-     * `notify.owner.{channel,to}`.
-     */
     to?: string;
-    /** Provider/channel name. Required unless `to` is `owner` (or ownerMode). */
     channel?: string;
     thread?: string;
-    /** Local file paths. */
     attachments?: string[];
-    /** Links / remote media refs — appended to the body so every provider sees them. */
     urls?: string[];
     from?: string;
     dryRun?: boolean;
-    /**
-     * When true (a feed owner sink), missing channel/to default to `notify.owner`.
-     * Explicit flags still win.
-     */
     ownerMode?: boolean;
 }
 type ResolveSendResult = {
@@ -57,37 +30,14 @@ type ResolveSendResult = {
     ok: false;
     error: string;
 };
-/** True when the destination token means “the configured owner”. */
 export declare function isOwnerAlias(to: string | undefined): boolean;
-/** Compose body + optional URL lines (skip urls already present in the body). */
 export declare function composeSendText(text: string, urls?: string[]): string;
-/**
- * Read the owner destination. humans.yaml is canonical; notify.owner remains a
- * migration fallback for installations that have not run the schema migration.
- */
 export declare function readOwnerDest(meta: Meta): {
     channel: string;
     to: string;
 } | null;
-/**
- * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
- * no I/O, no provider registration — so unit tests do not need a real PATH.
- */
 export declare function resolveSendEnvelope(input: ResolveSendInput, meta: Meta): ResolveSendResult;
-/**
- * Register providers, resolve transport, deliver. Used by the CLI and by any
- * internal caller that already has a resolved envelope.
- */
 export declare function deliverEnvelope(envelope: SendEnvelope, meta: Meta): Promise<SendResult>;
-/**
- * Resolve + deliver in one step (CLI happy path).
- *
- * `ownerCompose`, when given, shapes the body PER owner destination on the
- * policy fan-out — Slack gets `mrkdwn` labeled links, iMessage stays plain
- * (PHNX-3698). Only the owner-policy path uses it; a direct `--channel`/`--to`
- * send is delivered verbatim. The envelope's own `text` remains the plain
- * default (validation, `--json`, dry-run display).
- */
 export declare function sendMessage(input: ResolveSendInput, meta: Meta, ownerCompose?: (format: SinkMessageFormat) => string): Promise<{
     result: SendResult;
     envelope: SendEnvelope;

package/dist/lib/channels/send.js

@@ -3,11 +3,9 @@ import { registerBuiltinProviders } from './providers/index.js';
 import { resolveTransport } from './resolve.js';
 import { sendToOwner } from '../notify.js';
 const OWNER_ALIAS = 'owner';
-/** True when the destination token means “the configured owner”. */
 export function isOwnerAlias(to) {
     return (to ?? '').trim().toLowerCase() === OWNER_ALIAS;
 }
-/** Compose body + optional URL lines (skip urls already present in the body). */
 export function composeSendText(text, urls) {
     const body = text.trim();
     const extra = (urls ?? [])
@@ -18,10 +16,6 @@ export function composeSendText(text, urls) {
         return body;
     return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
 }
-/**
- * Read the owner destination. humans.yaml is canonical; notify.owner remains a
- * migration fallback for installations that have not run the schema migration.
- */
 export function readOwnerDest(meta) {
     const canonical = getOwnerNotifyFromHumans();
     if (canonical)
@@ -30,10 +24,6 @@ export function readOwnerDest(meta) {
     const to = meta.notify?.owner?.to?.trim();
     return channel && to ? { channel, to } : null;
 }
-/**
- * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
- * no I/O, no provider registration — so unit tests do not need a real PATH.
- */
 export function resolveSendEnvelope(input, meta) {
     const positional = (input.positionalText ?? '').trim();
     const flagged = (input.text ?? '').trim();
@@ -52,8 +42,6 @@ export function resolveSendEnvelope(input, meta) {
             error: 'Message is empty. Pass --text "…", a positional message, and/or --url.',
         };
     }
-    // Owner defaults fill only missing fields (and expand the bare "owner" alias).
-    // humans.yaml is the canonical source. Explicit --channel/--to always win.
     let channel = (input.channel ?? '').trim();
     let to = (input.to ?? '').trim();
     const usedOwnerAlias = isOwnerAlias(to);
@@ -92,10 +80,6 @@ export function resolveSendEnvelope(input, meta) {
         },
     };
 }
-/**
- * Register providers, resolve transport, deliver. Used by the CLI and by any
- * internal caller that already has a resolved envelope.
- */
 export async function deliverEnvelope(envelope, meta) {
     registerBuiltinProviders();
     const provider = resolveTransport(envelope.channel, meta);
@@ -108,15 +92,6 @@ export async function deliverEnvelope(envelope, meta) {
         dryRun: envelope.dryRun,
     });
 }
-/**
- * Resolve + deliver in one step (CLI happy path).
- *
- * `ownerCompose`, when given, shapes the body PER owner destination on the
- * policy fan-out — Slack gets `mrkdwn` labeled links, iMessage stays plain
- * (PHNX-3698). Only the owner-policy path uses it; a direct `--channel`/`--to`
- * send is delivered verbatim. The envelope's own `text` remains the plain
- * default (validation, `--json`, dry-run display).
- */
 export async function sendMessage(input, meta, ownerCompose) {
     const resolved = resolveSendEnvelope(input, meta);
     if (!resolved.ok)

package/dist/lib/checkpoint.d.ts

@@ -1,54 +1,18 @@
-/**
- * Harness-level loop checkpoint (issue #332).
- *
- * A checkpoint is the durable harness state for a `--loop` run: it records the
- * iteration count, the pinned session id, the prompt being re-injected, and the
- * loop config — everything `--resume-checkpoint` needs to continue a run that a
- * SIGTERM, timeout, or machine sleep killed mid-flight.
- *
- * This is NOT provider-side state. `--session-id` resumes Claude's *conversation*
- * (server-side); a checkpoint resumes the *harness* (iteration count, loop
- * variables, prompt chain) — the part Claude's own resume cannot recover.
- *
- * Atomic write (temp + rename) mirrors `writeRunMeta` in routines.ts so a crash
- * mid-write never leaves a half-written checkpoint that `readCheckpoint` would
- * choke on. `readCheckpoint` returns null on a missing or corrupt file (mirrors
- * `readRunMeta`) — a corrupt checkpoint is a "start fresh", never a throw.
- */
 import type { AgentId } from './types.js';
 import type { LoopConfig, LoopSignal } from './loop.js';
-/** Durable harness state for a looped run, serialized to checkpoint.json. */
 export interface Checkpoint {
-    /** runId == the run directory name under getRunsDir(). */
     id: string;
     agent: AgentId;
     version?: string;
-    /** The prompt re-injected each iteration. */
     prompt?: string;
-    /** Pinned Claude session id so a resume continues the same conversation. */
     sessionId?: string;
-    /** Iterations COMPLETED so far. A resume starts at iteration + 1. */
     iteration: number;
-    /** The loop config governing termination. */
     loop: LoopConfig;
-    /** Last loop-signal read, if any (for audit / resume context). */
     loopSignal?: LoopSignal;
-    /** Cumulative tokens consumed across all iterations so far. */
     cumulativeTokens?: number;
     createdAt: string;
     updatedAt: string;
 }
-/** Path to a run's checkpoint file: <runsDir>/<runId>/checkpoint.json. */
 export declare function checkpointPath(runId: string): string;
-/**
- * Write a checkpoint atomically (temp file + rename). The rename is atomic on a
- * single filesystem, so a reader never observes a partially written file.
- * Mirrors the durable-write contract of `writeRunMeta`.
- */
 export declare function writeCheckpoint(c: Checkpoint, file?: string): void;
-/**
- * Read a checkpoint from disk. Returns null if the file is missing or its
- * contents are not valid JSON — corruption means "no resumable state", which
- * the caller treats as a fresh start. Mirrors `readRunMeta`.
- */
 export declare function readCheckpoint(file: string): Checkpoint | null;

package/dist/lib/checkpoint.js

@@ -1,32 +1,9 @@
-/**
- * Harness-level loop checkpoint (issue #332).
- *
- * A checkpoint is the durable harness state for a `--loop` run: it records the
- * iteration count, the pinned session id, the prompt being re-injected, and the
- * loop config — everything `--resume-checkpoint` needs to continue a run that a
- * SIGTERM, timeout, or machine sleep killed mid-flight.
- *
- * This is NOT provider-side state. `--session-id` resumes Claude's *conversation*
- * (server-side); a checkpoint resumes the *harness* (iteration count, loop
- * variables, prompt chain) — the part Claude's own resume cannot recover.
- *
- * Atomic write (temp + rename) mirrors `writeRunMeta` in routines.ts so a crash
- * mid-write never leaves a half-written checkpoint that `readCheckpoint` would
- * choke on. `readCheckpoint` returns null on a missing or corrupt file (mirrors
- * `readRunMeta`) — a corrupt checkpoint is a "start fresh", never a throw.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getRunsDir } from './state.js';
-/** Path to a run's checkpoint file: <runsDir>/<runId>/checkpoint.json. */
 export function checkpointPath(runId) {
     return path.join(getRunsDir(), runId, 'checkpoint.json');
 }
-/**
- * Write a checkpoint atomically (temp file + rename). The rename is atomic on a
- * single filesystem, so a reader never observes a partially written file.
- * Mirrors the durable-write contract of `writeRunMeta`.
- */
 export function writeCheckpoint(c, file) {
     const target = file ?? checkpointPath(c.id);
     fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -34,11 +11,6 @@ export function writeCheckpoint(c, file) {
     fs.writeFileSync(tmp, JSON.stringify(c, null, 2), 'utf-8');
     fs.renameSync(tmp, target);
 }
-/**
- * Read a checkpoint from disk. Returns null if the file is missing or its
- * contents are not valid JSON — corruption means "no resumable state", which
- * the caller treats as a fresh start. Mirrors `readRunMeta`.
- */
 export function readCheckpoint(file) {
     if (!fs.existsSync(file))
         return null;

package/dist/lib/claude-account-token.d.ts

@@ -1,113 +1,15 @@
 import { ReservedBundleWrongBackendError } from './reserved-stores.js';
 import type { DeviceAccountSlot, NativeAccountRecord } from './types.js';
-/**
- * Reserved FILE-BASED secrets bundle holding long-lived, non-rotating Claude
- * setup-tokens. Usage/probe reads authenticate with these instead of Claude
- * Code's ACL-bound login item, so they never pop Touch ID. Keyed strictly
- * per-account (`CLAUDE_CODE_OAUTH_TOKEN_<slug>` from the account email) — never a
- * bare key, so one account's token can't be misapplied to another in a
- * multi-account fleet.
- */
-/** Alias of the reserved-store name so mint/seed shares one source of truth. */
 export declare const AUTH_BUNDLE = "auth";
 export { ReservedBundleWrongBackendError };
-/** Drop every memoized setup-token; called after this process seeds or rotates one. */
 export declare function invalidateClaudeSetupTokenCache(): void;
-/** True only for a clean, single-line `sk-ant-oat01-…` token — see {@link SETUP_TOKEN_RE}. */
 export declare function isValidClaudeSetupToken(value: string): boolean;
-/** The per-account key an email maps to inside the `auth` bundle. */
 export declare function claudeAccountTokenKey(account: string): string;
-/** Signed-in account email for a version home, from `.claude.json` (no keychain). */
 export declare function readClaudeAccountEmail(home?: string): string | null;
-/**
- * Resolve a long-lived `claude setup-token` for the account signed into `home`
- * from the reserved FILE-BASED `auth` bundle. Returns the token or null. Reads
- * ONLY when the bundle is file-backed (never keychain), so this path itself can
- * never trigger a Touch ID prompt — that is the entire point: usage/probe reads
- * authenticate with the shareable setup-token, not the ACL-bound login item.
- */
 export declare function resolveClaudeSetupToken(home?: string): string | null;
-/**
- * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
- * any version home's `.claude.json`. This is what lets worker-slot provisioning
- * seed a headless worker home that has never had an interactive login: the
- * account's non-rotating setup-token is already fleet-synced in the file-based
- * `auth` bundle, keyed by email ({@link claudeAccountTokenKey}), so we can write
- * the home's `.oauth_token` from it without the circular
- * "read the home's email to resolve the home's token" dependency that
- * {@link resolveClaudeSetupToken} has. Same file-backed-only, fail-closed,
- * fingerprint-stable read as the home-keyed path — it is the shared core.
- *
- * `cacheKey` scopes the process-local token cache; callers pass a version home
- * so a home-keyed and email-keyed read of the same account share nothing stale.
- */
 export declare function resolveClaudeSetupTokenForEmail(email: string, cacheKey?: string): string | null;
-/**
- * Seed a keychain-less Linux worker's Claude version-home identity so an account's
- * fleet-synced setup-token resolves for it. A worker home never had an interactive
- * browser login, so its `.claude.json` carries no `oauthAccount.emailAddress` and
- * the account reads "signed out" even though its non-rotating setup-token is present
- * in the `auth` bundle. This writes ONLY the descriptive identity (the email), merged
- * into both `.claude.json` locations Claude Code reads, preserving every other field.
- * It never copies a rotating OAuth credential (`.credentials.json`) — the setup-token
- * stays the credential of record.
- */
-/**
- * Write a Claude worker slot's `.oauth_token` (0600) from a durable setup-token,
- * the way the pre-slot worker home was provisioned. Refuses a malformed token so
- * a corrupt bundle entry can never reach the auth header (see {@link SETUP_TOKEN_RE}).
- * `home` is the slot dir; the claude adapter shim reads `$CLAUDE_CONFIG_DIR/.oauth_token`
- * where `CLAUDE_CONFIG_DIR` is `<home>/.claude`. Returns the written path.
- */
 export declare function writeClaudeWorkerOauthToken(home: string, token: string): string;
-/**
- * Read one non-rotating credential value from a reserved store by its storage
- * key. Returns null when the bundle or key is absent. Used to materialize a
- * worker slot from a synced durable credential (setup-token / API key).
- *
- * A reserved `__<harness>__` store is file-backed by design (headless, fleet-
- * shareable) and its item is read directly, symmetric with how it is written —
- * `readAndResolveBundleEnv`'s name validation does not yet accept a reserved
- * name on the READ path (a secrets-track seam; see the PR body). A non-reserved
- * bundle (the legacy `auth` alias, a provider bundle) goes through the normal
- * resolver so refs/expiry/lease gates still apply.
- */
 export declare function readReservedCredential(bundle: string, key: string): string | null;
-/**
- * Materialize a worker slot for a portable account from its synced durable
- * credential (PHNX-3940 T6 — the generalization of the pre-slot Claude worker-home
- * provisioning). Creates the HOME-shaped slot dir (T1 `ensureSlot`), then, for a
- * durable harness, writes the credential into it the way the Claude worker home is
- * provisioned today: for `claude`, the setup-token → `.oauth_token` (0600) + the
- * seeded identity email (the read-side join in agent-spec then completes the uuids
- * from the registry row). API-key harnesses need no file — the key is injected at
- * spawn from the reserved store (T5) — so their slot is created and recorded
- * `durable` with no write. A per-device harness (`worker: 'none'`) gets a
- * `per-device` slot and no credential — it logs in per box.
- *
- * This is worker-side reconciliation: it runs on the box where the key landed and
- * NEVER transports anything (the SSH push that delivered the key is the daemon's
- * job — invariant 1). Fails loud when a durable claude account has no resolvable
- * token on this device rather than recording a slot that cannot authenticate.
- */
 export declare function provisionWorkerSlot(account: NativeAccountRecord): DeviceAccountSlot;
-/**
- * True when a claude worker slot carries everything provisioning seeds: the
- * identity email AND the completed-onboarding flag. A slot provisioned before
- * onboarding was seeded answers false, so the daemon's reconcile re-seeds it.
- */
 export declare function isClaudeWorkerHomeSeeded(home: string): boolean;
-/**
- * Seed a worker slot's `.claude.json` (both locations Claude Code reads) with
- * the account identity AND `hasCompletedOnboarding`. A worker never has a human
- * at it, so nothing else can complete Claude Code's first-run onboarding (theme
- * picker, "Let's get started"); without the flag every slot launch re-onboarded.
- * Everything else in the document is preserved.
- *
- * Without an email only the onboarding flag is seeded: a provider (setup-token)
- * launch runs in the shared version home, whose identity belongs to whatever
- * native login lives there, so it must not be rewritten. A document already
- * carrying the requested state is left untouched, so a launch never rewrites a
- * config Claude Code is using.
- */
 export declare function seedClaudeWorkerHomeIdentity(versionHome: string, email?: string): void;