argus-code 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. argus/AGENTS.md +50 -0
  2. argus/__init__.py +1 -1
  3. argus/adapters/AGENTS.md +44 -0
  4. argus/adapters/claude_code/adapter.py +14 -3
  5. argus/adapters/claude_code/discover.py +14 -1
  6. argus/cli.py +41 -5
  7. argus/collector/AGENTS.md +37 -0
  8. argus/collector/first_run.py +9 -1
  9. argus/daemon/process.py +6 -0
  10. argus/dashboard-dist/_astro/charts.36uaSAWt.js +1 -1
  11. argus/dashboard-dist/_astro/format.BexCUztC.js +1 -1
  12. argus/dashboard-dist/_astro/index.astro_astro_type_script_index_0_lang.BF0nZzma.js +11 -11
  13. argus/dashboard-dist/_astro/index.astro_astro_type_script_index_0_lang.D-QKQJAF.js +24 -24
  14. argus/dashboard-dist/_astro/models.astro_astro_type_script_index_0_lang.0Aczy7Vm.js +13 -13
  15. argus/dashboard-dist/_astro/prompts.astro_astro_type_script_index_0_lang.B1i5N4zM.js +17 -17
  16. argus/dashboard-dist/_astro/session.CGJ-XRoC.css +1 -0
  17. argus/dashboard-dist/_astro/session.astro_astro_type_script_index_0_lang.SRsknMTL.js +126 -126
  18. argus/dashboard-dist/_astro/{settings.astro_astro_type_script_index_0_lang.BLXx3usF.js → settings.astro_astro_type_script_index_0_lang.DyHh8NQi.js} +24 -24
  19. argus/dashboard-dist/_astro/tools.astro_astro_type_script_index_0_lang.DHTUv2RL.js +12 -0
  20. argus/dashboard-dist/_astro/trends.astro_astro_type_script_index_0_lang.CBtUcxGK.js +5 -5
  21. argus/dashboard-dist/index.html +1 -1
  22. argus/dashboard-dist/prompts/index.html +17 -17
  23. argus/dashboard-dist/session/index.html +1 -2
  24. argus/dashboard-dist/settings/index.html +8 -8
  25. argus/dashboard-dist/tools/index.html +1 -1
  26. argus/scaffold/scaffolder.py +29 -0
  27. argus/scaffold/snapshot.py +42 -2
  28. argus/scaffold/storage.py +17 -1
  29. argus/server/AGENTS.md +46 -0
  30. argus/server/api.py +37 -13
  31. argus/server/app.py +58 -1
  32. argus/store/AGENTS.md +43 -0
  33. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/METADATA +1 -1
  34. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/RECORD +38 -32
  35. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/WHEEL +1 -1
  36. argus/dashboard-dist/_astro/tools.astro_astro_type_script_index_0_lang.OvyHH6MH.js +0 -12
  37. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/entry_points.txt +0 -0
  38. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/licenses/LICENSE +0 -0
  39. {argus_code-0.4.2.dist-info → argus_code-0.4.4.dist-info}/licenses/NOTICE +0 -0
