@aeye/ginny 0.3.9

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,180 @@
1
+ # @aeye/ginny — Architecture: Sub-Agents & the Build Loop
2
+
3
+ Part of the [@aeye/ginny LLM reference](./aeye-ginny.md).
4
+
5
+ ## The pipeline
6
+
7
+ ```
8
+ ┌─────────────┐
9
+ user request ──▶ │ programmer │
10
+ └──────┬──────┘
11
+ ┌────────────────┬──────┴──────┬────────────────┐
12
+ ▼ ▼ ▼ ▼
13
+ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
14
+ │ architect │ │ designer │ │ dba │ │ researcher │
15
+ │ (types) │ │ (fns) │ │ (vars) │ │ (web) │
16
+ └─────────────┘ └──────┬───────┘ └──────────────┘ └──────────────┘
17
+ │
18
+ ▼ (recursive spin-up)
19
+ programmer
20
+ ```
21
+
22
+ The CLI entry (`src/index.ts`) appends the user's text to a `Message[]`
23
+ history and streams the **programmer** prompt (`programmer.get('stream',
24
+ …)`). Each `message` event is captured into history so the next REPL turn
25
+ has full context. A shared `originalRequest` and a `programmerDepth`
26
+ (starting at 0) are threaded down through every recursive sub-agent.
27
+
28
+ Each sub-agent is an `ai.prompt(...)` (from `@aeye/core` via the
29
+ `@aeye/ai` instance in `src/ai.ts`) with its own tool list. Sub-agents
30
+ other than the programmer set `excludeMessages: true` — they take their
31
+ task through a `{{description}}` / `{{question}}` template variable rather
32
+ than inheriting the parent's conversation, which avoids forwarding a
33
+ half-finished `tool_calls` assistant message to the provider.
34
+
35
+ ## The five sub-agents and their tools
36
+
37
+ All tool names below are the literal `name` fields the model sees.
38
+
39
+ ### programmer (`gin_programmer`)
40
+
41
+ The orchestrator. Writes, tests, and finalizes gin programs; delegates to
42
+ the others when it needs catalog items. `dynamic: true`,
43
+ `toolIterations` from `GIN_TOOL_ITERATIONS`. Tools:
44
+
45
+ - `find_or_create_types` → delegates to **architect**
46
+ - `find_or_create_functions` → delegates to **designer**
47
+ - `find_or_create_vars` → delegates to **dba**
48
+ - `research` → delegates to **researcher** (only present when Tavily is configured)
49
+ - `write`, `test`, `finish` — the build loop (below)
50
+ - `edit_type` — backwards-compatible edit of a saved type
51
+ - `search_fns`, `search_vars`, `print_fn` — inspect the catalog (lookups also register a saved fn into the engine so it becomes callable)
52
+ - `ask` — prompt the human user
53
+
54
+ The programmer's system prompt embeds: the full method surface of every
55
+ registered type, a names-only preview of the on-disk catalog, and the
56
+ signatures of fns already loaded this session. It distinguishes three
57
+ response modes — informational answers, simple one-shot computations
58
+ (straight to write/test/finish), and complex requests (a
59
+ **plan-and-approve** workflow: ask clarifying questions, present a written
60
+ plan of types/fns/vars, iterate until the user approves, then implement).
61
+
62
+ ### architect (types)
63
+
64
+ Designs or picks gin types. Tools: `search_types`, `get_type`, `ask`.
65
+ Returns structured `{ use: string[], create: TypeDef[] }`.
66
+
67
+ ### designer (functions)
68
+
69
+ Finds or authors reusable functions. Tools: `search_fns`, `get_fn`,
70
+ `print_fn`, `create_new_fn`, `edit_fn`, `ask`. Returns structured
71
+ `{ use: string[], created: string[] }`, and **validates** that every named
72
+ fn is actually readable on disk (re-prompts the model if it hallucinates).
73
+
74
+ - `create_new_fn` — the designer decides the signature (`args`, `returns`,
75
+ optional `types` aliases) and then **recursively spawns a programmer**
76
+ to author the body. Backwards behavior is enforced by the inner
77
+ programmer reaching a passing test and calling `finish({ saveAs })`.
78
+ - `edit_fn` — change a saved fn's signature + body. The new signature is
79
+ compat-checked **before** spawning the inner programmer: args may widen
80
+ (add optional params, widen types); returns may **narrow**. Removing
81
+ required args, narrowing arg types, or widening returns is rejected.
82
+
83
+ ### dba (vars)
84
+
85
+ Curates `vars.*`. Tools: `search_vars`, `get_var`, `create_var`, `ask`.
86
+ For credentials/external parameters the user hasn't supplied, it creates
87
+ the var with a placeholder value and **setup instructions in the var's
88
+ `docs`** rather than halting to ask.
89
+
90
+ ### researcher (web)
91
+
92
+ Only wired into the programmer when `ctx.features.webSearch` is true
93
+ (Tavily configured). Tools: `web_search` (Tavily; `query`, optional
94
+ `maxResults` default 5), `web_get_page` (`url`; renders HTML via headless
95
+ Puppeteer, parses PDF/DOCX/XLSX to markdown, output capped ~16k chars),
96
+ and `ask`. Returns structured `{ answer, sources }`.
97
+
98
+ ## Recursion and the depth cap
99
+
100
+ Function authoring is recursive: programmer → `find_or_create_functions`
101
+ → designer → `create_new_fn` → a fresh programmer that writes the body.
102
+
103
+ - `MAX_PROGRAMMER_DEPTH = 3` (in `src/context.ts`).
104
+ - `ctx.programmerDepth` increments by 1 on each `create_new_fn` /
105
+ `edit_fn`.
106
+ - `find_or_create_functions`, `create_new_fn`, and `edit_fn` set
107
+ `applicable` to require depth `< MAX_PROGRAMMER_DEPTH - 1`. The deepest
108
+ programmer **cannot** delegate further — it must write the function body
109
+ inline.
110
+ - When a programmer is authoring a specific fn body, `ctx.targetFn` is set
111
+ (the designer-designed signature). `find_or_create_functions` is
112
+ withheld in that case so the programmer can't respawn a designer for the
113
+ same task and recurse uncontrolled.
114
+ - A `programmerChain` records the ancestry so a deep programmer sees which
115
+ caller needs its output and what the original user request was.
116
+
117
+ ## The write / test / finish loop
118
+
119
+ This is the programmer's core cycle (`src/tools/write.ts`, `test.ts`,
120
+ `finish.ts`):
121
+
122
+ 1. **`write({ program: <ExprDef> })`** — stores the draft. It renders the
123
+ program back as TypeScript-like pseudocode (via `toCode`), runs static
124
+ validation, and reports:
125
+ - **ERRORS** (must be fixed before `test`),
126
+ - **WARNINGS** (advisory; too many block `finish`),
127
+ - a **complexity** figure vs the cap (continuous feedback so the model
128
+ decomposes before it's rejected).
129
+ Full problem detail (with underlined spans, in both TS and JSON form)
130
+ goes to `ginny.log` under a grep id; the tool result keeps the compact
131
+ TS form.
132
+
133
+ 2. **`test({ args?, expectError? })`** — runs the draft. When a `targetFn`
134
+ is in scope the draft is wrapped in a lambda and invoked through gin's
135
+ call machinery (so `args` and `recurse` resolve like the saved fn
136
+ will); otherwise it runs via `engine.run`. `args` schema is auto-built
137
+ from the function's args type. Set `expectError: true` to treat a
138
+ runtime error as success (e.g. "divide by zero and tell me what
139
+ happens"). Var mutations from the run are persisted via dirty-tracking.
140
+
141
+ 3. **`finish({ saveAs?, docs? })`** — finalize after a passing test.
142
+ - Without `saveAs`: returns the one-shot result; nothing is persisted.
143
+ - With `saveAs`: re-validates the draft and **rejects the save** if
144
+ warnings exceed `GIN_MAX_WARNINGS` (default 5), if any errors are
145
+ present, or if structural complexity exceeds `GIN_MAX_COMPLEXITY`
146
+ (default 400 — decompose into helper fns to reduce it; each helper
147
+ call costs 1 at the call site regardless of its body size). On
148
+ success it writes `./fns/<saveAs>.json` and registers the fn as a
149
+ callable top-level global.
150
+
151
+ "Everything is a function": there is no separate programs concept. A
152
+ finished one-shot computation is just a `fn() => T` whose `call.get` is
153
+ the program body.
154
+
155
+ ## Catalog search behavior
156
+
157
+ `src/store.ts` implements search per directory. Important and easy to get
158
+ wrong: **search is keyword text-match scoring, not embeddings.**
159
+
160
+ - If a directory has at most `GIN_SEARCH_THRESHOLD` (default 20) entries,
161
+ **or** no keywords are given, search returns all entries (up to the
162
+ limit) with score 0.
163
+ - Above the threshold, each entry's searchable text (name, docs,
164
+ `extends`, prop names, etc.) is scored by counting keyword occurrences;
165
+ entries with score 0 are dropped; the top-N (default limit 10) are
166
+ returned.
167
+
168
+ The programmer's prompt also embeds a names-only preview (capped at 20 per
169
+ category with a `+N more` suffix) so the model can skip blind `search_*`
170
+ calls when an obviously-named entry already exists.
171
+
172
+ ## Editing existing types
173
+
174
+ - `edit_type({ name, def })` (programmer tool) — replace a saved type's
175
+ definition. Allowed: add **optional** fields, widen existing field
176
+ types, loosen constraints. Rejected: remove fields, add required fields,
177
+ narrow field types, change the type class. The compat check runs at
178
+ parse time. If a change is genuinely breaking, the right move is to
179
+ create a new type/fn under a different name so existing callers keep
180
+ working.
@@ -0,0 +1,186 @@
1
+ # @aeye/ginny — CLI, Configuration & Persistence
2
+
3
+ Part of the [@aeye/ginny LLM reference](./aeye-ginny.md).
4
+
5
+ ## Invocation
6
+
7
+ The binary is `ginny` (`bin.ginny → dist/index.js`). There are exactly
8
+ two ways to invoke it — the entry point reads a single positional
9
+ argument (`process.argv[2]`); there are **no option flags**.
10
+
11
+ ```bash
12
+ ginny # interactive REPL (no arg)
13
+ ginny "your request" # one-shot: runs the request, then exits
14
+ ```
15
+
16
+ - **REPL mode** (no arg): clears the screen (TTY only), prints a startup
17
+ banner, then loops on a `> ` prompt. Each non-empty line is processed
18
+ as a request; history is carried across turns.
19
+ - **One-shot mode** (one arg): runs that single request and exits. Wrap
20
+ multi-word requests in quotes.
21
+
22
+ ### Interrupts
23
+
24
+ - **ESC** — interrupts the in-flight request and returns to the `> `
25
+ prompt without killing the REPL. (Listened for on both `keypress` and
26
+ raw `data`/SIGINT channels for cross-platform reliability.)
27
+ - **Ctrl+C** — also aborts an in-flight request; at the idle prompt it
28
+ exits the process.
29
+
30
+ The interrupt signal is forwarded into in-program I/O (`fns.fetch`,
31
+ `fns.llm`) and into web tools so a long network call unwinds cleanly.
32
+
33
+ ### npm scripts (from `package.json`)
34
+
35
+ | Script | Command | Purpose |
36
+ |---|---|---|
37
+ | `build` | `npm run clean && node esbuild.config.cjs` | Bundle to `dist/index.js` (single ESM file + shebang). |
38
+ | `dev` | `tsx src/index.ts` | Run from source. |
39
+ | `start` | `tsx --conditions=source src/index.ts` | Run from source using workspace `source` exports. |
40
+ | `clean` | `rimraf dist tsconfig.tsbuildinfo` | Remove build output. |
41
+ | `typecheck` | `tsc --noEmit` | Type-check only. |
42
+
43
+ ## First run in a directory
44
+
45
+ If `config.json` does not exist in the CWD, ginny:
46
+
47
+ 1. Writes a `config.json` template.
48
+ 2. Appends `config.json` and `ginny.log` to `.gitignore` (creating it if
49
+ needed).
50
+ 3. Prints setup instructions and **exits** (no request is processed).
51
+
52
+ Populate at least one provider credential, then re-run. Example
53
+ `config.json`:
54
+
55
+ ```json
56
+ {
57
+ "OPENAI_API_KEY": "sk-...",
58
+ "GIN_PROVIDER": "openai",
59
+ "GIN_MODEL": "gpt-4o-mini",
60
+ "TAVILY_API_KEY": "tvly-..."
61
+ }
62
+ ```
63
+
64
+ ## Providers
65
+
66
+ At least one provider must resolve at startup or ginny throws. The three
67
+ candidates:
68
+
69
+ - **openai** — enabled when `OPENAI_API_KEY` is set.
70
+ - **openrouter** — enabled when `OPENROUTER_API_KEY` is set.
71
+ - **aws** (Bedrock) — there is **no single env var**. ginny probes the
72
+ AWS SDK's standard credential chain at startup via a health check
73
+ (`ListFoundationModels`). Any working credential source enables it:
74
+ `aws sso login`, `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, an
75
+ attached IAM role, `~/.aws/credentials`, or container credentials.
76
+ `AWS_REGION` defaults to `us-east-1`.
77
+
78
+ The startup banner reports which providers came up, which were skipped
79
+ (with reasons), the configured model IDs, and whether web research
80
+ (Tavily) is enabled.
81
+
82
+ ## Configuration
83
+
84
+ Config values come from `config.json` in the CWD **or** from environment
85
+ variables. **Environment variables always win** on conflict. `config.json`
86
+ values are hydrated into `process.env` at startup before anything reads
87
+ them.
88
+
89
+ ### Keys recognized in `config.json` (and as env vars)
90
+
91
+ These are the typed fields in the `config.json` template:
92
+
93
+ | Key | Default | Purpose |
94
+ |---|---|---|
95
+ | `OPENAI_API_KEY` | — | Enable OpenAI provider. |
96
+ | `OPENROUTER_API_KEY` | — | Enable OpenRouter provider. |
97
+ | `AWS_ACCESS_KEY_ID` | — | Optional explicit AWS key (chain usually suffices). |
98
+ | `AWS_SECRET_ACCESS_KEY` | — | Optional explicit AWS secret. |
99
+ | `AWS_REGION` | `us-east-1` | Bedrock region. |
100
+ | `TAVILY_API_KEY` | — | Enable `web_search` / `web_get_page` and the `research` tool. |
101
+ | `GIN_PROVIDER` | — | Preferred provider (`openai` \| `openrouter` \| `aws`). |
102
+ | `GIN_MODEL` | — | Pin a model id; fallback for any sub-agent without an override. |
103
+ | `GIN_SEARCH_THRESHOLD` | `20` | Catalog size at/below which a search returns all entries (above it, keyword-scored top-N). |
104
+ | `GIN_TOOL_ITERATIONS` | `100` | Max tool-call iterations per prompt run. |
105
+
106
+ ### Env-only variables (not in the template)
107
+
108
+ | Variable | Default | Purpose |
109
+ |---|---|---|
110
+ | `GIN_PROGRAMMER_MODEL` | — | Model id for the programmer sub-agent. |
111
+ | `GIN_DESIGNER_MODEL` | — | Model id for the designer (functions) sub-agent. |
112
+ | `GIN_ARCHITECT_MODEL` | — | Model id for the architect (types) sub-agent. |
113
+ | `GIN_DBA_MODEL` | — | Model id for the dba (vars) sub-agent. |
114
+ | `GIN_RESEARCHER_MODEL` | — | Model id for the researcher sub-agent. |
115
+ | `GIN_LLM_MODEL` | — | Model id for in-program `fns.llm` calls. |
116
+ | `GIN_MAX_WARNINGS` | `5` | Max validation warnings allowed on a saved fn (`finish` rejects above this). |
117
+ | `GIN_MAX_COMPLEXITY` | `400` | Max structural complexity for a saved fn body (`finish` rejects above this). |
118
+ | `GIN_WRITE_MAX_ARGS_LENGTH` | `16384` | Byte cap on the raw `write` tool args (guards against wire double-encoding). |
119
+ | `GIN_LOG_FULL_PAYLOAD` | unset | When set, logs full request/response payloads (large; for debugging 400s). |
120
+
121
+ Per-sub-agent model resolution: each agent reads `GIN_<KEY>_MODEL`
122
+ (`KEY` ∈ `PROGRAMMER`, `DESIGNER`, `ARCHITECT`, `DBA`, `RESEARCHER`,
123
+ `LLM`), falling back to `GIN_MODEL`, falling back to the AI model
124
+ registry's default selection. This lets the heavyweight programmer run on
125
+ a strong model while catalog curators run on something cheaper:
126
+
127
+ ```bash
128
+ GIN_PROGRAMMER_MODEL=gpt-5
129
+ GIN_DBA_MODEL=gpt-4o-mini
130
+ GIN_RESEARCHER_MODEL=gpt-4o-mini ginny "build a small task tracker"
131
+ ```
132
+
133
+ ## Persistence — the on-disk catalog
134
+
135
+ Everything the agent saves is one JSON file per name, in three
136
+ directories relative to the **current working directory**. The filename
137
+ **is** the identity (no internal id field needed).
138
+
139
+ ```
140
+ ./types/Task.json # a gin TypeDef
141
+ ./fns/factorial.json # a function (TypeDef whose body is at call.get)
142
+ ./vars/apiBaseUrl.json # a persistent var: { type, value, docs }
143
+ ```
144
+
145
+ - You can hand-edit any of these between sessions; the next run picks up
146
+ the changes. Drop a new file into a directory by hand and ginny
147
+ discovers it on the next catalog search.
148
+ - A saved function becomes a **callable top-level global** for the rest of
149
+ the session (and future sessions on load) — invoked by its bare name,
150
+ not under `fns.*`.
151
+
152
+ Example `./vars/apiBaseUrl.json`:
153
+
154
+ ```json
155
+ {
156
+ "type": { "name": "text", "options": { "pattern": "^https?://" } },
157
+ "value": "https://api.example.com",
158
+ "docs": "production API root"
159
+ }
160
+ ```
161
+
162
+ See [aeye-ginny-api.md](./aeye-ginny-api.md) for the function and type
163
+ file shapes in detail.
164
+
165
+ ## Logging
166
+
167
+ Each session writes a verbose timeline to `./ginny.log` (truncated at
168
+ startup). Tool inputs/outputs, full validation problems, zod parse
169
+ errors, retry/backoff events, and stack traces land there. The terminal
170
+ view stays compact (one short line per error). Errors in the terminal are
171
+ stamped with a 6-character id; `grep <id> ginny.log` recovers the full
172
+ record. Memory-probe lines (`[mem] ...`) are emitted for leak hunting.
173
+
174
+ ## Building from source
175
+
176
+ ```bash
177
+ git clone https://github.com/ClickerMonkey/aeye.git
178
+ cd aeye
179
+ npm install
180
+ cd packages/ginny
181
+ npm run start # dev run (tsx --conditions=source)
182
+ npm run build # bundled dist/index.js with shebang
183
+ ```
184
+
185
+ The production build is a single ESM file with a Node shebang; the global
186
+ install (`npm i -g @aeye/ginny`) links `ginny` straight to it.
package/aeye-ginny.md ADDED
@@ -0,0 +1,109 @@
1
+ # @aeye/ginny — LLM Reference (Overview & Index)
2
+
3
+ > Audience: an LLM (or an agent) that needs to understand, run, or reason
4
+ > about `@aeye/ginny`. Everything here is verified against the source in
5
+ > `packages/ginny/src`. Do not invent flags, env vars, or APIs beyond
6
+ > what these files document.
7
+
8
+ ## What ginny is
9
+
10
+ `@aeye/ginny` is a **CLI that turns natural-language requests into
11
+ executable [gin](../gin) programs**. You type a request in plain English;
12
+ ginny writes a gin program (a JSON expression tree) to satisfy it, tests
13
+ it against sample inputs, and returns the result. Types, functions, and
14
+ vars the agent creates are persisted as JSON files in the current working
15
+ directory, so a typed catalog of reusable code grows across sessions.
16
+
17
+ - Package name: `@aeye/ginny`
18
+ - Binary: `ginny` (maps to `dist/index.js`, an ESM file with a Node shebang)
19
+ - License: GPL-3.0
20
+ - Node engine: `>=18.0.0`
21
+ - It is an **application/CLI, not a library** — see
22
+ [aeye-ginny-api.md](./aeye-ginny-api.md) for what that means for
23
+ programmatic use.
24
+
25
+ ## When to use ginny
26
+
27
+ Use ginny when you want to:
28
+
29
+ - Generate, test, and persist small typed programs from natural language
30
+ without writing gin `ExprDef` JSON by hand.
31
+ - Build a reusable, CWD-local catalog of typed functions / types / vars
32
+ that survives across sessions and is hand-editable.
33
+ - Call HTTP APIs with typed response parsing, invoke an LLM with
34
+ structured typed output, or prompt the user interactively — all from
35
+ inside generated programs (`fns.fetch`, `fns.llm`, `fns.ask`).
36
+ - Study a reference embedding of `@aeye/gin` + `@aeye/ai`: a recursive
37
+ multi-sub-agent system with strict-mode tool schemas and multi-provider
38
+ model selection.
39
+
40
+ Do **not** use ginny as an importable library — importing its entry
41
+ module runs the CLI. To embed the same capabilities, use `@aeye/gin`
42
+ directly.
43
+
44
+ ## Quick start
45
+
46
+ ```bash
47
+ npm install -g @aeye/ginny
48
+ cd my-project
49
+ ginny # interactive REPL
50
+ ginny "add 2 and 3" # one-shot (single positional arg)
51
+ ```
52
+
53
+ On the **first run in a directory**, ginny scaffolds a `config.json`
54
+ template, adds `config.json` and `ginny.log` to `.gitignore`, prints
55
+ setup instructions, and exits. Populate at least one provider key and
56
+ re-run. Full details: [aeye-ginny-cli.md](./aeye-ginny-cli.md).
57
+
58
+ ## How it works (one-paragraph pipeline)
59
+
60
+ The REPL/one-shot entry point appends your request to a conversation
61
+ history and streams the **programmer** sub-agent. The programmer writes a
62
+ gin program via the `write` tool, runs it via `test`, and persists it via
63
+ `finish`. When it needs types, reusable functions, or named vars not
64
+ already in scope, it delegates to specialist sub-agents — **architect**
65
+ (types), **designer** (functions), **dba** (vars), and **researcher**
66
+ (web) — each of which searches the on-disk catalog and creates new
67
+ entries when nothing matches. The designer authors a new function body by
68
+ **recursively spawning another programmer** (bounded to 3 levels deep).
69
+ Everything is typed end-to-end inside gin's type system, and structured
70
+ outputs are produced through Zod schemas so the model cannot emit invalid
71
+ expressions. See [aeye-ginny-architecture.md](./aeye-ginny-architecture.md).
72
+
73
+ ## Relationship to other @aeye packages
74
+
75
+ - **`@aeye/gin`** — the typed-program runtime ginny builds on: the type
76
+ system, the expression engine (`engine.run`), and the Zod schema
77
+ generation the agents use to author valid programs. ginny is a thin
78
+ layer of tool/prompt definitions over gin's public API.
79
+ - **`@aeye/core`** — the prompt / tool / agent primitives (`ai.prompt`,
80
+ `ai.tool`, `Message`, `ToolInterrupt`, prompt-event streaming) that
81
+ every ginny sub-agent is built from.
82
+ - **`@aeye/ai`** — the `AI` instance: provider registration, model
83
+ selection, metadata, and hooks.
84
+ - **`@aeye/openai`, `@aeye/openrouter`, `@aeye/aws`** — the three
85
+ providers ginny can enable.
86
+ - **`@aeye/models`** — the model registry plus `strictSupport`, which
87
+ opts strict-capable model families into grammar-constrained tool inputs.
88
+
89
+ ## Index of detailed docs
90
+
91
+ | File | Covers |
92
+ |---|---|
93
+ | [aeye-ginny-cli.md](./aeye-ginny-cli.md) | Running the CLI, REPL vs one-shot, interrupts, first-run scaffold, config.json, all environment variables, persistence/catalog layout, logging, building from source. |
94
+ | [aeye-ginny-architecture.md](./aeye-ginny-architecture.md) | The sub-agent council, each agent's tools, the write/test/finish loop, recursive function authoring, depth cap, complexity/warning gates, catalog search behavior. |
95
+ | [aeye-ginny-api.md](./aeye-ginny-api.md) | Built-in program globals (`fns.fetch` / `fns.llm` / `fns.log` / `fns.ask`, `vars.*`, saved fns), on-disk JSON shapes, programmatic-use note, gotchas. |
96
+
97
+ ## Source map (for deeper reading)
98
+
99
+ - `src/index.ts` — CLI entry: REPL loop, one-shot, ESC/Ctrl+C interrupts, startup banner.
100
+ - `src/ai.ts` — AI instance, provider probing, hooks, native wiring (`fns.*`).
101
+ - `src/config.ts` — `config.json` load/scaffold, `.gitignore` management, env hydration.
102
+ - `src/model-selection.ts` — per-sub-agent model resolution, tool-iteration cap.
103
+ - `src/store.ts` — CWD-relative catalog read/write/search.
104
+ - `src/context.ts` — the `Ctx` shared across sub-agents; `MAX_PROGRAMMER_DEPTH`.
105
+ - `src/prompts/*` — the sub-agent definitions (programmer, architect, designer, dba, researcher).
106
+ - `src/tools/*` — `write`, `test`, `finish`, `research`, `find-or-create-*`, `edit-type`, `ask`, web tools, etc.
107
+ - `src/natives/*` — `fns.fetch`, `fns.llm`, `fns.log`, `fns.ask` implementations.
108
+ - `src/consumer.ts` — interactive type-walker behind `fns.ask`.
109
+ - `src/progress.ts`, `src/event-display.ts`, `src/logger.ts` — terminal/log output.