@kingcrab/pi-imessage 1.1.0 → 1.2.0

package/docs/adr/0042-background-schedules-and-workspace-extensions.md

@@ -1,44 +0,0 @@
-# 0042. Background schedules and workspace extensions
-
-Status: accepted (owner accepted on 2026-10-06; consolidates ADRs 0019 and 0032–0035 without changing behavior)
-
-**Problem.** Scheduling was removed (0019), rebuilt natively (0032–0034) and
-then separated from personal business code (0035). The current rules are
-spread over five ADRs that partly contradict each other.
-
-**Example.** A daily 07:45 workspace task and six-hour compaction both keep
-their deadlines across a restart. Changing the task's code changes only
-`WORKING_DIR/extensions/<name>/`, not the framework.
-
-**Decision.**
-
-- **Retired services stay removed:** cron, reminders, delayed prompts,
-  completion watchers, PT Automation and HTTP `/prompt` / `/send`. Their
-  endpoints return 404; stored old data is kept but unused.
-- **Workspace extensions** hold personal code: `WORKING_DIR/extensions/<name>/`
-  with `index.ts` and `config.json`. Each is a trusted native Durable extension
-  with tools, tasks and optional schedules. The owner and the chat assistant
-  may both create them. Startup, `/reload` and `reload_extensions` scan direct
-  child directories. Duplicate names are rejected; a failed reload keeps the
-  old definitions; running calls keep their code.
-- **Framework scheduling** gives each schedule a dedicated conversation with a
-  background task whose checkpoint saves the absolute next deadline. Each
-  occurrence is a child task; occurrences never overlap. Daily slots run only
-  today's slot, without backfill; interval slots skip missed ticks. Six-hour
-  compaction uses the same mechanism and stays built in.
-- **Time** is the service machine's local timezone (or `TZ`). Daily slots are
-  computed by calendar date, so daylight-saving changes keep the wall-clock
-  time. Saved deadlines are never reset by reload, restart or timezone change.
-- **Delivery** commits business state and the outgoing item together. The host
-  sends through existing receipts at most once; `unknown` is never resent.
-- **Operator run:** `serve --run-scheduled JOB --request-id ID` admits one
-  occurrence at startup; repeating the same request ID returns the same task.
-- **History:** `/scheduled` shows each schedule, its deadline and the latest
-  ten occurrences from native task records. Viewing never starts work.
-- **Removal:** removing an extension stops future scheduling only. Unfinished
-  work keeps its code in memory; restart fails explicitly if required code is
-  missing.
-
-**Consequences.** The service must be running to act at a deadline. Workspace
-extensions are trusted code and need backup. This supersedes ADRs 0019 and
-0032–0035, and the scheduler clause of ADR 0013.

package/docs/adr/0043-remove-legacy-migration.md

@@ -1,23 +0,0 @@
-# 0043. Remove the legacy migration code
-
-Status: accepted (owner decided on 2026-10-06)
-
-**Problem.** The one-time cutover from the legacy service is done, but its code
-and runbook remain: `src/migrate/`, the `pi-imessage import` command, a test and
-`ops/CUTOVER.md`. Readers must learn a whole layer that will never run again.
-
-**Example.** A new contributor reads the package table, finds `migrate/` next to
-`main.ts`, and spends time on history import rules unrelated to any change.
-
-**Decision.**
-
-- Delete `src/migrate/`, the `import` CLI command, `test/migrate.test.ts` and
-  `ops/CUTOVER.md`.
-- Keep them reachable at the annotated tag `archive/legacy-migration`, the last
-  revision that contains them. A tag is fixed and runnable; a wiki copy is not.
-- The rule "never run old and new message pipelines concurrently" stays in
-  `AGENTS.md` and `ops/README.md`.
-
-**Consequences.** Imported history already lives in Durable storage and is
-unaffected. Rerunning a migration means checking out the tag in a separate
-worktree. This replaces ADRs 0005 and 0009, whose work is complete.

package/docs/adr/0044-message-channels.md

