@jongleberry/atel 0.0.0

package/dist/mcp/schemas.mjs

@@ -0,0 +1,69 @@
+/**
+ * The three MCP tools this server exposes. Credential management
+ * (`create`/`list`/`delete`) is deliberately NOT here — that's CLI/admin
+ * only, per the plan's hard separation between admin and telemetry
+ * surfaces.
+ */
+const TELEMETRY_APPEND_TOOL = {
+    name: 'telemetry_append',
+    description: 'Append a telemetry entry for the current (or given) session. `data` is unstructured JSON — attach whatever is useful: notes, branch names, PR numbers, decisions made. This is a stream-of-consciousness log, not a knowledge base.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            data: { type: 'object', description: 'Unstructured JSON payload for this entry.' },
+            sessionId: {
+                type: 'string',
+                description: 'Session id to record telemetry under. Defaults to the current session.',
+            },
+            agent: { type: 'string', description: "Agent identifier. Defaults to 'claude-code'." },
+        },
+        required: ['data'],
+    },
+};
+const TELEMETRY_GET_TOOL = {
+    name: 'telemetry_get',
+    description: 'Reads back telemetry entries for the current (or given) session, optionally filtered by agent/archived.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sessionId: {
+                type: 'string',
+                description: 'Session id to read. Defaults to the current session.',
+            },
+            agent: { type: 'string', description: 'Filter by agent identifier.' },
+            archived: { type: 'boolean', description: 'Filter by archived status.' },
+            format: {
+                type: 'string',
+                enum: ['json', 'jsonl'],
+                description: 'Internal wire format. Defaults to jsonl.',
+            },
+        },
+    },
+};
+const TELEMETRY_PATCH_TOOL = {
+    name: 'telemetry_patch',
+    description: 'Batch-patches telemetry entries by id — archive them and/or shallow-merge new data into their existing `data` blob (e.g. attach a PR number once it exists).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            patches: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        archived: { type: 'boolean' },
+                        data: { type: 'object', description: 'Shallow-merged into the existing data blob.' },
+                    },
+                    required: ['id'],
+                },
+            },
+        },
+        required: ['patches'],
+    },
+};
+export const TELEMETRY_TOOLS = [
+    TELEMETRY_APPEND_TOOL,
+    TELEMETRY_GET_TOOL,
+    TELEMETRY_PATCH_TOOL,
+];

package/dist/mcp/server.d.mts

@@ -0,0 +1,10 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientConfig } from '../client/types.mjs';
+/**
+ * Builds the MCP server with the three telemetry tools registered, but does
+ * not connect a transport — kept separate so tests can drive it over an
+ * `InMemoryTransport` instead of real stdio.
+ */
+export declare function createMcpServer(config: ClientConfig): Server;
+/** Starts the MCP stdio server — the `atel mcp` entrypoint. */
+export declare function startMcpServer(config: ClientConfig): Promise<void>;

package/dist/mcp/server.mjs

@@ -0,0 +1,35 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { formatError } from '../format-error.mjs';
+import { dispatchTool } from './dispatch.mjs';
+import { TELEMETRY_TOOLS } from './schemas.mjs';
+const SERVER_INFO = { name: 'atel', version: '0.0.0' };
+/**
+ * Builds the MCP server with the three telemetry tools registered, but does
+ * not connect a transport — kept separate so tests can drive it over an
+ * `InMemoryTransport` instead of real stdio.
+ */
+export function createMcpServer(config) {
+    const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TELEMETRY_TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        try {
+            const result = await dispatchTool(request.params.name, request.params.arguments ?? {}, config);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+        }
+    });
+    return server;
+}
+/* v8 ignore start -- real stdio transport; requires an actual MCP client process attached to
+   stdin/stdout, which vitest can't drive. `createMcpServer` above (the tested logic) is exercised
+   directly via InMemoryTransport in server.test.mts. */
+/** Starts the MCP stdio server — the `atel mcp` entrypoint. */
+export async function startMcpServer(config) {
+    const server = createMcpServer(config);
+    await server.connect(new StdioServerTransport());
+}
+/* v8 ignore stop */

package/dist/mcp/tool-append.d.mts

@@ -0,0 +1,3 @@
+import type { ClientConfig, TelemetryEntry } from '../client/types.mjs';
+/** `telemetry_append` — args `{ data, sessionId?, agent? }`. */
+export declare function handleTelemetryAppend(args: Record<string, unknown>, config: ClientConfig): Promise<TelemetryEntry>;

package/dist/mcp/tool-append.mjs

