@jongleberry/atel 0.0.0

package/README.md

@@ -0,0 +1,168 @@
+# @jongleberry/atel
+
+Client library, CLI, and MCP server for [atel](https://github.com/jonathanong/atel) (Agent
+Telemetry) — a telemetry stream for autonomous agents to record a stream of
+consciousness while working unmonitored, then pull it back later to distill
+learnings. This package is the piece you install; it talks to the
+(separately deployed) atel HTTP service over `fetch` — no AWS SDK, no server
+code.
+
+```sh
+npx @jongleberry/atel --help
+```
+
+## Install
+
+```sh
+pnpm add @jongleberry/atel
+```
+
+Requires Node 24+.
+
+## Configuration
+
+| Env var                  | Used by             | Meaning                                           |
+| ------------------------ | ------------------- | ------------------------------------------------- |
+| `ATEL_URL`               | CLI, MCP            | Base URL of the atel server                       |
+| `ATEL_TOKEN`             | CLI, MCP            | Telemetry credential (`atl_sk_<credId>_<secret>`) |
+| `ATEL_ADMIN_TOKEN`       | CLI (`credentials`) | Admin credential (`atl_admin_<name>_<secret>`)    |
+| `CLAUDE_CODE_SESSION_ID` | session resolution  | Fallback session id (Claude Code)                 |
+| `CODEX_THREAD_ID`        | session resolution  | Fallback session id (Codex)                       |
+
+Telemetry and admin tokens are never interchangeable: `/telemetry` requires
+a telemetry token, `/credentials` requires an admin token.
+
+## CLI
+
+```sh
+atel append '{"note": "found a flaky retry in the payments worker"}'
+atel append   # reads JSON from stdin if no argument is given
+
+atel get                              # this session, format json (default)
+atel get --format jsonl
+atel get --format markdown
+atel get --all-sessions --agent codex  # across every session for this credential
+atel get --archived false
+
+atel patch <id> --archived true
+atel patch <id> --data '{"pr": 7777}'  # shallow-merged into existing data
+atel patch --file patches.json         # batch: a JSON array of { id, archived?, data? }
+
+atel credentials create --name "my laptop"   # admin-only; prints the token once
+atel credentials list
+atel credentials delete --name "my laptop"   # or --id <id>
+
+atel mcp   # starts the MCP stdio server (see below)
+```
+
+Notes:
+
+- `get` streams the raw response body straight to stdout as it arrives, in
+  whatever format was requested — it never buffers the full response first,
+  regardless of format.
+- By default, `get` and `append` resolve the session id the same way (see
+  [Session resolution](#session-resolution) below). Pass `--all-sessions` to
+  `get` to skip that and read across every session visible to the credential.
+- Output is JSON by default; `--format jsonl`/`--format markdown` are only
+  meaningful for `get`.
+- Exit code is `0` on success, `1` on any error, with a one-line
+  `Error: ...` message on stderr — never a raw stack trace.
+
+## Library
+
+```ts
+import { Telemetries, Telemetry, Auth } from '@jongleberry/atel'
+
+// Telemetry — bound to one session + agent
+const telemetry = new Telemetry({ baseUrl, token, agent: 'claude-code' }) // sessionId auto-resolved
+await telemetry.append({ note: 'found a flaky retry' })
+for await (const entry of telemetry.get({ archived: false })) {
+  console.log(entry)
+}
+
+// Telemetries — cross-session operations
+const telemetries = new Telemetries({ baseUrl, token })
+await telemetries.append({ sessionId: 's1', agent: 'claude-code', data: { note: 'hi' } })
+for await (const entry of telemetries.get({ agent: 'claude-code' })) {
+  console.log(entry)
+}
+await telemetries.patch([
+  { id: 'entry-1', archived: true },
+  { id: 'entry-2', data: { pr: 7777 } }, // shallow merge, not a replace
+])
+
+// Auth — admin-only credential management (never exposed over MCP)
+const auth = new Auth({ baseUrl, adminToken })
+const { token: newToken } = await auth.createCredentials({ name: 'ci-bot' }) // shown once
+await auth.listCredentials()
+await auth.deleteCredentials({ name: 'ci-bot' }) // or { id }
+```
+
+Non-2xx responses throw `AtelError` (`status`, `body`).
+
+### Streaming reads — an honest tradeoff
+
+`Telemetry.get()` / `Telemetries.get()` return an `AsyncIterable<TelemetryEntry>`.
+Under the hood, reads default to requesting the server's `jsonl`
+(newline-delimited JSON) wire format and parse it **genuinely
+incrementally**: each line is parsed and yielded as soon as it has fully
+arrived off the `ReadableStream` reader, not after buffering the whole
+response. This is the recommended default and what the library uses
+internally wherever it needs entries (including the MCP server).
+
+Pass `format: 'json'` to match the server's default array wire format
+instead — this exists for parity, but a JSON array isn't a valid document
+until its closing `]` arrives, so that path **buffers the full response**
+before yielding anything. It is not genuinely incremental; prefer the
+`jsonl` default.
+
+The CLI's `get` command sidesteps this entirely for output purposes: it
+never parses entries, it just relays the raw response body straight to
+stdout as bytes arrive — so it's genuinely incremental for every format
+(`json`, `jsonl`, `markdown` alike), since it never needs to wait for a
+complete, parseable document.
+
+## Session resolution
+
+`resolveSessionId(explicit?, options?)` resolves the session id to record
+telemetry under, in order:
+
+1. An explicit id passed by the caller.
+2. A hook-written state file at `.atel/session.json`, found by
+   walking up from the current directory to the nearest ancestor containing
+   `.git` (falling back to the current directory itself if none is found). A
+   missing or unparsable file is treated as absent, not an error.
+3. `CLAUDE_CODE_SESSION_ID`.
+4. `CODEX_THREAD_ID`.
+5. A generated id (`crypto.randomUUID()`), memoized for the lifetime of the
+   current process.
+
+Steps 2–4 are re-read fresh on every call (never cached) so a long-lived
+process — like the MCP stdio server — picks up a state file rewritten by a
+`SessionStart` hook (e.g. after `/clear`) without needing to restart. Only
+the last-resort generated id is memoized, so repeated calls with no other
+source agree on the same session for that process's lifetime.
+
+## MCP server
+
+```sh
+atel mcp
+```
+
+A stdio MCP server exposing exactly three tools — deliberately **not**
+credential management, which is CLI/admin-only:
+
+- **`telemetry_append`** — `{ data: object, sessionId?: string, agent?: string }` → the created entry.
+- **`telemetry_get`** — `{ sessionId?: string, agent?: string, archived?: boolean, format?: 'json' | 'jsonl' }` → `{ entries: TelemetryEntry[] }`.
+  `sessionId` defaults to the current session (same resolution as `telemetry_append`), so "read back what I just recorded" needs no arguments.
+- **`telemetry_patch`** — `{ patches: Array<{ id: string, archived?: boolean, data?: object }> }` → `{ patched: TelemetryEntry[] }`.
+
+Reads reuse the same genuinely-incremental client internally, then collect
+into the tool response — MCP tool results aren't naturally streaming to the
+model.
+
+Reads config from `ATEL_URL` / `ATEL_TOKEN`.
+
+## License
+
+MIT

package/dist/cli/append.d.mts

@@ -0,0 +1,3 @@
+import type { CliContext } from './context.mjs';
+/** `atel append <json>` (or stdin if no argument) — posts one entry. */
+export declare function runAppend(argv: string[], ctx: CliContext): Promise<void>;

package/dist/cli/append.mjs

@@ -0,0 +1,38 @@
+import { appendEntry } from '../client/append.mjs';
+import { resolveSessionId } from '../session.mjs';
+import { parseArgs, stringFlag } from './args.mjs';
+import { CliError } from './errors.mjs';
+import { telemetryConfigFromEnv } from './env.mjs';
+import { writeLine } from './output.mjs';
+const DEFAULT_AGENT = 'claude-code';
+async function readStdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** `atel append <json>` (or stdin if no argument) — posts one entry. */
+export async function runAppend(argv, ctx) {
+    const { positional, flags } = parseArgs(argv);
+    const raw = positional[0] ?? (await readStdin(ctx.stdin));
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError('append expects a JSON object, either as an argument or piped via stdin.');
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw new CliError('append expects a JSON object (not an array or primitive).');
+    }
+    const config = telemetryConfigFromEnv(ctx.env);
+    const sessionId = resolveSessionId(stringFlag(flags, 'session-id'), { env: ctx.env });
+    const agent = stringFlag(flags, 'agent') ?? DEFAULT_AGENT;
+    const entry = await appendEntry(config, {
+        sessionId,
+        agent,
+        data: data,
+    });
+    writeLine(ctx.stdout, JSON.stringify(entry));
+}

package/dist/cli/args.d.mts

@@ -0,0 +1,14 @@
+export interface ParsedArgs {
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * A minimal, zero-dependency `argv` parser. Supports `--flag value`,
+ * `--flag=value`, and bare boolean flags (`--flag` with no following
+ * value, or immediately followed by another `--flag`).
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Reads a flag expected to be a string; `undefined` if unset or given as a bare boolean. */
+export declare function stringFlag(flags: ParsedArgs['flags'], key: string): string | undefined;
+/** Parses a `true`/`false` flag value (string or bare boolean). Throws on anything else. */
+export declare function parseBooleanFlag(value: string | boolean | undefined): boolean | undefined;

package/dist/cli/args.mjs

@@ -0,0 +1,49 @@
+import { CliError } from './errors.mjs';
+/**
+ * A minimal, zero-dependency `argv` parser. Supports `--flag value`,
+ * `--flag=value`, and bare boolean flags (`--flag` with no following
+ * value, or immediately followed by another `--flag`).
+ */
+export function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const body = arg.slice(2);
+        const eqIndex = body.indexOf('=');
+        if (eqIndex !== -1) {
+            flags[body.slice(0, eqIndex)] = body.slice(eqIndex + 1);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[body] = next;
+            i += 1;
+        }
+        else {
+            flags[body] = true;
+        }
+    }
+    return { positional, flags };
+}
+/** Reads a flag expected to be a string; `undefined` if unset or given as a bare boolean. */
+export function stringFlag(flags, key) {
+    const value = flags[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Parses a `true`/`false` flag value (string or bare boolean). Throws on anything else. */
+export function parseBooleanFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    throw new CliError(`Expected "true" or "false", got: ${value}`);
+}

package/dist/cli/context.d.mts

@@ -0,0 +1,15 @@
+/**
+ * The I/O the CLI depends on, injected so subcommands are testable by
+ * calling their exported functions directly (no shelling out to a built
+ * binary, no real stdin/stdout).
+ */
+export interface CliContext {
+    env: NodeJS.ProcessEnv;
+    stdin: AsyncIterable<Buffer | string>;
+    stdout: {
+        write: (chunk: string) => void;
+    };
+    stderr: {
+        write: (chunk: string) => void;
+    };
+}

package/dist/cli/context.mjs

@@ -0,0 +1 @@
+export {};

package/dist/cli/credentials.d.mts

@@ -0,0 +1,6 @@
+import type { CliContext } from './context.mjs';
+/**
+ * `atel credentials create|list|delete` — admin-only, uses
+ * `ATEL_ADMIN_TOKEN`. Never exposed over MCP.
+ */
+export declare function runCredentials(argv: string[], ctx: CliContext): Promise<void>;

package/dist/cli/credentials.mjs

@@ -0,0 +1,45 @@
+import { Auth } from '../client/auth.mjs';
+import { parseArgs, stringFlag } from './args.mjs';
+import { CliError } from './errors.mjs';
+import { adminConfigFromEnv } from './env.mjs';
+import { writeLine } from './output.mjs';
+/**
+ * `atel credentials create|list|delete` — admin-only, uses
+ * `ATEL_ADMIN_TOKEN`. Never exposed over MCP.
+ */
+export async function runCredentials(argv, ctx) {
+    const [sub, ...rest] = argv;
+    const { flags } = parseArgs(rest);
+    const config = adminConfigFromEnv(ctx.env);
+    const auth = new Auth({ baseUrl: config.baseUrl, adminToken: config.token });
+    switch (sub) {
+        case 'create': {
+            const name = stringFlag(flags, 'name');
+            if (name === undefined)
+                throw new CliError('credentials create requires --name <name>.');
+            writeLine(ctx.stdout, JSON.stringify(await auth.createCredentials({ name })));
+            return;
+        }
+        case 'list': {
+            writeLine(ctx.stdout, JSON.stringify(await auth.listCredentials()));
+            return;
+        }
+        case 'delete': {
+            const id = stringFlag(flags, 'id');
+            const name = stringFlag(flags, 'name');
+            if (id !== undefined) {
+                await auth.deleteCredentials({ id });
+            }
+            else if (name !== undefined) {
+                await auth.deleteCredentials({ name });
+            }
+            else {
+                throw new CliError('credentials delete requires --id <id> or --name <name>.');
+            }
+            writeLine(ctx.stdout, JSON.stringify({ deleted: true }));
+            return;
+        }
+        default:
+            throw new CliError(`Unknown credentials subcommand: ${sub ?? '(none)'}. Expected one of: create, list, delete.`);
+    }
+}

package/dist/cli/env.d.mts

@@ -0,0 +1,5 @@
+import type { ClientConfig } from '../client/types.mjs';
+/** Telemetry config from env — used by `append`/`get`/`patch`. Never the admin token. */
+export declare function telemetryConfigFromEnv(env: NodeJS.ProcessEnv): ClientConfig;
+/** Admin config from env — used only by `credentials`. Never the telemetry token. */
+export declare function adminConfigFromEnv(env: NodeJS.ProcessEnv): ClientConfig;

package/dist/cli/env.mjs

@@ -0,0 +1,21 @@
+import { CliError } from './errors.mjs';
+/** Telemetry config from env — used by `append`/`get`/`patch`. Never the admin token. */
+export function telemetryConfigFromEnv(env) {
+    const baseUrl = env.ATEL_URL;
+    if (!baseUrl)
+        throw new CliError('ATEL_URL is not set.');
+    const token = env.ATEL_TOKEN;
+    if (!token)
+        throw new CliError('ATEL_TOKEN is not set.');
+    return { baseUrl, token };
+}
+/** Admin config from env — used only by `credentials`. Never the telemetry token. */
+export function adminConfigFromEnv(env) {
+    const baseUrl = env.ATEL_URL;
+    if (!baseUrl)
+        throw new CliError('ATEL_URL is not set.');
+    const token = env.ATEL_ADMIN_TOKEN;
+    if (!token)
+        throw new CliError('ATEL_ADMIN_TOKEN is not set.');
+    return { baseUrl, token };
+}

package/dist/cli/errors.d.mts

@@ -0,0 +1,3 @@
+/** A user-facing CLI error (bad args, missing env, etc.) — never a raw stack trace. */
+export declare class CliError extends Error {
+}

package/dist/cli/errors.mjs

@@ -0,0 +1,3 @@
+/** A user-facing CLI error (bad args, missing env, etc.) — never a raw stack trace. */
+export class CliError extends Error {
+}

package/dist/cli/get.d.mts

@@ -0,0 +1,9 @@
+import type { CliContext } from './context.mjs';
+/**
+ * `atel get [--session-id] [--agent] [--archived] [--format]` —
+ * streams the raw response body to stdout as it arrives, in whatever wire
+ * format was requested (default `json`). By default this resolves and
+ * filters to the current session, same as `append`; pass `--all-sessions`
+ * to read across every session visible to this credential.
+ */
+export declare function runGet(argv: string[], ctx: CliContext): Promise<void>;

package/dist/cli/get.mjs

@@ -0,0 +1,55 @@
+import { fetchTelemetriesRaw } from '../client/stream.mjs';
+import { resolveSessionId } from '../session.mjs';
+import { parseArgs, parseBooleanFlag, stringFlag } from './args.mjs';
+import { CliError } from './errors.mjs';
+import { telemetryConfigFromEnv } from './env.mjs';
+const VALID_FORMATS = ['json', 'jsonl', 'markdown'];
+function parseFormatFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && VALID_FORMATS.includes(value)) {
+        return value;
+    }
+    throw new CliError(`--format must be one of: ${VALID_FORMATS.join(', ')}`);
+}
+/**
+ * `atel get [--session-id] [--agent] [--archived] [--format]` —
+ * streams the raw response body to stdout as it arrives, in whatever wire
+ * format was requested (default `json`). By default this resolves and
+ * filters to the current session, same as `append`; pass `--all-sessions`
+ * to read across every session visible to this credential.
+ */
+export async function runGet(argv, ctx) {
+    const { flags } = parseArgs(argv);
+    const config = telemetryConfigFromEnv(ctx.env);
+    const format = parseFormatFlag(flags.format) ?? 'json';
+    const sessionId = flags['all-sessions'] === true
+        ? undefined
+        : resolveSessionId(stringFlag(flags, 'session-id'), { env: ctx.env });
+    const agent = stringFlag(flags, 'agent');
+    const archived = parseBooleanFlag(flags.archived);
+    const query = { format };
+    if (sessionId !== undefined)
+        query.sessionId = sessionId;
+    if (agent !== undefined)
+        query.agent = agent;
+    if (archived !== undefined)
+        query.archived = archived;
+    const response = await fetchTelemetriesRaw(config, query);
+    if (!response.body)
+        return;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (value)
+                ctx.stdout.write(decoder.decode(value, { stream: true }));
+            if (done)
+                break;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/cli/index.d.mts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { startMcpServer } from '../mcp/server.mjs';
+export interface RunCliOptions {
+    env?: NodeJS.ProcessEnv;
+    stdin?: AsyncIterable<Buffer | string>;
+    stdout?: {
+        write: (chunk: string) => void;
+    };
+    stderr?: {
+        write: (chunk: string) => void;
+    };
+    startMcpServer?: typeof startMcpServer;
+}
+/**
+ * Runs one CLI invocation and resolves to a process exit code (never calls
+ * `process.exit` itself, so it's directly testable).
+ */
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;

package/dist/cli/index.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { formatError } from '../format-error.mjs';
+import { startMcpServer } from '../mcp/server.mjs';
+import { runAppend } from './append.mjs';
+import { runCredentials } from './credentials.mjs';
+import { CliError } from './errors.mjs';
+import { telemetryConfigFromEnv } from './env.mjs';
+import { runGet } from './get.mjs';
+import { writeLine } from './output.mjs';
+import { runPatch } from './patch.mjs';
+import { USAGE } from './usage.mjs';
+const HELP_COMMANDS = new Set(['help', '--help', '-h']);
+/**
+ * Runs one CLI invocation and resolves to a process exit code (never calls
+ * `process.exit` itself, so it's directly testable).
+ */
+export async function runCli(argv, options = {}) {
+    const ctx = {
+        env: options.env ?? process.env,
+        stdin: options.stdin ?? process.stdin,
+        stdout: options.stdout ?? process.stdout,
+        stderr: options.stderr ?? process.stderr,
+    };
+    const [command, ...rest] = argv;
+    try {
+        if (command === undefined || HELP_COMMANDS.has(command)) {
+            writeLine(ctx.stdout, USAGE);
+            return 0;
+        }
+        switch (command) {
+            case 'append':
+                await runAppend(rest, ctx);
+                break;
+            case 'get':
+                await runGet(rest, ctx);
+                break;
+            case 'patch':
+                await runPatch(rest, ctx);
+                break;
+            case 'credentials':
+                await runCredentials(rest, ctx);
+                break;
+            case 'mcp':
+                await (options.startMcpServer ?? startMcpServer)(telemetryConfigFromEnv(ctx.env));
+                break;
+            default:
+                throw new CliError(`Unknown command: ${command}. Expected one of: append, get, patch, credentials, mcp.`);
+        }
+        return 0;
+    }
+    catch (err) {
+        writeLine(ctx.stderr, `Error: ${formatError(err)}`);
+        return 1;
+    }
+}
+/* v8 ignore start -- real process entrypoint; exercised via the built `atel` binary, not under vitest */
+// realpathSync, not a raw string compare: every real install path (npx, a
+// global install, or a workspace-linked bin like this package's own) invokes
+// this file through a symlink. `import.meta.url` resolves through it to the
+// real file, but `process.argv[1]` is the symlink path as typed on the
+// command line — comparing them directly would silently never match and
+// this entrypoint would never run.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const code = await runCli(process.argv.slice(2));
+    process.exitCode = code;
+}
+/* v8 ignore stop */

