Add package services runtime

docs/contributing/architecture/request-lifecycle.md

@@ -54,6 +54,20 @@ Requests are handled in this order:
 9. App server routes:
    - Everything else is handled by `packages/worker/src/app/handler.ts`
 
+## Package service runtime
+
+Saved packages may also declare long-lived package services under
+`package.json#kody.services`.
+
+- Package services are **not** routed through a public HTTP path the way package
+  apps are.
+- Instead, the Worker hosts them via the `PackageServiceInstance` Durable Object
+  binding and controls them through package runtime bridges and MCP
+  capabilities.
+- Package services share package identity with apps/jobs and can publish into
+  package app realtime sessions, but they own their own durable storage bucket
+  and lifecycle.
+
 ## App server flow
 
 `packages/worker/src/app/handler.ts` validates environment variables and

docs/guides/README.md

@@ -10,6 +10,7 @@ available `guide` ids).
 | [integration-bootstrap.md](./integration-bootstrap.md)                         | **Start here** for third-party integrations that must work before saving a dependent package or package app |
 | [secret-backed-integration.md](./secret-backed-integration.md)                 | Default recipe for non-OAuth integrations that use one or more saved secrets                                |
 | [integration-backed-app-happy-path.md](./integration-backed-app-happy-path.md) | Default package app pattern after integration smoke test passes                                             |
+| [package-service-pattern.md](./package-service-pattern.md)                      | General package-service pattern for native long-lived runtimes inside Kody                                   |
 | [oauth.md](./oauth.md)                                                         | **Start here** for third-party OAuth (`/connect/oauth`, redirect URI, params)                               |
 | [generated-ui-oauth.md](./generated-ui-oauth.md)                               | Edge case: OAuth in a hosted package app (`open_generated_ui` on a saved package)                           |
 | [connect-secret.md](./connect-secret.md)                                       | `/connect/secret` URL parameters and policies                                                               |

docs/guides/package-service-pattern.md

@@ -0,0 +1,193 @@
+# Package service pattern
+
+Use this guide when you want a **native Kody package** to own a long-lived
+runtime instead of relying on a separate external service.
+
+This guide assumes:
+
+- the package runtime already supports `package.json#kody.services`
+- the package will likely also expose a package app for operator UI
+- protocol credentials and downstream delivery details are handled separately
+
+## Recommended package shape
+
+Prefer one saved package with:
+
+- `package.json#kody.app.entry` for setup UI, dashboards, and callback endpoints
+- `package.json#kody.services.realtime-supervisor.entry` for the long-lived
+  runtime
+- package exports for reusable helpers and formatting logic
+
+Example manifest shape:
+
+```json
+{
+  "name": "@scope/realtime-supervisor",
+  "exports": {
+    ".": "./src/index.ts",
+    "./format-event": "./src/format-event.ts"
+  },
+  "kody": {
+    "id": "realtime-supervisor",
+    "description": "Native long-lived service package",
+    "app": {
+      "entry": "./src/app.ts"
+    },
+    "services": {
+      "realtime-supervisor": {
+        "entry": "./src/services/realtime-supervisor.ts",
+        "autoStart": true,
+        "timeoutMs": 300000
+      }
+    }
+  }
+}
+```
+
+## Runtime model
+
+Package services run as **background-managed** service instances:
+
+- `service_start` returns immediately with a running state
+- the service Durable Object keeps lifecycle state such as `status`,
+  `active_run_id`, `stop_requested`, and `next_alarm_at`
+- the service module runs with:
+  - `packageContext`
+  - `serviceContext`
+  - service-owned writable `storage`
+  - a `service` helper from `kody:runtime`
+
+Import shape inside a service module:
+
+```ts
+import { service, serviceContext, storage } from 'kody:runtime'
+```
+
+The `service` helper exposes:
+
+- `await service.getStatus()`
+- `await service.shouldStop()`
+- `await service.setAlarm(runAt)`
+- `await service.clearAlarm()`
+
+## Recommended service loop
+
+Treat the service entry as a **runtime supervisor**, not just a one-shot job.
+
+Recommended loop:
+
+1. Load persisted session state from `storage`
+   - configuration references
+   - last checkpoint / cursor / offset
+   - reconnect endpoint or transport metadata
+   - topology metadata if applicable
+2. Open the outbound connection or initialize the runtime session
+3. Authenticate, subscribe, or resume
+4. Enter a loop that:
+   - reads remote events or messages
+   - persists resumable state before acting on them
+   - publishes normalized events to the package app or package exports
+   - periodically checks `await service.shouldStop()`
+5. On clean shutdown:
+   - close the connection
+   - clear alarms when no reconnect is desired
+6. On transient disconnect:
+   - persist the latest resumable state
+   - schedule reconnect with `await service.setAlarm(...)`
+   - exit the current run
+
+Pseudo-code shape:
+
+```ts
+import { service, storage } from 'kody:runtime'
+
+async function openSocket(session: unknown) {
+  void session
+  return await new Promise<WebSocket>((resolve, reject) => {
+    const socket = new WebSocket('wss://example.com/stream')
+    socket.addEventListener('open', () => resolve(socket), { once: true })
+    socket.addEventListener('error', () => reject(new Error('Failed to open stream')), {
+      once: true,
+    })
+  })
+}
+
+export default async function run() {
+  const session = (await storage.get('session-state')) ?? null
+  const socket = await openSocket(session)
+
+  try {
+    // Authenticate, subscribe, or resume here.
+
+    while (
+      socket.readyState !== WebSocket.CLOSING &&
+      socket.readyState !== WebSocket.CLOSED
+    ) {
+      if (await service.shouldStop()) {
+        socket.close(1000, 'service stop requested')
+        await service.clearAlarm()
+        return { stopped: true }
+      }
+
+      const event = await readNextEvent(socket)
+      await persistRuntimeState(storage, event)
+      await handleRuntimeEvent(event)
+    }
+  } catch (error) {
+    await persistFailure(storage, error)
+    await service.setAlarm(new Date(Date.now() + 5_000))
+    throw error
+  }
+}
+```
+
+## Use the package app as the operator plane
+
+Do not push all operational interaction into the service itself.
+
+Use the package app for:
+
+- health dashboards
+- reconnect / pause / resume controls
+- logs
+- live event inspection
+- setup flows
+
+The package app can call the package service lifecycle surface and consume
+service status through the existing package runtime bridge.
+
+## Prefer bounded reconnect loops over one immortal run
+
+Cloudflare Durable Objects can open outbound WebSockets, but outgoing WebSockets
+do **not** hibernate. Favor a design where the service can:
+
+- reconnect intentionally
+- reschedule itself with alarms
+- persist resumable state early
+- stop cooperatively
+
+Use `timeoutMs` to give the service enough room to run, but do not rely on
+indefinite execution as the only lifecycle mechanism.
+
+## What to persist
+
+At minimum, persist:
+
+- reconnect/session identifiers
+- latest offset / sequence / cursor
+- topology metadata if needed
+- reconnect URL or endpoint metadata
+- last error / last disconnect reason
+
+Persist before any expensive or lossy downstream work so reconnects can resume
+from durable state.
+
+## Downstream delivery
+
+A long-lived package service usually needs a second delivery plane:
+
+- package app realtime sessions for human/operator UIs
+- package exports or jobs for reusable downstream logic
+
+Keep connection ingest, downstream formatting, and UI concerns separate so the
+service can stay focused on connection lifecycle and event normalization.

