@raidiant/notifai 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rafael Vidaurre
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,76 @@
+# notifai
+
+Send native phone notifications from agents and local programs.
+
+An agent working while you are away has no way to reach you, so it either
+guesses or sits blocked in a terminal nobody is watching. `notifai` gives
+it a way to tell you something finished, and a way to ask you a question
+and get your answer back — as a banner on your phone, with buttons.
+
+```sh
+npm install -g @raidiant/notifai
+notifai init
+```
+
+`init` walks the setup one step at a time and tells you the single next
+thing to do. Run it again after each step; it works out what remains.
+
+## Telling you something happened
+
+```sh
+notifai send --title "Deploy finished" --body "staging, 2m14s" --kind done
+```
+
+Write for a lock screen. The title gets a couple of seconds of attention
+and usually has to carry the whole message; assume the body may never be
+read. Long-form content belongs in `--detail`, which never appears on the
+banner and is shown in the companion app for when you sit down.
+
+## Asking you a question
+
+```sh
+notifai ask "Deploy the migration to production?" --choice "Yes,No"
+```
+
+The agent registers the question, ends its turn, and your answer comes
+back on its next turn. On iPhone the choices are buttons on the banner
+itself.
+
+By default a question stays in your terminal while you are actually at
+the keyboard, and only reaches your devices once you have stepped away —
+a push you are sitting in front of is just noise. `require_idle = false`
+turns that off if you would rather always be notified.
+
+For a harness that cannot resume an idle agent turn, `notifai send
+--reply` blocks and waits for the answer instead.
+
+## Agent harnesses
+
+```sh
+notifai hooks install
+```
+
+Wires question routing into Claude Code, Codex, Cursor or OpenCode. This
+is what lets an agent's question reach your phone without the agent
+having to cooperate — no question detection, no state in a context window
+that compaction will eat.
+
+## Checking it works
+
+```sh
+notifai doctor
+```
+
+Reports every part of the setup and names where to start if something is
+wrong. `--json` for machine-readable output.
+
+## Reference
+
+`notifai <command> --help` is the exhaustive and current flag surface.
+Everything useful is possible non-interactively, so an agent never
+reaches a prompt and hangs.
+
+Source, issues and the security policy:
+<https://github.com/RafaelVidaurre/notifai>
+
+Apache-2.0.

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import type { BeginPairingResponse, CapabilityDocument, CreateMediaUploadRequestT, CreateMediaUploadResponse, EvidenceSnapshot, ListDevicesResponse, ListRepliesResponse, Platform, PollPairingResponse, SubmissionReceipt, SubmitNotificationRequestT } from '@raidiant/notifai-protocol';
+export declare class ApiCallError extends Error {
+    status: number;
+    code: string;
+    nextAction: string | null;
+    details: unknown;
+    constructor(status: number, code: string, message: string, nextAction?: string | null, details?: unknown);
+}
+export declare class NetworkError extends Error {
+}
+export interface ApiClient {
+    beginPairing(body: {
+        machine_name: string;
+        credential_hash: string;
+        poll_verifier_hash: string;
+    }): Promise<BeginPairingResponse>;
+    pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>;
+    listDevices(): Promise<ListDevicesResponse>;
+    capabilities(platform?: Platform): Promise<CapabilityDocument>;
+    submit(body: SubmitNotificationRequestT, waitSeconds: number): Promise<SubmissionReceipt>;
+    evidence(requestId: string): Promise<EvidenceSnapshot>;
+    replies(requestId: string, options: {
+        waitSeconds: number;
+        afterSeq: number;
+    }): Promise<ListRepliesResponse>;
+    /** Retire a question so a late device answer is rejected rather than lost. */
+    closeReplies(requestId: string): Promise<void>;
+    createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>;
+    uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>;
+    health(): Promise<boolean>;
+}
+export interface ClientOptions {
+    /**
+     * Ceiling for a single request, on top of any long poll the server has been
+     * asked to hold. Callers running inside a harness hook shrink this so their
+     * whole network path stays inside the budget the harness allows them.
+     */
+    timeoutMs?: number;
+}
+export declare function createClient(baseUrl: string, bearer: string | null, options?: ClientOptions): ApiClient;

package/dist/client.js