@@ -1,32 +0,0 @@
-# 0044. Organize message sources as channels
-
-Status: proposed
-
-**Problem.** `transport/` is iMessage-only: it polls `chat.db` and sends through
-Messages.app. A second message source, such as Telegram, has no place to go, and
-the name "transport" suggests a network layer. `transport/http.ts` is the shared
-outgoing HTTP client, not a message source.
-
-**Example.** Adding Telegram today would mean putting `telegram-watch.ts` beside
-`watch.ts`, while `agent/` imports `MessageSender` from the iMessage `send.ts`.
-
-**Decision.** Apply this when the second channel is implemented, not before
-(no abstraction until needed):
-
-- Rename `transport/` to `channels/`, with one directory per channel:
-  `channels/imessage/` (`watch.ts`, `send.ts`, `rich-text.ts`,
-  `attachments.ts`), `channels/telegram/`, and so on.
-- Put the shared contract in `channels/types.ts`: the incoming message shape and
-  `MessageSender`. `agent/` depends on this contract, never on one channel.
-- Move the process HTTP client (ADR 0016) out of the channel package, for example
-  to `config/` or a small `net/` package at the bottom layer.
-- Identify chats as `<channel>:<id>` for new channels. Existing iMessage chat
-  GUIDs stay unchanged, so `settings.json` allowlists and Durable `Chats`
-  records remain valid.
-
-**Consequences.** One rename and an import update when the second channel
-arrives; until then the code stays as it is. The layer rule (ADR 0002) is
-unchanged: channels stay below `agent/` and contain no agent logic.
-
-**Rejected.** A generic plugin loader for channels: there is one real channel
-today, and workspace extensions (ADR 0042) already cover tool plugins.

package/docs/adr/0045-chat-scheduling-tools.md

@@ -1,51 +0,0 @@
-# 0045. Native chat scheduling tools
-
-Status: proposed
-
-**Problem.** A simple deferred chat request currently requires the assistant to
-write a trusted workspace extension and reload it. That is useful for reusable
-business code, but unnecessarily complex for an ordinary reminder or agent task.
-
-**Example.** In iMessage, "remind me in ten minutes" should create a task through
-`schedule_task`, just as it does in the coding agent. "Every day at 09:00,
-summarize new items" should not require generated TypeScript either.
-
-**Decision.**
-
-- Add built-in `schedule_task`, `list_scheduled_tasks` and
-  `cancel_scheduled_task` tools for chat conversations. The scheduling tool takes
-  a time and a prompt, with optional explicit daily or interval repetition.
-  Support durations, clock times and absolute datetimes; do not add a cron parser.
-- Bind each task to its originating chat in host code. List and cancellation
-  operate only on that chat's interactive schedules, never framework maintenance
-  or workspace extension schedules. Return a stable ID and the actual deadline.
-- Use native Durable background tasks and documents in the existing owning
-  service. Creation must be atomic and deduplicated by the scheduling tool call;
-  interruption must not create a second schedule. Persist absolute deadlines,
-  configuration and cancellation. No detached timer, operating-system scheduler,
-  legacy job files, HTTP prompt/send endpoint or second pipeline.
-- Execute each occurrence in a fresh isolated agent conversation with the
-  normal authorized tools. Send its final result back to the originating chat
-  through the existing at-most-once receipts and passive chat records, without
-  steering an unrelated active chat turn. A scheduled prompt is a saved user
-  request, not a system instruction.
-- Recurring occurrences never overlap and skip missed slots. One-shot tasks
-  execute once when overdue, including after restart. Cancellation prevents
-  future admission; it does not undo an already admitted occurrence or resend
-  uncertain effects. Keep existing restart recovery and unknown-send safeguards.
-- Use the service machine's timezone, including explicit `TZ`, and expose native
-  deadlines and occurrence records on the existing read-only Scheduled page.
-  The service must be running to execute work; persistence does not wake a
-  stopped service or machine.
-- Keep workspace extensions for reusable business tools and tasks. Existing
-  extension schedules and six-hour compaction retain their IDs, deadlines and
-  behavior. Reload must not disable or reset interactive schedules.
-- Replace the chat prompt's extension-writing requirement for ordinary scheduled
-  work with brief instructions to use these tools. Do not remove unrelated chat
-  steering or delivery safeguards.
-
-**Consequences.** This deliberately replaces ADR 0042's retirement of ordinary
-reminders and delayed agent prompts, but not its retired external services or
-workspace extension contract. It also replaces that clause of ADR 0018. It is a
-small native management interface over Durable, not a return to the old cron
-service. Implementation follows owner acceptance; accepted ADRs stay unchanged.

package/docs/adr/0046-selective-command-redaction.md

