jagc 0.1.0

package/docs/architecture.md

@@ -0,0 +1,161 @@
+# jagc architecture (current implementation)
+
+This doc is the implementation snapshot (not design intent).
+
+- Current operator-facing contract: [`README.md`](../README.md)
+- Deferred/historical notes: [`docs/future.md`](./future.md)
+
+## Implemented surface (v0)
+
+### HTTP API
+
+- Core run lifecycle: `GET /healthz`, `POST /v1/messages`, `GET /v1/runs/:run_id`
+- OAuth broker: `GET /v1/auth/providers`, `POST /v1/auth/providers/:provider/login`, `GET /v1/auth/logins/:attempt_id`, `POST /v1/auth/logins/:attempt_id/input`, `POST /v1/auth/logins/:attempt_id/cancel`
+- Runtime controls: `GET /v1/models`, `GET /v1/threads/:thread_key/runtime`, `PUT /v1/threads/:thread_key/model`, `PUT /v1/threads/:thread_key/thinking`, `DELETE /v1/threads/:thread_key/session`
+
+### CLI
+
+- `jagc health`
+- `jagc message`
+- `jagc run wait`
+- `jagc auth providers`, `jagc auth login <provider>`
+- `jagc new`, `jagc model list|get|set`, `jagc thinking get|set`
+- Service lifecycle + diagnostics: `jagc install|status|restart|uninstall|doctor` (macOS launchd implementation, future Linux/Windows planned)
+
+### Runtime/adapters
+
+- Executors: `echo` (deterministic), `pi` (real agent)
+- Telegram polling adapter (personal chats) with `/settings`, `/new`, `/model`, `/thinking`, `/auth`
+- SQLite persistence (`runs`, ingest idempotency, `thread_sessions`)
+- SQLite DB is configured in WAL mode with `foreign_keys=ON`, `synchronous=NORMAL`, and `busy_timeout=5000`
+- Structured Pino JSON logging with component-scoped child loggers shared across server/runtime/adapters
+- HTTP request completion/error events are emitted from Fastify hooks with request IDs and duration fields
+- In-process run scheduler for dispatch/recovery (no external workflow engine)
+- CI release gate runs in GitHub Actions via `pnpm release:gate` (typecheck + lint + test + build + package smoke)
+
+## Workspace bootstrap
+
+- Startup bootstraps `JAGC_WORKSPACE_DIR` (`~/.jagc` by default) with directory mode `0700`.
+- Bootstrap creates default `SYSTEM.md`, `AGENTS.md`, and `settings.json` from repo templates when missing (never overwrites existing files).
+- Bootstrap also seeds bundled `defaults/skills/**` and `defaults/extensions/**` files into the workspace when missing (never overwrites existing files).
+- Default `settings.json` includes bootstrap pi packages (`pi-librarian`, `pi-subdir-context`) but remains user-editable after creation.
+- Bootstrap also ensures workspace `.gitignore` has `.sessions/`, `auth.json`, `git/`, `jagc.sqlite`, `jagc.sqlite-shm`, and `jagc.sqlite-wal` entries.
+
+## macOS service lifecycle (CLI-managed)
+
+- `jagc install` writes a per-user launch agent at `~/Library/LaunchAgents/<label>.plist` (`com.jagc.server` by default), then `launchctl bootstrap` + `kickstart` starts the service.
+- launchd runs `node <installed package>/dist/server/main.mjs` directly (no `pnpm` runtime dependency after install).
+- launchd environment variables include `JAGC_WORKSPACE_DIR`, `JAGC_DATABASE_PATH`, `JAGC_HOST`, `JAGC_PORT`, `JAGC_RUNNER`, and optional `JAGC_TELEGRAM_BOT_TOKEN`.
+- Logs default to `$JAGC_WORKSPACE_DIR/logs/server.out.log` and `server.err.log`.
+- `jagc status` inspects launchd (`launchctl print`) and API health (`/healthz`).
+- `jagc restart` issues `launchctl kickstart -k` and waits for `/healthz`.
+- `jagc uninstall` removes the launch agent and unloads it; `--purge-data` additionally deletes the workspace directory.
+
+## Request/execution flow
+
+### 1) Message ingest (`POST /v1/messages`)
+
+- `src/server/app.ts` validates payload.
+- Header/body idempotency key mismatch returns `400`.
+- `RunService.ingestMessage(...)` writes/gets run via `RunStore.createRun(...)`.
+- Non-deduplicated runs are enqueued into the in-process run scheduler.
+- Response is a normalized run envelope (`run_id`, `status`, `output`, `error`) with `202`.
+
+### 2) Run dispatch and execution
+
+- `LocalRunScheduler` dispatches runs in process.
+- Scheduler deduplicates currently scheduled run IDs (`run_id`) and does not use an external queue/workflow engine.
+- Scheduler serializes dispatch per `thread_key` (FIFO at dispatch boundary), while allowing different threads to dispatch concurrently.
+- Scheduler calls `RunService.dispatchRunById(run_id)`, which starts background execution only if the run is still `running` and not already in-flight.
+- `RunExecutor.execute(run)` returns structured `RunOutput` or throws.
+- `RunService` emits run progress lifecycle events (`queued`, `started`, `succeeded`, `failed`) and forwards executor/session progress events when provided (for adapters/UIs).
+- Service finalizes with `markSucceeded` / `markFailed`.
+
+### 3) Run polling (`GET /v1/runs/:run_id`)
+
+- Returns normalized run response.
+- Failed runs include `error.message`.
+
+## Durability + recovery
+
+- Source of truth is SQLite run state (`runs.status`).
+- `RunService.init()` performs:
+  - immediate scan of `runs.status='running'`
+  - periodic recovery pass (15s) to re-enqueue missing in-process work
+- Recovery skips runs already in the local in-flight completion set.
+- Scheduler deduplicates currently scheduled run IDs so ingest + recovery can race safely.
+
+### Concurrency scope
+
+- Run dispatch is in-process and single-server-process scoped.
+- Same-thread turn ordering (`followUp` / `steer`) is enforced by per-thread `ThreadRunController` instances in the pi executor.
+- Multi-process/global run coordination is intentionally deferred post-v0.
+
+## Session/thread model (pi executor)
+
+- Session identity is per `thread_key`.
+- `thread_sessions` persists `thread_key`, `session_id`, `session_file`.
+- `PiRunExecutor` reopens persisted sessions when possible; creates/persists when missing/invalid.
+- In-memory session cache is hot-path only; SQLite mapping is source of truth across restarts.
+
+### Same-thread coordination (non-obvious)
+
+`ThreadRunController` coordinates same-thread turns against a single pi session:
+
+- First active run uses `session.prompt(...)`.
+- Additional same-thread runs queue via `session.followUp(...)` or `session.steer(...)`.
+- Run completion attribution comes from session events (not prompt promise timing), using user/assistant boundary events.
+
+Operational note:
+
+- With the in-process scheduler feeding a per-thread controller, same-thread `followUp`/`steer` messages can be delivered while a session is active.
+- If the process crashes, pending `running` rows are replayed from SQLite on recovery.
+
+## Telegram polling behavior
+
+- Ingest source: grammY long polling (personal chats).
+- Thread mapping: `thread_key = telegram:chat:<chat_id>`.
+- User mapping: `user_key = telegram:user:<from.id>`.
+- Default delivery mode for normal text messages: `followUp` (`/steer` is explicit).
+- Telegram `/new` and API `DELETE /v1/threads/:thread_key/session` abort/dispose the current thread session, clear persisted `thread_sessions` mapping, and cause the next message to create a fresh pi session.
+- Adapter starts a per-run progress reporter (in-chat append-style progress message + typing indicator) as soon as a run is ingested.
+- Progress is driven by run-level events emitted from `RunService` and pi session events forwarded by `ThreadRunController` (`assistant_text_delta`, `assistant_thinking_delta`, `tool_execution_*`, turn/agent lifecycle), rendered as compact append-log lines (`>` for tool calls with args-focused snippets, `~` for short thinking snippets).
+- Status updates are edit-throttled and retry-aware for Telegram rate limits (`retry_after`).
+- Adapter waits for terminal run status and replies with output/error.
+- If foreground wait exceeds adapter timeout, Telegram receives a "still running" notice and the adapter continues waiting in the background, then posts final output when complete.
+- `/model` and `/thinking` use button pickers; text args are intentionally unsupported.
+- After model/thinking changes, the adapter returns to the `/settings` panel and shows the updated runtime state.
+- The `/settings` panel does not include a dedicated refresh button; reopening `/settings` (or returning from a change) re-fetches live state.
+- Outdated/invalid callback payloads trigger stale-menu recovery: the adapter re-renders the latest `/settings` panel.
+- Telegram callback payload size is capped at 64 bytes; over-limit model/auth options are hidden and surfaced with an in-chat warning.
+
+## OAuth broker + runtime controls
+
+### OAuth broker
+
+- Backed by `PiAuthService` + `OAuthLoginBroker`.
+- Login attempts are owner-scoped via `X-JAGC-Auth-Owner`.
+- Follow-up endpoints require owner header and return `404` on owner mismatch.
+- Capacity behavior: if active attempts fill broker capacity, new starts return `429 auth_login_capacity_exceeded` (no eviction of active attempts).
+- Successful credentials persist via pi `AuthStorage` to workspace `auth.json`.
+
+### Runtime controls (model/thinking)
+
+- `PiRunExecutor` is source of truth for per-thread runtime state.
+- Model updates call `AgentSession.setModel(...)` (validated via pi `ModelRegistry`, persisted via `SettingsManager`).
+- Thinking updates call `AgentSession.setThinkingLevel(...)` and return effective/clamped level + available levels.
+- jagc does not duplicate model/thinking state in its own DB.
+
+## Contracts + schema source of truth
+
+- API schemas: `src/shared/api-contracts.ts` (used by server + CLI)
+- Run progress event contract: `src/shared/run-progress.ts`
+- Migrations: `migrations/001_runs_and_ingest.sql`, `migrations/002_thread_sessions.sql`
+- Migration runner: `src/server/migrations.ts` (`schema_migrations`; startup apply runs in a SQLite `BEGIN IMMEDIATE` transaction to avoid concurrent bootstrap races)
+
+## Known gaps / intentional limitations
+
+- Telegram webhook mode is intentionally unsupported in core (polling is the only supported Telegram mode).
+- Webhook hardening beyond current baseline is pending (signatures/replay protection).
+- Linux/systemd and Windows service lifecycle commands are not implemented yet (macOS launchd is first supported target).
+- Multi-process one-active-run-per-thread coordination is deferred.