package/dist/cli/output.d.mts

@@ -0,0 +1,4 @@
+/** Writes `text` followed by a newline to the given output stream. */
+export declare function writeLine(stream: {
+    write: (chunk: string) => void;
+}, text: string): void;

package/dist/cli/output.mjs

@@ -0,0 +1,4 @@
+/** Writes `text` followed by a newline to the given output stream. */
+export function writeLine(stream, text) {
+    stream.write(`${text}\n`);
+}

package/dist/cli/patch.d.mts

@@ -0,0 +1,7 @@
+import type { CliContext } from './context.mjs';
+/**
+ * `atel patch <id> [--archived] [--data <json>]` for a single
+ * patch, or `atel patch --file <path>` to apply a batch from a
+ * JSON array file (each element shaped like `{ id, archived?, data? }`).
+ */
+export declare function runPatch(argv: string[], ctx: CliContext): Promise<void>;

package/dist/cli/patch.mjs

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { Telemetries } from '../client/journals.mjs';
+import { parseArgs, parseBooleanFlag, stringFlag } from './args.mjs';
+import { CliError } from './errors.mjs';
+import { telemetryConfigFromEnv } from './env.mjs';
+import { writeLine } from './output.mjs';
+function loadPatchesFromFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        throw new CliError(`Could not read patch file: ${path}`);
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+        throw new CliError(`Patch file must contain a JSON array of patches: ${path}`);
+    return parsed;
+}
+function buildSinglePatch(id, flags) {
+    const patch = { id };
+    const archived = parseBooleanFlag(flags.archived);
+    if (archived !== undefined)
+        patch.archived = archived;
+    const dataFlag = stringFlag(flags, 'data');
+    if (dataFlag !== undefined) {
+        try {
+            patch.data = JSON.parse(dataFlag);
+        }
+        catch {
+            throw new CliError('--data must be a JSON object.');
+        }
+    }
+    return patch;
+}
+/**
+ * `atel patch <id> [--archived] [--data <json>]` for a single
+ * patch, or `atel patch --file <path>` to apply a batch from a
+ * JSON array file (each element shaped like `{ id, archived?, data? }`).
+ */
+export async function runPatch(argv, ctx) {
+    const { positional, flags } = parseArgs(argv);
+    const file = stringFlag(flags, 'file');
+    let patches;
+    if (file !== undefined) {
+        patches = loadPatchesFromFile(file);
+    }
+    else {
+        const id = positional[0];
+        if (id === undefined)
+            throw new CliError('patch requires an <id> argument, or --file <path> for a batch.');
+        patches = [buildSinglePatch(id, flags)];
+    }
+    const telemetries = new Telemetries(telemetryConfigFromEnv(ctx.env));
+    const result = await telemetries.patch(patches);
+    writeLine(ctx.stdout, JSON.stringify(result));
+}

