@hraness/message-like-me 0.8.20 → 0.8.22

package/docs/textbutler/getting-started.md

@@ -1,15 +1,16 @@
 # Start using Textbutler
 
-Textbutler is a local Mac assistant for selected conversations. Start with its
-inbox and replies you write yourself. Automatic replies stay paused until you
-choose a ready agent and explicitly enable a contact.
-
-AI replies require a verified Textbutler bundle with reviewed composition
-admission and use a separately installed [xcb](https://github.com/hraness/xcb)
-native runtime and an explicitly connected subscription account. This local
-pilot requires current xcb admission and a successful account check. Installation
-does not enable replies, and live messaging still needs verification with your
-chosen recipient. Claude API retains a separate trusted runtime admission gate.
+Textbutler is an AI butler for the iMessage, WhatsApp, and Beeper chats you choose on your Mac.
+Start with its inbox and replies you write yourself. Automatic replies stay
+paused until you choose a ready agent account, turn them on for a contact, and
+resume the butler.
+
+AI replies need a local build of Textbutler and a Claude Code, Codex, or Devin
+subscription connected through [xcb](https://github.com/hraness/xcb). The account
+also has to pass `providers check`. Installing doesn't turn replies on, and you
+should test live messaging with a recipient you trust. The Claude API route
+needs a separately reviewed runtime that neither the source checkout nor the
+local build supplies.
 
 ## Open the guided terminal
 
@@ -27,11 +28,11 @@ bun run textbutler:install
 ~/.local/bin/textbutler
 ```
 
-The installer builds a self-contained local pilot, checks the reviewed
-composition receipt against current source and contact profiles, and verifies
-its contents and exact Bun runtime before use. Missing or stale composition
-evidence blocks the build. Source daemon startup carries no such admission and
-keeps subscription inference unavailable. It starts no services and connects no accounts.
+The installer builds a self-contained local copy, checks your source files and
+both contact permission profiles against the reviewed record in
+`qualification/`, and verifies its contents and exact Bun runtime before use. If
+the source doesn't match the reviewed record, the build stops. A daemon started
+from source never runs AI replies. The installer starts no services and connects no accounts.
 An existing, different `textbutler` command is preserved. This is a local build,
 not a signed public release. Connect xcb separately for AI replies. Keep the same
 Bun runtime installed. To upgrade a verified existing installation, stop its
@@ -41,7 +42,7 @@ rollback, and atomically switches the command. It never replaces an unrelated
 command or changes your settings. Restart the installed daemon afterward.
 
 The terminal has numbered actions for setup, app connections, conversations,
-replies, contacts, pause and the menu bar. Enter goes back from a selection;
+replies, contacts, pause, the menu bar and macOS access. Enter goes back from a selection;
 `q` or Ctrl-C closes the terminal. It does not stop an installed background
 service. Commands below use `bun run textbutler`; the help abbreviates that
 prefix to `textbutler`. You can use `~/.local/bin/textbutler` for these commands.
@@ -100,9 +101,42 @@ source service is installed.
 See [messaging app support](messaging-apps.md) for Beeper limitations and native
 alternatives, including requirements that affect Telegram AI processing.
 
-## Give TextButler access to iMessage
+## Shape a contact's butler
+
+Contact habitats keep a small owner-authored `soulCore` (voice, relationship
+context, shared context and boundaries) separate from the butler's learned tone
+and formality. The contact-local memory archive can retain 64 sourced notes;
+each reply sees only a small snapshot, and the butler can search older notes
+locally for relevant preferences or open topics. Inspect or clear it with
+`habitats show CONTACT` or `habitats memory-clear CONTACT REVISION`.
+
+Search and memory are contact-scoped. JavaScript is separately disabled by
+default; enable it only for a contact whose butler should receive the pure-data
+tool. It runs code in a fresh QuickJS WebAssembly runtime without network,
+filesystem, timers or host APIs, under strict CPU and memory budgets. Exa web
+search remains separately owner-controlled and can send public queries to the
+search provider, so leave it off when that is not wanted.
+
+Configure an individual plan while the daemon is paused, using the exact
+revision reported by `habitats show CONTACT`:
+
+```sh
+textbutler habitats configure CONTACT REVISION '{"version":1,"guidance":"Be considerate and remember useful shared context without assuming familiarity.","contextMessages":12,"maxReplyCharacters":640,"humor":"match","webSearch":false,"memeSearch":true,"javascript":true,"memorySearch":true,"soulCore":{"voice":"Warm and concise","relationshipContext":"Longtime friend","sharedContext":"They are planning a trip together","boundaries":"Do not make plans or commitments for the owner"}}'
+```
 
-Use the native app when you want macOS Full Disk Access to belong to TextButler.
+Replace the contact ID and plan values with what you want for that conversation.
+The learned style can evolve from sourced feedback, but it cannot rewrite the
+owner-authored `soulCore` or change tool grants. Tool output is evidence, never
+permission to send a message. See [contact calculation and memory tools](javascript-tools.md)
+for the runtime limits and memory-search behavior.
+
+## Give Textbutler access to iMessage
+
+In the guided terminal, **Give Textbutler access** walks you through the two
+macOS settings below in order and opens each System Settings pane when you
+press Enter or `o`. It never causes a macOS prompt itself.
+
+Use the native app when you want macOS Full Disk Access to belong to `TextButler.app`.
 The app supervises its pinned runtime and background service. Build it from an
 already installed, verified payload on your Mac:
 
@@ -113,15 +147,17 @@ bun run textbutler:app build \
 bun run textbutler:app install --from /absolute/new/app-build-directory
 ```
 
-The default destination is `~/Applications/TextButler.app`. Building and
-installing the app does not start replies or change macOS permissions. In
+The default destination is `~/Applications/TextButler.app`, which macOS lists
+as Textbutler. Building and installing the app does not start replies or change
+macOS permissions. macOS never asks for Full Disk Access, so `install` ends
+with a notice; at a terminal, press Enter to open the Full Disk Access pane. In
 **System Settings → Privacy & Security → Full Disk Access**, click **+**, press
 **Command-Shift-G**, enter `~/Applications/TextButler.app`, and choose **Open**.
 Enable its switch. macOS may require your password in its own dialog.
 
 Configure the exact Ghostget `src/cli.ts`, Bun runtime, private state directory
 and `imessage:ACCOUNT` binding using `setup` above. This development version pins
-Ghostget 0.18.21 and its reviewed `imsg` helper artifact. Native setup provisions
+Ghostget 0.18.43 and its reviewed `imsg` helper artifact. Native setup provisions
 that pinned helper into the connector state directory (`imessage transport install`)
 before linking; a missing or mismatched artifact stops setup instead of reaching
 messaging. Setup links only
@@ -137,6 +173,12 @@ bun run textbutler:app imessage-setup \
   --data-dir "$HOME/Library/Application Support/Textbutler"
 ```
 
+Before macOS asks to let Textbutler control Messages, setup prints a notice;
+press Enter to continue or `s` to skip. If you choose Don't Allow, macOS won't
+ask again: turn on Textbutler in **System Settings → Privacy & Security →
+Automation**, then run the setup command again. `textbutler doctor` shows
+which of these steps is left.
+
 After app setup completes, use the installed `daemon install` command to
 register its background service. If an older service is installed, first use
 `daemon uninstall`; this preserves your settings and contacts. Startup verifies
@@ -153,11 +195,26 @@ with the following command:
 bun run textbutler:app install --from /absolute/new/app-build-directory --upgrade
 ```
 
+Apps now include the Textbutler icon, and releases from before the icon can't
+verify them. To go back to an earlier release, stop the
+service, move `~/Applications/TextButler.app` and `state/macos-app.json` in
+your data folder somewhere safe, then build and install the app from that
+release. Then turn on macOS access for the reinstalled app again.
+
 The upgrade verifies both versions and retains the previous signed
 app and receipt. If it reports an uncertain transition, preserve its records
 and reconcile that transition before retrying. Recheck Full Disk Access and
 Messages Automation after the upgrade.
 
+Changing the connector's provider implementation changes its reported
+identity. Existing conversation enrollments then report that the provider
+identity changed and must be enrolled again; per-operation owner permissions
+likewise key on the implementation and must be approved again through the
+permission command. Re-enrolling preserves each contact's memory and run
+history: enroll the same conversation coordinate, grant the new binding, and
+update the contact's route reference to the new enrollment in one owner-state
+write, then revoke the superseded grants.
+
 See [local data](local-data.md) for retained setup records and installation data
 removal. Repeating setup preserves an already linked account and its identity.
 
@@ -181,8 +238,8 @@ bun run textbutler setup \
   --xcb-model FULL_MODEL_KEY
 ```
 
-For Codex, use `--xcb-account codex:ACCOUNT_ID` and a matching observed model.
-Repeat setup to add a second account. The command pins the executable bytes and
+For Codex or Devin, use `--xcb-account codex:ACCOUNT_ID` or `--xcb-account devin:ACCOUNT_ID`
+and a matching observed model. Repeat setup to add another provider's account. The command pins the executable bytes and
 explicit routing; it does not activate a contact. Setup refuses changes to an
 existing binary or account/model binding. After an xcb upgrade, stop the daemon
 and review its private `state/host.json` binding before updating the executable
@@ -244,10 +301,25 @@ bun run textbutler menubar install
 `start` opens it now; `install` registers login startup. The first start retrieves
 and verifies the pinned shared native companion. No local Rust build is needed.
 
-The menu gives you pause, connection checks, conversation selection, per-contact
-activation, agent selection, the reply inbox and recent activity. Draft previews
-are intentionally labeled: use the terminal to review complete outgoing actions
-before sending. The menu cannot send hidden or truncated draft content.
+The menu starts with one status line, then the one thing to do next: start
+Textbutler, open the macOS setting iMessage still needs, read the setup guide,
+or check for replies. **Conversations** holds per-contact replies and agent
+choice, conversation search and app connections; **Pause automatic replies**
+and **Resume automatic replies** sit at the top level. **Details** keeps
+activity, agent accounts and capabilities out of the way. When an action
+doesn't work, a ⚠︎ line under the status says why. Suggestions show a preview
+only: use the terminal to review complete outgoing actions before sending. The
+menu cannot send hidden or truncated draft content.
+
+If you installed `TextButler.app`, you can have it run the menu too, so macOS
+lists Textbutler rather than Bun under Login Items. This is off by default while
+the local app identity is checked on a clean macOS account. To try it, use the
+installed command the app was built from:
+`HRANESS_LOCAL_APP=1 ~/.local/bin/textbutler menubar install`. If the app was
+built from another version, the command stops and says so. After
+`bun run textbutler:install --upgrade`, the installer tells you when the menu
+still starts the previous version: run `textbutler menubar install` again, or
+rebuild and upgrade the app when the menu runs through it.
 
 Menu startup and daemon startup are separate. Quitting the menu leaves the
 installed daemon running. `menubar stop` closes the menu; `daemon uninstall`

package/docs/textbutler/ghostget-contract.md

@@ -8,8 +8,8 @@ menu companion's private helper or open provider databases.
 
 The automation contract was first admitted with
 [Ghostget 0.18.2](https://github.com/hraness/ghostget/releases/tag/v0.18.2).
-This development version of native TextButler iMessage setup pins Ghostget
-0.18.21. Its matching artifact and live conversation checks remain pending.
+This development version of the native `TextButler.app` iMessage setup pins Ghostget
+0.18.43. Its matching artifact and live conversation checks remain pending.
 The required contract preserves the native helper's resource bundle, avoids
 opening unrelated protected folders during state validation, and exposes bounded
 discovery diagnostics without message bodies. Valid native chat rows without
@@ -39,7 +39,7 @@ Restarting Textbutler does not silently clear it.
 | --- | --- |
 | `status`, `start` | Observe capabilities; explicitly start supported synchronization. |
 | `conversations`, `enroll`, `enrollments` | Exact account generation and direct participant-bound conversation enrollment. |
-| `poll`, `history`, `events` | Bounded history, durable observation cursors, revisions, catch-up and gap detection. |
+| `poll`, `pollSet`, `history`, `events` | Bounded history, durable observation cursors, revisions, catch-up and gap detection; `pollSet` shares one provider session across a contact set and reports each enrollment separately. An enrollment busy with another operation reports its current stored row — not necessarily synced this tick. |
 | `grant`, `grant.get`, `grant.by-intent`, `revoke` | Recipient, action, expiry and quota limits; idempotent issuance lookup and immediate revocation. |
 | `asset`, `prepare` | Admit exact attachment bytes and bind the ordered action list to a context revision and expiry. |
 | `submit`, `cancel`, `run` | Journal an action claim before dispatch and retain accepted, failed, partial or indeterminate results. |

package/docs/textbutler/javascript-tools.md

@@ -0,0 +1,63 @@
+# Contact calculation and memory tools
+
+Each contact plan controls two local tools. `memorySearch` defaults to `true` and
+searches that conversation's retained memory archive. `javascript` defaults to
+`false`; enable it in the owner's complete plan with `habitats configure` while
+automatic replies are paused. Learning preserves both flags.
+
+Memory search ranks exact words and phrases in the contact's source notes. It
+returns up to eight excerpts with their source IDs, digests, authors and
+categories. Each excerpt contains at most 256 UTF-8 bytes, and the complete result
+fits within 4,096 bytes. Results report omitted matches and shortened text. A
+search reads the archive without changing it or contacting an external service.
+
+JavaScript supports small calculations and data transformations. The model supplies
+a synchronous function body and optional JSON input, available as `input`:
+
+```json
+{"kind":"javascript","code":"return input.prices.reduce((total, price) => total + price, 0);","input":{"prices":[12,8,5]}}
+```
+
+The result is JSON, such as `{"ok":true,"value":25}`. A failed calculation returns
+a bounded error code. The model may use the remaining tool call to correct it.
+All tools share the existing limit of two calls per reply.
+
+Each calculation runs in a new QuickJS interpreter compiled to WebAssembly. The
+host supplies only copied JSON. There are no file, network, process, module,
+timer or messaging APIs inside the interpreter. `Date` and `Math.random` are
+unavailable. A calculation cannot inspect contact memory unless the reply agent
+passes selected data as input. That data stays on the local host during execution.
+
+| Resource | Limit |
+| --- | --- |
+| Code | 8,192 UTF-8 bytes |
+| Input JSON | 16,384 UTF-8 bytes |
+| Output JSON | 4,096 UTF-8 bytes |
+| QuickJS heap | 8 MiB |
+| Interpreter stack | 256 KiB |
+| Cooperative interrupt | 50 ms, with at most 5,000 interrupt checks |
+| Worker watchdog | 250 ms after worker startup; a calculation that misses this gets a resource-limit result and termination is requested |
+| Worker startup | 2,000 ms maximum before a bounded failure result |
+| Worker admission | One active worker, up to sixteen queued calls, with a 5,000 ms queue wait |
+| Input/output structure | 16 levels and 1,024 values |
+
+The interpreter checks its deadline during execution and is disposed after every
+call. A separate worker watchdog requests termination if a native engine
+operation fails to reach an interrupt check. The host returns a bounded
+resource-limit result; one worker remains active, and at most sixteen later calls
+wait up to five seconds for its slot. Calls beyond that queue return
+resource-limit. If termination cannot be confirmed, JavaScript stays unavailable
+for that app process and queued calls time out; restarting the app clears the
+fail-closed guard. JSON output rejects pending asynchronous work. Loading the
+interpreter and generating the model response take additional time. The
+WebAssembly runtime and worker have fixed overhead outside the QuickJS heap
+limit.
+
+Submitted replies retain tool outcomes for inspection and reflection. JavaScript
+evidence labels the code with its SHA-256 digest. Offline personality evaluation
+does not execute either tool and cannot measure tool behavior from a text replay.
+
+The implementation uses the pinned `quickjs-emscripten-core` and embedded
+`@jitl/quickjs-singlefile-browser-release-sync` packages. The upstream
+[runtime documentation](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/classes/QuickJSRuntime.md)
+describes interpreter memory, stack and interrupt controls.

package/docs/textbutler/local-data.md

@@ -2,7 +2,7 @@
 
 Textbutler keeps settings, contact memory, reply journals and setup records in
 `~/Library/Application Support/Textbutler`, unless you select another data
-directory. These files are private to the Mac user. XCB and Ghostget keep their
+directory. These files are private to the Mac user. xcb and Ghostget keep their
 own accounts and credentials in their separately configured state directories.
 
 Explicit CLI media imports live in the selected contact's private `outbox`.
@@ -24,9 +24,22 @@ directory until completion or rollback is proven. Keep both locations intact
 while an upgrade is unresolved.
 
 When habitats are enabled, the run journal additionally keeps per-contact
-habitat state (the promoted reply plan, bounded reply episodes, observed
-follow-up windows, evaluation records and rollback lineage), replayable
-inference receipts for each evaluation, and a global daily table of API
+habitat state (personality and tool configuration, owner-authored soul anchors,
+learned excerpts, reply episodes, observed follow-up windows, evaluation records
+and rollback history). A reply episode can include up to two tool queries and
+results shortened to 4 KiB each, plus the kinds of actions submitted. Learned
+memory holds up to 64 source-backed 1 KiB excerpts under a 96 KiB encoded archive
+limit, with categories, source message IDs, authors, dates, source digests and
+truncation flags. Digests cover the bounded canonical observations used by
+learning. Episodes retain at most eight 512-byte excerpts shown while composing
+the final reply, plus up to 24 IDs and digests for excerpts exposed only by tool
+steps. Clearing learned memory removes the active excerpts and prevents older
+observations from restoring them; retained episodes, inference records and
+`MEMORY.md` are separate records. JavaScript tool evidence stores a code digest,
+not executable source, and a bounded result.
+Habitat state is limited to 512 KiB per
+contact. The journal keeps the latest 32 replayable inference records per
+contact and a global daily table of API
 usage reservations with their provider-cost settlements. Gateway and other
 provider credentials live under `state/provider-credentials` with owner-only
 permissions; they never enter contact workspaces or journal evidence.
@@ -47,7 +60,7 @@ needed to settle that operation first.
 To erase an installation, the owner can then delete its complete Textbutler
 data directory. This removes settings, contact memory, journals, setup results
 and the iMessage account binding. It does not delete Messages history, Ghostget
-or XCB accounts, or macOS permission grants. Removing individual binding or
+or xcb accounts, or macOS permission grants. Removing individual binding or
 custody records is not a supported way to replace an account or retry a failed
 operation. Reinstalling the command and uninstalling the background service
 both preserve data by default.

package/docs/textbutler/native-process-plan.md

@@ -29,7 +29,7 @@ repository's layout. This change does not activate a provider backend.
   application work or turn the operation into success.
 - The existing contact task profile still requires `noCommandTools`, exact tool
   inventory, read/write isolation, isolated configuration, authentication outside
-  the workspace and `hostBrokerOnly`. Oompa's persistent coding session is a
+  the workspace and `hostBrokerOnly`. xcb's persistent coding session is a
   separate explicit profile. It cannot reuse the contact task policy unchanged.
 
 ## 1. Package-local process seam
@@ -186,7 +186,7 @@ admission and application factory wiring remain pending:
   confinement, relay and account-generation checks retain their existing owners.
 - Keep the current unqualified task paths unavailable until each exact runtime,
   configuration and effective tool inventory has relevant evidence. Add a
-  separate persistent coding profile for Oompa, with its own application
+  separate persistent coding profile for xcb, with its own application
   authority and lifecycle, rather than widening contact task capabilities.
 
 Acceptance requires migration of actual consumers and removal of replaced

package/docs/textbutler/native-subscription.md

@@ -1,7 +1,7 @@
 # AI subscriptions through xcb
 
 Textbutler uses [xcb (Excalibur)](https://github.com/hraness/xcb) to draft replies
-through an explicitly connected Claude Code or Codex subscription. xcb owns
+through an explicitly connected Claude Code, Codex, or Devin subscription. xcb owns
 provider sign-in, runtime admission, operating-system confinement and account
 custody. Textbutler owns contact context, response policy and every message send.
 Textbutler is an MIT-licensed reference application for this separation.
@@ -36,8 +36,9 @@ bun run textbutler setup \
   --xcb-model FULL_MODEL_KEY
 ```
 
-Repeat setup with `--xcb-account codex:ACCOUNT_ID` and its full model key to add
-a Codex account. Setup records the xcb executable's SHA-256 and the explicit
+Repeat setup with `--xcb-account codex:ACCOUNT_ID` or `--xcb-account devin:ACCOUNT_ID`
+and the matching full model key to add a Codex or Devin account; one account per
+provider. Setup records the xcb executable's SHA-256 and the explicit
 account/model binding. It does not copy subscription credentials, create a
 provider sign-in or enable a contact. Restart the installed daemon, run `providers list`,
 and use the returned Textbutler account ID with `providers check ACCOUNT_ID`.

package/docs/textbutler/readiness.md

@@ -23,14 +23,14 @@ remain visible in setup and must be resolved before that claim is made.
 
 ## Interface direction
 
-XCB is a useful interaction reference: a clear status view, filtered pickers,
+xcb is a useful interaction reference: a clear status view, filtered pickers,
 contextual choices, complete review and clean cancellation. Textbutler follows
 that separation with a thin terminal client over its owner control protocol.
 All permission, account, contact, grant and dispatch checks remain in the daemon.
 
 The native menu already uses the shared Rust desktop foundation. A new Rust
 runtime is not required to make these controls usable. If the terminal grows
-into a full-screen workspace, XCB's Ratatui/Crossterm interface is an appropriate
+into a full-screen workspace, xcb's Ratatui/Crossterm interface is an appropriate
 reference. The subscription connection uses xcb's dedicated zero-tool `generate`
 contract. It does not use the workspace coding command or inherit its tools and
 sessions.
@@ -41,7 +41,7 @@ The verified bundle connects to an explicitly selected xcb installation after
 its build checks reviewed composition evidence against current source bytes and
 both contact profiles. A source daemon has no embedded admission and keeps
 subscription inference unavailable. xcb handles
-Claude Code or Codex subscription authentication, confinement and provider
+Claude Code, Codex, or Devin subscription authentication, confinement and provider
 custody. Textbutler uses zero-tool generation, parses one operation proposal at
 a time and applies its contact-scoped broker policy before any effect.
 

package/docs/textbutler/whatsapp.md

@@ -8,7 +8,7 @@ credentials, synchronization and send implementation. Textbutler never runs
 ```mermaid
 flowchart LR
   App[Textbutler menu companion] --> Butler[Textbutler daemon]
-  Butler --> Agents[Agentrouter]
+  Butler --> Xcb[xcb]
   Butler --> Ghostget[Ghostget owner process]
   Ghostget --> Messages[iMessage helper]
   Ghostget --> WhatsApp[Pinned wacli linked device]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/message-like-me",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "description": "A local-first CLI and Agent Skill for studying private messaging history and drafting messages that sound like you.",
   "license": "MIT",
   "type": "module",
@@ -94,15 +94,17 @@
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.268",
     "@anthropic-ai/sdk": "0.125.0",
-    "@hraness/agentmixer": "https://github.com/hraness/agentmixer/releases/download/v0.1.1/hraness-agentmixer-0.1.1.tgz",
-    "@hraness/algal": "github:hraness/algal#c5bd50452a676dc0b035ef206178c397de0cba92",
-    "@hraness/desktop-foundation": "https://github.com/hraness/desktop-foundation/releases/download/v0.7.0/hraness-desktop-foundation-0.7.0.tgz",
+    "@hraness/agentmixer": "https://github.com/hraness/xcb/releases/download/v0.3.0/hraness-agentmixer-0.3.0.tgz",
+    "@hraness/algal": "github:hraness/algal#ac68f096d2e10e1824b9ee4d6fe031b4846094da",
+    "@hraness/desktop-foundation": "https://github.com/hraness/desktop-foundation/releases/download/v0.8.0/hraness-desktop-foundation-0.8.0.tgz",
     "@hraness/local-custody": "github:hraness/local-custody#v0.4.0",
-    "@hraness/support-foundation": "github:hraness/support-foundation#2d034b357680353574411217d68b02b6755b07ed",
+    "@hraness/support-foundation": "github:hraness/support-foundation#8bb514d24b79dc3f305390700ae312cab88e7ad2",
+    "@jitl/quickjs-singlefile-browser-release-sync": "0.32.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@types/bun": "1.3.14",
     "effect": "3.22.1",
     "fast-check": "4.9.0",
+    "quickjs-emscripten-core": "0.32.0",
     "sigstore": "4.1.1",
     "typescript": "6.0.3",
     "zod": "4.6.2"