package/docs/auth.md

@@ -0,0 +1,104 @@
+# Authentication and model access (v0)
+
+## Current behavior
+
+jagc uses pi SDK auth resolution order for model credentials:
+
+1. Runtime API key override (not used by jagc yet)
+2. `auth.json` in `JAGC_WORKSPACE_DIR` (default `~/.jagc/auth.json`)
+3. Provider environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
+4. Custom provider fallback from `models.json`
+
+`JAGC_WORKSPACE_DIR` is the single directory for both jagc workspace files and pi agent resources (skills, prompts, extensions, themes, settings, auth, sessions).
+
+## Workspace bootstrap
+
+On server startup, jagc ensures `JAGC_WORKSPACE_DIR` exists (mode `0700`), creates missing defaults (`SYSTEM.md`, `AGENTS.md`, `settings.json`), seeds bundled `defaults/skills/**` and `defaults/extensions/**` files when missing, and ensures workspace `.gitignore` contains:
+
+- `.sessions/`
+- `auth.json`
+- `git/`
+
+It **does not copy** `~/.pi/agent/settings.json` or `~/.pi/agent/auth.json`.
+
+## Fast setup paths
+
+### Path A: OAuth login via jagc (recommended for remote/headless)
+
+Start from CLI:
+
+```bash
+jagc auth providers --json
+jagc auth login openai-codex
+
+# optional: make retries/resume deterministic across terminals
+jagc auth login openai-codex --owner-key cli:anton:laptop
+```
+
+Start from Telegram:
+
+- `/auth` opens provider picker
+- tap a provider to start login
+- if input is requested, send `/auth input <value>`
+- `/auth status` refreshes the current attempt
+
+### Path B: provide env vars to the jagc process
+
+Set provider vars in the environment where the server runs (shell, launchd env, systemd env file).
+
+Examples:
+
+```bash
+export OPENAI_API_KEY=...
+export ANTHROPIC_API_KEY=...
+```
+
+For deployment, inject these into your service manager instead of interactive shells.
+
+### Path C: manually manage `auth.json`
+
+You can still pre-populate `JAGC_WORKSPACE_DIR/auth.json` using pi-compatible credentials.
+
+## Discover what is missing
+
+Use the auth/runtime status endpoints via CLI:
+
+```bash
+jagc auth providers --json
+jagc model list --json
+jagc model get --thread-key cli:default --json
+jagc thinking get --thread-key cli:default --json
+```
+
+This reports:
+
+- per provider auth state (`has_auth`, credential type, env var hint, OAuth support)
+- model catalog grouped by provider
+- current thread model selection
+- current thread thinking level and available thinking levels
+
+## OAuth broker API (implemented)
+
+Server endpoints:
+
+- `POST /v1/auth/providers/:provider/login` — start OAuth login attempt (or return the active one for the same owner + provider)
+- `GET /v1/auth/logins/:attempt_id` — inspect current attempt status
+- `POST /v1/auth/logins/:attempt_id/input` — submit requested input (`prompt` or `manual_code`)
+- `POST /v1/auth/logins/:attempt_id/cancel` — cancel attempt
+
+Ownership/isolation rules:
+
+- OAuth attempts are scoped by `X-JAGC-Auth-Owner`.
+- `POST /login` accepts an optional owner header; if omitted, jagc generates one.
+- Follow-up endpoints (`GET`, `/input`, `/cancel`) require `X-JAGC-Auth-Owner`.
+- Attempt operations with the wrong owner return `404` to avoid cross-client/session leakage.
+
+Attempt snapshots include:
+
+- owner key + provider + attempt id
+- current status (`running|awaiting_input|succeeded|failed|cancelled`)
+- browser URL/instructions (when available)
+- requested input prompt (when waiting for user input)
+- progress messages and terminal error text
+
+Successful logins are persisted to `auth.json` through pi `AuthStorage.login()` and are used immediately by `ModelRegistry`.