argus/AGENTS.md ADDED
@@ -0,0 +1,50 @@
1
+ # AGENTS.md — Python backend package (`argus`)
2
+
3
+ Parent: repo-root `AGENTS.md`. Read it first for the workflow and global rules.
4
+
5
+ ## Purpose
6
+
7
+ The `argus` package: ingest Claude Code transcripts, store them in SQLite, serve
8
+ the dashboard, and provide the `argus` CLI. Runs directly from source
9
+ (`uv run argus start`) — no build step. Entry point: `argus = "argus.cli:app"`.
10
+
11
+ ## Ownership
12
+
13
+ This doc owns backend-wide rules and the subsystems that have no child doc:
14
+ - `core/` — runtime wiring (`RuntimeOptions`, building the watcher + server).
15
+ - `daemon/` — `argusd` background service: pidfile, process lifecycle, logging.
16
+ - `detectors/` — alert detectors (registry + individual rules like tool-error-rate spike).
17
+ - `pricing/` — pricing table load / refresh / compute; bundled JSON under repo `pricing/`.
18
+ - `scaffold/` — `argus claude` scaffolding (templates, snapshot, storage).
19
+ - `schema/` — shared pydantic types (`Session`, `Turn`, …). Changing a stored
20
+ field ripples into `store/` (columns) and `server/` (serialization).
21
+
22
+ Delegated subtrees (see their own AGENTS.md): `store/`, `collector/`, `adapters/`, `server/`.
23
+
24
+ ## Local Contracts
25
+
26
+ - **Version lives in two files** that must stay in lock-step: `__init__.py`
27
+ (`__version__`) and repo-root `pyproject.toml`. Bump both on release (root doc).
28
+ - **CLI command groups** are Typer apps wired in `cli.py`. When renaming a
29
+ user-facing command, keep the old name as a `hidden=True` alias and nudge to the
30
+ new one (precedent: `search` → `indexing`). Update help strings, the daemon
31
+ read-only API hint, and dashboard copy together.
32
+ - **Privacy stays intact:** no network calls or telemetry beyond opt-in
33
+ `argus pricing refresh`. Don't add outbound calls.
34
+
35
+ ## Work Guidance
36
+
37
+ - Follow existing module patterns; keep files focused and small.
38
+ - Python ≥ 3.11. Dependencies are deliberately minimal (fastapi, uvicorn,
39
+ pydantic, watchdog, typer, httpx) — don't add deps without cause.
40
+
41
+ ## Verification
42
+
43
+ `uv run pytest` (full suite). Subsystem tests live under `tests/<subsystem>/`.
44
+
45
+ ## Child DOX Index
46
+
47
+ - `store/AGENTS.md` — SQLite, migrations, repository; data-safety + path normalization.
48
+ - `collector/AGENTS.md` — ingest pipeline and missing-data backfill.
49
+ - `adapters/AGENTS.md` — Claude Code adapter and transcript-segment extraction.
50
+ - `server/AGENTS.md` — FastAPI routes, static serving, clean shutdown.
argus/__init__.py CHANGED
@@ -1,3 +1,3 @@
1
1
  """Argus — local-first analytics for Claude Code and other coding agents."""
2
2
 
3
- __version__ = "0.4.2"
3
+ __version__ = "0.4.4"
@@ -0,0 +1,44 @@
1
+ # AGENTS.md — adapters (Claude Code transcript adapter)
2
+
3
+ Parent: `python/argus/AGENTS.md`. Parses agent transcript files into typed results.
4
+
5
+ ## Purpose
6
+
7
+ `claude_code/` reads Claude Code's `.jsonl` transcripts: `adapter.py` discovers and
8
+ ingests files, `schemas.py` validates each line (`AssistantLine`, `UserLine`, …),
9
+ `extract_transcript.py` derives searchable segments.
10
+
11
+ ## Local Contracts
12
+
13
+ - **Discovery excludes sub-agent files.** `discover_session_files()` returns
14
+ top-level session files only; sub-agent transcripts are reached via
15
+ `sub_session_files_for(parent_file)`, which walks the parent's `subagents/`
16
+ directory (including the nested `subagents/workflows/<wf>/agent-*.jsonl` layout).
17
+ - **Sub-agent session id** = `<parent_session_id>/<sub_file_stem>` (e.g.
18
+ `claude_code:<parent>/agent-<hex>`). The `/` is what marks a row as a sub-agent
19
+ everywhere downstream.
20
+ - **`extract_transcript_segments`** emits `RawSegment`s with roles `assistant`,
21
+ `thinking`, `user`, and `tool_result`; each is byte-capped (`_cap_text`). The
22
+ first `user` segment of a sub-agent is its "Task given" in the dashboard.
23
+ - **Known data limitation — do not design against it:** `subagent_type` is empty
24
+ for every row, sub-agent ids are exactly one level deep, and there is no stored
25
+ workflow grouping or spawn-turn link. Don't build features that assume a nested
26
+ sub-agent tree, type pills, or a spawn→child edge; the data isn't there.
27
+ - **`ingest_file(path, offset)` is pure-ish:** it parses from a byte offset and
28
+ returns `(result, new_offset)`. It does not write to the DB — `collector/` owns
29
+ persistence and offset bookkeeping.
30
+ - **Path containment is enforced at `ClaudeCodeAdapter.ingest_file`, and that is
31
+ deliberate.** It is the one choke point every read reaches — discovery, the
32
+ watcher's fs events, and the pipeline's sub-agent walk — so a path that doesn't
33
+ `resolve()` under the adapter's root gets an empty result and a logged warning
34
+ instead of being read. Don't move this check out to the callers: it lived only
35
+ in `discover_session_files()` once, and `sub_agent_files_for()` plus the watcher
36
+ silently bypassed it into an arbitrary-file-read (bytes reached `parse_errors`,
37
+ which `GET /api/parse-errors` serves out). `sub_agent_files_for()` now *also*
38
+ takes `claude_root` and filters — required, not optional, so a new caller must
39
+ confront it. Covers symlinks and NTFS junctions alike (both resolve out).
40
+
41
+ ## Verification
42
+
43
+ `uv run pytest tests/adapters`. Real-`~/.claude/` tests are gated by
44
+ `ARGUS_REAL_CLAUDE_ROOT` and skipped otherwise.
@@ -1,19 +1,22 @@
1
1
  """The Claude Code adapter — façade that wires the package together."""
