From 3becca79d270fd31b93b743831d134eb58068906 Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Wed, 14 Oct 2026 13:56:12 -0300 Subject: [PATCH 1/3] chore: start 103 From 765d888fdb2486e5cf9d6aa4be78237f996f2ece Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Fri, 6 Nov 2026 11:51:58 +0000 Subject: [PATCH 2/3] chore(tooling): propagate reviewed Beans AI tooling --- .codegraph-version | 1 + .codegraph/.gitignore | 5 +++ AGENTS.md | 2 + docs/ai-tooling.md | 86 +++++++++++++++++++++++++++++++++++++++++++ scripts/codegraph.sh | 17 +++++++++ 5 files changed, 111 insertions(+) create mode 100644 .codegraph-version create mode 100644 .codegraph/.gitignore create mode 100644 docs/ai-tooling.md create mode 100755 scripts/codegraph.sh diff --git a/.codegraph-version b/.codegraph-version new file mode 100644 index 00000000..fdd3be6d --- /dev/null +++ b/.codegraph-version @@ -0,0 +1 @@ +1.6.2 diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore new file mode 100644 index 00000000..d20c0fe4 --- /dev/null +++ b/.codegraph/.gitignore @@ -0,0 +1,5 @@ +# CodeGraph data files — local to each machine, not for committing. +# Ignore everything in .codegraph/ except this file itself, so transient +# files (the database, daemon.pid, sockets, logs) never show up in git. +* +!.gitignore diff --git a/AGENTS.md b/AGENTS.md index a6f3edd8..e4ffb564 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Beans +For T3 onboarding, retrieval, command output and model reservations, follow [AI tooling](docs/ai-tooling.md). Product work remains HOLD until Heitor explicitly says OK. + Read [ARCHITECTURE.md](./ARCHITECTURE.md) before writing code, then the subject docs it lists for the parts you change. Identity is a local key pair. Paired Devices sync through an E2E relay. Provider credentials belong to the account: they sync to every paired Device as a blob encrypted with the account key. The AppKit app talks to the local CLI. diff --git a/docs/ai-tooling.md b/docs/ai-tooling.md new file mode 100644 index 00000000..b781f692 --- /dev/null +++ b/docs/ai-tooling.md @@ -0,0 +1,86 @@ +# Prepare and use AI tooling + +Read [AGENTS.md](../AGENTS.md), [BEANS.md](../BEANS.md) and [ARCHITECTURE.md](../ARCHITECTURE.md) before changing Beans. `CLAUDE.md` points to `AGENTS.md`; preserve that link and all existing instructions. + +## Keep product work on HOLD + +This preparation permits onboarding, tooling installation, independently reviewed tooling PRs, normal tooling merges and branch propagation. Product work remains HOLD until Heitor explicitly says OK. Green checks, a tooling merge and completed propagation do not release product work. Do not merge product PRs during this rollout. + +The central coordinator owns global settings and routing. Read `/Users/heitor/.config/ai-tooling/COORDINATION.md` and the current `GLOBAL-ROLLOUT.md` linked there. Report global configuration gaps to that coordinator. Keep one external rollout REPORT with commands, exit codes, receipt hashes, exact heads, resources and blockers. + +Target `bloodf/beans` explicitly for GitHub operations. `origin` is the Beans repository; `upstream` is `egoist/lorca`. T3's upstream canonical identity does not authorize upstream publication or integration. Confirm remotes, branch, HEAD, current base, worktrees and dirty state before writing. Similar source content does not prove ancestry. + +Preserve all refs with a verified Git bundle before propagation. Save staged and unstaged patches, untracked files and their hashes separately. Use an isolated tooling checkout. Preserve existing worktrees and previous work. Do not use automatic stash, `reset --hard`, force push or shared cleanup. + +## Retrieve source with CodeGraph 1.6.2 + +The standalone CLI is pinned by `.codegraph-version`. `scripts/codegraph.sh` checks the installed version, disables telemetry for its process and runs from this checkout's root. Keep CodeGraph outside application dependencies. + +Use the existing installation when it matches the pin. For workstation installation, inspect the installer at `https://raw.githubusercontent.com/colbymchenry/codegraph/f72c9d2efb14454ff4f9fd7b8460abd82f19a287/install.sh`, then run the inspected file with `CODEGRAPH_VERSION=v1.6.2`. Installation and user-specific MCP configuration belong to the central coordinator. + +Run these commands from the repository root: + +```sh +sh scripts/codegraph.sh init --yes +sh scripts/codegraph.sh sync +sh scripts/codegraph.sh status --json +sh scripts/codegraph.sh query dispatch --limit 5 --json +sh scripts/codegraph.sh callers dispatch --file crates/cli/src/api.rs --limit 5 --json +sh scripts/codegraph.sh explore --max-files 3 'api dispatch websocket serve' +``` + +Start with a bounded query before broad source reads. For exact text, missing results or unsupported syntax, use bounded `rg` and exact file ranges. Inspect the actual definition and caller before changing a flow. A graph relationship does not prove runtime behavior or complete dynamic call coverage. + +Each worktree has its own `.codegraph/` index. Do not copy databases between checkouts. Run `sync` and inspect `status --json` after checkout or edits. Check indexed languages, file/node counts, pending changes, worktree mismatch and index completion. Rebuild with `index` after changing include/exclude/extension rules. Version 1.6.2 has no `--strict` flag. + +Track only `.codegraph/.gitignore` inside `.codegraph/`. The ignore file excludes databases, logs, sockets, locks and daemon state. Never commit generated graphs or index data. With a configured CodeGraph MCP, keep the default single `codegraph_explore` tool; otherwise use the same bounded CLI commands. + +## Preserve command status with RTK 1.0.1 + +Read `/Users/heitor/.codex/RTK.md` when present. With a native RTK PreToolUse hook, run normal commands and do not wrap them twice. Without a native hook, use supported explicit commands such as `rtk git status` and `rtk gh pr list --repo bloodf/beans`. MiniMax uses this CLI route. Do not assume one harness's hooks apply to another. + +Preserve the actual exit code and first failure receipt. If condensed output is empty, contradictory or unusable, recover it with `rtk bypass ` or the stored raw receipt. Diagnose the first failure before another attempt. Do not weaken a check, timeout, baseline, security boundary or review requirement to obtain green results. + +## Use Caveman and Ponytail + +Use concise, complete Portuguese sentences with the user. Keep errors, identifiers, numbers and negations exact. Write code, persisted documents and critical instructions in complete language. + +Inspect the affected flow and callers, reuse existing code and standard libraries, and make the smallest complete change. Verify behavior at the relevant boundary. Preserve security, accessibility, approval, encryption and data-loss controls. Installation, synthetic probes, local checks, hosted checks and live behavior are separate evidence. + +## Verify TokenEconomizer per harness + +Reuse the central installation. Preserve the mode without auxiliary paid model calls: `microskills=envfacts`, `loopguard=off`, `repomap=off` and `toolprune=propose`. Do not set a paid model or enable paid proposers. Keep orchestration, review, device and required verification tools available; proposals cannot override project policy. + +From the checkout, inspect effective state without a model call: + +```sh +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" status +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" config show +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" repos list +``` + +Confirm the repository identity is the Beans origin and verify a worktree maps to that same repository. Record the installed adapter's supported events for each harness actually used. Codex's installed hook file declares `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop` and `SessionEnd`; declaration alone does not prove delivery through T3. + +Separate configuration present from fresh-session runtime proof. Loading a skill, starting a process or seeing a zero-session status does not prove the full lifecycle. Record unproved events as UNKNOWN. Do not invent adapters or hook support for Antigravity, MiniMax or another harness. TokenEconomizer learns repository facts and proposes tool pruning; it is not a generic output compressor. No local token savings are claimed without measurement. + +## Reserve every worker through the central dispatcher + +Before each tooling worker, reserve a route: + +```sh +t3-model-route reserve --project beans --purpose tooling --task '' +``` + +Launch only the exact returned provider, model and options through the applicable T3 delegation mechanism. Antigravity accepts Google models only. MiniMax M3.1 Flash requires `m:minimax:MiniMax-M3.1-Flash:v:thinking`. Quota UNKNOWN is not proof of capacity. Never substitute another project, provider or model, retry quota blindly, edit the global helper or implement a local round robin. + +Give each worker exact scope and file ownership. State that concurrent work must be preserved. Record the lease, task/run, provider, model and terminal outcome. Release only the exact lease after terminal evidence. Start no top-level thread for a worker. Use a fresh independent reviewer for each review or re-check, with the exact base/head and applicable risk requirements. No author approves their own change. + +## Verify and propagate tooling + +Keep the existing Beans gates. `bun run check:docs`, `bun run check:catalog` and the same-repository PR test matrix remain applicable. Inspect the current workflow definitions before execution; a local tooling smoke does not replace hosted checks. Product homes, accounts, relays, signing inputs and deployments are not tooling fixtures. + +Create one tooling PR against current Beans `main` and link it immediately to T3. Merge only after independent exact-head review and the real required checks pass. When waiting for hosted checks, use T3's PR watch and end the run; do not poll CI. + +Before propagation, prepare a per-ref plan with original head, target payload, old-head ancestry proof and recovery instructions. Append only tooling to every existing local and origin branch, including historical branches and open PR heads. Preserve each branch's existing instruction and ignore bytes. Do not merge unrelated product history, silently resolve divergence or recreate a branch absent from the server. Push fast-forward with explicit refspecs. Stop on the first remote write failure, re-read remote state and report to central before retry or a strategy change. + +Recheck current remote and PR heads, rescan for new refs, validate indexes in used checkouts and settle owned processes and leases. Record any uncovered ref as BLOCKED with a concrete reason. Product work still waits for Heitor's explicit OK. diff --git a/scripts/codegraph.sh b/scripts/codegraph.sh new file mode 100755 index 00000000..d6aa27fb --- /dev/null +++ b/scripts/codegraph.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# Run from any directory with the repository's reviewed CodeGraph version. +set -eu +codegraph_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd) +cd "$codegraph_root" +codegraph_expected=$(cat .codegraph-version) +if ! command -v codegraph >/dev/null 2>&1; then + echo "CodeGraph $codegraph_expected required. See docs/ai-tooling.md." >&2 + exit 1 +fi +codegraph_actual=$(codegraph --version) +if [ "$codegraph_actual" != "$codegraph_expected" ]; then + echo "CodeGraph $codegraph_expected required; found $codegraph_actual. See docs/ai-tooling.md." >&2 + exit 1 +fi +export CODEGRAPH_TELEMETRY=0 +exec codegraph "$@" From 2c332335b6ef7fd23d05aa5bd7d0ac117d2aee29 Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Sat, 7 Nov 2026 17:00:11 -0300 Subject: [PATCH 3/3] test(mobile): record phone memory controls and transport contract --- docs/architecture/phone-app.md | 3 ++ docs/assessments/phone-memory.md | 32 ++++++++++++++++++++ mobile/src/core/phoneMemoryContract.test.ts | 33 +++++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 docs/assessments/phone-memory.md create mode 100644 mobile/src/core/phoneMemoryContract.test.ts diff --git a/docs/architecture/phone-app.md b/docs/architecture/phone-app.md index 845e91bf..2823c206 100644 --- a/docs/architecture/phone-app.md +++ b/docs/architecture/phone-app.md @@ -30,6 +30,9 @@ JS `coreHome()` returns `beans-v2/core` or `beans-dev-v2/core` without mkdir; co - **Group details**: Group Info edits Name and Description; Description pushes a full editor and saves through `chats.set_description`. Every member reads the shared description in its system prompt. A DM uses its bot's description instead; see [DMs and groups](bots.md#the-lead-bot). - **Memory services** (`app/chat-info/memory/`, `app/settings/memory/`, `src/core/memoryService.ts`): DM Details › Memory opens the bot's recall/capture draft, explicit save/search/inspect/reflect, delivery queue, fenced deletion and capability-driven backend panels. The page links account connections and embedding profiles. The focused native wrapper uses the same public `beans-core.request` transport as `engine.ts`; service operations route to the assigned Runner, while local asset setup names a selected paired Runner. The phone contains no vector SDK or ONNX runtime. Stored keys/endpoints/options stay masked; secret edits distinguish keep, replace and clear. OpenViking binds exact bot IDs to USER keys or an explicitly trusted gateway. Capture starts off, covers future eligible turns only, and group text has separate approval; unattended capture stays unavailable without enforceable downstream spending policy. Service, reflect and advanced operations require explicit action approval with plaintext/cost disclosure, never render-time requests or automatic retries. Pgvector setup displays the actual target and full SQL; Lance binding/export/import displays private Runner-local paths, namespace and vector-space fingerprint. Local runtime/model/tokenizer setup previews exact sources, licenses, bytes and hashes on the selected Runner. Apply sends only the frozen one-use token/digest and affirmative confirmation, not changed paths or SQL. The independent local MEMORY.md editor retains hash-based conflict protection. Save/Cancel and system dismissal share draft guards; busy work blocks removal and failed requests retain drafts. Phone fixture tests cover consent, masking, exact approvals and failure states without live service calls. +Basic memory actions remain visible with a reason when their capability is absent. Advanced panels require both a negotiated feature and an exact permitted verb and are omitted when unavailable. All service actions use the existing native request adapter; capability checks also reject unsupported dispatch before transport. + + Memory deletion invalidates its confirmation at attempt start and refreshes preferences in `finally`, including failed and pending remote results. A failed refresh disables document/bank deletion until an explicit refresh succeeds; cleanup confirmation uses the refreshed deletion epoch. OpenViking connection edits patch only named bot IDs: omitted bindings keep their private identity/key, and explicitly confirmed `null` removes only that bot’s binding. Keep key requires the exact saved bot/mode/account/user identity, enforced by core. Changing identity, changing key action or removing/reopening a draft discards entered replacement bytes. Metadata-only saves omit options; the phone never sends whole-map replacement flags or reads saved keys back. Advanced panels intersect their concrete adapter-defined forms with the negotiated `advanced_actions` map for the exact feature and verb. Missing or empty permissions hide feature links, action selectors, fields and Run controls; feature-level support alone never authorizes a verb. The request helper rechecks exact permission and plaintext approval before dispatch. Document deletion is excluded from advanced actions and uses only the confirmed revision/epoch-fenced `memory.service.delete` path. diff --git a/docs/assessments/phone-memory.md b/docs/assessments/phone-memory.md new file mode 100644 index 00000000..0af52e9c --- /dev/null +++ b/docs/assessments/phone-memory.md @@ -0,0 +1,32 @@ +# Phone memory control assessment + +Issue [#103](https://github.com/bloodf/beans/issues/103), PR [#356](https://github.com/bloodf/beans/pull/356). Source baseline is main `f3f793d49f40e66f416084c512aba2738a3f867e`, integrated into the reserved PR without rewriting phone pages. This is a source and fixture contract, dated 2026-11-07. Satisfied means the source implements the control; it does not mean device acceptance passed. + +## AppKit checklist mapping + +The acceptance list in [#101](https://github.com/bloodf/beans/issues/101) is the comparison contract. References below name current definitions or page controls so they remain searchable as line numbers change. + +| Control | Assessment | Source evidence and remaining acceptance | +| --- | --- | --- | +| Create connection with keep/replace/clear | satisfied | `mobile/app/settings/memory/connection.tsx` calls `setConnection` with `secretPatch`; `mobile/src/ui/memoryUI.tsx` exposes `MemorySecret`; `mobile/src/core/memoryService.ts` `connectionRequest` preserves omitted fields and strips arbitrary scope. Existing `memoryService.test.ts` covers masked configuration, secret patches and blocked Lance Cloud configuration. Device save/reopen is deferred. | +| Bind bot and enable recall with consent | satisfied | `mobile/app/chat-info/memory/[id].tsx` connection chooser, Approve Exact Recall/Capture Choices and Save use `MemoryPreferencesDraft` and `savePreferences`. Draft defaults disable capture/recall; exact bot/connection/choices approval is required. `memoryService.test.ts` covers approval; `memoryAdvanced.test.ts` covers cap increases and invalid budgets. | +| Changing connection clears approvals | satisfied | `MemoryPreferencesDraft.connectionID` clears plaintext/group approvals and invalidates saved consent, including switching back. Existing consent fixture in `memoryService.test.ts` exercises connection changes. | +| Missing capability disables rather than hides | partial | `[id].tsx` `reason` supplies disabled reasons to `MemoryAction` for basic controls. `memoryUI.tsx` removes `onPress` when a reason exists. Advanced panels use `advanced.filter` and `advancedForms`, so absent feature/verb hides them. This is an explicit difference from #101, consistent with the current shared advanced-action contract in `docs/architecture/memory-ui.md`. No new issue or page rewrite is proposed without a product decision to change that contract. `phoneMemoryContract.test.ts` proves each basic action rejects absent/false capability before dispatch and sends the exact payload only when enabled. `memoryAdvanced.test.ts` covers absent maps and sibling verbs. | +| Health, delivery_unknown and deletion pending are distinct | satisfied | `[id].tsx` displays Service state, Readiness reason, Deletion pending, each operation state and the queue deletion state separately. `readMemoryHealth` and `readMemoryOperations` retain these states. Only completed means stored; pending never means verified erasure. Existing service and deletion fixtures cover parsing and deletion refresh locks. Device presentation remains deferred. | +| Every control has an accessible name | missing | `mobile/src/ui/forms.tsx` `ToggleRow` and `FieldRow` do not attach their sibling title/label to Switch/TextInput in this baseline. Already assigned [#329](https://github.com/bloodf/beans/issues/329), PR #362. No duplicate issue or shared-form edit here. VoiceOver/TalkBack acceptance is NOT_RUN. | + +## Other shared controls + +| Control | Assessment | Source evidence and boundary | +| --- | --- | --- | +| Embedding profiles | satisfied | `mobile/app/settings/memory/embedding.tsx` supplies full API/local profile edits; `embeddingRequest` validates vector space, preserves prefixes and excludes local Runner paths. `memoryAdvanced.test.ts` covers that boundary. Saving does not perform inference or reindexing. | +| English and Simplified Chinese | missing | Memory page text and `memoryUI.tsx` disclosures are English literals at this baseline. Already assigned [#330](https://github.com/bloodf/beans/issues/330), PR #365. This assessment does not edit localization. | +| Explicit service action and no automatic remote work | satisfied | `[id].tsx` opens with listConnections/getPreferences only. Health/retain/reflect use explicit confirmations. `memoryServiceNative.ts` passes the existing public native `request` to the adapter. Fixture dispatch proves adapter behavior, not native transport delivery or mounted UI behavior. | +| Fenced deletion and setup | satisfied | `memoryTask.ts` `MemoryDeletionState` locks and refreshes authoritative preferences after deletion. `memoryDeletion.test.ts` tests failure and epoch handling. `memoryService.ts` setup approval objects bind target/revision/expiry and are consumed once; `memoryAdvanced.test.ts` tests stale, expired and reused approvals. No remote erasure or DDL is executed by these fixtures. | +| Local MEMORY.md | satisfied | `mobile/app/chat-info/memory/local.tsx` uses the separate local editor with expected hash; `memoryAdvanced.test.ts` tests stale-hash refusal. This is independent of service capture. | + +## Verification and acceptance boundary + +Run the existing mobile Vitest configuration with `src/core/phoneMemoryContract.test.ts`, `src/core/memoryService.test.ts`, `src/core/memoryAdvanced.test.ts` and `src/ui/memoryDeletion.test.ts`. Run `pnpm run check:docs` and the existing mobile typecheck through the assigned executor. There is no mobile lint script in this baseline. This change adds fixtures and documentation only; it changes no native build input or production mechanism. + +Manual device, hardware, browser, E2E and full-suite acceptance are NOT_RUN/deferred. In particular #103's manual scenario remains open. #329/#330 completion must be reconciled at their actual merged heads, followed by device acceptance; draft ownership is not evidence that either gap is fixed. No additional confirmed missing implementation outside those existing assignments was found in this bounded assessment. diff --git a/mobile/src/core/phoneMemoryContract.test.ts b/mobile/src/core/phoneMemoryContract.test.ts new file mode 100644 index 00000000..570bbf7f --- /dev/null +++ b/mobile/src/core/phoneMemoryContract.test.ts @@ -0,0 +1,33 @@ +import { expect, test } from 'vitest'; +import { MemoryServiceAPI, type MemoryCapabilities } from './memoryService'; + +// The existing phone controls share this adapter with the native request wrapper. +const revision = { counter: 7, device_id: 'fixture' }; +const controls = [ + { capability: 'recall', method: 'memory.service.recall', params: { bot_id: 'bot', query: 'query' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.recall('bot', 'query', caps, true) }, + { capability: 'reflect', method: 'memory.service.reflect', params: { bot_id: 'bot', query: 'query' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.reflect('bot', 'query', caps, true) }, + { capability: 'inspect', method: 'memory.service.inspect', params: { bot_id: 'bot', document_id: 'doc' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.inspect('bot', 'doc', caps) }, + { capability: 'retain', method: 'memory.service.retain', params: { bot_id: 'bot', text: 'note', request_id: 'request' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.retain('bot', 'note', 'request', caps, true) }, + { capability: 'operation_status', method: 'memory.operations.status', params: { bot_id: 'bot', id: 'op' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.operation('bot', 'op', 'status', caps, true) }, + { capability: 'cancel_operation', method: 'memory.operations.cancel', params: { bot_id: 'bot', id: 'op' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.operation('bot', 'op', 'cancel', caps, true) }, + { capability: 'delete_document', method: 'memory.service.delete', params: { bot_id: 'bot', document_id: 'doc', connection_revision: revision, deletion_epoch: 4, confirm: true }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.delete('bot', 'doc', revision, 4, caps, true) }, + { capability: 'clear', method: 'memory.service.delete', params: { bot_id: 'bot', connection_revision: revision, deletion_epoch: 4, confirm: true }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.delete('bot', undefined, revision, 4, caps, true) }, +] as const; + +for (const control of controls) { + test(`${control.capability} requires its negotiated capability before transport`, async () => { + const calls: { method: string; params: unknown }[] = []; + const api = new MemoryServiceAPI(async (method, params) => { + calls.push({ method, params }); + if (method === 'memory.service.delete') return { pending: true, deletion_epoch: 5, operation_id: 'remote' }; + if (method === 'memory.service.retain' || method.startsWith('memory.operations.')) + return { id: 'op', document_id: 'doc', state: 'delivery_unknown', operation_id: 'remote', error_code: null }; + return { evidence: [], document: null, operation: null, data: {} }; + }); + await expect(control.run(api, {})).rejects.toThrow('unsupported_operation'); + await expect(control.run(api, { [control.capability]: false })).rejects.toThrow('unsupported_operation'); + expect(calls).toEqual([]); + await control.run(api, { [control.capability]: true }); + expect(calls).toEqual([{ method: control.method, params: control.params }]); + }); +}