@@ -1,31 +0,0 @@
-# 0046. Selective command-preview redaction
-
-Status: proposed (owner requested `***` value masking on 2026-10-06; implementation tracked in #36)
-
-Supersedes only ADR 0040's whole-command credential suppression rule.
-
-**Problem.** A mention of `token`, `password`, `.env` or `auth.json` hides the
-entire command, even when it is just a source search or filename.
-
-**Example.** `TOKEN=demo123 curl --retry 3` becomes
-`→ [tool] bash: TOKEN=*** curl --retry 3`. `rg 'token' src` remains readable.
-
-**Decision.** Replace recognized credential values with `***`, retaining the
-surrounding command instead of a hidden-command placeholder. Cover sensitive
-assignments, options, authorization headers, URL userinfo, structured values,
-known credential prefixes and PEM private-key blocks. Read complete shell words,
-including quoted fragments, escaped spaces and command substitutions. Opaque
-escaped JSON and ambiguous substitutions may lose additional argument text to
-avoid showing a partial credential. Filenames and keyword mentions alone do not
-trigger hiding. Screening remains best effort, not an arbitrary-secret guarantee.
-
-Apply masking to the full command before whitespace normalization, URL/domain
-defanging and the existing 120-Unicode-code-point bound. Native execution,
-non-bash summaries, progress ownership, settlement and durable receipts remain
-unchanged. No new scheduler, pipeline, tool execution or delivery replay.
-
-**Verification.** Extend the existing isolated messaging regression with exact
-preview examples, quote/escape cases, structured credentials, line continuations,
-substitutions, known prefixes, private keys, keyword-only searches and masking
-before truncation. Existing native execution, ownership and uncertain-send
-regressions remain in force.

package/docs/adr/0047-one-scheduling-path.md

@@ -1,158 +0,0 @@
-# 0047. One scheduling path for recurring and one-off work
-
-Status: accepted (owner requested the minimal implementation on 2026-10-06)
-
-## Problem
-
-Recurring workspace jobs currently enter through a native scheduler task, while
-`serve --run-scheduled JOB --request-id ID` calls `runOnce()` and creates an
-occurrence directly. Both use Durable, but admission follows two paths, and a
-manual trial requires a service restart.
-
-Calling all work "scheduled" is not sufficient. The common path must own deadline
-persistence, deduplication and non-overlap. A trial must also retain the original
-job's business state, rather than create an empty English learning history or
-bypass the monthly quota.
-
-## Example
-
-Workplace English has a daily 07:45 trigger. An operator requests one trial now.
-The trial receives its own stable trigger ID, but targets the existing English
-job and business conversation. Reloading twice does not run it twice, and the
-regular 07:45 deadline does not move. Existing per-date card deduplication still
-applies: a trial is not permission to resend today's card.
-
-## Evaluation
-
-- **One common scheduling path:** recommended. Recurrence and an immediate trial
-  differ in their deadlines and repetition, not their executor or delivery path.
-- **One physical configuration file:** unnecessary. Keep trusted business code
-  and configuration in the workspace extensions required by ADR 0042. Their
-  declarations pass through one framework admission function.
-- **Automatic configuration polling:** unnecessary for the first version. The
-  existing `reload_extensions` tool and `/reload` already apply configuration
-  through the owning service without restart. Polling would add partial-write,
-  repeated-load and failure-handling concerns without helping deadline execution.
-- **A local CLI/socket or HTTP run API:** unnecessary here. A trial can be a
-  one-off declaration followed by the existing reload. This trades one explicit
-  reload operation for avoiding another control protocol.
-- **A separate business executor for every cadence:** rejected. Reminder,
-  script and model workflows remain native business tasks; they do not become
-  separate schedulers.
-
-## Decision
-
-### One admission and execution path
-
-```text
-Workspace extension configuration
-                |
-      startup / reload_extensions / /reload
-                |
-       validate and register triggers
-                |
-       native background Scheduler task
-                |
-       sleep(persisted absolute deadline)
-                |
-       native occurrence wrapper
-                |
-       registered native business task
-                |
-       native receipts -> read-only Scheduled Web
-                |
-       optional outbox -> existing send receipts
-```
-
-The reload commands are configuration-loading entry points, not direct execution
-paths. No file edit alone invokes business work. An immediate trial becomes due
-once its declaration has been accepted; it is not a promise of zero latency.
-The service must be running, and publication of validated code/configuration must
-complete before newly due work can execute under that definition.
-
-The framework retains one owning Harness. Do not introduce another daemon,
-operating-system timer, SDK scheduler bridge, database, or polling watcher.
-
-### Job identity and trigger identity
-
-- A **job** names registered business code, input, destination and its existing
-  business conversation/state. It is not an arbitrary command or prompt supplied
-  by a new public execution API.
-- A **trigger** names when that job is eligible to run. Recurring triggers and
-  one-off triggers use the same registration function and scheduler definition.
-- The minimal version preserves elapsed-time intervals and one local daily slot,
-  and adds a one-off absolute deadline or `now`. Multiple daily slots and monthly
-  calendars are deferred, not part of this first change. Do not add a cron parser.
-- Resolve `now` to an absolute timestamp once, in the admission transaction.
-  Persist the stable trigger ID, target job and deadline together. Subsequent
-  reloads/restarts recover that trigger, including a terminal one; they never
-  reevaluate `now`. A new intended trial needs a new trigger ID. Conflicting reuse
-  of a one-off ID fails explicitly.
-- A one-off declaration targets an existing registered job. Do not give it a
-  fresh business conversation, reset learning/checkpoints, or change the regular
-  trigger's deadline. A workspace extension must provide this declarative trial
-  binding; trial requests do not require generating a new extension per run.
-- Enforce non-overlap by target job, not merely by trigger. A due one-off can wait
-  for that job's active occurrence, then admit its own occurrence. Do not report
-  another trigger's work as completion of the new request.
-- Commit occurrence admission and the scheduler checkpoint together. A one-off
-  scheduler becomes terminal after its occurrence; a recurring scheduler saves
-  the next deadline. Failures remain visible in native occurrence records.
-
-### Recovery, reload and delivery
-
-- Preserve ADR 0042's machine-local calendar/DST rules, saved absolute deadlines,
-  daily/interval overdue behavior and lack of historical backfill. A one-off
-  admitted before shutdown runs once when overdue after restart.
-- Load and validate a complete candidate before accepting declarations. A failed
-  reload leaves old definitions and schedules active and must not start a trial.
-  Reload does not interrupt existing business calls. Pausing/removing a declaration
-  prevents future admission, not undoing already admitted effects.
-- Use native task versions/migrations where persisted structures change. Preserve
-  existing job/conversation/task IDs, learning state, checkpoints, execution
-  history and delivery receipts. Do not recreate terminal trials on startup.
-- Business tasks keep their own replay and success policy under ADR 0041. A shared
-  clock does not make a script's external effects transactional or replay-safe.
-  Reflection advances its checkpoint and starts backup only after verified success.
-- Keep the existing outgoing queue and at-most-once transport receipts. An
-  interrupted send becomes `unknown` and is not automatically resent. One-off
-  execution does not override a business quota, per-date dedupe or a send receipt.
-- Reuse the compact Scheduled page and native occurrence history. Show one-off
-  executions under their target job, with links to their Task tree. Viewing the
-  page starts no work; add no execution buttons.
-
-### Entry points removed or deferred
-
-After the unified one-off path is available, remove the operator startup-run
-flags and the direct-occurrence `runOnce()` bypass. Keep their historical request
-and execution records; do not replay them during migration. Do not add a CLI or
-Unix socket replacement.
-
-ADR 0045 remains a separate proposal about chat scheduling tools. This ADR does
-not enable or reject those tools. If accepted, their declarations must use this
-same admission/clock/occurrence path, preserve chat ownership boundaries, and
-must not introduce another scheduler or call a business executor directly.
-
-## Scope and consequences
-
-Framework changes concern the schedule declaration contract, common admission,
-calendar calculation, scheduler lifecycle and removal of the operator bypass.
-Personal messages, weather/news logic, memory updates, photo-date checks and
-Reflection remain workspace extensions, not framework-specific branches.
-
-Restoring the selected legacy jobs uses this path. Stop only their competing old
-cron producers during the authorized cutover; do not disable unrelated system
-jobs. Fixed-message business tasks do not restore the retired reminder service,
-PT workers or HTTP `/prompt` / `/send`. No restoration or migration is performed
-by accepting a file reload alone
-unless those jobs are explicitly declared.
-
-The first version requires an explicit reload after editing configuration. This
-is intentional: it avoids a new watcher and a new management service. Persistence
-cannot wake a stopped process or machine. Exactly-once external delivery is not
-claimed.
-
-This supersedes only ADR 0042's operator-run clause (which
-consolidated ADR 0033), and extends its cadence/declaration contract. Its workspace
-ownership, recovery and delivery rules remain in force. Accepted ADRs stay
-unchanged.

