@hraness/message-like-me 0.8.8 → 0.8.10

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.10 (2026-09-13)
+
+- Show a compact ASCII robot before interactive root help. Piped output,
+  machine-readable commands, version output, and command help stay unchanged.
+- Refine the informational site's shared surfaces and robot identity. The native
+  Textbutler app remains in development; this package does not enable replies.
+- Route legacy installation to the exact public `@hraness/message-like-me@0.8.10` npm package after release admission, with the same reviewed bytes mirrored in the immutable GitHub Release.
+
+## 0.8.9 (2026-09-10)
+
+- Use the shared Paper theme on the informational website, with warm neutral surfaces, compact Nebula Sans headings, and a blue action color in light and dark appearances.
+- Verify the theme snapshot's immutable source and file digests independently of the existing component package versions.
+- Route installation to the exact public `@hraness/message-like-me@0.8.9` npm package after release admission, with the same reviewed bytes mirrored in the immutable GitHub Release. CLI behavior and private data boundaries remain unchanged.
+
 ## 0.8.8 (2026-09-09)
 
 - Route installation to the exact public `@hraness/message-like-me@0.8.8` npm package after release admission, with the same reviewed bytes in the immutable GitHub Release.

package/README.md

@@ -1,7 +1,44 @@
-# Message Like Me
+# Textbutler
 
 [![skills.sh](https://skills.sh/b/hraness/message-like-me)](https://skills.sh/hraness/message-like-me)
 
+Textbutler is a personal message butler for macOS, powered by the coding agent
+you choose. Activate a few contacts, give each relationship a private folder of
+context, and let a clearly identified assistant help when it is useful.
+
+The new product lives at [textbutler.app](https://textbutler.app). Its default
+response looks like `🤖{ hello this is my response }`. Each contact can choose
+the three symbols, a keyword, and smart or keyword-only response mode.
+
+**Development status:** the source includes the Mac settings app, background
+daemon lifecycle, owner-selected Ghostget conversation enrollment, optional
+history initialization, private memory, executable hooks, reply policy and send
+journal. Agentrouter includes a restricted Claude Agent SDK adapter and shared
+account custody. Live automated replies remain unavailable until Ghostget's
+durable events and scoped automation grants, and the provider's contact-only
+execution, are qualified. Codex execution and native rich actions are also
+unavailable. The Mac app has not been released as a signed/notarized download.
+The website is informational; it has no connection to private messages or
+contact folders.
+
+Start with the [architecture and capability status](docs/textbutler/architecture.md),
+[Textbutler runtime](packages/textbutler/README.md),
+[Agentrouter](packages/agentrouter/README.md),
+[transport adapter](packages/transport/README.md), or
+[Mac app](apps/macos/README.md).
+
+```sh
+bun install --frozen-lockfile --ignore-scripts
+bun run check:textbutler
+```
+
+The source is MIT licensed. New packages remain unpublished while their
+contracts are developed. Message Like Me's published history readers and
+message-bundle contracts are retained below for existing consumers; they are
+not the new live messaging runtime.
+
+## Legacy Message Like Me history tools
+
 **A local-first CLI and Agent Skill for studying private messaging history and
 drafting messages that sound like you.**
 
@@ -43,7 +80,7 @@ Message Like Me requires Bun 1.3.14 or newer. Install the exact public npm
 package, then install both bundled Agent Skills:
 
 ```sh
-bun add --global @hraness/message-like-me@0.8.8
+bun add --global @hraness/message-like-me@0.8.10
 messagelikeme skill install
 ```
 

package/dist/cli.js

@@ -24750,7 +24750,7 @@ function rejectUnused(parsed, allowedOptions, allowedFlags) {
 import { isAbsolute as isAbsolute6, resolve as resolve8 } from "path";
 
 // src/version.ts
-var MESSAGE_LIKE_ME_VERSION = "0.8.8";
+var MESSAGE_LIKE_ME_VERSION = "0.8.10";
 
 // src/command-input.ts
 var HELP = `Message Like Me ${MESSAGE_LIKE_ME_VERSION}
@@ -27504,6 +27504,19 @@ function runClosed(effect2) {
   return exports_Effect.runPromise(effect2);
 }
 
+// src/cli-intro.ts
+function terminalIntro(terminal) {
+  if (terminal.isTTY !== true || terminal.term === "dumb" || (terminal.columns ?? 80) < 48)
+    return "";
+  return `   _|_
+ .----- .   textbutler
+ | o o |   A little help in your conversations.
+ | === |
+ '-----'
+
+`;
+}
+
 // src/io.ts
 var processIo = {
   stdout: (text3) => process.stdout.write(text3),
@@ -27514,7 +27527,12 @@ var processIo = {
 // src/cli.ts
 async function main(argv, io = processIo) {
   try {
-    await runCommand(argv, io);
+    const rootHelp = argv.length === 0 || argv.length === 1 && argv[0] === "--help";
+    const output = rootHelp && io === processIo ? {
+      ...io,
+      stdout: (text3) => io.stdout((text3 === HELP ? terminalIntro({ isTTY: process.stdout.isTTY, columns: process.stdout.columns, term: process.env.TERM }) : "") + text3)
+    } : io;
+    await runCommand(argv, output);
     return 0;
   } catch (error) {
     io.stderr(`${errorMessage(error)}

package/docs/publishing.md

@@ -1,5 +1,72 @@
 # Publish Message Like Me
 
+## Textbutler informational-site delivery
+
+The following explicit site-subject route supersedes the package-publication
+prerequisite below for the informational Textbutler website only. It grants no
+package publication, native app release, provider qualification, or live message
+authority. The legacy tagged package route and its exact-byte/npm checks remain
+unchanged. Source repository identity remains `hraness/message-like-me` until
+the separately reviewed repository-name migration is applied.
+
+Use the existing `Promote website production` workflow with `site_sha` set to
+the exact reviewed current `main` commit, `site_ci_run_id` and
+`site_ci_run_attempt` set to its successful `CI` run, and `release_tag` empty.
+Do not rerun a promotion attempt; make a fresh attempt-1 dispatch. The route
+requires exactly the current standalone/site job and macOS fixture/native job,
+rejects an older attempt after CI is rerun, rebuilds the site, and admits a
+bounded immutable Actions build-manifest artifact by exact run, attempt, source
+tree, site subtree, lockfile digest, artifact ID/digest, and manifest bytes.
+
+An advancing site target uses the same `website-production` ref, shared
+promotion concurrency, existing status-only App, environment, rulesets, and
+ordinary GitHub Actions ref writer as the legacy route. Before the App key is
+available, complete governed Git histories and all ordered workflow-tree
+changes must pass the site control-epoch admission. A changed workflow range
+requires the independently reviewed exact digest emitted by preflight in
+`control_epoch_digest`; unchanged ranges reject a supplied digest. Site epochs
+use domain `textbutler/control-epoch/site/v1`, bind target and workflow source to
+the same current `main` commit, and carry `tag: null`. They cannot authorize a
+legacy package release. Both routes retain checked helper hashes and code-owner
+review for the complete authority implementation.
+
+Preserve the environment's actual protection rules. If the existing key
+environment requires a reviewer, satisfy that exact run's review through
+GitHub's normal environment approval interface after source admission and
+independent control review. The site redesign does not remove reviewers, wait
+timers or other runtime gates; the legacy setup policy below is not permission
+to bypass an existing protection.
+
+The site writer consumes prior status, proves that the ordinary writer is
+denied by the exact required App status, attests one target, revokes the App
+token, verifies current rules/status/source again, and makes one sterile
+fast-forward push with the expected-old lease. App-only steps receive no ref
+token; writer/admission steps receive no App key. The terminal consumption step
+runs even after failure or cancellation when admission completed. The final
+read-only jobs verify status consumption, revocations, unchanged rules, and
+twice-confirmed REST/GraphQL Vercel Production identity for the exact source.
+
+`textbutler-site-attempt` retains the explicitly listed public phase receipts
+for 30 days when the runner can upload them. Hard termination may prevent this
+upload; remote ref/status/provider readback and the existing interrupted
+authority cleanup remain authoritative. Never blindly repeat an uncertain
+write. If the ref already equals the site source, a fresh dispatch takes a
+read-only qualification route with no App key or ref token. It requires the
+status already consumed by the exact App bot (including its numeric actor
+identity), the unchanged App-pinned rules, and the matching Production
+deployment after the original successful CI completion. The retry's newly
+built manifest is not treated as that existing deployment's publication time.
+Leave `control_epoch_digest` empty for this already-exact route. An outstanding
+success status must first pass the documented custody cleanup, not be silently
+cleared by read-only qualification.
+
+After provider success, verify `textbutler.app` serves the exact intended
+deployment, truthful development status, canonical metadata and legacy links.
+The current Vercel project/production branch remain the target; domain or
+repository renaming is a separate inspected provider mutation.
+
+## Legacy package publication
+
 Message Like Me builds one exact public package tarball, validates those bytes
 on macOS and Linux, and publishes the same tarball plus `SHA256SUMS` to an
 immutable GitHub Release. Only then does it publish that tarball to npm through

package/docs/textbutler/architecture.md

@@ -0,0 +1,154 @@
+# Textbutler architecture
+
+Textbutler is a personal message butler for macOS. An owner activates a bounded set of contacts. Each contact gets a private workspace that a coding agent can read and evolve. A separate daemon decides when to invoke that agent and controls every outward action.
+
+The source includes the owner daemon, contact reply loop, versioned Ghostget automation protocol and Mac application. Synthetic tests establish their control and recovery behavior. Live provider delivery and signed distribution have separate acceptance requirements below.
+
+## Ownership
+
+```mermaid
+flowchart LR
+  App[Mac settings app] --> Control[Owner-only control socket]
+  Control --> Butler[Textbutler daemon]
+  Butler --> Router[Agentrouter]
+  Router --> Provider[Admitted agent provider]
+  Provider --> Tools[Contact-bound tool broker]
+  Tools --> Memory[One contact workspace]
+  Tools --> Web[Public web broker]
+  Tools --> Intents[Proposed actions]
+  Intents --> Butler
+  Butler --> Transport[Versioned transport adapter]
+  Transport --> Ghostget[Ghostget]
+  Ghostget --> Messages[iMessage and WhatsApp]
+```
+
+Ghostget owns native permissions, message and contact acquisition, provider actions, and receipts. Textbutler does not open chat.db or automate Messages directly. Agentrouter owns provider selection, shared-account leases, cancellation, model catalogs, qualification evidence, and a bounded tool interface. Textbutler owns conversation policy and the durable send transaction. The Mac app changes owner settings through a small local protocol; it never gives a model arbitrary Tauri commands.
+
+The background lifecycle uses a user LaunchAgent: native messaging belongs to the signed-in Mac user, and login persistence is independent of the settings window. Installation records the exact runtime, entrypoint, data directory and generation; removal verifies its private receipt and loaded service identity. Uninstall preserves contact data. New settings start paused. A private SQLite custody lock prevents duplicate daemon ownership and permits recovery only for a dead recorded process and its exact unserved socket. A temporary live launchd install/start/uninstall test passed while preserving synthetic owner data. Signed distribution remains a separate gate.
+
+The daemon serves owner controls, enrollment jobs and a reply loop through its own supervised Ghostget process. Startup, enablement and recovery establish a silent event boundary, refresh bounded history and admit only subsequent eligible inbound messages. A failed catch-up pauses the affected conversation. No provider work starts without explicit owner account configuration.
+
+## Contact data
+
+The intended application-support tree is:
+
+```text
+Textbutler/
+  daemon.sock                  owner-only native control socket
+  state/
+    settings.json              owner configuration and contact bindings
+    host.json                  optional private installed Ghostget CLI/account binding
+    runs.sqlite                private run and send journal
+    daemon-custody.sqlite      exclusive process/socket ownership
+    launch-agent-custody.sqlite lifecycle serialization
+    launch-agent.json          exact LaunchAgent installation receipt
+    ghostget-automation-custody.json exact supervised messaging process claim
+  plugins/
+    extensions.json            explicit owner-installed hook manifest
+    quiet-hours.ts             example trusted executable extension
+  contacts/
+    <opaque-contact-id>/       the only model-visible workspace for one run
+      AGENTS.md                editable response guidance; never authority
+      ABOUT.md                 relationship context and owner instructions
+      MEMORY.md                concise, dated, source-attributed working notes
+      STYLE.md                 owner-style evidence and response preferences
+      history/                 bounded, attributed conversation excerpts
+      notes/                   task-specific notes and outstanding questions
+      attachments/             broker-admitted incoming files
+      outbox/                  files proposed for this conversation
+```
+
+Directory names use opaque identifiers, not contact names or phone numbers. Files are private to the Mac user. Models cannot traverse parent paths, links, other contact folders, or host configuration. The file broker supports reads, conditional writes, and exact edits. It exposes no symlink, directory, delete-tree, shell, or executable permission operations. Atomic replacement preserves the preceding file if a write fails. A stale memory revision produces a conflict instead of overwriting an owner's correction.
+
+The owner chooses one verified direct conversation from a bounded Ghostget list. Enrollment rechecks the account incarnation and participant identity and creates a disabled contact. History import is a separate opt-in, limited to 200 recent, explicitly scoped messages, with message ID, time, and author preserved. The import records shortening and omissions; it does not fetch media. These records are context only, and historical automation may be unobservable. A later qualified initialization run may summarize preferences, conversational style, open tasks, and useful context into memory. It must distinguish evidence from inference and retain uncertainty. Later runs correct outdated notes and record sources. Proven butler output never becomes owner-style training evidence. No global person model or cross-contact retrieval is supplied by default.
+
+The original Message Like Me corpus and profile tools remain an optional bounded bootstrap source. They do not become the live message transport. Old databases are not reset or silently migrated. There is no need to carry every previous archive/source feature into the new UI.
+
+## Reply admission
+
+Default contact mode is smart, but a new contact starts disabled. Activating more than the configured limit fails atomically; no existing contact is displaced. The initial limit is five, with owner settings from one to fifty.
+
+An inbound event must identify one activated direct conversation. Historical, outgoing, butler-authored, unknown-author, group, reaction-only, and delivery events do not start reply runs. Persisted event identity prevents a duplicate send. One run may own a contact at a time.
+
+The daemon waits eight seconds after an incoming message to collect a burst. Newer messages supersede older candidates. Owner typing suppresses a reply when that signal exists. Any recent owner message causes a five-minute cooldown. The runtime checks current messages and settings again after composition. Disabling a contact or pressing global pause cancels pending runs and invalidates their grants.
+
+A whole-word, case-insensitive `butler` invocation permits a response after those deterministic gates. In keyword mode, other messages stay silent. In smart mode, a tool-free cheap model returns a strict structured classification. It should answer useful assistance requests, and stay silent during ordinary conversation, acknowledgments, emotional exchanges, or uncertain intent. Confidence below 0.85 stays silent. Malformed results, exhausted accounts, stale model catalogs, or timeouts never escalate to a more expensive agent automatically.
+
+Classifier choice comes from the selected provider's fresh available-model catalog, with explicit cost metadata and structured-output capability. No permanently hard-coded "cheap" model alias is assumed. An owner can pin a classifier or reply model after availability validation. Classifier and responder share the chosen provider/account policy; one classifier gets no tool authority.
+
+No typing signal can prove the owner is absent. The current adapters expose no typing signal; the daemon retains its message-based cooldown and final revision checks. The selected provider/account must independently qualify before smart mode can invoke a model.
+
+## Send transaction and disclosure
+
+The model proposes actions. It does not dispatch them. Owner-installed hooks may shape the work or veto a reply, but all action validation, contact binding, limits, and disclosure run afterwards.
+
+Every text action is wrapped by trusted code with the contact's three symbols. Each field must be one visible grapheme; an empty or invisible disclosure is rejected. Default rendering is `🤖{ hello this is my response }`.
+
+Reactions, stickers, link previews, and app cards cannot literally carry that text prefix. A disclosed text companion is therefore the first action in a nontext response, and counts toward the eight-action maximum. The provider must execute in order and stop if that companion fails. App-specific cards may additionally identify Textbutler in their content, but never remove the companion requirement.
+
+Before send, the runtime rechecks owner activity, conversation revision, current settings, capability availability, cancellation, attachment ownership, target message membership, and the contact grant. It asks the transport to prepare an exact plan with an expiry and digest. Immediately before submission, it journals the dispatch intent. The transport must atomically validate the grant, contact route, context revision, and plan digest at its own effect boundary.
+
+`submitted` is not `delivered`. Partial and indeterminate outcomes pause further automated activity for that contact until explicit reconciliation. A crash while dispatching becomes indeterminate on recovery; it never causes a blind retry. A crash before dispatch abandons the run without sending. Provider failover cannot replay a possibly submitted action.
+
+## Hooks and plugins
+
+The initial lifecycle is `message.received`, `reply.decide`, `reply.compose`, `reply.before-send`, `reply.sent`, `memory.updated`, and `run.failed`. Hooks have a named/versioned owner-installed extension, deterministic registration order, a deadline, and a cancellation signal. Failure before dispatch closes admission. A notification-hook failure after a receipt cannot change that receipt or trigger resend.
+
+Executable extensions are application code with the daemon's trust. They are installed outside contact folders; the agent cannot write them or turn message text into imports. Agent self-evolution means revising guidance and memory, not installing executable code. A future untrusted plugin mode needs its own process or language sandbox and explicit capabilities. In-process hooks are never described as a plugin security boundary.
+
+The daemon reads a bounded private `plugins/extensions.json` manifest and preflights its complete inventory before importing listed TypeScript/JavaScript entry modules. Each default export must match the manifest ID/version and known hook names. Source digests appear in the loaded extension metadata. No directory scanning, package installation or hot reload occurs; changes require a full daemon process restart. The routed agent emits `memory.updated` only after a successful conditional write, with its path and committed revision. A notification failure does not undo that write or replay it.
+
+## Agentrouter
+
+Agentrouter begins as an MIT-licensed source package independent of Textbutler's product model. Its account lease coordinates the selected provider account without embedding credentials in a contact workspace. Credential resolvers remain trusted host services. A lease cannot be stolen merely because its time elapsed while a process might still be alive.
+
+Provider adapters declare observed, exact-version qualification. A launch plan is not proof of a sandbox. Codex's shell-disable setting and Claude's exact tool list are useful inputs, but an adapter is not admitted until attempted shell/process calls, host file reads, inherited MCP/plugin configuration, auth-file access, alternate agents, and additional workspaces are demonstrably blocked. No bypass-permissions mode is acceptable.
+
+The source implements a pinned Claude Agent SDK adapter with explicit API-key account binding, a private verified executable snapshot, isolated runtime directories, no built-in tools or inherited settings, broker-only MCP, bounded raw output, and joined process-group termination. Its production gate requires independent qualification of the exact executable and SDK identity. Synthetic protocol and native-runtime fixtures do not activate it. The experimental Codex app-server driver verifies each model request's tool inventory through a host relay and keeps contact storage outside native scratch. It has no live account transport or production registration; native confinement and adversarial custody qualification remain incomplete. See the [Agentrouter implementation and evidence](../../packages/agentrouter/README.md).
+
+A separately selected Claude API adapter executes the bounded tool loop in the trusted host. It exposes only the six broker tools and never starts a model-selected process. Account checks bind the actual packaged runtime and private credential generation; replacing a credential invalidates old discovery and running account work. Fresh model availability and price metadata select a cheap classifier. This explicit API choice does not silently replace Claude Code or Codex and does not use their subscription authentication.
+
+The model receives a fixed contact/workspace identity and a fixed run ID. File operations are brokered and conditional. Public web requests are separately bounded and must not reach loopback, private networks, local sockets, or cloud metadata through DNS or redirects. Message tools stage recipient-free intents for the one conversation. Unknown tool names and unknown input fields fail. Credential/account services are never model tools.
+
+Oompa's existing runtime provider port and account/process-custody patterns are source references. Its ordinary workspace-write execution profile is not the requested contact-only sandbox. AI Charts is a prospective second consumer. Do not migrate either product to Agentrouter until an adapter has equivalent feature and recovery evidence; avoid changing their active work in this redesign.
+
+## Ghostget contract and rich features
+
+WhatsApp follows the same Ghostget ownership boundary. Its private wacli-backed transport provides durable observations and recipient-bound actions; pairing, session state and synchronization stay in Ghostget. The [WhatsApp guide](whatsapp.md) describes setup and action support. Textbutler does not embed WPPConnect or invoke wacli directly.
+
+Current source inspection found Ghostget's Tauri 2 webview with a packaged Bun helper. That helper lives with the app, and its private socket handles approvals/control, not a public messaging subscription service. Textbutler must not couple to it.
+
+The older generic messaging APIs retain expiring route references and owner-confirmed previews. Automation uses a separate explicit owner protocol with durable enrollment, revocable grants and event observations. The iMessage provider negotiates attachments, reactions, stickers, rich links and polls separately; unsupported App Clips and arbitrary experiences remain unavailable. Native Contacts directory discovery is not implemented in this protocol.
+
+Text and file sending use the native helper's AppleScript path. The upstream rich-action bridge injects into Messages and requires SIP to be disabled. Textbutler and Ghostget never change that security setting or install the injection automatically. Rich actions therefore remain unavailable unless the required bridge is already working. This is a significant installation constraint, not a completed rich-messaging experience on a stock Mac.
+
+Ghostget 0.18.2 includes the admitted imsg `0.14.1+private-transport.3` helper. Automated rich links use `send.rich` with `fetch_metadata: false`, constructing the URL and host-title card without helper metadata or image fetching. Availability still requires current managed permission and a compatible native bridge; this does not claim network isolation for Messages itself. The host never falls back to fetching an agent-provided URL.
+
+The [Ghostget integration contract](ghostget-contract.md) documents the implemented binding, grant, event, action and receipt semantics.
+
+The Textbutler transport supports capability negotiation, conversations, bounded history, cursor-based events, exact preparation, authorization and receipts. File paths become admitted bytes before crossing the boundary. Per-action permission and context checks stop a rich batch when conversation activity changes. Private database access stays inside Ghostget's provider implementation.
+
+Linq's documented iMessage API includes attachments, reactions, stickers, rich links, App Clips, and experiences. App cards and rich links are standalone messages. Those hosted capabilities do not establish availability through native macOS Messages. Optional Linq would be a separate transport with explicit account setup, sender identity, webhook signature verification, replay protection, and the same Textbutler policy gates. It is not a way to silently route an owner's personal conversation through a different phone number.
+
+Ghostget currently imports published Message Like Me bundle contracts. Keep that immutable package a leaf. Do not repoint it at the Textbutler runtime. Extract the neutral bundle contracts before reversing a live package dependency, or consume Ghostget's installed CLI contract without a package import in the interim. Preserve historical wire-format identifiers.
+
+## Mac application
+
+The app has an explicit conversation picker, optional history initialization, a contact list, per-contact activation and mode settings, disclosure preview, memory editing, activity, provider status, and global pause. Long provider reads use bounded asynchronous jobs; Pause stays available and preserves unsaved choices. Unsupported capabilities show their actual setup or transport limitation. A separate synthetic demo is clearly labeled and is not included in the native app's live data graph.
+
+One narrow native command accepts the versioned control request. It connects to the private user socket, bounds requests/responses, applies timeouts, and verifies same-user ownership. The webview has no generic shell, filesystem, opener, or network plugin. The app does not inherit access to arbitrary Ghostget operations.
+
+## Admission still required
+
+1. Use the verified Ghostget 0.18.2 package, which includes the reviewed automation source and native helpers. Real account synchronization, recipient identity, rich actions and revocation still require a bounded owner-authorized live test; artifact admission and synthetic fixtures do not prove delivery.
+2. Independently qualify the native Claude SDK and Codex adapters for the requested no-shell, contact-only profile before enabling those choices. The separate Claude API path requires explicit account setup and packaged-runtime admission.
+3. Sign and notarize the exact Mac artifact with an available Apple Developer identity, then verify the final downloaded bytes and installation lifecycle. The unsigned local package and successful launchd test are not a signed release.
+4. Keep historical repository and published package identities as compatibility and provenance anchors. The Textbutler site is assigned to `textbutler.app`; later identity migrations must preserve immutable artifacts and existing release protections.
+
+## Sources
+
+- [Codex App Server](https://learn.chatgpt.com/docs/app-server): programmatic threads, turns, tool requests, account operations, and sandbox configuration.
+- [Codex security](https://learn.chatgpt.com/docs/security): sandbox and approval boundaries.
+- [Claude Agent SDK permissions](https://platform.claude.com/docs/en/agent-sdk/permissions): tool permission controls.
+- [Linq messages](https://docs.linqapp.com/channel/imessage/api/resources/chats/subresources/messages/): transport-specific rich message behavior.
+- [Linq reactions](https://docs.linqapp.com/channel/imessage/api/resources/messages/methods/add_reaction/): emoji and sticker reactions.

package/docs/textbutler/ghostget-contract.md

@@ -0,0 +1,88 @@
+# Ghostget integration contract
+
+Textbutler owns reply policy and contact memory. Ghostget owns messaging
+accounts, native permissions, synchronization, event storage and outward
+actions. Textbutler communicates with its own Ghostget owner process through
+`ghostget messaging automation serve --stdio`; it does not share the Ghostget
+Mac app's private helper or open provider databases.
+
+[Ghostget 0.18.2](https://github.com/hraness/ghostget/releases/tag/v0.18.2) is the
+verified published dependency for this contract. Its package includes both
+private messaging runtimes; installation is explicit and starts no provider.
+Older generic CLI routes do not become automation grants.
+
+## Owner process
+
+The private protocol is `ghostget.messaging-automation/1`. Every bounded JSON
+request has an ID, method and parameters; every response repeats its protocol
+and ID and carries either a checked result or a typed error. Initialization
+selects up to two explicit accounts, one per network, through stdin. Contact
+memory and model tools cannot configure that process or invoke its control API.
+
+Textbutler records process custody before launch, bounds its streams and queue,
+and removes custody only after a successful close response and verified clean
+process exit. Cancellation and revocation can interrupt an active submission.
+A malformed response, crash or uncertain cleanup retains the recovery fence.
+Restarting Textbutler does not silently clear it.
+
+## Contacts, events and grants
+
+| Surface | Implemented contract |
+| --- | --- |
+| `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. |
+| `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. |
+| `close` | Wait for owned provider cleanup before acknowledging shutdown. |
+
+Enrollment records contain the provider account incarnation, source generation,
+implementation identity, exact conversation coordinate and participants. Display
+titles are labels, not authority. Account or participant replacement invalidates
+the binding. Existing Textbutler version 1 read bindings remain readable;
+automation requires explicit version 2 enrollment.
+
+Ghostget's managed permissions must explicitly allow each requested operation.
+A broad capability advertisement does not create a grant. Textbutler activation
+issues a bounded grant only after checking the selected agent account and
+conversation. It renews standing enabled-contact grants within their limits,
+and persists grant intent before issuance so a lost response can be resolved
+without blindly creating another grant. Disabled and uncommitted grants are
+reconciled through revocation.
+
+Startup, re-enablement and recovery drain old events silently. An unresolved gap
+pauses automation. Textbutler waits for a new eligible inbound event and applies
+debounce, owner cooldown, classification and rate limits. Ghostget rechecks
+identity, permission, context and grant before dispatch, and observes intervening
+conversation changes between actions. Neither component retries an uncertain
+send automatically.
+
+## Rich actions
+
+Attachments, reactions, stickers, rich links and native polls are separate
+capabilities. They become available only when the installed provider, current
+account and managed permission admit them. Message targets must belong to the
+enrolled conversation. Attachment and sticker paths are resolved by Textbutler's
+contact file broker; Ghostget receives admitted bytes, not arbitrary paths.
+
+Every response starts with disclosed text. For a nontext response, Textbutler
+inserts a companion such as `🤖{ … }` before the rich actions. Execution stops
+when a preceding action fails or the conversation changes. An accepted receipt
+does not claim delivery.
+
+Native iMessage exposes text and files through the pinned helper and its
+currently usable rich methods for six standard tapbacks, stickers, links and
+polls. Rich methods require the owner's separately configured native bridge.
+App Clips and arbitrary mini-app experiences remain unavailable: no reviewed
+native executor exists. Linq's hosted APIs are a design reference and cannot
+silently substitute another sender for the owner's personal conversation.
+
+## Verification boundary
+
+The source tests cover account changes, cursor restart and gaps, grant revocation
+and lost responses, exact byte admission, ordered actions, cancellation and
+uncertain results using synthetic accounts. They do not establish live provider
+delivery. A bounded live acceptance test needs explicit account, recipient and
+message authorization and must record the exact provider/runtime versions.
+See [WhatsApp](whatsapp.md) and [the architecture](architecture.md).

package/docs/textbutler/whatsapp.md

@@ -0,0 +1,74 @@
+# WhatsApp through Ghostget
+
+WhatsApp uses the same Textbutler contact settings, memory, disclosure, hooks
+and reply policy as iMessage. Ghostget owns the linked device, pairing,
+credentials, synchronization and send implementation. Textbutler never runs
+`wacli` directly or imports a WhatsApp session database.
+
+```mermaid
+flowchart LR
+  App[Textbutler Mac app] --> Butler[Textbutler daemon]
+  Butler --> Agents[Agentrouter]
+  Butler --> Ghostget[Ghostget owner process]
+  Ghostget --> Messages[iMessage helper]
+  Ghostget --> WhatsApp[Pinned wacli linked device]
+```
+
+## Setup and behavior
+
+Configure the WhatsApp account and its managed automation permissions in
+Ghostget, install its verified private messaging helper, then select that
+account in Textbutler's private `state/host.json`. The Mac app's messaging setup
+explicitly starts synchronization. Choose one returned direct conversation,
+optionally import recent history, and enable it only after the selected agent
+account passes its checks. New contacts and new installations start inactive.
+See [runtime setup](../../packages/textbutler/README.md).
+
+Version 2 enrollment preserves the canonical conversation JID, exact account
+incarnation, source generation and participant identity. Phone-number and
+linked-identity JIDs are never equated from similar digits. Self chats,
+broadcasts, newsletters and unsupported groups cannot be enrolled.
+
+The Ghostget provider uses a reviewed private transport patch on
+[wacli](https://github.com/openclaw/wacli) 0.15.0. A single owned synchronization
+process maintains a bounded SQLite event journal and accepts generation-bound
+private requests. Each outward request gets a durable claim and one application
+dispatch attempt. It does not reuse stock send retry behavior after a timeout.
+The exact binary, patch and resource hashes are recorded in Ghostget's package.
+
+Events preserve message identity, authored time, edits, deletion and reactions.
+Cursor anchors detect retention gaps and replaced stores. Catch-up and old
+history never trigger replies. A new owner message cancels pending composition
+and starts the contact's cooldown. Uncertain send or process cleanup blocks
+further automatic activity until reconciled.
+
+## Actions
+
+| Action | Implementation |
+| --- | --- |
+| Text and files | Recipient-bound sends with admitted bytes and durable result claims. |
+| Reactions | Add/remove a supported reaction to a message in the selected conversation. |
+| Stickers | Bounded admitted media through the private provider action. |
+| Links and polls | Native provider operations when observed and explicitly allowed. |
+| App Clips and mini-app experiences | Unavailable; no corresponding reviewed WhatsApp executor. |
+
+Capabilities are observed per account and intersected with its managed
+permissions. An unavailable capability is never converted to another action.
+Textbutler adds its configured disclosure before all rich responses.
+
+[WPPConnect](https://github.com/wppconnect-team/wppconnect) remains an alternative
+Ghostget provider implementation if a specific missing capability warrants it.
+It is not a second linked-device stack inside Textbutler. Replacing the provider
+must preserve identity and pending-action reconciliation or require explicit
+re-enrollment.
+
+## Evidence
+
+Synthetic adapter, SQLite journal, private transport, and process tests exercise
+the implemented boundary without pairing a real account or messaging anyone.
+The native patch has plain and FTS Go tests, vet checks and repeat-build evidence.
+These checks establish source behavior, not live WhatsApp delivery. Real pairing,
+reconnect and rich-action acceptance still require a bounded owner-authorized
+test. The older `createGhostgetWhatsAppTransport()` stays a read-only compatibility
+adapter; automation uses `createGhostgetAutomationTransport()` and the
+[versioned owner protocol](ghostget-contract.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/message-like-me",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "A local-first CLI and Agent Skill for studying private messaging history and drafting messages that sound like you.",
   "license": "MIT",
   "type": "module",
@@ -77,16 +77,23 @@
     "check:standalone": "bun scripts/check-standalone.ts",
     "check:dist": "bun scripts/check-dist.ts",
     "check:package": "bun scripts/package-smoke.ts",
-    "check": "bun run typecheck && bun run check:effect && bun run test && bun run check:skill && bun run check:standalone && bun run build && bun run check:public-graphs && bun run check:dist && bun run check:package",
+    "check": "bun run typecheck && bun run check:effect && bun run test && bun run check:skill && bun run check:standalone && bun run build && bun run check:public-graphs && bun run check:dist && bun run check:package && bun run check:textbutler",
+    "check:textbutler": "bun test packages && tsc --noEmit -p packages/agentrouter/tsconfig.json && tsc --noEmit -p packages/transport/tsconfig.json && tsc --noEmit -p packages/textbutler/tsconfig.json && bun run --cwd apps/macos check",
+    "textbutler": "bun packages/textbutler/src/cli.ts",
     "prepack": "bun run check",
     "check:effect": "bun scripts/check-effect-architecture.ts",
     "check:public-graphs": "bun scripts/check-public-graphs.ts"
   },
   "devDependencies": {
+    "@tauri-apps/cli": "2.11.4",
+    "@anthropic-ai/claude-agent-sdk": "0.3.268",
+    "@anthropic-ai/sdk": "0.125.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@types/bun": "1.3.14",
     "effect": "3.22.1",
     "fast-check": "4.9.0",
     "sigstore": "4.1.1",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "zod": "4.6.2"
   }
 }