@hasna/bridge 0.1.2 → 0.2.1

package/dist/types.d.ts

@@ -27,6 +27,13 @@ export interface WebhookChannelConfig extends BaseChannelConfig {
 export interface IMessageChannelConfig extends BaseChannelConfig {
     kind: "imessage";
     account?: string;
+    serviceName?: string;
+    defaultHandle?: string;
+    allowedHandles?: string[];
+    allowAllHandles?: boolean;
+    receiveMode?: "disabled" | "chat-db";
+    chatDbPath?: string;
+    pollLimit?: number;
 }
 export type ChannelConfig = TelegramChannelConfig | ConsoleChannelConfig | WebhookChannelConfig | IMessageChannelConfig;
 export interface ProfileConfig {
@@ -75,13 +82,69 @@ export interface BridgeMessage {
     channelId: string;
     text: string;
     chatId?: string;
+    threadId?: string;
+    responseTargetId?: string;
     from?: string;
     receivedAt: string;
     raw?: unknown;
 }
+export type BridgeSessionStatus = "active" | "paused" | "closed";
+export type AgentSessionMode = "durable" | "compatibility";
+export interface AgentSessionRef {
+    kind: AgentKind;
+    mode: AgentSessionMode;
+    refId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    detail?: string;
+}
+export interface BridgeSession {
+    id: string;
+    agentId: string;
+    profileId?: string;
+    cwd?: string;
+    title?: string;
+    status: BridgeSessionStatus;
+    createdAt: string;
+    updatedAt: string;
+    lastMessageAt?: string;
+    agentSession?: AgentSessionRef;
+}
+export interface BridgeBinding {
+    id: string;
+    channelId: string;
+    conversationId: string;
+    activeSessionId: string;
+    defaultSessionId?: string;
+    createdAt: string;
+    updatedAt: string;
+    authorization?: {
+        chatId?: string;
+        from?: string;
+    };
+}
+export type LedgerStatus = "processing" | "agent_completed" | "delivered" | "skipped" | "unauthorized" | "failed";
+export interface MessageLedgerEntry {
+    id: string;
+    channelId: string;
+    messageId: string;
+    conversationId?: string;
+    sessionId?: string;
+    status: LedgerStatus;
+    attempts: number;
+    firstSeenAt: string;
+    updatedAt: string;
+    terminalAt?: string;
+    error?: string;
+    responseText?: string;
+    deliveredResponse?: boolean;
+    agentExitCode?: number | null;
+    agentTimedOut?: boolean;
+}
 export interface AgentRunInput {
     message: BridgeMessage;
     route: RouteConfig;
+    session?: BridgeSession;
 }
 export interface AgentRunResult {
     agentId: string;
@@ -97,6 +160,16 @@ export interface RoutedMessageResult {
     agent: AgentRunResult;
     deliveredResponse?: boolean;
 }
+export interface SessionMessageResult {
+    kind: "session";
+    session?: BridgeSession;
+    binding?: BridgeBinding;
+    conversationId?: string;
+    agent?: AgentRunResult;
+    deliveredResponse?: boolean;
+    status: "delivered" | "no_session" | "paused" | "closed" | "unauthorized" | "no_output" | "failed";
+    message?: string;
+}
 export interface DoctorCheck {
     name: string;
     ok: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,EAAG,CAAU,CAAC;AAEzC,eAAO,MAAM,aAAa,yDAA0D,CAAC;AACrF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,WAAW,uDAAwD,CAAC;AACjF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,oBAAoB,GACpB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,cAAc,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,iBAAiB,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC;AAElH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,WAAW,GAAG,QAAQ,CAAC;IACnG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB"}

package/docs/architecture.md

@@ -1,35 +1,50 @@
 # Bridge Architecture
 
-`bridge` separates channel connectors from agent adapters.
+`bridge` separates channel connectors from agent adapters. In `0.2.x`, the
+primary product model is session-backed routing: external conversations bind to
+durable bridge sessions, and bridge sessions bind to agent sessions.
 
 Channels own external transport details such as Telegram bot tokens, chat IDs,
-webhooks, or future iMessage transport. Agents own local execution details such
-as Codewith auth profiles, Claude profile homes, AIcopilot state roots, command
-arguments, cwd, and environment. Routes connect one channel to one agent.
+webhooks, or iMessage transport. Agents own local execution details such as
+Codewith auth profiles, Claude profile homes, AIcopilot state roots, cwd, and
+environment. Bindings connect a channel conversation to a durable bridge
+session. Routes remain a compatibility surface for explicit stateless tests.
 
-The package deliberately keeps Telegram-specific behavior out of Codewith,
-Claude, and AIcopilot integrations. Agent adapters receive plain text prompts
-and return stdout/stderr plus process metadata. Channel connectors decide how
-to receive and deliver messages.
+The package deliberately keeps Telegram-specific or iMessage-specific behavior
+out of Codewith, Claude, and AIcopilot integrations. Agent adapters receive
+normalized session messages and return final responses or stream events. Channel
+connectors decide how to receive, authorize, normalize, and deliver messages.
 
 ## Data Model
 
 - `channels`: external message transports.
 - `profiles`: reusable identity/state settings for an agent family.
 - `agents`: runnable targets, usually pointing at one profile.
-- `routes`: mapping rules from channel messages to agents.
+- `sessions`: bridge-owned conversations with one agent target and optional
+  external agent session reference.
+- `bindings`: mapping from normalized external conversation IDs to active
+  bridge sessions.
+- `messageLedger`: idempotency and retry records for inbound channel messages.
+- `cursors`: per-channel offsets committed after terminal processing.
+- `routes`: compatibility mapping rules from channel messages to agents.
+
+Runtime state uses `schemaVersion: 2` and is backward-compatible with the
+`0.1.x` state shape that only stored `telegramOffsets`.
 
 ## Profile Model
 
-Codewith profiles use `authProfile` and render as `codewith --auth-profile
-<name> --cd <cwd> exec <prompt>`.
+Codewith profiles use `authProfile`. The durable adapter should use Codewith's
+background-agent surface where a noninteractive create/send/resume flow is
+available. `codewith --auth-profile <name> --cd <cwd> exec <prompt>` is
+compatibility mode because it is a one-shot process and does not preserve
+agent-side conversation context.
 
 Claude profiles can use `home` or custom env vars so multiple accounts do not
 share local state.
 
-AIcopilot profiles currently use cwd/env/command isolation. The target repo
-work dispatched on spark02 is expected to add or document first-class profile
-support.
+AIcopilot profiles currently use cwd/env/command isolation. The adapter must add
+or consume first-class create/send/events session support before AIcopilot can
+be presented as a durable bridge session target.
 
 ## Telegram
 
@@ -48,7 +63,22 @@ MCP config inspection redacts profile and agent environment values so local
 secrets are not exposed through `bridge_config`.
 
 Long-poll offsets are persisted in a private state file so process restarts do
-not replay already-seen updates and re-run agents.
+not replay already-seen terminal updates and re-run agents. In session mode,
+offsets must be committed only after the inbound message reaches a terminal
+ledger state: delivered, intentionally skipped, or unauthorized. Failed
+messages remain retryable and do not advance the Telegram offset.
+
+If the agent succeeds and outbound delivery fails, the ledger stores the final
+response in `agent_completed`; retry attempts deliver the stored response rather
+than invoking the agent again.
+
+When a Telegram chat has an active binding, plain text routes to that session.
+When no binding exists, the bridge can reply with setup instructions and does
+not invoke an agent. Route matching is still available as compatibility fallback
+for explicit configured routes.
+
+Telegram forum topics are part of the normalized conversation ID:
+`telegram:<channelId>:<chatId>:<messageThreadId>`.
 
 `BRIDGE_TELEGRAM_API_BASE` can override the Telegram API origin for local tests.
 The override accepts only `http` or `https` URLs without credentials. It is not
@@ -80,3 +110,27 @@ errors.
 `bridge serve` handles per-channel poll errors without exiting in long-running
 mode. `serve --once` still fails fast so health checks and tests can catch
 misconfiguration.
+
+## iMessage
+
+iMessage support is local macOS-only. The adapter must send through Messages
+automation and receive through local Messages state or a documented helper mode.
+It must fail closed when Automation or Full Disk Access permissions are missing.
+Diagnostics should report the missing permission without reading or logging
+private message contents unnecessarily.
+
+The implemented adapter sends with `osascript` and can optionally receive by
+polling `~/Library/Messages/chat.db` when `receiveMode` is `chat-db`. The send
+script honors `account` when configured. The receive path filters out messages
+from the local user, enforces `allowedHandles` unless `allowAllHandles` is
+explicitly set, scans ahead past disallowed rows to avoid cursor starvation, and
+keeps local Messages chat GUIDs so group chats do not collapse to a single
+sender handle. Daemon cursors store the last processed Messages row ID per
+channel.
+
+## MCP
+
+MCP must expose session-first tools for listing, creating, attaching, sending
+to, and inspecting bridge sessions. Route-based MCP tools are compatibility-only
+after `0.2.x`; MCP clients should use `bridge_session_route_message` when they
+want normal inbound message behavior through bindings.

package/docs/session-bridge-plan.md

@@ -0,0 +1,204 @@
+# Session-Backed Multi-Channel Bridge Plan
+
+This is the working plan for the `0.2.x` bridge release. The repo folder is
+`open-bridge`, the package is `@hasna/bridge`, and the CLI remains `bridge`.
+
+## Goal
+
+`bridge` should connect external conversations to durable agent sessions. A
+Telegram chat, iMessage thread, Slack channel, or future channel should map to a
+bridge conversation and then to a Codewith, Claude Code, or AIcopilot session.
+Normal messages go to the active bound session. Prefixes are only acceptable as
+an optional compatibility route, not as the main product model.
+
+## Target Model
+
+```text
+channel event
+  -> normalized bridge conversation
+  -> durable bridge binding
+  -> agent session adapter
+  -> streamed or final channel response
+```
+
+- Channels normalize inbound events and deliver outbound text.
+- Bindings map external conversation IDs to bridge sessions.
+- Agent adapters own account/profile state and send messages to a durable agent
+  session.
+- Session commands manage control flow; ordinary text is user intent.
+
+## Versioned State
+
+`0.2.x` must add versioned state separate from static config:
+
+- `schemaVersion`: state schema version with forward-only migration.
+- `sessions`: bridge-owned session records keyed by stable session ID.
+- `bindings`: external conversation bindings keyed by normalized channel
+  conversation ID.
+- `messageLedger`: per-channel inbound processing records for idempotency,
+  retries, and delivery status.
+- `cursors`: per-channel cursor/offset state, committed only after the inbound
+  message has reached a terminal routing state.
+
+Session records must include agent ID, profile ID, cwd, status
+(`active`, `paused`, `closed`), external agent session reference, timestamps,
+last activity, timeout policy, and compatibility-mode marker when an adapter
+falls back to one-shot execution.
+
+Binding records must include channel ID, normalized conversation ID, active
+session ID, optional default session ID, created/updated timestamps, and an
+authorization snapshot such as Telegram chat ID or iMessage handle.
+
+## Idempotency And Retry
+
+- Inbound message processing writes a ledger row before invoking an agent.
+- Channel cursors advance only after a message is delivered, intentionally
+  skipped, or rejected as unauthorized. Failed messages remain retryable until a
+  retry-exhaustion policy is added.
+- Agent failure leaves a retryable `failed` ledger state.
+- Outbound send failure after an agent succeeds leaves an `agent_completed`
+  ledger state with the generated response, so retries do not re-run the agent.
+- Replayed updates must not run the agent twice after a successful delivery.
+- Daemon restart must recover in-progress ledger rows without losing prompts.
+
+## Commands
+
+Planned CLI surface:
+
+```sh
+bridge sessions list
+bridge sessions show <id>
+bridge sessions create --agent codewith --cwd /repo
+bridge sessions attach <id> --channel telegram-main --conversation 1225577096
+bridge sessions use <id> --channel telegram-main --conversation 1225577096
+bridge sessions detach --channel telegram-main --conversation 1225577096
+bridge sessions close <id>
+bridge sessions pause <id>
+bridge sessions resume <id>
+```
+
+Telegram and future command-capable channels should expose the same session
+controls as slash commands:
+
+```text
+/sessions
+/new
+/use <id>
+/attach <id>
+/detach
+/pause
+/resume
+/close
+/help
+```
+
+## Channels
+
+Telegram:
+
+- Plain messages route to the active session for that chat.
+- If no active session exists, the bot responds with a short setup prompt and
+  does not invoke an agent.
+- Slash commands manage sessions and never require a `cw` prefix.
+- Group chats must support `/command@BotName`, topic/thread IDs when Telegram
+  provides them, and unauthorized command rejection.
+- Unknown slash commands are treated as control errors, not agent prompts.
+- A literal agent prompt that starts with `/` must require an explicit escape
+  command or compatibility route, so control messages and prompts do not collide.
+- Existing route-based behavior can remain for explicit compatibility tests.
+
+iMessage:
+
+- The first adapter is local macOS-only.
+- Sending uses Messages automation through `osascript` and reports TCC
+  Automation failures clearly.
+- Receiving uses local Messages state with a per-chat cursor or a documented
+  helper mode. It must fail closed when Full Disk Access or Messages data access
+  is unavailable.
+- Conversation IDs are normalized from service, chat GUID, handle, and optional
+  account so multiple local accounts do not collide.
+- Permission diagnostics explain needed macOS Automation and Full Disk Access
+  grants without storing private message contents in config.
+- Tests must be skip-safe on non-macOS and on macOS machines without the needed
+  permissions.
+- The current implementation supports send through `osascript` and optional
+  receive through `chat.db` polling when `receiveMode` is `chat-db`.
+
+## Channel Adapter Contract
+
+Each channel adapter must provide:
+
+- `poll` or `receive` with a cursor and bounded batch size.
+- `send` with normalized conversation ID and delivery result.
+- `diagnose` for auth, permissions, and environment checks.
+- Per-channel backoff hints for daemon runtime.
+- Redaction rules for sensitive channel metadata and message contents.
+
+## Agents
+
+Codewith:
+
+- Use a stable local session API or mailbox-backed background session.
+- Use auth profiles explicitly, for example `account001`.
+- Avoid typing into the interactive TUI as the primary integration method.
+
+Claude Code:
+
+- Use the official resumable/session surface where available.
+- Keep account homes/profiles isolated.
+- Mark any process-wrapper fallback clearly as compatibility mode and do not
+  advertise it as a durable session.
+
+AIcopilot:
+
+- Use the same session contract as Codewith where possible.
+- Add create/send/events semantics if the repo does not expose them yet.
+
+## Agent Adapter Contract
+
+Each agent adapter must provide:
+
+- `createSession(profile, cwd, options) -> agentSessionRef`.
+- `sendMessage(sessionRef, text, options) -> final response or stream events`.
+- `resumeSession(sessionRef)` after daemon restart.
+- `cancel(sessionRef)` where the underlying agent supports cancellation.
+- `close(sessionRef)` for local cleanup.
+- Explicit timeout, output limit, stderr, and compatibility-mode behavior.
+
+## Tracked Tasks
+
+The local `todos` plan is `cba73b38-97c5-4a02-bf58-1a03069cc0c4`:
+
+- `4e73f3bf-3fbb-4aae-8d01-045501db925d`: define durable bridge session model.
+- `630b62e3-6d57-4121-b3de-90052ad21f66`: add session CLI and persistent bindings.
+- `e5820e95-3c91-4523-a583-84bb4b1e7a56`: implement session-aware agent adapters.
+- `56906077-0fdb-4767-bdd0-a1990508eade`: make Telegram work without prefixes.
+- `a93e4741-529e-4718-a6c9-f8ed213756db`: add macOS iMessage channel adapter.
+- `54698f24-7a62-4f02-9dba-4095194adc59`: release, reinstall, and verify bridge 0.2.
+- `e268d9a7-ac40-4df9-9cfb-8e820795d87a`: adversarially verify the release.
+
+## Done Criteria
+
+- `bun run build`, `bun run typecheck`, and `bun test` pass.
+- Session bindings survive daemon restarts.
+- Telegram live test works with plain messages against the configured bot.
+- iMessage diagnostics and send/receive smoke behavior work on macOS or fail
+  closed with a clear permission result.
+- The package is committed, pushed, published, reinstalled locally, and smoke
+  tested from the public npm package.
+- An adversarial review checks routing security, secret handling, daemon
+  lifecycle, replay/idempotency, channel spoofing, and package installability.
+
+## MCP Migration
+
+`bridge-mcp` must expose session-first tools:
+
+- `bridge_session_list`
+- `bridge_session_create`
+- `bridge_session_attach`
+- `bridge_session_send`
+- `bridge_session_status`
+- `bridge_session_route_message`
+
+`bridge_route_message` can remain during `0.2.x` as compatibility-only and must
+be documented that way in MCP metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/bridge",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Agent messaging bridge for Telegram and other channels",
   "type": "module",
   "main": "dist/index.js",