@ap3x/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @ap3x/cli
+
+The `ap3x` command line: an interactive coding agent with tool use, sessions, slash commands, hooks, and a durable job scheduler.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/cli
+```
+
+## Install
+
+```bash
+npm install -g @ap3x/cli
+ap3x --help
+```
+
+## What's inside
+
+- **Interactive + single-shot modes** — a full TUI session, or `ap3x -p "…"` to print an answer and exit.
+- **Auth** — browser OAuth for subscription backends, or API keys from the environment.
+- **Slash commands** — a curated command set operating over an injected context, so they are testable without a terminal.
+- **Hooks** — lifecycle hooks around tool use and delegation, configurable and dry-runnable.
+- **`ap3x cron`** — durable scheduled jobs hosted on `@ap3x/cadence`.
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/agent-session.d.ts

@@ -0,0 +1,163 @@
+import { type AgentBackend, type AgentEvent, type AgentHooks, type AgentRunResult, type AnyAgentTool, type Session, type SessionRepo, type StreamFn, type ThinkingLevel } from "@ap3x/agent-core";
+import { type Model } from "@ap3x/ai";
+/**
+ * Typed surface emitted by an {@link AgentSession}. F2 (interactive/print/rpc)
+ * subscribes to these to render output; the orchestration layer (swarms)
+ * consumes the higher-level AgentSession rather than this raw event surface.
+ */
+export type AgentSessionEvent = {
+    type: "prompt_start";
+    prompt: string;
+} | {
+    type: "agent_event";
+    event: AgentEvent;
+} | {
+    type: "prompt_end";
+    result: AgentRunResult;
+} | {
+    type: "error";
+    error: Error;
+};
+/** Listener registered via {@link AgentSession.on}. */
+export type AgentSessionListener = (event: AgentSessionEvent) => void | Promise<void>;
+/** Options accepted by {@link createAgentSession}. */
+export interface AgentSessionOptions {
+    /** The model to drive the agent. Either a {@link Model} or a provider+id. */
+    model?: Model<string>;
+    /** Provider slug used with {@link modelId} when {@link model} is omitted. */
+    provider?: string;
+    /** Model id used with {@link provider} when {@link model} is omitted. */
+    modelId?: string;
+    systemPrompt?: string;
+    /** Reasoning intensity (excluding "off", which simply omits reasoning). */
+    thinking?: ThinkingLevel;
+    /** Tools the agent may call. Defaults to the standard coding tool set. */
+    tools?: AnyAgentTool[];
+    maxLoops?: number;
+    toolExecution?: "sequential" | "parallel";
+    /** Auto-compact context when it nears the window. Default: enabled. */
+    autoCompact?: boolean;
+    /** Working directory for the default tool environment. */
+    cwd?: string;
+    /** Custom shell for the bash tool; undefined = auto-detect. */
+    shellPath?: string;
+    /** Enforce the destructive-command blocklist in the default env. */
+    enforceBlocklist?: boolean;
+    /** A persistent session tree to record the conversation into. */
+    session?: Session;
+    /**
+     * The store {@link AgentSessionRuntime}'s lifecycle methods (new/switch/fork/
+     * import) create and read sessions from. Defaults to a `JsonlSessionRepo` at
+     * `~/.ap3x/sessions`; inject a repo over a temp dir in tests. Ignored by the
+     * bare session — it only governs the runtime wrapper.
+     */
+    sessionRepo?: SessionRepo;
+    /** A pre-built backend; when given, model/tools/etc. wiring is skipped. */
+    backend?: AgentBackend;
+    /**
+     * Custom provider stream function threaded into the backend
+     * (`AgentOptions.streamFn`) — the injection seam for tests / alternate
+     * transports. Ignored when {@link backend} is injected.
+     */
+    streamFn?: StreamFn;
+    /** Stable id used for prompt-cache affinity and logging. */
+    sessionId?: string;
+    /**
+     * Resolved API key / bearer token for the provider (from the unified auth
+     * seam). Threaded into the backend's stream options so an OAuth access token
+     * or API key reaches the provider call.
+     */
+    apiKey?: string;
+    /**
+     * Extra request headers (e.g. `chatgpt-account-id`) from the unified auth
+     * seam. Merged onto the provider request via stream options.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Loop hooks threaded into the runtime backend (`AgentOptions.hooks`) — the
+     * seam the CLI uses to install the discovered hook engine. Ignored when
+     * {@link backend} is injected.
+     */
+    hooks?: AgentHooks;
+}
+/**
+ * The resolved services an {@link AgentSession} composes over. Splitting this
+ * out lets F2 and tests inject a faux backend / model without touching the
+ * factory wiring. See {@link createAgentSessionServices}.
+ */
+export interface AgentSessionServices {
+    backend: AgentBackend;
+    model: Model<string>;
+    tools: AnyAgentTool[];
+    session?: Session;
+    sessionId: string;
+    /**
+     * The hooks threaded into the backend, kept here (not just inside the
+     * backend) so {@link AgentSession} can re-arm a {@link HookAgentHooks}'
+     * `reset()` between runs — the backend has no seam for that itself.
+     */
+    hooks?: AgentHooks;
+}
+/**
+ * Build the runtime services for a session from high-level options. This is the
+ * injection seam: callers (F2, tests) can construct services with a faux
+ * backend and hand them to {@link createAgentSessionFromServices}.
+ */
+export declare function createAgentSessionServices(options?: AgentSessionOptions): AgentSessionServices;
+/**
+ * The central coding-agent session. It composes the agent-core backend
+ * (#36: the default backend wraps an Agent; a multi-turn tool loop maps to one
+ * run()) and exposes a prompt queue, model selection, a typed event surface,
+ * and optional session-tree persistence. F2 layers the interactive / print /
+ * rpc run modes on top of this; orchestration consumes it directly.
+ */
+export declare class AgentSession {
+    private readonly services;
+    private readonly listeners;
+    private readonly backendUnsubscribe?;
+    private running;
+    /**
+     * The LAST mid-run compaction event of the current run (a later swap's counts
+     * supersede an earlier one's). Captured so persist() can record a durable
+     * CompactionEntry — without it the swap lives only in loop memory and a
+     * --resume replays the raw uncompacted history.
+     */
+    private lastCompaction?;
+    /** Pending prompts queued while a run is in progress. */
+    private readonly queue;
+    constructor(services: AgentSessionServices);
+    /** The active model. */
+    get model(): Model<string>;
+    /** The session id used for cache affinity / logging. */
+    get sessionId(): string;
+    /** The persistent session tree, if one was provided. */
+    get session(): Session | undefined;
+    /** The tools the agent may call. */
+    get tools(): AnyAgentTool[];
+    /** Whether a prompt is currently being processed. */
+    get isRunning(): boolean;
+    /** Subscribe to session events. Returns an unsubscribe function. */
+    on(listener: AgentSessionListener): () => void;
+    /** Abort the active run, if the backend supports it. */
+    abort(): void;
+    /**
+     * Submit a prompt. Runs immediately when idle, otherwise queues behind the
+     * in-flight prompt so callers can fire-and-forget. Resolves with the run
+     * result (final assistant text + usage + stop reason).
+     */
+    prompt(prompt: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AgentRunResult>;
+    private runPrompt;
+    private drainQueue;
+    /** Persist produced messages into the session tree, when one is attached. */
+    private persist;
+    private emit;
+    /** Release backend subscriptions. Safe to call multiple times. */
+    dispose(): void;
+}
+/** Build an {@link AgentSession} from pre-resolved services (injection seam). */
+export declare function createAgentSessionFromServices(services: AgentSessionServices): AgentSession;
+/** The high-level factory: resolve services from options, then build a session. */
+export declare function createAgentSession(options?: AgentSessionOptions): AgentSession;
+//# sourceMappingURL=agent-session.d.ts.map

package/dist/agent-session.d.ts.map

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

package/dist/auth/anthropic-login.d.ts

@@ -0,0 +1,98 @@
+import { AuthStorage, type FetchLike, type OAuthToken } from "@ap3x/ai";
+/** Loopback callback ports tried, in order. Mirrors the Claude Code default. */
+export declare const DEFAULT_ANTHROPIC_CALLBACK_PORTS: number[];
+/** The query a successful callback delivers. */
+export interface AnthropicCallbackParams {
+    code?: string;
+    state?: string;
+    error?: string;
+}
+/**
+ * A running loopback callback listener. `port` is the bound port (used to build
+ * the redirect URI); `waitForCallback` resolves once the browser hits the
+ * redirect; `close` tears the listener down. Abstracted so tests can inject a
+ * fake that fires a simulated callback with no real socket bind.
+ */
+export interface AnthropicLoopbackServer {
+    port: number;
+    waitForCallback: () => Promise<AnthropicCallbackParams>;
+    close: () => void;
+}
+/** Starts an {@link AnthropicLoopbackServer} on the first usable port. */
+export type StartAnthropicLoopbackServer = (ports: number[]) => Promise<AnthropicLoopbackServer>;
+/**
+ * Default loopback server: binds a real `node:http` server on the Claude Code
+ * `/callback` path. Tries each port in order; the first that binds wins. The
+ * single callback request resolves the pending promise, replies with a small
+ * confirmation page, and the server is closed by the caller.
+ */
+export declare const startRealAnthropicLoopbackServer: StartAnthropicLoopbackServer;
+/**
+ * Parse a manually pasted authorization value. Accepts a full redirect URL, a
+ * bare code, a `code#state` fragment, or a `code=...&state=...` query fragment
+ * (the remote-browser paste fallback where the loopback cannot be reached).
+ */
+export declare function parseAuthorizationInput(input: string): {
+    code?: string;
+    state?: string;
+};
+/** Options for {@link loginAnthropic}; every IO seam is injectable. */
+export interface LoginAnthropicOptions {
+    /** Token storage; defaults to the on-disk {@link AuthStorage}. */
+    storage?: AuthStorage;
+    /** Open the authorization URL in a browser. Default: cross-platform open. */
+    openBrowser?: (url: string) => void;
+    /** Injectable fetch for the token exchange. */
+    fetchImpl?: FetchLike;
+    /** Candidate loopback ports. Default: {@link DEFAULT_ANTHROPIC_CALLBACK_PORTS}. */
+    ports?: number[];
+    /** Abort the wait (e.g. user cancelled). */
+    signal?: AbortSignal;
+    /** Print a line (e.g. the URL for headless users). Default: console.log. */
+    print?: (text: string) => void;
+    /** Start the loopback server. Default: a real node:http bind. Tests inject. */
+    startServer?: StartAnthropicLoopbackServer;
+    /** Override the callback wait timeout (ms). */
+    timeoutMs?: number;
+    /** Explicit client id override (else env / vendor default). */
+    clientId?: string;
+    /**
+     * Remote-browser fallback: resolve with a pasted code / redirect URL. When
+     * provided, it races the loopback callback — whichever completes first wins.
+     */
+    promptManualCode?: (signal: AbortSignal) => Promise<string>;
+}
+/** The outcome of a successful Anthropic subscription sign-in. */
+export interface AnthropicLoginResult {
+    mode: "oauth";
+}
+/**
+ * Run the native Anthropic (Claude Pro/Max) loopback OAuth flow:
+ *
+ *   1. Bind a loopback server and derive the exact redirect URI from its port.
+ *   2. Build the authorize URL (PKCE + state + the Claude Code client id).
+ *   3. Open the URL in a browser (and print it for headless use).
+ *   4. Await the loopback callback (or a manually pasted code / redirect URL),
+ *      verify `state`, then exchange the code at platform.claude.com.
+ *   5. Persist the token set under the `anthropic` provider slug.
+ *
+ * Every external interaction (browser, HTTP, server bind, manual input) is
+ * injectable, so a test drives the whole flow with no real IO.
+ */
+export declare function loginAnthropic(options?: LoginAnthropicOptions): Promise<AnthropicLoginResult>;
+/** Options for {@link refreshAnthropic}; injectable for tests. */
+export interface RefreshAnthropicOptions {
+    fetchImpl?: FetchLike;
+    clientId?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Exchange an Anthropic refresh token for a fresh access token. Delegates to the
+ * shared {@link refreshAccessToken} flow so the manual and auto-refresh paths
+ * post an identical JSON body (Anthropic's token endpoint rejects form-encoding).
+ * The shared flow carries the refresh token forward when the endpoint omits it.
+ */
+export declare function refreshAnthropic(refreshToken: string, options?: RefreshAnthropicOptions): Promise<OAuthToken>;
+/** Clear stored Anthropic (Claude Pro/Max) credentials. */
+export declare function logoutAnthropic(storage?: AuthStorage): Promise<void>;
+//# sourceMappingURL=anthropic-login.d.ts.map

package/dist/auth/anthropic-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-login.d.ts","sourceRoot":"","sources":["../../src/auth/anthropic-login.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,KAAK,SAAS,EAEd,KAAK,UAAU,EAIhB,MAAM,UAAU,CAAC;AAMlB,gFAAgF;AAChF,eAAO,MAAM,gCAAgC,UAAiB,CAAC;AAK/D,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACxD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAQjG;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAE,4BAa9C,CAAC;AAwCF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BxF;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,4BAA4B,CAAC;IAC3C,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;CACf;AAuED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAmD/B;AAuHD,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED,2DAA2D;AAC3D,wBAAsB,eAAe,CAAC,OAAO,GAAE,WAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F"}

package/dist/auth/codex-login.d.ts

@@ -0,0 +1,80 @@
+import { AuthStorage, type FetchLike } from "@ap3x/ai";
+/** Ports tried, in order, for the loopback OAuth callback server. */
+export declare const DEFAULT_CALLBACK_PORTS: number[];
+/** The query a successful callback delivers. */
+export interface CallbackParams {
+    code?: string;
+    state?: string;
+    error?: string;
+}
+/**
+ * A running loopback callback listener. `port` is the bound port (used to build
+ * the redirect URI); `waitForCallback` resolves once the browser hits the
+ * redirect; `close` tears the listener down. Abstracted so tests can inject a
+ * fake that fires a simulated callback with no real socket bind.
+ */
+export interface LoopbackServer {
+    port: number;
+    waitForCallback: () => Promise<CallbackParams>;
+    close: () => void;
+}
+/** Starts a {@link LoopbackServer} on the first usable port from `ports`. */
+export type StartLoopbackServer = (ports: number[]) => Promise<LoopbackServer>;
+/**
+ * Default loopback server: binds a real `node:http` server. Tries each port in
+ * order; the first that binds wins. The single `/auth/callback` request resolves
+ * the pending promise, replies with a small confirmation page, and the server is
+ * closed by the caller.
+ */
+export declare const startRealLoopbackServer: StartLoopbackServer;
+/** Open a URL in the user's default browser (best-effort, cross-platform). */
+export declare function defaultOpenBrowser(url: string): void;
+/** Options for {@link loginWithChatGPT}; every IO seam is injectable. */
+export interface LoginWithChatGPTOptions {
+    /** Token storage; defaults to the on-disk {@link AuthStorage}. */
+    storage?: AuthStorage;
+    /** Open the authorization URL in a browser. Default: cross-platform open. */
+    openBrowser?: (url: string) => void;
+    /** Injectable fetch for the token exchange. */
+    fetchImpl?: FetchLike;
+    /** Candidate loopback ports. Default: {@link DEFAULT_CALLBACK_PORTS}. */
+    ports?: number[];
+    /** Abort the wait (e.g. user cancelled). */
+    signal?: AbortSignal;
+    /** Print a line (e.g. the URL for headless users). Default: console.log. */
+    print?: (text: string) => void;
+    /** Start the loopback server. Default: a real node:http bind. Tests inject. */
+    startServer?: StartLoopbackServer;
+    /** Override the callback wait timeout (ms). */
+    timeoutMs?: number;
+    /**
+     * Remote-browser / headless fallback: resolve with a pasted authorization code
+     * or full redirect URL. When provided it races the loopback callback —
+     * whichever completes first wins — so sign-in works on a machine with no local
+     * browser (the user authorizes elsewhere and pastes the redirect URL back).
+     */
+    promptManualCode?: (signal: AbortSignal) => Promise<string>;
+}
+/** The outcome of a successful ChatGPT sign-in. */
+export interface LoginResult {
+    mode: "oauth";
+    accountId?: string;
+}
+/**
+ * Run the native "Sign in with ChatGPT" loopback OAuth flow:
+ *
+ *   1. Bind a loopback server and derive the exact redirect URI from its port.
+ *   2. Build the authorize URL (PKCE + state + ChatGPT extra params).
+ *   3. Open the URL in a browser (and print it for headless use).
+ *   4. Await the loopback callback — or a manually pasted code / redirect URL
+ *      when `promptManualCode` is supplied (remote-browser / headless) — verify
+ *      `state`, then exchange the code.
+ *   5. Persist the token set (incl. account id) under the `openai-codex` slug.
+ *
+ * Every external interaction (browser, HTTP, server bind, manual input) is
+ * injectable, so a test drives the whole flow with no real IO.
+ */
+export declare function loginWithChatGPT(options?: LoginWithChatGPTOptions): Promise<LoginResult>;
+/** Clear stored ChatGPT/Codex credentials. */
+export declare function logoutCodex(storage?: AuthStorage): Promise<void>;
+//# sourceMappingURL=codex-login.d.ts.map

package/dist/auth/codex-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-login.d.ts","sourceRoot":"","sources":["../../src/auth/codex-login.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EACX,KAAK,SAAS,EAKf,MAAM,UAAU,CAAC;AAKlB,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,UAAe,CAAC;AAKnD,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAQ/E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAarC,CAAC;AAuCF,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAoBpD;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,WAAW,CAAC,CA+CtB;AAqHD,8CAA8C;AAC9C,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF"}

package/dist/auth/copilot-login.d.ts

@@ -0,0 +1,36 @@
+import { AuthStorage, type FetchLike } from "@ap3x/ai";
+/** Options for {@link loginGitHubCopilot}; every IO seam is injectable. */
+export interface LoginGitHubCopilotOptions {
+    /** Token storage; defaults to the on-disk {@link AuthStorage}. */
+    storage?: AuthStorage;
+    /** Print a line (the user code + verification URL). Default: console.log. */
+    print?: (text: string) => void;
+    /** Open the verification URL in a browser. Default: cross-platform open. */
+    openBrowser?: (url: string) => void;
+    /** Injectable fetch for the device-authorization + token polling requests. */
+    fetchImpl?: FetchLike;
+    /** Abort the flow (e.g. user cancelled). */
+    signal?: AbortSignal;
+    /** Sleep between token polls (ms). Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** The outcome of a successful GitHub Copilot sign-in. */
+export interface CopilotLoginResult {
+    mode: "oauth";
+}
+/**
+ * Run the GitHub device-code OAuth flow for Copilot:
+ *
+ *   1. Request a device + user code from GitHub's device-authorization endpoint.
+ *   2. Show the user code and verification URL (and open the browser to it).
+ *   3. Poll the token endpoint until the user authorizes (honoring
+ *      `authorization_pending` / `slow_down` per RFC 8628).
+ *   4. Persist the durable GitHub OAuth token under the `github-copilot` slug —
+ *      the runtime's unified auth exchanges it for the short-lived Copilot API
+ *      bearer on first use.
+ *
+ * Every external interaction (browser, HTTP, sleep) is injectable, so a test
+ * drives the whole flow with no real IO.
+ */
+export declare function loginGitHubCopilot(options?: LoginGitHubCopilotOptions): Promise<CopilotLoginResult>;
+//# sourceMappingURL=copilot-login.d.ts.map

package/dist/auth/copilot-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copilot-login.d.ts","sourceRoot":"","sources":["../../src/auth/copilot-login.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,KAAK,SAAS,EAMf,MAAM,UAAU,CAAC;AAMlB,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,kBAAkB,CAAC,CA4C7B"}

package/dist/auth/login-dispatch.d.ts

@@ -0,0 +1,76 @@
+import { type Api, type AuthStorage, type Model, type Provider } from "@ap3x/ai";
+import { type AnthropicLoginResult, type LoginAnthropicOptions } from "./anthropic-login";
+import { type LoginResult, type LoginWithChatGPTOptions } from "./codex-login";
+import { type CopilotLoginResult, type LoginGitHubCopilotOptions } from "./copilot-login";
+/**
+ * The ONE login/logout provider dispatch, shared by the `ap3x login`/`logout`
+ * subcommands and the `/login`/`/logout` slash commands so the two consumers
+ * cannot diverge again (the pre-A3 bug: the subcommand was a binary
+ * anthropic-vs-ChatGPT split that ran the ChatGPT OAuth flow for API-key
+ * providers like `openai`).
+ *
+ * Routing — each OAuth provider reaches ITS OWN flow, never another's (the
+ * pre-B15 bug: github-copilot fell through to the ChatGPT flow and persisted
+ * under the wrong slug):
+ *   - `anthropic` → Anthropic (Claude Pro/Max) authorization-code OAuth flow.
+ *   - `github-copilot` → GitHub device-code OAuth flow.
+ *   - `openai-codex` → ChatGPT/Codex authorization-code OAuth flow.
+ *   - Any other provider WITH an OAuth config → an actionable error (a future
+ *     provider must get its own flow, not silently borrow one).
+ *   - No OAuth config → API-key probe via {@link getApiKeyAndHeaders}; nothing
+ *     is stored, the outcome just reports whether a credential resolved.
+ */
+/** What {@link performLogin} did; the caller renders its own success output. */
+export type LoginOutcome = {
+    flow: "anthropic-oauth";
+} | {
+    flow: "codex-oauth";
+    accountId?: string;
+} | {
+    flow: "copilot-oauth";
+} | {
+    flow: "api-key";
+    mode: "oauth" | "api-key" | "none";
+};
+export interface PerformLoginOptions {
+    /** The resolved provider slug the dispatch routes on. */
+    provider: Provider;
+    /** Token storage (inject in-memory for tests; on-disk by default). */
+    storage: AuthStorage;
+    /** Line printer the OAuth flows use (URL for headless users, etc.). */
+    print: (text: string) => void;
+    /**
+     * The concrete model, when the caller has one (the slash command does). The
+     * API-key probe reads only `model.provider`, so callers without a resolved
+     * model (the `ap3x login` subcommand) may omit it.
+     */
+    model?: Model<Api>;
+    /** Injectable Anthropic OAuth flow (tests). Defaults to {@link loginAnthropic}. */
+    loginAnthropic?: (options?: LoginAnthropicOptions) => Promise<AnthropicLoginResult>;
+    /** Injectable ChatGPT/Codex OAuth flow (tests). Defaults to {@link loginWithChatGPT}. */
+    loginCodex?: (options?: LoginWithChatGPTOptions) => Promise<LoginResult>;
+    /** Injectable GitHub Copilot device-code flow (tests). Defaults to {@link loginGitHubCopilot}. */
+    loginCopilot?: (options?: LoginGitHubCopilotOptions) => Promise<CopilotLoginResult>;
+}
+/**
+ * Authenticate `provider` via the routing above. OAuth flow errors propagate
+ * to the caller (both consumers catch and render them); the API-key path never
+ * signs anything in — a `mode: "none"` outcome means no credential was found.
+ */
+export declare function performLogin(options: PerformLoginOptions): Promise<LoginOutcome>;
+export interface PerformLogoutOptions {
+    /** The resolved provider slug whose credentials are cleared — ONLY this one. */
+    provider: Provider;
+    /** Token storage (inject in-memory for tests; on-disk by default). */
+    storage: AuthStorage;
+}
+/**
+ * Clear exactly the resolved provider's stored credentials. Reports whether a
+ * token was actually stored so callers never print a sign-out that did not
+ * happen (the pre-A3 subcommand cleared the CODEX token for every non-anthropic
+ * provider and claimed success).
+ */
+export declare function performLogout(options: PerformLogoutOptions): Promise<{
+    cleared: boolean;
+}>;
+//# sourceMappingURL=login-dispatch.d.ts.map

package/dist/auth/login-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-dispatch.d.ts","sourceRoot":"","sources":["../../src/auth/login-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,QAAQ,EAGd,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAoB,MAAM,eAAe,CAAC;AACjG,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAE/B,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;GAiBG;AAEH,gFAAgF;AAChF,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,EAAE,QAAQ,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,WAAW,CAAC;IACrB,uEAAuE;IACvE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,mFAAmF;IACnF,cAAc,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACpF,yFAAyF;IACzF,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,uBAAuB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACzE,kGAAkG;IAClG,YAAY,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,yBAAyB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrF;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCtF;AAED,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,EAAE,QAAQ,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAKhG"}

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  main
+} from "./chunk-3WSVGI7R.js";
+
+// src/bin.ts
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.stack ?? error.message : String(error)}
+`
+  );
+  process.exitCode = 1;
+});

package/dist/branding.d.ts

@@ -0,0 +1,89 @@
+/**
+ * AP3X CLI branding + path resolution. Every identifier here is AP3X-native:
+ * binary `ap3x`, config dir `~/.ap3x/`, env prefix `AP3X_` — Hard Constraint 2.
+ * No third-party brand appears anywhere in this module.
+ */
+/** The CLI binary / application name. */
+export declare const APP_NAME = "ap3x";
+/** Human-facing display name used in help text and banners. */
+export declare const DISPLAY_NAME = "AP3X";
+/** The per-user config directory name (under the home directory). */
+export declare const CONFIG_DIR_NAME = ".ap3x";
+/** Environment-variable prefix for every AP3X-honored variable. */
+export declare const ENV_PREFIX = "AP3X_";
+/** Env var that overrides the resolved config directory wholesale. */
+export declare const ENV_CONFIG_DIR = "AP3X_CONFIG_DIR";
+/** The package version, sourced from the CLI package.json. */
+export declare const VERSION = "0.1.0";
+/** The npm package name for this CLI. */
+export declare const PACKAGE = "@ap3x/cli";
+/** The settings file name written inside the config directory. */
+export declare const SETTINGS_FILE_NAME = "settings.json";
+/** The sessions sub-directory inside the config directory. */
+export declare const SESSIONS_DIR_NAME = "sessions";
+/** The logs sub-directory inside the config directory. */
+export declare const LOGS_DIR_NAME = "logs";
+/** The skills sub-directory inside the config directory. */
+export declare const SKILLS_DIR_NAME = "skills";
+/** The cron-scheduler state sub-directory inside the config directory. */
+export declare const CRON_DIR_NAME = "cron";
+/**
+ * The fully-resolved AP3X config directory. Precedence:
+ *  1. explicit `override`
+ *  2. `AP3X_CONFIG_DIR` env var
+ *  3. `~/.ap3x`
+ *
+ * `env` is injectable so tests don't depend on the ambient process env.
+ */
+export declare function resolveConfigDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** Absolute path to the settings file inside the resolved config dir. */
+export declare function resolveSettingsPath(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** Absolute path to the sessions directory inside the resolved config dir. */
+export declare function resolveSessionsDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** Absolute path to the logs directory inside the resolved config dir. */
+export declare function resolveLogsDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** Absolute path to the skills directory inside the resolved config dir. */
+export declare function resolveSkillsDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** Absolute path to the cron state directory inside the resolved config dir. */
+export declare function resolveCronDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** The hooks config file name inside the config directory (and project `.ap3x/`). */
+export declare const HOOKS_FILE_NAME = "hooks.json";
+/** Absolute path to the user hooks file inside the resolved config dir. */
+export declare function resolveHooksPath(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/** The traces sub-directory inside the config directory (TraceWriter's default). */
+export declare const TRACES_DIR_NAME = "traces";
+/** Absolute path to the traces directory inside the resolved config dir. */
+export declare function resolveTracesDir(options?: {
+    override?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+//# sourceMappingURL=branding.d.ts.map