package/docs/future.md

@@ -0,0 +1,57 @@
+# jagc future (deferred + historical notes)
+
+This file is intentionally short.
+
+- **Current behavior/contracts** live in [`README.md`](../README.md) and [`docs/architecture.md`](./architecture.md).
+- This file tracks only **post-v0 priorities** and a few **historical decisions** worth keeping visible.
+- Removed pre-v0 draft detail can be recovered from git history if needed.
+
+## v0 shipped baseline (context only)
+
+v0 is shipped as pre-alpha with:
+
+- Server: `/healthz`, `/v1/messages`, `/v1/runs/:run_id`, auth endpoints, model/runtime controls.
+- CLI: `health`, `message`, `run wait`, auth/model/thinking commands, and macOS service lifecycle (`install|status|restart|uninstall|doctor`).
+- Runtime: pi SDK in-process sessions with SQLite-backed run state + in-process scheduling.
+- Concurrency: in-process dispatch + per-thread pi session turn control (`followUp` / `steer`); multi-process/global locking deferred.
+- Telegram: polling adapter for personal chats + button-based `/settings` `/model` `/thinking` `/auth`.
+
+Do not add implementation detail here unless it is deferred/future-looking.
+
+## Post-v0 priorities
+
+### P1 — high leverage
+
+1. **Webhook hardening**
+   - Keep bearer-token baseline.
+   - Add per-source signature verification where available.
+   - Add replay protection (timestamp + nonce window).
+
+2. **Release hardening follow-ups**
+   - Add automated policy checks for changelog section quality/content.
+   - Add optional staged/canary release flow before promoting to `latest`.
+
+### P2 — operator/developer UX
+
+1. **`jagc workspace init`** for quick workspace scaffolding.
+2. **Explicit integration test target** (e.g., `pnpm test:integration`) distinct from unit tests.
+3. **Service logs UX** (structured tail/filter command) to reduce launchctl/manual log digging.
+
+### P3 — deployment maturity
+
+1. Add first-class Linux (`systemd`) and Windows (`SCM`) implementations behind the same `jagc install|status|restart|uninstall` interface.
+2. Add backup/restore guidance for workspace + SQLite before risky upgrades.
+3. Add one-command operator backup verification smoke before upgrades.
+
+## Near-term non-goals
+
+- Telegram webhook runtime mode in core (polling remains the supported Telegram mode).
+- Multi-host/distributed runtime orchestration.
+- New ingress adapters in core beyond current v0 scope.
+- Large API surface expansion before hardening current contracts.
+
+## Historical decisions worth preserving
+
+- Keep `output` as a structured payload contract (not plain text only).
+- Keep same-thread default delivery mode as `followUp`; `steer` is explicit.
+- Keep provider/model/thinking state in pi settings/session state; do not duplicate in jagc DB.