docs/use/execute.md

@@ -21,6 +21,18 @@ and export a default function. These helpers are runtime exports:
   active execute or job params instead of receiving them as a function argument
 - use **`import { packageContext } from 'kody:runtime'`** inside saved package
   code when you need package metadata; it is **`null`** for ad hoc execute calls
+- use **`import { serviceContext } from 'kody:runtime'`** inside package service
+  code when you need the current service identity; it is **`null`** outside
+  package service runs
+- package service runs also expose **`service`** through **`kody:runtime`** for
+  background lifecycle control:
+  - `await service.getStatus()` — read the current package-service status
+  - `await service.shouldStop()` — cooperatively observe stop requests
+  - `await service.setAlarm(runAt)` — schedule the next service wake-up
+  - `await service.clearAlarm()` — clear a pending service wake-up
+- package service runs may also declare **`kody.services.<name>.timeoutMs`** in
+  `package.json` when they need a longer executor budget than the default
+  package-service timeout
 - use **`import thing from 'kody:@scope/my-package/export-name'`** to reuse a
   saved package export by full package name
 
@@ -52,6 +64,8 @@ module-oriented runtime model:
 - package-specific metadata lives under `package.json#kody`
 - package jobs are schedules declared under `package.json#kody.jobs`
 - package apps are optional UI surfaces declared under `package.json#kody.app`
+- package services are optional long-lived runtimes declared under
+  `package.json#kody.services`
 - non-package jobs can also be scheduled directly with
   **`codemode.job_schedule(...)`** without creating a saved package
 - **`codemode.job_schedule_once(...)`** remains available as a convenience alias
@@ -94,6 +108,11 @@ package-owned jobs and non-package jobs created with `job_schedule` or
 `job_schedule_once`.
 
 - bound storage is execute-, app-, package-, or job-owned durable state
+- package service runs also get writable service-owned durable state scoped to
+  the declared service name
+- package service runs are background-managed by the service Durable Object, so
+  `service_start` returns immediately with a running state while the service code
+  continues in the background until it finishes, errors, or cooperatively stops
 - import **`storage`** from **`kody:runtime`**
 - use **`storage.get(...)`**, **`storage.set(...)`**, **`storage.list(...)`**,
   and **`storage.sql(query, params?)`**

docs/use/packages.md

@@ -13,6 +13,7 @@ Think in terms of:
 - packages
 - package exports
 - package apps