package/docs/adr/0048-quiet-attachment-reads.md

@@ -1,11 +0,0 @@
-# 0048. Quiet attachment reads
-
-Status: proposed (owner-requested behavior in #38, 2026-10-07)
-
-**Problem.** Reading an archived attachment adds noisy tool notices containing long private archive paths.
-
-**Example.** A native `read` of `WORKING_DIR/attachments/<chat>/<file>` produces no request or completion notice. An ordinary file read still shows the existing progress pair.
-
-**Decision.** Add a narrow exception to ADR 0040's all-tool progress rule: suppress both admission and settlement notices for native `read` calls under the active workspace attachment root, including owned child calls and failed reads. Normalize relative, home, @ and file-URL paths and resolve filesystem aliases using metadata only. Match directory boundaries, not a generic attachment substring. Other reads, tools, task progress, manual compaction and final replies remain unchanged.
-
-The existing native observer filters before assigning notice routing or making direct-send receipts. Execution, result/error history, receipt/no-replay rules and the single pipeline are unchanged. No new poller, sender, permission boundary, data removal or credential policy is introduced.

package/docs/adr/0049-per-chat-progress-notices.md

@@ -1,21 +0,0 @@
-# 0049. Per-chat progress notices
-
-Status: proposed (owner-requested implementation, 2026-10-24)
-
-**Problem.** `progressMessages` in `settings.json` turns tool progress notices on or off for every chat at once. A busy group wants only the final messages while an admin chat wants to watch the tools.
-
-**Example.**
-
-```text
-/verbose            -> Verbose: on (default)
-/verbose off        -> Verbose: off (this chat only)
-/verbose default    -> Verbose: on (default)
-```
-
-**Decision.**
-
-- Each chat record in the native `imessage.chats` document gets an optional `progress` boolean. `/verbose on|off` sets it and `/verbose default` removes it; `/verbose` alone reports the effective state. The record version is unchanged; old records have no field.
-- The progress observer (ADR 0040) resolves the owning chat first and then gates both the admission and the settlement notice by `chat.progress ?? settings.progressMessages`. Reply-enabled allowlisting, formatting, screening, receipts and no-replay rules are unchanged.
-- `settings.json` stays the default and is never rewritten by a command; the per-chat choice lives only in Durable.
-
-**Consequences.** A `/verbose off` chat still runs tools and records their results; it only stops seeing the two notice lines. Child notices follow the owning chat's choice. Changing the global default does not touch chats with an explicit choice.

package/docs/adr/0052-host-owned-self-restart.md

@@ -1,53 +0,0 @@
-# 0052. The host owns its own restart
-
-Status: accepted (owner accepted on 2026-10-24)
-
-**Problem.** A chat assistant restarts the service by writing a controller
-script and running it from a `bash` tool call. The host cannot tell that this
-call is about to stop it. When the call is still running at the stop, ADR 0041
-reruns it on the next start, which launches another controller and stops the
-service again (#39: about 70 restarts in eleven minutes). A host-side stop
-heuristic that aborts a tool interrupted twice in a row was tried the same
-day; it limits the damage after the fact, does not remove the cause, and
-aborts any long tool that two deployments happen to interrupt in a row.
-
-**Example.**
-
-```text
-restart_service({ release: "d627232…" })
--> Restart into /Users/clawbot/pi-imessage-releases/d627232… is scheduled;
-   the service stops after this call settles. Controller directory:
-   /tmp/pi-imessage-restart.Xy12ab. Verify in a later call.
-```
-
-The call settles, the host opens the controller in Terminal, the controller
-stops the old process and becomes the new one. The next turn verifies the
-listener, the log and the running release directory.
-
-**Decision.**
-
-- A built-in `restart_service` tool takes the full commit hash of a prepared
-  release directory, a sibling of the running one. It refuses a hash that is not
-  a directory with `src/cli.ts`, `node_modules` and `ops/restart.command`, and
-  a second request while one is scheduled.
-- The tool writes the private controller directory of ops/README.md step 3
-  itself: `environment.sh` from the process environment, `control.sh` from the
-  process's own PID, start time and command line, and a copy of
-  `ops/restart.command` from the target release. The controller deletes
-  `environment.sh` after sourcing it.
-- The tool returns at once. The host launches the controller only after the
-  tool task has settled, so the stop can never interrupt the call that asked
-  for it.
-- The tool is `replay: "unsafe"`. If it is interrupted anyway, the model gets
-  an interrupted result and checks what is running instead of a rerun
-  launching a second controller.
-- Ordinary tools keep the rerun default of ADR 0041. Operators keep the manual
-  procedure for a cold start when no service is running.
-
-**Consequences.** A self-restart costs one restart and no extra model turn.
-The stop still happens at a tool boundary of the requesting chat, so that chat's
-next model request is repeated after the restart, as ADR 0041 accepts. The
-restart loop of #39 cannot recur through this tool, so the stop heuristic is
-removed and ADR 0041 applies unchanged to every other tool. A chat that writes
-its own controller through `bash` is still subject to the ops rule of ending
-the call right after `open`.