@@ -0,0 +1,118 @@
+export class ApiCallError extends Error {
+    status;
+    code;
+    nextAction;
+    details;
+    constructor(status, code, message, nextAction = null, details = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.nextAction = nextAction;
+        this.details = details;
+    }
+}
+export class NetworkError extends Error {
+}
+/**
+ * A deadline that fired reads as an abort, which says nothing useful on its
+ * own. Naming the timeout is what lets someone tell a hung server apart from a
+ * refused connection.
+ */
+function networkFailure(err, root, limitMs) {
+    const name = err instanceof Error ? err.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new NetworkError(`${root} did not respond within ${Math.round(limitMs / 1000)}s`);
+    }
+    return new NetworkError(`Could not reach ${root}: ${String(err)}`);
+}
+/** Generous enough for a slow link, short enough that nothing hangs for ever. */
+const DEFAULT_TIMEOUT_MS = 20_000;
+export function createClient(baseUrl, bearer, options = {}) {
+    const root = baseUrl.replace(/\/$/, '');
+    const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    async function call(method, apiPath, body, 
+    /** Seconds the server was asked to hold the connection open. */
+    serverWaitSeconds = 0) {
+        // Without this, a server that accepts the connection and then never answers
+        // hangs until the harness kills the whole hook — and the reply-poll deadline
+        // cannot interrupt an individual fetch. The signal covers the
+        // body read too, not just the response headers.
+        const limitMs = budgetMs + serverWaitSeconds * 1000;
+        const signal = AbortSignal.timeout(limitMs);
+        let response;
+        try {
+            response = await fetch(`${root}${apiPath}`, {
+                method,
+                headers: {
+                    ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                    ...(bearer ? { authorization: bearer } : {}),
+                },
+                signal,
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (err) {
+            throw networkFailure(err, root, limitMs);
+        }
+        if (!response.ok) {
+            let parsed = null;
+            try {
+                parsed = (await response.json());
+            }
+            catch {
+                // non-JSON body
+            }
+            throw new ApiCallError(response.status, parsed?.error.code ?? 'internal_error', parsed?.error.message ?? `Request failed with status ${response.status}`, parsed?.error.next_action ?? null, parsed?.error.details ?? null);
+        }
+        if (response.status === 204)
+            return undefined;
+        try {
+            return (await response.json());
+        }
+        catch (err) {
+            // A truncated or abandoned body is a transport failure, not a protocol
+            // one: it must be retryable like any other, not surface as a raw abort.
+            throw networkFailure(err, root, limitMs);
+        }
+    }
+    return {
+        beginPairing: (body) => call('POST', '/api/v1/pairings', body),
+        pollPairing: (pairingId, pollVerifier) => call('POST', `/api/v1/pairings/${pairingId}/poll`, { poll_verifier: pollVerifier }),
+        listDevices: () => call('GET', '/api/v1/devices'),
+        capabilities: (platform = 'ios') => call('GET', `/api/v1/capabilities/${platform}`),
+        submit: (body, waitSeconds) => call('POST', `/api/v1/notifications?wait_seconds=${waitSeconds}`, body, waitSeconds),
+        evidence: (requestId) => call('GET', `/api/v1/notifications/${requestId}`),
+        replies: (requestId, { waitSeconds, afterSeq }) => call('GET', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies?wait_seconds=${waitSeconds}&after_seq=${afterSeq}`, undefined, waitSeconds),
+        closeReplies: (requestId) => call('POST', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`),
+        createMediaUpload: (body) => call('POST', '/api/v1/media', body),
+        uploadMedia: async (grant, bytes) => {
+            let response;
+            try {
+                response = await fetch(grant.upload_url, {
+                    method: 'PUT',
+                    headers: grant.upload_headers,
+                    body: bytes,
+                    // Media can be large, so this gets its own allowance rather than the
+                    // per-request budget — but still a finite one.
+                    signal: AbortSignal.timeout(Math.max(budgetMs, 60_000)),
+                });
+            }
+            catch (err) {
+                throw new NetworkError(`Upload failed: ${String(err)}`);
+            }
+            if (!response.ok) {
+                throw new NetworkError(`Upload rejected with status ${response.status}`);
+            }
+        },
+        health: async () => {
+            try {
+                await call('GET', '/healthz');
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/commands.d.ts

@@ -0,0 +1,225 @@
+import { type ListRepliesResponse, type Platform, type ReplyView } from '@raidiant/notifai-protocol';
+import { type ApiClient, type ClientOptions } from './client.js';
+import type { CredentialStore } from './credentials.js';
+import { type Readiness } from './readiness.js';
+import { type SendFlags } from './send.js';
+export interface CommandIo {
+    out(line: string): void;
+    err(line: string): void;
+    /** Interactive confirmation; resolves `fallback` (default false) when not interactive. */
+    confirm(question: string, fallback?: boolean): Promise<boolean>;
+    openUrl(url: string): void;
+    /**
+     * True only when a human is demonstrably driving a terminal. Everything below
+     * is optional sugar that MUST only be called behind this flag: an agent that
+     * reaches an interactive prompt does not error, it hangs — the prompt
+     * libraries wait on stdin for ever — so the gate is bypass, not handling.
+     * Test fakes leave all of this undefined and exercise the plain paths.
+     */
+    interactive?: boolean;
+    select?(message: string, options: {
+        value: string;
+        label: string;
+        hint?: string;
+    }[]): Promise<string | null>;
+    intro?(title: string): Promise<void>;
+    outro?(message: string): Promise<void>;
+    note?(message: string, title?: string): Promise<void>;
+    spinner?(message: string): Promise<CommandSpinner | null>;
+    check?(ok: boolean, message: string): Promise<void>;
+}
+export interface CommandSpinner {
+    message(message: string): void;
+    stop(message: string): void;
+    error(message: string): void;
+}
+export interface CommandDeps {
+    io: CommandIo;
+    store: CredentialStore;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** Test seam; production uses fetch against base_url. */
+    clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient;
+    /** Test seam for bounded polling without wall-clock sleeps. */
+    now?: () => number;
+    /** Test seam for retry/backoff timing. */
+    sleep?: (milliseconds: number) => Promise<void>;
+    /** Test seam for the OS idle probe; production shells out to the platform. */
+    idleSeconds?: () => number | null;
+}
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly noReply: 3;
+    readonly auth: 4;
+    readonly network: 5;
+};
+export declare function loginCommand(deps: CommandDeps, flags: {
+    name?: string;
+    baseUrl?: string;
+    open?: boolean;
+}): Promise<number>;
+export declare function logoutCommand(deps: CommandDeps): number;
+export declare function authStatusCommand(deps: CommandDeps, flags: {
+    json?: boolean;
+}): number;
+export declare function devicesCommand(deps: CommandDeps, flags: {
+    json?: boolean;
+}): Promise<number>;
+export declare function capabilitiesCommand(deps: CommandDeps, flags: {
+    json?: boolean;
+    platform?: Platform;
+}): Promise<number>;
+export declare function sendCommand(deps: CommandDeps, flags: SendFlags & {
+    json?: boolean;
+    wait?: number;
+    noWait?: boolean;
+    replyTimeout?: number;
+    noBlock?: boolean;
+    idempotencyKey?: string;
+    baseUrl?: string;
+}): Promise<number>;
+export declare function repliesCommand(deps: CommandDeps, requestId: string, flags: {
+    wait?: number;
+    after?: number;
+    json?: boolean;
+}): Promise<number>;
+interface ReplyWaitOptions {
+    timeoutSeconds: number;
+    afterSeq: number;
+    now?: (() => number) | undefined;
+    sleep?: ((milliseconds: number) => Promise<void>) | undefined;
+}
+interface ReplyWaitResult {
+    response: ListRepliesResponse;
+    timedOut: boolean;
+    /**
+     * The wait ended while polls were failing, so silence is unproven: the user
+     * may well have answered and we could not see it.
+     */
+    degraded: boolean;
+}
+/** Loop over server-capped long polls until a reply arrives or the caller's deadline passes. */
+export declare function waitForReply(client: ApiClient, requestId: string, options: ReplyWaitOptions): Promise<ReplyWaitResult>;
+/**
+ * The other half of first-reply-wins.
+ *
+ * A blocking send returns the first non-empty batch and acts on it, so a later
+ * answer that disagrees is silently ignored. That is the right default — an
+ * agent wants one answer, not a quorum — but silently is the wrong way to do
+ * it. The server now retires the question on the other devices the moment one
+ * answers, which makes this rare; it is still reachable, because a device can
+ * answer between the first reply landing and its retirement arriving.
+ *
+ * Ordered by seq, so `replies[0]` is the one that won.
+ */
+export declare function contradictingAnswer(replies: ReplyView[]): string | null;
+export declare function statusCommand(deps: CommandDeps, requestId: string, flags: {
+    json?: boolean;
+}): Promise<number>;
+export declare const HOOK_EVENTS: readonly ["user-prompt-submit", "stop", "session-end"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/**
+ * Runs one harness hook. Contract with every harness: hook JSON arrives on
+ * stdin, the decision (if any) goes to stdout, diagnostics go to stderr, and
+ * exit 0 with no stdout means "no decision — carry on as normal".
+ *
+ * Every failure path in here must reach that no-decision state. A hook that
+ * throws, or that blocks past the harness's timeout, degrades the agent for a
+ * feature the user only asked to make it more convenient.
+ */
+export declare function hookRunCommand(deps: CommandDeps, event: string, readStdin: () => Promise<string>, harness?: 'cursor'): Promise<number>;
+/**
+ * What went wrong, in terms of what to do about it.
+ *
+ * On 2026-08-03 a contract change shipped without the server deploy that goes
+ * with it. The CLI stamped `lifecycle` on every question draft, the deployed
+ * server rejected the unknown field, and escalation stopped working entirely —
+ * announced as "hook failed, deferring to the terminal", which reads like a
+ * flaky network. The information needed to diagnose it in one second was
+ * already in hand: a 422 whose details name the offending path. It was being
+ * thrown away by `String(err)`.
+ *
+ * A hook still exits 0 whatever this says. Handing the terminal back is always
+ * right; the only question is whether the user is told anything they can use.
+ */
+export declare function describeHookFailure(err: unknown): string[];
+export interface AskFlags {
+    choice?: string | string[];
+    session?: string;
+}
+/**
+ * Registers a question for turn-end routing under the user's presence config.
+ * Returns immediately so the agent can ask in prose and end its turn. With the
+ * default presence gate, recent keyboard or mouse activity keeps it local;
+ * `require_idle = false` intentionally permits a push while the user is active.
+ */
+export declare function askCommand(deps: CommandDeps, question: string, flags: AskFlags): number;
+/** Retire a question so a late answer is rejected rather than silently lost. */
+export declare function closeCommand(deps: CommandDeps, requestId: string): Promise<number>;
+export interface HooksInstallFlags {
+    harness?: string;
+    global?: boolean;
+    /** Test seam; production resolves the running CLI. */
+    execPath?: string;
+    scriptPath?: string;
+}
+export declare function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags): number;
+export declare function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlags): number;
+export declare function configShowCommand(deps: CommandDeps, flags: {
+    json?: boolean;
+    explain?: boolean;
+}): number;
+export declare function configSetCommand(deps: CommandDeps, key: string, rawValue: string, flags: {
+    project?: boolean;
+    local?: boolean;
+    session?: string;
+    yes?: boolean;
+}): Promise<number>;
+/** Derive a contract-valid project slug from a directory name. */
+export declare function projectSlugFrom(name: string): string;
+export interface InitFlags {
+    projectId?: string;
+    /**
+     * Install the agent guidance skill. Tri-state on purpose:
+     * true installs, false skips silently, and undefined means "offer it when a
+     * human is present, do nothing when one is not" — an unattended run must
+     * never spawn npx against the network by default.
+     */
+    skills?: boolean;
+    /** Same tri-state, for the harness hooks. */
+    hooks?: boolean;
+}
+/**
+ * Setup as one step at a time.
+ *
+ * The old version ran five steps in a fixed order and ended with a list of
+ * everything still outstanding. That is a report, and a report is the wrong
+ * output here: someone handed five things to do does none of them, and the
+ * order was the script's rather than the dependency graph's — it offered to
+ * install hooks after a sign-in that had just failed.
+ *
+ * So this closes what it can, then surfaces exactly one thing, the first that
+ * stands in the way. Re-running advances by one. Idempotence stops being a
+ * property to preserve and becomes the mechanism: every decision is derived
+ * from observed state, so a partial run, a second project, a fresh worktree
+ * and a revoked credential are the same code path arriving at different
+ * states rather than four branches to enumerate.
+ */
+export declare function initCommand(deps: CommandDeps, flags: InitFlags): Promise<number>;
+/**
+ * Read the whole setup once, in dependency order.
+ *
+ * Descent stops where a prerequisite is missing: without a credential there is
+ * nothing to ask the server with, and without a reachable server a contract
+ * mismatch is unknowable rather than absent. Those downstream states report
+ * `unknown`, which is the honest answer and keeps a network outage from
+ * looking like a broken install.
+ */
+export declare function assessReadiness(deps: CommandDeps): Promise<Readiness>;
+export declare function doctorCommand(deps: CommandDeps, flags: {
+    json?: boolean;
+}): Promise<number>;
+export declare function realIo(env?: NodeJS.ProcessEnv): CommandIo;
+export {};