package/dist/cli/usage.d.mts

@@ -0,0 +1 @@
+export declare const USAGE = "atel \u2014 telemetry for autonomous agents\n\nUsage:\n  atel append <json>              Append one entry (or pipe JSON via stdin)\n  atel get [flags]                Stream entries to stdout\n  atel patch <id> [flags]         Patch one entry (or --file <path> for a batch)\n  atel credentials <subcommand>   create | list | delete (admin-only)\n  atel mcp                        Start the MCP stdio server\n\nGet flags:\n  --session-id <id>     Defaults to the resolved current session\n  --agent <name>        Filter by agent\n  --archived true|false Filter by archived status\n  --format json|jsonl|markdown   Defaults to json\n  --all-sessions         Read across every session for this credential\n\nEnv:\n  ATEL_URL            Server base URL\n  ATEL_TOKEN          Telemetry credential\n  ATEL_ADMIN_TOKEN    Admin credential (credentials subcommand only)\n";

package/dist/cli/usage.mjs

@@ -0,0 +1,21 @@
+export const USAGE = `atel — telemetry for autonomous agents
+
+Usage:
+  atel append <json>              Append one entry (or pipe JSON via stdin)
+  atel get [flags]                Stream entries to stdout
+  atel patch <id> [flags]         Patch one entry (or --file <path> for a batch)
+  atel credentials <subcommand>   create | list | delete (admin-only)
+  atel mcp                        Start the MCP stdio server
+
+Get flags:
+  --session-id <id>     Defaults to the resolved current session
+  --agent <name>        Filter by agent
+  --archived true|false Filter by archived status
+  --format json|jsonl|markdown   Defaults to json
+  --all-sessions         Read across every session for this credential
+
+Env:
+  ATEL_URL            Server base URL
+  ATEL_TOKEN          Telemetry credential
+  ATEL_ADMIN_TOKEN    Admin credential (credentials subcommand only)
+`;

package/dist/client/append.d.mts

@@ -0,0 +1,5 @@
+import type { AppendInput, ClientConfig, TelemetryEntry } from './types.mjs';
+/** Posts a single telemetry entry. `POST /telemetry` echoes back the created entry. */
+export declare function appendEntry(config: ClientConfig, input: AppendInput): Promise<TelemetryEntry>;
+/** Posts a batch of telemetry entries. `POST /telemetry` echoes back the created entries. */
+export declare function appendEntriesBatch(config: ClientConfig, inputs: AppendInput[]): Promise<TelemetryEntry[]>;