@uptimizr/collector-server 2.1.0 → 2.2.0

package/dist/agentReport.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `uptimizr agent report` — headless, scheduled analytics reports (ADR 0051 §6,
+ * design sketch §F.4).
+ *
+ * A weekly scene-health digest should not need a human to open a chat. This
+ * subcommand runs the **same** headless loop the browser assistant and the MCP
+ * server run — `runAgent` from `@uptimizr/agent-core` over the generated
+ * read-only tool catalog — once, from a shell, and writes Markdown to a file,
+ * to stdout, or to a signed webhook.
+ *
+ * Three boundaries are deliberate and load-bearing:
+ *
+ * 1. **The collector gains no in-process LLM loop.** This is a separate process
+ *    that talks to the collector over its ordinary HTTP query API with an
+ *    ordinary project API key, exactly as any other agent client would. Nothing
+ *    here is importable by the server (keep backends thin, ADR 0005).
+ * 2. **Scheduling is the operator's.** cron, a systemd timer, a GitHub Action —
+ *    the CLI runs once and exits with a meaningful code. Uptimizr operates
+ *    nothing (ADR 0017).
+ * 3. **Provider configuration comes from the environment only and is never
+ *    persisted.** The provider key is read once into the adapter; it is never
+ *    logged, echoed, written to a report or included in an error message. The
+ *    collector key is likewise never printed.
+ *
+ * The report is **read-only**: the catalog it exposes performs `GET`s against
+ * the query API and nothing else, so a `query`-capability key is all it needs
+ * (and all it should be given — #309 / ADR 0051 §7).
+ */
+import { type AgentMessage, type AgentSkill, type LlmProvider, type ProviderUsage, type ReadTool } from "@uptimizr/agent-core";
+/**
+ * A problem the operator can fix, reported as one clear line rather than a
+ * stack trace. Everything user-facing this module rejects — a missing variable,
+ * an unknown skill, an unreachable provider — is one of these.
+ */
+export declare class AgentReportError extends Error {
+    /** Process exit code to use (see {@link EXIT}). */
+    readonly exitCode: number;
+    constructor(message: string, 
+    /** Process exit code to use (see {@link EXIT}). */
+    exitCode?: number);
+}
+/**
+ * Exit codes, documented because a scheduled job branches on them.
+ *
+ * `incomplete` is deliberately non-zero: a digest whose tool calls partly failed
+ * is still written (and says so), but a cron wrapper must be able to notice.
+ */
+export declare const EXIT: {
+    /** The report was produced and every tool call succeeded. */
+    readonly ok: 0;
+    /** Usage or configuration error — nothing ran. */
+    readonly usage: 1;
+    /** The provider call, or the webhook delivery, failed. */
+    readonly provider: 2;
+    /** A report was produced but is incomplete: a tool call failed, or no answer. */
+    readonly incomplete: 3;
+};
+/** Wire formats the hosted adapter speaks, plus the model-free CI provider. */
+export type ReportProviderKind = "anthropic" | "openai" | "scripted";
+/** Version tag on the JSON report, so a consumer can branch on the shape. */
+export declare const REPORT_SCHEMA = "uptimizr.agent-report/1";
+/** Injectable process surface, so the whole command is testable in-process. */
+export interface AgentReportDeps {
+    env: NodeJS.ProcessEnv;
+    /** Current time in epoch ms (pinned by tests). */
+    now: () => number;
+    fetchImpl: typeof fetch;
+    /** Report output (stdout): written verbatim, no trailing newline added. */
+    stdout: (text: string) => void;
+    /** Progress and diagnostics (stderr): one line at a time. */
+    stderr: (line: string) => void;
+    /** File writer, so tests need no temp directory. */
+    writeFile: (path: string, content: string) => void;
+    /**
+     * Build the LLM backend. Defaults to the hosted adapter (or the scripted
+     * provider); tests inject a deterministic one.
+     */
+    createProvider: (config: ResolvedProvider, context: ProviderContext) => LlmProvider;
+}
+/** What `createProvider` needs beyond the resolved configuration. */
+export interface ProviderContext {
+    skill: AgentSkill;
+    tools: readonly ReadTool[];
+    window: ReportWindow;
+    scene?: string;
+}
+/** The provider configuration, minus the key, which is never surfaced. */
+export interface ResolvedProvider {
+    kind: ReportProviderKind;
+    model: string;
+    endpoint: string;
+    /** Present only for a hosted run; never logged, reported or serialised. */
+    apiKey?: string;
+}
+/** The analysis window in epoch milliseconds. */
+export interface ReportWindow {
+    since: number;
+    until: number;
+    /** How it was expressed (`7d`, or `explicit` for `--since/--until`). */
+    label: string;
+}
+/** One tool call the agent made, as the report records it. */
+export interface ReportToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Wall-clock milliseconds of the collector request, when one was made. */
+    durationMs: number | null;
+    ok: boolean;
+    /** The error text the loop fed back to the model, when the call failed. */
+    error: string | null;
+    /** Characters of the result handed back to the model. */
+    resultChars: number;
+}
+/** The structured report written by `--json` and posted to `--webhook`. */
+export interface AgentReportJson {
+    schema: typeof REPORT_SCHEMA;
+    skill: string;
+    title: string;
+    scene: string | null;
+    window: ReportWindow;
+    collectorUrl: string;
+    provider: {
+        kind: ReportProviderKind;
+        model: string;
+    };
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    steps: number;
+    maxSteps: number;
+    stoppedOnMaxSteps: boolean;
+    /** Token accounting summed over the run, when the provider reported any. */
+    usage: ProviderUsage | null;
+    /** Whether `GET /api/v1/context` answered, and how much prompt it contributed. */
+    context: {
+        available: boolean;
+        chars: number;
+    };
+    toolCalls: ReportToolCall[];
+    answer: string;
+}
+interface ParsedArgs {
+    flags: Record<string, string>;
+    switches: Set<string>;
+}
+/**
+ * Parse `--flag value` / `--flag=value` / `--switch`. Deliberately tiny and
+ * dependency-free, matching the rest of the CLI, and strict: an unknown flag is
+ * an error rather than being silently ignored, because a typo'd `--scene` in a
+ * cron line would otherwise produce a confidently project-wide report.
+ */
+export declare function parseAgentReportArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * Resolve the analysis window: explicit `--since`/`--until` epoch milliseconds
+ * win, otherwise `--window <N><h|d|w>` counts back from now.
+ *
+ * Parsed by hand (digits then a unit letter) rather than with a regular
+ * expression — the value is operator input and plain scanning has no ReDoS
+ * surface at all.
+ */
+export declare function resolveWindow(flags: Record<string, string>, nowMs: number, defaultWindow?: string): ReportWindow;
+/**
+ * The window in the words a skill's text expects (`{{range}}`): "the last 7d",
+ * or the two dates when the window was given explicitly.
+ *
+ * The system prompt already states the window in epoch milliseconds, but the
+ * user turn a skill renders opens with a range of its own, and a report run with
+ * `--window 24h` must not ask for "the last 7 days" (#316).
+ */
+export declare function describeWindow(window: ReportWindow): string;
+/**
+ * Compose the system prompt: role, shared guidelines, the clock, the window the
+ * operator asked for, the project context document, and the output rules.
+ *
+ * `projectContext` is the compact rendering of `GET /api/v1/context` (ADR 0051
+ * §5) — the project's real scene ids, region ids and custom-event names. It is
+ * injected here exactly as `useAssistant` and the eval harness inject it, and is
+ * simply absent on a collector too old to serve the endpoint.
+ */
+export declare function buildReportSystemPrompt(options: {
+    nowMs: number;
+    window: ReportWindow;
+    scene?: string;
+    projectContext?: string;
+}): string;
+/** One collector request the run made, timed. */
+interface RecordedRead {
+    path: string;
+    durationMs: number;
+    ok: boolean;
+}
+/**
+ * Pair the transcript's tool calls with the timed reads, in order.
+ *
+ * A tool result that starts with one of {@link NO_REQUEST_PREFIXES} was rejected
+ * by the loop before it built a request, so it consumes no recorded read; every
+ * other result — including a collector error, which *did* make a request —
+ * consumes the next one.
+ */
+export declare function collectToolCalls(messages: readonly AgentMessage[], reads: readonly RecordedRead[]): ReportToolCall[];
+/**
+ * Render the Markdown report: the model's findings, then a **Method** section
+ * that lists every tool call with its arguments and outcome.
+ *
+ * The Method section is not decoration — it is what makes an unattended,
+ * model-written document auditable: a reader can see exactly which aggregates
+ * the figures came from, re-run them, and spot a call that silently failed.
+ */
+export declare function renderReportMarkdown(report: AgentReportJson): string;
+/**
+ * The deterministic, key-free provider (`UPTIMIZR_AGENT_PROVIDER=scripted`).
+ *
+ * It is a real {@link LlmProvider} driven through the real loop against the real
+ * collector — only the "model" is replaced by a rule: on its first turn it calls
+ * exactly the tools the chosen skill names, scoped to the run's window and
+ * scene; on its second it renders what the collector returned.
+ *
+ * It performs **no analysis** and is documented as such. What it is good for is
+ * everything around the analysis: proving the collector URL, the API key, the
+ * skill name, the output paths and the webhook signature all work, in CI or on a
+ * new host, with no provider account and no egress.
+ */
+export declare function createScriptedReportProvider(context: ProviderContext): LlmProvider;
+/**
+ * Resolve the provider from the environment — and only from the environment
+ * (ADR 0051 §6): nothing about a provider is ever written to disk by this CLI.
+ *
+ * The key is read from `UPTIMIZR_AGENT_API_KEY`, falling back to the provider's
+ * own conventional variable so an operator who already exports `ANTHROPIC_API_KEY`
+ * needs no second export. It is returned for the adapter's constructor and is
+ * never placed in any other value this module produces.
+ */
+export declare function resolveProvider(env: NodeJS.ProcessEnv): ResolvedProvider;
+/** `uptimizr agent report --help`. */
+export declare function reportUsage(): string;
+/**
+ * `uptimizr agent report --list-skills`.
+ *
+ * A skill declares its own arguments, but this command does not expose one flag
+ * per argument: `scene` comes from `--scene` and `range` is filled in from the
+ * resolved window (`--window`, or `--since`/`--until`). Printing `[--range]`
+ * would advertise a flag that does not exist, so arguments are named the way an
+ * operator actually supplies them.
+ */
+export declare function listSkills(): string;
+/**
+ * Run `uptimizr agent report`.
+ *
+ * Returns the process exit code rather than calling `process.exit`, so the whole
+ * command is exercisable in-process by the test suite. Every failure the
+ * operator can act on surfaces as one stderr line, never a stack trace, and
+ * never containing a key.
+ */
+export declare function runAgentReport(argv: readonly string[], overrides?: Partial<AgentReportDeps>): Promise<number>;
+export {};
+//# sourceMappingURL=agentReport.d.ts.map

package/dist/agentReport.d.ts.map

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