2
2
  from __future__ import annotations
3
3
 
4
+ import logging
4
5
  from pathlib import Path
5
6
  from typing import TYPE_CHECKING
6
7
 
7
8
  from ..base import AdapterIngestResult
8
9
  from ..registry import register
9
- from .discover import discover_session_files, sub_agent_files_for
10
+ from .discover import _safe_realpath_under, discover_session_files, sub_agent_files_for
10
11
  from .history_jsonl import ingest_history_file
11
- from .ingest_file import ingest_claude_code_file
12
+ from .ingest_file import _empty_result, ingest_claude_code_file
12
13
  from .model import canonicalize_claude_model
13
14
 
14
15
  if TYPE_CHECKING:
15
16
  from ...store.repository import Repository
16
17
 
18
+ logger = logging.getLogger(__name__)
19
+
17
20
 
18
21
  def _default_root() -> Path:
19
22
  return Path.home() / ".claude"
@@ -38,6 +41,14 @@ class ClaudeCodeAdapter:
38
41
  def ingest_file(
39
42
  self, path: Path, from_offset: int = 0
40
43
  ) -> tuple[AdapterIngestResult, int]:
44
+ # Containment lives here, at the one choke point every read passes
45
+ # through -- discovery, the watcher's fs events, and the sub-agent
46
+ # walk in the pipeline all land on this method. Checking here rather
47
+ # than at each caller is what stops a future call site from quietly
48
+ # reopening the arbitrary-file-read hole (see discover.py's rules).
49
+ if _safe_realpath_under(path, self._root) is None:
50
+ logger.warning("refusing to ingest a path outside the claude root: %s", path)
51
+ return _empty_result(path), from_offset
41
52
  return ingest_claude_code_file(path, from_offset)
42
53
 
43
54
  # ─── Extension-point overrides ─────────────────────────────────────
@@ -52,7 +63,7 @@ class ClaudeCodeAdapter:
52
63
  ingest_history_file(path, repo)
53
64
 
54
65
  def sub_session_files_for(self, session_file: Path) -> list[Path]:
55
- return sub_agent_files_for(session_file)
66
+ return sub_agent_files_for(session_file, self._root)
56
67
 
57
68
  def should_skip(self, path: Path) -> bool:
58
69
  # The subagents/ tree is walked as part of the parent's ingest,
@@ -66,7 +66,7 @@ def discover_session_files(claude_root: Path) -> list[Path]:
66
66
  return out
67
67
 
68
68
 