+- package services
 - package-owned jobs
 
 Packages are the saved-entity unit across search, execute, repo editing, and UI
@@ -30,6 +31,7 @@ Important fields:
 - `kody.description` — package description for search/detail
 - `kody.tags` — package tags
 - `kody.app` — optional hosted package app config
+- `kody.services` — optional package-owned service runtimes
 - `kody.jobs` — optional package-owned schedules
 
 `package.json` is the manifest.
@@ -70,6 +72,34 @@ Treat package apps like Worker-style modules:
 - internal Durable Objects or facets are implementation details, not the public
   authoring contract
 
+## Package services
+
+A package service is optional.
+
+When `package.json#kody.services` is present, the package can declare one or
+more named service entrypoints that Kody runs with package-owned storage and
+package caller context.
+
+Use the package service model when the package needs:
+
+- long-lived or repeated background work
+- package-owned daemon-like logic
+- package state that is separate from browser sessions
+- a service that should publish updates into a package app
+
+Treat package services like package-owned runtime modules:
+
+- service code lives in the package repo
+- each service entry module is declared by `kody.services.<name>.entry`
+- services may optionally declare `kody.services.<name>.timeoutMs` to raise the
+  executor timeout for long-lived or connector-style runs
+- service lifecycle is controlled through the `services` capability domain
+- service starts return immediately and the service keeps running in the
+  background until it finishes or is stopped
+- service code can inspect its own lifecycle through `serviceContext` and the
+  `service` helper exposed by `kody:runtime`
+- services share the same saved package identity as package apps and jobs
+
 ## Package-owned jobs
 
 Packages can own jobs, and Kody also supports schedules that are not owned

packages/worker/src/env-schema.ts

@@ -208,6 +208,18 @@ export const EnvSchema = object({
 			context.path,
 		)
 	}),
+	PACKAGE_SERVICE_INSTANCE: createSchema<
+		unknown,
+		DurableObjectNamespace
+	>((value, context) => {
+		if (value) {
+			return { value: value as DurableObjectNamespace }
+		}
+		return fail(
+			'Missing PACKAGE_SERVICE_INSTANCE binding for package service runtimes.',
+			context.path,
+		)
+	}),
 	APP_BASE_URL: optionalUrlStringSchema,
 	APP_COMMIT_SHA: optionalCommitShaSchema,
 	CLOUDFLARE_EMAIL_FROM: optionalNonEmptyStringSchema,

packages/worker/src/index.ts

@@ -9,6 +9,7 @@ import { StorageRunner } from './storage-runner.ts'
 import { AgentTurnRunner } from './agent-turn/runner-do.ts'
 import { RepoSession } from './repo/repo-session-do.ts'
 import { PackageRealtimeSession } from '#worker/package-runtime/realtime-session.ts'
+import { PackageServiceInstance } from '#worker/package-runtime/package-service.ts'
 import { chatAgentBasePath } from '@kody-internal/shared/chat-routes.ts'
 import { getWorkerSentryOptions } from './sentry-options.ts'
 import { handleRequest } from '#app/handler.ts'
@@ -54,6 +55,7 @@ export {
 	MCP,
 	JobManager,
 	PackageRealtimeSession,
+	PackageServiceInstance,
 	PackageAppRuntimeBridge,
 	StorageRunner,
 }

packages/worker/src/jobs/service.ts

@@ -185,6 +185,7 @@ async function persistPublishedJobBundleArtifact(input: {
 		modules: bundle.modules,
 		dependencies: bundle.dependencies,
 		packageContext: input.packageContext ?? null,
+		serviceContext: null,
 		createdAt: new Date().toISOString(),
 	}
 	await persistPublishedBundleArtifact({

packages/worker/src/mcp/capabilities/builtin-domains.ts

@@ -5,6 +5,7 @@ import { metaDomain } from './meta/domain.ts'
 import { packagesDomain } from './packages/domain.ts'
 import { repoDomain } from './repo/domain.ts'
 import { secretsDomain } from './secrets/domain.ts'
+import { servicesDomain } from './services/domain.ts'
 import { storageDomain } from './storage/domain.ts'
 import { valuesDomain } from './values/domain.ts'
 
@@ -24,6 +25,7 @@ export const builtinDomains = [
 	packagesDomain,
 	repoDomain,
 	secretsDomain,
+	servicesDomain,
 	storageDomain,
 	valuesDomain,
 ] as const

packages/worker/src/mcp/capabilities/coding/kody-official-guide.node.test.ts

@@ -32,6 +32,11 @@ test('kody_official_guide returns markdown when fetch succeeds', async () => {
 	}
 })
 
+test('kody_official_guide exposes the package service pattern guide', () => {
+	const url = buildKodyOfficialGuideUrlForTest('package_service_pattern')
+	expect(url).toMatch(/\/package-service-pattern\.md$/)
+})
+
 test('kody_official_guide surfaces fetch failures', async () => {
 	const originalFetch = globalThis.fetch
 	try {