dsh-agy-link 0.6.17 → 0.6.21

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.
@@ -0,0 +1,70 @@
1
+ # Architecture
2
+
3
+ `dsh-agy-link` is a **modular monolith**: one npm package, one host entry, one
4
+ client bundle and one CLI, with a one-way dependency rule.
5
+
6
+ ## Layers
7
+
8
+ ```
9
+ common/ pure types, protocol extensions, config schema, errors
10
+ ↑
11
+ domain/ pure business rules (quota bucket math, account paths/eligibility)
12
+ ↑
13
+ runtime/ process and platform I/O (agy runner/parser/mapper, proxy/env)
14
+ ↑
15
+ provider/ the LlmAdapter pipeline (call context, purpose policy, prompt,
16
+ account selection, failure classification, attempt/finalize)
17
+ ↑
18
+ features/ translation, image, warmup, diagnostics, commands
19
+ ↑
20
+ transport/ HTTP routes, respond helpers, tool registration
21
+ ↑
22
+ host/services.ts composition factory
23
+ index.ts composition root (apply): wire services, commands, routes
24
+ ```
25
+
26
+ `src/client/**` may import **only** `src/common/**`; it never imports host,
27
+ provider, transport or `index.ts`.
28
+
29
+ The rule is enforced by `scripts/check-architecture.mjs` (import graph + cycle
30
+ detection); size budgets are enforced by `scripts/check-budgets.mjs` with a
31
+ ratchet in `scripts/budgets-allowlist.json`.
32
+
33
+ ## Provider pipeline
34
+
35
+ ```
36
+ resolveCallContext (purpose, permission, session, workspace, tool mode)
37
+ -> purposePolicy (aux / tools / binding / effort as data)
38
+ -> selectSessionAccount (sticky affinity, cross-family fallback, diagnostics)
39
+ -> buildPromptPlan (trailing messages, binding, digest, image staging, text)
40
+ -> runAttempt (spawn agy, parse NDJSON, map StreamChunks)
41
+ -> classifyFailure (pure: code/message/retryability)
42
+ -> finalize (pool success/failure/rotation, binding persistence, usage)
43
+ ```
44
+
45
+ `AgyAdapter.stream()` remains the host-facing surface and owns the
46
+ effort-refusal replay. `prepareCall()` binds model metadata for newer hosts.
47
+
48
+ ## HTTP surface
49
+
50
+ 29 routes are registered by `transport/http/router.ts` from six modules
51
+ (status, pool, auth, config, translate, media). Route paths, methods and JSON
52
+ shapes are frozen and covered by `test/http-contract.test.ts`.
53
+
54
+ ## Client
55
+
56
+ `client/index.ts` only injects styles, registers locale dictionaries and mounts
57
+ slots. `sections/*` compose `ui/*` primitives; `hooks/*` own actions; `api.ts`
58
+ owns fetch. No inline button styling outside `ui/`.
59
+
60
+ ## Verification
61
+
62
+ ```bash
63
+ npm run check # tsc --noEmit
64
+ npm run lint:arch # dependency direction + cycles
65
+ npm run lint:budget # file/function size ratchet
66
+ npm run build # tsdown (host, client, bridge, image CLI)
67
+ npm test # full suite
68
+ npm run test:coverage# Node built-in coverage with thresholds
69
+ npm run verify # all of the above except coverage
70
+ ```
@@ -0,0 +1,27 @@
1
+ # Development guardrails
2
+
3
+ ## Before a PR
4
+ ```bash
5
+ npm run check
6
+ npm run lint:arch
7
+ npm run lint:budget
8
+ npm run build
9
+ npm test
10
+ ```
11
+ `npm run verify` runs the first four plus the full suite.
12
+
13
+ ## Refactoring rules
14
+ 1. One phase per commit; moves are behavior-preserving. A "move" commit may
15
+ change imports/types only — reviewers compare with `git diff -M`.
16
+ 2. Add a characterization test before touching a God function.
17
+ 3. Freeze the public surface: `AgyAdapter.stream`, `apply`, route paths/status/
18
+ JSON, command names, config keys, CLI flags.
19
+ 4. Keep new files under 600 lines and top-level functions under 120 (the budget
20
+ script enforces the target modules immediately and ratchets legacy files).
21
+ 5. Do not mass-format the repository; format changed files only.
22
+
23
+ ## Where things live
24
+ - New provider stage: `src/provider/` (see ADR-002).
25
+ - New HTTP route: `src/transport/http/routes/` and add it to `test/http-contract.test.ts`.
26
+ - New UI row: `src/client/sections/`, using `src/client/ui/` primitives (ADR-004).
27
+ - New pure rule: `src/domain/`; never import node I/O there.
package/docs/README.en.md CHANGED
@@ -105,7 +105,7 @@ Common entry points: `/plugin`, the Antigravity settings panel, `DSH_AGY_*` envi
105
105
  ## 🧩 How it works