69
- def sub_agent_files_for(session_file: Path) -> list[Path]:
69
+ def sub_agent_files_for(session_file: Path, claude_root: Path) -> list[Path]:
70
70
  """Return the sub-agent transcript JSONLs for a session.
71
71
 
72
72
  Two on-disk layouts coexist under ``<session_dir>/<sid>/subagents/``:
@@ -88,12 +88,25 @@ def sub_agent_files_for(session_file: Path) -> list[Path]:
88
88
  sub = session_file.parent / sid / "subagents"
89
89
  if not sub.exists():
90
90
  return []
91
+ try:
92
+ canonical_root = claude_root.resolve(strict=True)
93
+ except (OSError, RuntimeError):
94
+ return []
91
95
  out: set[Path] = set()
92
96
  # Flat transcripts directly under subagents/ (dirs like workflows/ have
93
97
  # no .jsonl suffix, so they're skipped here).
94
98
  out.update(f for f in sub.iterdir() if f.is_file() and f.suffix == ".jsonl")
95
99
  # Nested Workflow sub-agent transcripts, any depth below subagents/.
96
100
  out.update(f for f in sub.rglob("agent-*.jsonl") if f.is_file())
101
+ # Same containment rule as discover_session_files: a symlink planted in
102
+ # subagents/ must not turn into an arbitrary file read. (rglob does not
103
+ # follow directory symlinks, but a symlinked *file* still resolves out.)
104
+ dropped = {f for f in out if _safe_realpath_under(f, canonical_root) is None}
105
+ for f in sorted(dropped):
106
+ logger.warning(
107
+ "skipping sub-agent transcript that escapes the claude root: %s", f
108
+ )
109
+ out -= dropped
97
110
 
98
111
  if not out and any(c.is_dir() for c in sub.iterdir()):
99
112
  # subagents/ has subdirectories but nothing matched — the layout
argus/cli.py CHANGED
@@ -15,7 +15,11 @@ import argus.detectors # noqa: F401 — triggers @register side-effects
15
15
  from .pricing.load import load_pricing_table
16
16
  from .pricing.refresh import diff_pricing, fetch_litellm_table
17
17
  from .scaffold.scaffolder import scaffold_project
18
- from .scaffold.snapshot import snapshot_candidates, snapshot_template
18
+ from .scaffold.snapshot import (
19
+ secret_files_in,
20
+ snapshot_candidates,
21
+ snapshot_template,
22
+ )
19
23
  from .scaffold.storage import RESERVED_TEMPLATE_NAMES, list_templates, resolve_template
20
24
  from .server.app import ServerOpts, build_app, serve_blocking
21
25
  from .store.db import open_db
@@ -24,9 +28,22 @@ from .store.repository import Repository
24
28
  logger = logging.getLogger("argus")
25
29
  app = typer.Typer(help="Local-first dashboard for coding-agent costs", no_args_is_help=True)
26
30
  pricing_app = typer.Typer(help="Pricing-table operations")
27
- search_app = typer.Typer(help="Manage transcript-search indexing")
31
+ indexing_app = typer.Typer(help="Manage transcript indexing (powers full-text search and sub-agent Task-given)")
32
+
33
+
34
+ @indexing_app.callback()
35
+ def _indexing_group(ctx: typer.Context) -> None:
36
+ # `search` is the old name, kept as a hidden alias so existing scripts and
37
+ # muscle memory keep working. Nudge toward the new name when invoked that way.
38
+ if ctx.info_name == "search":
39
+ typer.echo("Note: `argus search` has been renamed to `argus indexing`; the old name still works.", err=True)
40
+
41
+
42
+ # Back-compat alias: keep this binding so `search_*` command references resolve.
43
+ search_app = indexing_app
28
44
  app.add_typer(pricing_app, name="pricing")
29
- app.add_typer(search_app, name="search")
45
+ app.add_typer(indexing_app, name="indexing")
46
+ app.add_typer(indexing_app, name="search", hidden=True)
30
47
  claude_app = typer.Typer(help="Scaffold and manage .claude/ project setups")
31
48
  template_app = typer.Typer(help="Manage scaffolding templates")
32
49
  claude_app.add_typer(template_app, name="template")
@@ -185,7 +202,7 @@ def search_status(data_dir: Path = typer.Option(_default_data_dir(), "--data-dir
185
202
  typer.echo(f"Indexed: {segs['total']:,} segments across {segs['sessions']} sessions")
186
203
  if not enabled and segs["total"] > 0:
187
204
  typer.echo("Note: existing segments stay on disk but are hidden from search")
188
- typer.echo(" until you re-enable. Use 'argus search clear' to wipe them.")
205
+ typer.echo(" until you re-enable. Use 'argus indexing clear' to wipe them.")
189
206
 
190
207
 
191
208
  @search_app.command("enable")
@@ -211,7 +228,7 @@ def search_disable(data_dir: Path = typer.Option(_default_data_dir(), "--data-di
211
228
  typer.echo("Disabled.")
212
229
  if segs["total"] > 0:
213
230
  typer.echo(f"{segs['total']:,} existing segments are still on disk but hidden")
214
- typer.echo("from search. Run `argus search clear` to wipe them.")
231
+ typer.echo("from search. Run `argus indexing clear` to wipe them.")
215
232
 
216
233
 
217
234
  @search_app.command("clear")
@@ -275,6 +292,14 @@ def claude_init(
275
292
  """Scaffold a .claude/ setup (and CLAUDE.md) into a project."""
276
293
  try:
277
294
  template_dir = resolve_template(template, data_dir)
295
+ except ValueError:
296
+ # Path-like name (e.g. ../../x) — rejected before it touches the disk.
297
+ typer.echo(
298
+ f"Invalid template name '{template}'. "
299
+ "Use a plain name: letters, digits, dot, dash, underscore.",
300
+ err=True,
301
+ )
302
+ raise typer.Exit(code=1)
278
303
  except KeyError:
279
304
  avail = ", ".join(list_templates(data_dir)) or "(none)"
280
305
  typer.echo(f"Unknown template '{template}'. Available: {avail}", err=True)
@@ -345,6 +370,17 @@ def template_create(
345
370
  typer.echo(str(e), err=True)
346
371
  raise typer.Exit(code=1)
347
372
  typer.echo(f"Created template '{name}' at {target}")
373
+ # Say what was withheld. A credential filter that drops files silently is
374
+ # its own bug — the user needs to know the template is deliberately
375
+ # incomplete, and why.
376
+ withheld = secret_files_in(project / ".claude")
377
+ if withheld:
378
+ typer.echo(
379
+ "\nLeft out of the template (looks like credentials): "
380
+ + ", ".join(withheld)
381
+ + "\nTemplates get copied into every project you scaffold, so "
382
+ "secrets are never snapshotted."
383
+ )
348
384
 
349
385
 
350
386
  @app.command()
@@ -0,0 +1,37 @@
1
+ # AGENTS.md — collector (ingest pipeline + backfill)
2
+
3
+ Parent: `python/argus/AGENTS.md`. Turns transcript files into stored rows.
4
+
5
+ ## Purpose
6
+
7
+ `pipeline.py` ingests one file tick; `first_run.py` orchestrates the first-pass
8
+ ingest (foreground recent files, background older files) and backfills derived data
9
+ after a schema/feature upgrade.
10
+
11
+ ## Local Contracts
12
+
13
+ - **Offset-driven reads.** `ingest_file` reads only bytes after the stored file
14
+ offset, upserts turns/tool_calls/segments, then recomputes the session. A
15
+ fully-read file sits at EOF and is **not** re-read on the next tick. To force a
16
+ re-extract you MUST reset its offset to 0 (`repo.set_file_offset(path, 0)`) —
17
+ re-calling `ingest_file` alone does nothing for an EOF file.
18
+ - **Sub-agents are walked via the parent.** A parent ingest discovers
19
+ `adapter.sub_session_files_for(parent)` and ingests any that **grew past their
20
+ offset**. Sub-agent session ids contain `/` (`<parent>/agent-<hex>`).
21
+ - **Segments are gated on indexing.** Parent and sub-agent segments are written
22
+ only when `repo.is_search_indexing_enabled()` (see `store/AGENTS.md`). So
23
+ enabling indexing *after* ingest requires re-reading the relevant files.
24
+ - **Backfill (`_backfill_missing_derived_data`) routes through parents.** Ids with
25
+ `/` are skipped by the processing loop ("walked via parents"). Anything needing a
26
+ sub-agent file re-read must add the **parent** id to both the work set and
27
+ `deep_reset` (deep_reset zeroes the sub-agent file offsets). Missing-segment
28
+ sessions therefore map to their parent + deep_reset — otherwise sub-agent
29
+ segments never backfill and the dashboard's "Task given" stays empty.
30
+ - **Bounded per run.** Backfill candidates are capped (200) per `argus start`;
31
+ large installs may need several restarts to converge. If you add a new bounded
32
+ sweep, surface what was deferred rather than silently truncating.
33
+
34
+ ## Verification
35
+
36
+ `uv run pytest tests/collector` — covers incremental re-ingest, sub-agent
37
+ backfill, segment gating, and the "enable indexing late" path.
@@ -156,7 +156,15 @@ def _backfill_missing_derived_data(
156
156
  deep_reset: set[str] = set()
157
157
  if repo.is_search_indexing_enabled():
158
158
  for c in repo.sessions_missing_segments(200):
159
- ids.add(c["id"])
159
+ # A sub-agent's transcript is only re-read when its parent is
160
+ # re-ingested with the sub-agent file offsets reset (deep_reset).
161
+ # The sub-agent id itself is skipped by the loop below ("/" guard),
162
+ # so route to the parent (a top-level id maps to itself) and force a
163
+ # deep reset — otherwise sub-agent segments never backfill and the
164
+ # Sub-agents "Task given" stays empty after enabling indexing.
165
+ parent = c["id"].split("/", 1)[0]
166
+ ids.add(parent)
167
+ deep_reset.add(parent)
160
168
  for c in repo.sessions_missing_tool_use_ids(200):
161
169
  ids.add(c["id"])
162
170
  deep_reset.add(c["id"])
argus/daemon/process.py CHANGED
@@ -20,6 +20,12 @@ from . import pidfile
20
20
  def daemon_argv(data_dir: Path) -> list[str]:
21
21
  return [
22
22
  sys.executable,
23
+ # -P (3.11+) keeps the *caller's* cwd off the child's sys.path. Without
24
+ # it, `-m` prepends cwd, so running `argus daemon start` from inside a
25
+ # checkout that ships its own `argus/` directory would run that code
26
+ # instead of the installed package -- arbitrary execution in a detached
27
+ # process that outlives the shell.
28
+ "-P",
23
29
  "-m",
24
30
  "argus.cli",
25
31
  "daemon",