package/docs/release.md

@@ -0,0 +1,81 @@
+# Release runbook
+
+This is the canonical publish procedure for `jagc`.
+
+## Scope
+
+- Release channel: **latest** only (stable tags `vX.Y.Z`).
+- Publish target: npm package **`jagc`**.
+- Owner account: npm user **`akuzmenko`**.
+
+## One-time setup
+
+1. Ensure npm package ownership includes `akuzmenko`:
+   - `npm owner ls jagc`
+2. Enable npm trusted publishing for this repository in npm package settings.
+   - Provider: GitHub Actions
+   - Repo: `<github-owner>/jagc`
+3. Ensure GitHub Actions is enabled and can request OIDC tokens.
+   - Workflow must have `permissions: id-token: write`.
+
+> 2FA remains enabled on the npm account. Trusted publishing avoids long-lived npm tokens in repo secrets.
+
+### First-release bootstrap (only if needed)
+
+If npm does not allow trusted publishing setup before the package exists, do one manual bootstrap publish from a trusted local machine:
+
+1. `pnpm release:gate`
+2. `npm login` (account: `akuzmenko`)
+3. `npm publish --access public`
+4. Configure trusted publishing for this repo.
+5. All subsequent releases use tag-driven GitHub Actions only.
+
+## Changelog format (required)
+
+`CHANGELOG.md` must always contain:
+
+- `## [Unreleased]`
+- Version sections formatted as `## [X.Y.Z] - YYYY-MM-DD`
+- Structured subsections (`Added`, `Changed`, `Fixed`, optional `Removed`/`Security`)
+
+## Release steps
+
+1. **Prepare release commit**
+   - Move completed entries from `## [Unreleased]` into a new section:
+     - `## [X.Y.Z] - YYYY-MM-DD`
+   - Reset `## [Unreleased]` back to placeholders.
+   - Bump package version in `package.json` to `X.Y.Z`.
+
+2. **Validate locally**
+   - Run: `pnpm release:gate`
+
+3. **Commit + merge to main**
+   - Commit changelog/version/docs updates.
+   - Merge PR to `main`.
+
+4. **Tag release**
+   - `git tag -a vX.Y.Z -m "release: vX.Y.Z"`
+   - `git push origin vX.Y.Z`
+
+5. **Automated publish**
+   - GitHub Actions `release` workflow runs on the tag.
+   - Workflow verifies tag/version/changelog consistency.
+   - Workflow runs `pnpm release:gate`.
+   - Workflow publishes with:
+     - `npm publish --access public --provenance`
+   - Workflow creates/updates GitHub release notes from the matching changelog section.
+
+6. **Post-release verification**
+   - `npm view jagc version dist-tags --json`
+   - Fresh install smoke:
+     - `npm install -g jagc@latest`
+     - `jagc --help`
+
+## Failure + rollback
+
+- If publish fails before npm upload: fix and re-run workflow.
+- If a bad version is published:
+  1. Deprecate bad version:
+     - `npm deprecate jagc@X.Y.Z "broken release; upgrade to >=X.Y.Z+1"`
+  2. Cut hotfix `X.Y.Z+1` via same runbook.
+- Do **not** unpublish stable versions except for exceptional legal/security cases.