@@ -0,0 +1,17 @@
+import { Telemetry } from '../client/journal.mjs';
+import { resolveSessionId } from '../session.mjs';
+import { expectObject, optionalString } from './validate.mjs';
+const DEFAULT_AGENT = 'claude-code';
+/** `telemetry_append` — args `{ data, sessionId?, agent? }`. */
+export async function handleTelemetryAppend(args, config) {
+    const data = expectObject(args.data, 'data');
+    const sessionId = resolveSessionId(optionalString(args.sessionId, 'sessionId'));
+    const agent = optionalString(args.agent, 'agent') ?? DEFAULT_AGENT;
+    const telemetry = new Telemetry({
+        baseUrl: config.baseUrl,
+        token: config.token,
+        sessionId,
+        agent,
+    });
+    return telemetry.append(data);
+}

package/dist/mcp/tool-get.d.mts

@@ -0,0 +1,13 @@
+import type { ClientConfig, TelemetryEntry } from '../client/types.mjs';
+/**
+ * `telemetry_get` — args `{ sessionId?, agent?, archived?, format? }`.
+ * Defaults `sessionId` to the current session (same resolution as
+ * `telemetry_append`), so "read back what I just recorded" works with no
+ * arguments. Collects the async-iterable client read into a single
+ * response, since MCP tool results aren't naturally streaming to the
+ * model — the underlying read still streams internally (see
+ * `client/stream.mts`), for consistency/reuse with the CLI and library.
+ */
+export declare function handleTelemetryGet(args: Record<string, unknown>, config: ClientConfig): Promise<{
+    entries: TelemetryEntry[];
+}>;

package/dist/mcp/tool-get.mjs

@@ -0,0 +1,30 @@
+import { Telemetries } from '../client/journals.mjs';
+import { resolveSessionId } from '../session.mjs';
+import { optionalBoolean, optionalEntryFormat, optionalString } from './validate.mjs';
+/**
+ * `telemetry_get` — args `{ sessionId?, agent?, archived?, format? }`.
+ * Defaults `sessionId` to the current session (same resolution as
+ * `telemetry_append`), so "read back what I just recorded" works with no
+ * arguments. Collects the async-iterable client read into a single
+ * response, since MCP tool results aren't naturally streaming to the
+ * model — the underlying read still streams internally (see
+ * `client/stream.mts`), for consistency/reuse with the CLI and library.
+ */
+export async function handleTelemetryGet(args, config) {
+    const sessionId = resolveSessionId(optionalString(args.sessionId, 'sessionId'));
+    const agent = optionalString(args.agent, 'agent');
+    const archived = optionalBoolean(args.archived, 'archived');
+    const format = optionalEntryFormat(args.format);
+    const query = { sessionId };
+    if (agent !== undefined)
+        query.agent = agent;
+    if (archived !== undefined)
+        query.archived = archived;
+    if (format !== undefined)
+        query.format = format;
+    const telemetries = new Telemetries(config);
+    const entries = [];
+    for await (const entry of telemetries.get(query))
+        entries.push(entry);
+    return { entries };
+}

package/dist/mcp/tool-patch.d.mts

@@ -0,0 +1,5 @@
+import type { ClientConfig, TelemetryEntry } from '../client/types.mjs';
+/** `telemetry_patch` — args `{ patches: Array<{ id, archived?, data? }> }`. */
+export declare function handleTelemetryPatch(args: Record<string, unknown>, config: ClientConfig): Promise<{
+    patched: TelemetryEntry[];
+}>;

package/dist/mcp/tool-patch.mjs

@@ -0,0 +1,22 @@
+import { Telemetries } from '../client/journals.mjs';
+import { expectObject, optionalBoolean } from './validate.mjs';
+function toPatchOp(value, index) {
+    const obj = expectObject(value, `patches[${index}]`);
+    if (typeof obj.id !== 'string')
+        throw new Error(`patches[${index}].id must be a string.`);
+    const patch = { id: obj.id };
+    const archived = optionalBoolean(obj.archived, `patches[${index}].archived`);
+    if (archived !== undefined)
+        patch.archived = archived;
+    if (obj.data !== undefined)
+        patch.data = expectObject(obj.data, `patches[${index}].data`);
+    return patch;
+}
+/** `telemetry_patch` — args `{ patches: Array<{ id, archived?, data? }> }`. */
+export async function handleTelemetryPatch(args, config) {
+    if (!Array.isArray(args.patches))
+        throw new Error('"patches" must be an array.');
+    const patches = args.patches.map((item, index) => toPatchOp(item, index));
+    const telemetries = new Telemetries(config);
+    return { patched: await telemetries.patch(patches) };
+}