106
106
 
107
107
  1. **One short-lived process per turn**: `agy -p --output-format stream-json`, parsed as NDJSON.
108
- 2. **Per-account sandbox**: the primary account uses the system HOME/keychain; secondary accounts get an isolated HOME with their own agy OAuth credentials. On Windows the credential slot is leased by identity, so parallel sessions on the same account are not serialized.
108
+ 2. **Per-account sandbox**: the primary account uses the system HOME/keychain; secondary accounts get an isolated HOME with their own agy OAuth credentials. On Windows the credential slot is leased by identity, so parallel sessions on the same account are not serialized. Secondary credentials have a `.bak` in their account directory and are restored if the original file is missing.
109
109
  3. **Pooled failover**: 429/quota/region/auth failures are classified and routed — cool down, rotate the pointer, or retry on another account.
110
110
  4. **Aux routes**: translation and image generation ride the same pool through dedicated purposes (`translation`, `image`), so they never pollute a normal conversation binding.
111
111
 
@@ -0,0 +1,51 @@
1
+ # Refactoring plan (modular monolith, behavior-preserving)
2
+
3
+ Status: **implemented** on branch `refactor/modular-monolith` (worktree). Results: [REFACTORING-RESULTS.md](./REFACTORING-RESULTS.md).
4
+ Rules: one phase per commit, moves must not change behavior, public surface frozen
5
+ (`AgyAdapter.stream`, `apply`, route paths/status/JSON, command names, config keys, CLI flags).
6
+
7
+ ## Guardrails (done)
8
+ - `scripts/check-architecture.mjs`: dependency direction + zero cycles.
9
+ - `scripts/check-budgets.mjs` + `scripts/budgets-allowlist.json`: size ratchet.
10
+ - `npm run verify` = check + architecture + budgets + build + test.
11
+ - `npm run test:coverage`: Node's built-in coverage with thresholds.
12
+
13
+ ## Phase 1 (done)
14
+ - `src/common/protocol.ts`: typed `AgyGenerateOptions` (removes option casts).
15
+ - `src/runtime/net/account-env.ts`: one proxy precedence + env assembly.
16
+ - `src/provider/call-context.ts`: purpose/permission/session/workspace resolution.
17
+ - `src/provider/purpose-policy.ts`: aux/tools/binding/effort policy table.
18
+
19
+ ## Phase 3 — routes (done)
20
+ `src/index.ts` is 1,634 lines; `apply` is 1,521 and inlines 29 HTTP routes.
21
+ Target:
22
+ - `src/host/services.ts`: `createHostServices(ctx, entryConfig)` returning the shared
23
+ services (cfg/log/bin/store/pool/quota/warmup/translation/adapter/auth/poolAuth/catalog/lastRun).
24
+ - `src/transport/http/respond.ts`: `sendJson`, `methodOf`, `queryParam`, `readBody`.
25
+ - `src/transport/http/router.ts`: `registerRoutes(webServer, services)`.
26
+ - `src/transport/http/routes/{status,pool,auth,config,translate,media}.ts`: move the
27
+ handlers verbatim; each exports `register(reg, services)`.
28
+ - `src/index.ts` keeps: config, service construction, commands/tools, lifecycle, and
29
+ calls `registerRoutes`.
30
+ Acceptance: route paths/methods/status/JSON unchanged; `apply` ≤ 400 lines; 29 routes
31
+ covered by `test/http-contract.test.ts`; `pnpm check` + affected tests green.
32
+
33
+ ## Phase 4 — client (done)
34
+ `src/client/index.ts` is 3,031 lines; `apply` is 1,466 and contains the whole settings
35
+ panel + account console. Target files:
36
+ - `api.ts` (postJson/getJson), `status.ts` (cache/poll/useAgyStatus), `icons.ts`,
37
+ `styles.ts` (tokens + global CSS), `hooks/{useConfig,useAccounts,useAuthFlow}.ts`,
38
+ `ui/{Button,Row,Select,Toggle,Modal,Toast,Spinner}.ts`,
39
+ `sections/{SettingsSection,AccountsPanel,ModelsPanel,QuotaPanel}.ts`.
40
+ - `index.ts` only: styles + locale + slot registration (≤ 250 lines).
41
+ Acceptance: same UI behavior; `pnpm check` + `pnpm build`; client tests green; no
42
+ inline button style outside `ui/`.
43
+
44
+ ## Phase 2 — adapter (done: spawn/parse/outcome + policy/model modules)
45
+ Extracted `call-context` + `purpose-policy`. Remaining: prompt assembly, attempt
46
+ (spawn/parse), finalize (failure classification/rotation), continuation. Target
47
+ `streamAttempt` ≤ 250 lines, `adapter.ts` ≤ 1,800.
48
+
49
+ ## Phase 5 — stateful domain (done: store/admin/refresh/http/token/credentials extracted)
50
+ `pool.ts` → store/selection/admin; `quota.ts` → fetch/parse/buckets; `credential-slot.ts`
51
+ → state machine. Public methods unchanged; do last, separate release.
@@ -0,0 +1,52 @@
1
+ # Refactoring results
2
+
3
+ Branch `refactor/modular-monolith` (git worktree), based on `main` @ v0.6.18.
4
+
5
+ ## Before / after
6
+
7
+ | Metric | Before | After |
8
+ | --- | ---: | ---: |
9
+ | `src/index.ts` | 1,634 | **414** |
10
+ | `src/client/index.ts` | 3,031 | **219** |
11
+ | `src/host/adapter.ts` | 3,152 | **593** |
12
+ | `src/host/pool.ts` | 1,179 | **546** |
13
+ | `src/host/quota.ts` | 1,455 | **462** |
14
+ | Longest function (`streamAttempt`) | 1,673 | **384** |
15
+ | Modules | 54 | **205** |
16
+ | Import cycles | 0 | **0** |
17
+ | Tests | 754 | **1021** |
18
+ | Coverage (lines / branches / functions) | 78.79 / 75.73 / 75.82 | **88.44 / 80.94 / 84.09** |
19
+ | Files > 600 lines | 19 | **0** (largest: 597) |
20
+
21
+ New modules:
22
+ - `provider/`: call-context, purpose-policy, account-selection, failure, prompt,
23
+ prompt-text, finalize, span, attempt, attempt-outcome, notices.
24
+ - `transport/http/`: respond, router, routes/{status,pool,auth,config,translate,media}.
25
+ - `domain/`: quota/{buckets,identity,parse}, accounts/{selection,paths,store,admin},
26
+ credentials/{mutex,lock,docs,platform,lease,handoff,resolve,slot,errors}.
27
+ - `features/quota/`: refresh, http, token.
28
+ - `client/`: api, status, icons, styles, global-css, react, ui/*, hooks/*, sections/*,
29
+ toolview/*, images/*, translate-*.ts, mermaid-*.ts.
30
+ - `runtime/agy/`: bin, env, keychain, process, console, db/*.
31
+ - `host/commands/`, `provider/mapper/`, `provider/mirror/`.
32
+ - `host/services.ts` + `host/boot-hygiene.ts` (composition factory).
33
+
34
+ ## Verification commands
35
+ ```bash
36
+ npm run check # tsc --noEmit
37
+ npm run lint:arch # 103 modules, 0 cycles, 0 direction violations
38
+ npm run lint:budget # 103 files, 17 legacy ratchet entries
39
+ npm run build # host + client + bridge + image CLI
40
+ npm test # 788 pass / 0 fail
41
+ npm run test:coverage # Node coverage gate (85/80/80)
42
+ npm run verify # check + arch + budget + build + test
43
+ ```
44
+
45
+ ## Size status
46
+ - **Every source file is ≤ 600 lines** (largest: `src/host/services.ts` 597).
47
+ `scripts/budgets-allowlist.json` is now empty: the budget gate is strict for
48
+ all files, no legacy exceptions.
49
+ - `streamAttempt` is 384 lines; the adapter is a 593-line composition/delegate
50
+ layer. Spawn/parse/outcome, prompt, account selection, failure, finalize and
51
+ span streaming are separate provider modules.
52
+ - Client split is guarded by `test/client-architecture.test.ts`.
@@ -0,0 +1,25 @@
1
+ # ADR-001: Modular monolith with a one-way dependency rule
2
+
3
+ Status: accepted (2026-11-11)
4
+
5
+ ## Context
6
+ The plugin is one npm package with a host entry, a client bundle and a CLI. At
7
+ 30k lines the entry files had become God closures (`apply` 1,521 lines in the
8
+ host, 1,466 in the client) and duplicated runtime assembly existed in ~20 places.
9
+
10
+ ## Decision
11
+ Keep one package and one build, but enforce this dependency direction:
12
+
13
+ ```
14
+ common <- domain <- runtime <- provider <- features <- transport <- index
15
+ client -> common only (never host/provider/transport/index)
16
+ ```
17
+
18
+ `index.ts` and `host/services.ts` are the only composition points. The rule is
19
+ checked by `scripts/check-architecture.mjs` (cycles + forbidden edges) in
20
+ `npm run verify`.
21
+
22
+ ## Consequences
23
+ - New features get a natural home without a monorepo split.
24
+ - `common` stays importable by the browser bundle.
25
+ - A violation fails CI instead of being discovered in review.
@@ -0,0 +1,26 @@
1
+ # ADR-002: The provider is a pipeline, not one generator
2
+
3
+ Status: accepted (2026-11-11)
4
+
5
+ ## Context
6
+ `AgyAdapter.streamAttempt` was 1,673 lines: purpose flags, prompt assembly,
7
+ account selection, spawn/parse, tool mirroring, failure classification and
8
+ binding persistence all shared one closure. The behaviour is well covered
9
+ (≈88% lines, 2,691-line adapter test), which makes extraction safe but not free.
10
+
11
+ ## Decision
12
+ Split the attempt into named stages with narrow inputs:
13
+
14
+ ```
15
+ resolveCallContext -> purposePolicy -> buildPrompt -> acquireAccount
16
+ -> runAttempt (spawn + parse) -> classifyFailure -> finalize
17
+ ```
18
+
19
+ `stream()` keeps the host-facing signature and the effort-refusal replay. Stages
20
+ are pure where possible; the spawn stage owns the only process handle.
21
+
22
+ ## Consequences
23
+ - A new purpose is a policy row, not five edits.
24
+ - Failure classification is unit-testable without agy.
25
+ - Generator/yield ordering is the main risk: every extraction is validated by
26
+ the existing adapter tests plus a chunk-sequence golden test.
@@ -0,0 +1,18 @@
1
+ # ADR-003: One failure classifier with scope and retryability
2
+
3
+ Status: accepted (2026-11-11)
4
+
5
+ ## Context
6
+ Error codes were matched as strings in the adapter, quota, image and ask paths;
7
+ each had its own branch for "rotate account", "cool down" and "retry".
8
+
9
+ ## Decision
10
+ `src/provider/failure.ts` turns one attempt's evidence into a single
11
+ `AttemptFailure { kind, code, message, retryAfterMs? }`. Account-level codes
12
+ (`RATE_LIMIT`, `ELIGIBILITY`, `AUTH`) drive pool rotation; request-level codes
13
+ (`BAD_PARAMS`, `CONTEXT_WINDOW_EXCEEDED`) never rotate; transport codes carry a
14
+ backoff.
15
+
16
+ ## Consequences
17
+ - The classifier is table-tested for every branch.
18
+ - New agy error shapes are added in one place, with one test.
@@ -0,0 +1,18 @@
1
+ # ADR-004: One UI kit, no inline button styling
2
+
3
+ Status: accepted (2026-11-11)
4
+
5
+ ## Context
6
+ The settings panel had 100+ inline style objects and four button recipes. A new
7
+ copy button shipped without `S.btnSm` and looked like plain text — the class of
8
+ bug this ADR removes.
9
+
10
+ ## Decision
11
+ `src/client/ui/*` owns Button/Row/Select/Toggle/Modal/Toast/Spinner. Variants and
12
+ sizes map to the existing tokens (`S.btn`, `S.btnSm`, `S.btnPrimary`,
13
+ `S.btnDanger`). Sections compose primitives; `index.ts` only wires slots and
14
+ locale.
15
+
16
+ ## Consequences
17
+ - Style changes happen once.
18
+ - A source test rejects inline `<button style=...>` outside `ui/`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-agy-link",
3
- "version": "0.6.17",
3
+ "version": "0.6.21",
4
4
  "description": "Google Antigravity (agy CLI) models for DeepSeek Harness — stream Gemini/Claude/GPT-OSS subscriptions into DSH with thinking, tool activity, token usage and in-GUI Google OAuth login.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -35,8 +35,8 @@
35
35
  },
36
36
  "peerDependencies": {
37
37
  "@deepseek-ai/cordis": "*",
38
- "@deepseek-ai/dsh-commands": "*",
39
38
  "@deepseek-ai/dsh-client-locale": "*",
39
+ "@deepseek-ai/dsh-commands": "*",
40
40
  "@deepseek-ai/dsh-llm": "*",
41
41
  "@deepseek-ai/dsh-tools": "*",
42
42
  "react": "^18.0.0"
@@ -69,6 +69,9 @@
69
69
  "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
70
70
  "@types/node": "^24.3.0",
71
71
  "@types/qrcode": "^1.5.5",
72
+ "jsdom": "^29.1.1",
73
+ "react": "^18.0.0",
74
+ "react-dom": "^18.0.0",
72
75
  "tsdown": "^0.22.14",
73
76
  "typescript": "^5.9.2",
74
77
  "undici": "^8.10.0"
@@ -100,10 +103,14 @@
100
103
  "scripts": {
101
104
  "build": "tsdown",
102
105
  "check": "tsc --noEmit",
103
- "test": "node --experimental-transform-types --test --test-concurrency=1 \"test/**/*.test.ts\"",
106
+ "test": "node --experimental-transform-types --test \"test/**/*.test.ts\"",
104
107
  "test:fast": "node scripts/fast-test.mjs",
105
108
  "prepare": "npm run build",
106
- "prepack": "npm run build"
109
+ "prepack": "npm run build",
110
+ "lint:arch": "node scripts/check-architecture.mjs",
111
+ "lint:budget": "node scripts/check-budgets.mjs",
112
+ "test:coverage": "node --experimental-transform-types --test --test-concurrency=1 --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=80 --test-coverage-functions=80 \"test/**/*.test.ts\"",
113
+ "verify": "npm run check && npm run lint:arch && npm run lint:budget && npm run build && npm test"
107
114
  },
108
115
  "engines": {
109
116
  "node": ">=24.0.0"