package/docs/testing.md

@@ -0,0 +1,58 @@
+# Testing strategy
+
+## Database feedback loop (SQLite)
+
+DB-backed tests use `tests/helpers/sqlite-test-db.ts`:
+
+- one in-memory SQLite database per test file
+- migrations applied once in `beforeAll`
+- table reset (`DELETE`) before each test for deterministic isolation
+- no transactional test harness (`BEGIN/ROLLBACK`) and no external DB process
+
+This keeps tests fast, parallel-friendly, and hermetic under Vitest worker file parallelism.
+
+## Telegram adapter feedback loop
+
+Telegram tests use a local behavioral Bot API clone (`tests/helpers/telegram-bot-api-clone.ts`) instead of manual `grammY` context mocks.
+
+Primary coverage lives in:
+
+- shared harness: `tests/helpers/telegram-test-kit.ts` (common bot token/chat fixtures, adapter+clone lifecycle helper, thread control fake)
+- `tests/telegram-polling-message-flow.test.ts` (plain text, `/steer`, append-log progress + typing indicator behavior, `>`/`~` stream rendering, tool-argument snippet rendering, completion states, timeout/background completion handoff, long-output chunking, and adapter-level recovery from transient polling errors)
+- `tests/telegram-runtime-controls.test.ts` (settings/model/thinking/auth callback flows)
+- `tests/telegram-polling.test.ts` (command/callback parsing and stale callback recovery)
+- `tests/telegram-bot-api-clone.test.ts` (clone contract edges: `allowed_updates`/offset semantics, transient `getUpdates` error retry compatibility (`500`/`429 retry_after`), malformed payload handling, and urlencoded payload parsing)
+- `tests/telegram-system-smoke.test.ts` (system-level smoke: real run service + scheduler + SQLite + Fastify app + polling adapter + clone)
+- `tests/cli-service-manager.test.ts` (launchd service-manager helpers: plist rendering, server entrypoint resolution, launchctl output parsing)
+
+This clone is intentionally narrow: it only implements the polling and messaging surface that jagc uses in v0:
+
+- `getMe`
+- `getUpdates` (including `offset`, `limit`, `allowed_updates`, and long-poll timeout behavior)
+- `sendMessage`
+- `editMessageText`
+- `sendChatAction`
+- `answerCallbackQuery`
+
+### Why
+
+The goal is to test real adapter behavior through grammY's network stack and long-polling loop, not private handler internals.
+
+That gives us stable refactors and catches protocol-shape regressions that context stubs cannot.
+
+### Scope rules for the clone
+
+- Keep this clone a **contract clone**, not a full Telegram reimplementation.
+- Only add Bot API methods when jagc starts using them.
+- Keep method behavior deterministic and assertion-friendly.
+- Record outbound bot calls so tests assert on real API payloads (`text`, `reply_markup.inline_keyboard`, callback answers).
+- Accept both JSON and `application/x-www-form-urlencoded` Bot API payloads (including JSON-encoded nested fields like `reply_markup`) to stay resilient to client transport changes.
+- Fail loud on malformed request payloads (invalid JSON or invalid `getUpdates` argument shapes) to avoid silent transport bugs in tests.
+
+### Commands
+
+- Full non-smoke suite (includes Telegram behavioral tests): `pnpm test`
+- Focused Telegram suite (optional while iterating, includes Telegram system smoke): `pnpm test:telegram`
+- npm package smoke (pack + install + run from tarball): `pnpm test:pack`
+- macOS launchd service smoke (manual): `jagc install --runner echo --port <port> && jagc status && jagc doctor && jagc uninstall`
+- Local release gate: `pnpm release:gate` (equivalent to `pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm test:pack`)

