Add package email event subscriptions

docs/use/email-primitives.md

@@ -24,10 +24,16 @@ Use the MCP `email` domain:
 - Display names are not trusted. Kody stores envelope sender, parsed `From`, and
   authentication headers separately.
 - Outbound sending requires a verified sender identity.
-- Inbound package handlers are intentionally disabled in this first slice. Mail
-  is stored first; packages and agent loops decide what to do with it later.
-- Attachments are metadata-only for now; raw MIME for small messages is stored
-  so the first pass can be tested locally.
+- Stored inbound mail is the source of truth. If a user wants email automation,
+  they can publish a package that subscribes to the stored inbound email topic
+  `email.message.received` using normal package subscriptions. This is package
+  behavior, not a separate Kody-owned email handler or agent-loop primitive.
+- Subscription event payloads are metadata-first. Package handlers receive the
+  stored message id and receipt metadata, then use `email_message_get` or
+  `email_attachment_get` (or `import { email } from 'kody:runtime'`) when they
+  need bodies or attachment bytes.
+- Attachments remain metadata-first by default; raw MIME for small messages is
+  stored so on-demand attachment lookup can reconstruct bytes locally.
 
 ## Local inbound testing
 

packages/worker/src/email/inbound.ts

@@ -14,10 +14,11 @@ import {
 	insertEmailMessageWithAttachments,
 	touchEmailThread,
 } from './repo.ts'
+import { dispatchInboundEmailSubscriptionEvents } from './package-subscriptions.ts'
 
 export async function handleInboundEmail(
 	message: ForwardableEmailMessage,
-	env: Pick<Env, 'APP_DB'>,
+	env: Pick<Env, 'APP_DB' | 'BUNDLE_ARTIFACTS_KV' | 'APP_BASE_URL'>,
 	_ctx?: ExecutionContext,
 ) {
 	const recipient = normalizeEmailAddress(message.to)
@@ -160,4 +161,14 @@ export async function handleInboundEmail(
 			from_address: parsed.headerFrom,
 		},
 	})
+	const dispatchPromise = dispatchInboundEmailSubscriptionEvents({
+		env,
+		userId,
+		message: stored,
+	})
+	if (_ctx) {
+		_ctx.waitUntil(dispatchPromise)
+	} else {
+		await dispatchPromise
+	}
 }