package/dist/mcp/validate.d.mts

@@ -0,0 +1,6 @@
+import type { TelemetryEntryFormat } from '../client/types.mjs';
+/** Shared argument validation for MCP tool handlers — args arrive as untyped JSON. */
+export declare function expectObject(value: unknown, field: string): Record<string, unknown>;
+export declare function optionalString(value: unknown, field: string): string | undefined;
+export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;
+export declare function optionalEntryFormat(value: unknown): TelemetryEntryFormat | undefined;

package/dist/mcp/validate.mjs

@@ -0,0 +1,28 @@
+/** Shared argument validation for MCP tool handlers — args arrive as untyped JSON. */
+export function expectObject(value, field) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`"${field}" must be an object.`);
+    }
+    return value;
+}
+export function optionalString(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`"${field}" must be a string.`);
+    return value;
+}
+export function optionalBoolean(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`"${field}" must be a boolean.`);
+    return value;
+}
+export function optionalEntryFormat(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'json' || value === 'jsonl')
+        return value;
+    throw new Error('"format" must be "json" or "jsonl".');
+}

package/dist/session.d.mts

@@ -0,0 +1,24 @@
+export interface ResolveSessionIdOptions {
+    /** Directory to search from. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Environment to read fallback vars from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves the session id to record telemetry under, in priority order:
+ *
+ * 1. An explicit id passed by the caller.
+ * 2. A hook-written state file at `.atel/session.json`, found by
+ *    walking up from `cwd` to the nearest ancestor containing `.git` (the
+ *    project root) — falling back to `cwd` itself if no `.git` 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
+ *    this process so repeated calls with no other source agree.
+ *
+ * This is what makes a fresh session (e.g. after `/clear`) automatically
+ * start a fresh telemetry stream: a plugin hook rewrites the state file on
+ * `SessionStart`, and step 2 above is re-read from disk on every call.
+ */
+export declare function resolveSessionId(explicit?: string, options?: ResolveSessionIdOptions): string;

package/dist/session.mjs

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const SESSION_STATE_RELATIVE_PATH = '.atel/session.json';
+// Memoizes ONLY the last-resort generated id, so repeated calls within one
+// process agree on a session when no other source is available. The file
+// and env lookups below are deliberately re-read on every call (never
+// cached) so a long-lived process — e.g. the MCP stdio server — picks up a
+// state file rewritten by the SessionStart hook (e.g. after `/clear`)
+// without needing to restart.
+let generatedFallback;
+function findProjectRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return startDir;
+        dir = parent;
+    }
+}
+function readSessionStateFile(cwd) {
+    const root = findProjectRoot(cwd);
+    const path = join(root, SESSION_STATE_RELATIVE_PATH);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0
+            ? parsed.sessionId
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the session id to record telemetry under, in priority order:
+ *
+ * 1. An explicit id passed by the caller.
+ * 2. A hook-written state file at `.atel/session.json`, found by
+ *    walking up from `cwd` to the nearest ancestor containing `.git` (the
+ *    project root) — falling back to `cwd` itself if no `.git` 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
+ *    this process so repeated calls with no other source agree.
+ *
+ * This is what makes a fresh session (e.g. after `/clear`) automatically
+ * start a fresh telemetry stream: a plugin hook rewrites the state file on
+ * `SessionStart`, and step 2 above is re-read from disk on every call.
+ */
+export function resolveSessionId(explicit, options = {}) {
+    if (explicit)
+        return explicit;
+    const fromFile = readSessionStateFile(options.cwd ?? process.cwd());
+    if (fromFile)
+        return fromFile;
+    const env = options.env ?? process.env;
+    if (env.CLAUDE_CODE_SESSION_ID)
+        return env.CLAUDE_CODE_SESSION_ID;
+    if (env.CODEX_THREAD_ID)
+        return env.CODEX_THREAD_ID;
+    generatedFallback ??= randomUUID();
+    return generatedFallback;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@jongleberry/atel",
+  "version": "0.0.0",
+  "description": "Client library, CLI, and MCP server for atel (Agent Telemetry) — a telemetry stream for autonomous agents.",
+  "homepage": "https://github.com/jonathanong/atel#readme",
+  "bugs": {
+    "url": "https://github.com/jonathanong/atel/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonathanong/atel",
+    "directory": "packages/atel"
+  },
+  "bin": {
+    "atel": "./dist/cli/index.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}