package/migrations/001_runs_and_ingest.sql

@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS runs (
+  run_id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  thread_key TEXT NOT NULL,
+  user_key TEXT,
+  delivery_mode TEXT NOT NULL DEFAULT 'followUp' CHECK (delivery_mode IN ('steer', 'followUp')),
+  status TEXT NOT NULL CHECK (status IN ('running', 'succeeded', 'failed')),
+  input_text TEXT NOT NULL,
+  output TEXT,
+  error_message TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE TABLE IF NOT EXISTS message_ingest (
+  source TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  run_id TEXT NOT NULL REFERENCES runs(run_id),
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (source, idempotency_key)
+);
+
+CREATE INDEX IF NOT EXISTS runs_thread_status_idx ON runs (thread_key, status);
+CREATE INDEX IF NOT EXISTS runs_created_at_idx ON runs (created_at);

package/migrations/002_thread_sessions.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS thread_sessions (
+  thread_key TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  session_file TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS thread_sessions_session_id_idx ON thread_sessions (session_id);

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "jagc",
+  "version": "0.1.0",
+  "description": "just a good clanker",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/default-anton/jagc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/default-anton/jagc/issues"
+  },
+  "homepage": "https://github.com/default-anton/jagc#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "jagc": "dist/cli/main.mjs"
+  },
+  "files": [
+    "dist",
+    "defaults/AGENTS.md",
+    "defaults/SYSTEM.md",
+    "defaults/settings.json",
+    "migrations",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/architecture.md",
+    "docs/auth.md",
+    "docs/testing.md",
+    "docs/future.md",
+    "docs/release.md",
+    "deploy/launchd/com.jagc.server.plist",
+    "deploy/systemd/*.service",
+    "deploy/systemd/*.path",
+    "deploy/systemd/*.example",
+    ".env.example"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/server/main.ts",
+    "dev:cli": "tsx src/cli/main.ts",
+    "smoke": "scripts/smoke.sh",
+    "build": "tsdown src/server/main.ts src/cli/main.ts --format esm --out-dir dist",
+    "prepack": "pnpm build",
+    "start": "node dist/server/main.mjs",
+    "test": "vitest run",
+    "test:telegram": "vitest run tests/telegram-bot-api-clone.test.ts tests/telegram-polling.test.ts tests/telegram-polling-message-flow.test.ts tests/telegram-runtime-controls.test.ts tests/telegram-system-smoke.test.ts",
+    "test:pack": "scripts/pack-smoke.sh",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "release:verify-tag": "node scripts/verify-release-tag.mjs",
+    "release:notes": "node scripts/changelog-release-notes.mjs",
+    "release:gate": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm test:pack"
+  },
+  "dependencies": {
+    "@grammyjs/runner": "^2.0.3",
+    "@mariozechner/pi-coding-agent": "^0.52.7",
+    "better-sqlite3": "^12.4.1",
+    "commander": "^14.0.3",
+    "fastify": "^5.7.4",
+    "grammy": "^1.38.3",
+    "pino": "^10.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.2.1",
+    "tsdown": "^0.20.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}