feat(cloud-agent): add Kilo SDK session facade (#3671)

* feat(cloud-agent): add Kilo SDK session facade

* fix(cloud-agent): make Kilo prompt JSON parsing explicit

* perf(session-ingest): avoid schema allocation while sorting parts

* refactor(cloud-agent): simplify Kilo event proxy

* fix(cloud-agent): complete Kilo facade contracts

* test(cloud-agent): align SDK wake event assertion

Author: eshurakov

.kilo/rules/tools.md

@@ -7,9 +7,11 @@
   - Date handling: date-fns
   - Database: drizzle-orm with pg
 - For React components, ALWAYS use React hooks with @tanstack/react-query for data fetching, caching, and server state management. Do not implement custom data fetching logic when react-query can handle it.
-- The webserver should already be running. Read the dev server port from the `.dev-port` file in the project root (e.g., `cat .dev-port`), then access it via `http://localhost:<port>/`. If `.dev-port` does not exist, start the dev server by running `pnpm dev:start &` in the background, then wait for `.dev-port` to appear before reading the port from it.
-- If you need to log in as a fake user, open http://localhost:<port>/users/sign_in?fakeUser=<fake-email> where <port> is read from `.dev-port` (falling back to 3000) and <fake-email> is constructed from "kilo-", my username (based on homedir), and the time (include seconds) and then '@example.com'. If you need an admin account, the email address must end in @admin.example.com. After logging in, wait for the creating your account spinner to complete before proceeding. The admin panels can be accessed from your profile via the account icon in the top-right corner, which opens a drop-down, allowing access to the admin panel.
-- be sure to add the callbackPath url parameter to go directly to the page after logging in!
+- Before accessing local app or service endpoints, check this worktree's running services with `pnpm dev:status --json`. If local services are already active, reuse that session and its ports; do not start a competing stack.
+- If no local dev services are running for this worktree and the task requires them, start only the minimum required group or named services with `KILO_PORT_OFFSET=auto pnpm dev:start <needed-group-or-services>`. If generated local endpoint configuration is required before startup, first run `KILO_PORT_OFFSET=auto pnpm dev:env <needed-group-or-service>` (or the matching documented selector), then start the same selection with `KILO_PORT_OFFSET=auto`, retaining the selected offset/session.
+- After startup or when reusing services, obtain actual ports from `.dev-port`, `pnpm dev:status --json`, or `dev/logs/manifest.json`; never assume default ports. Access the web app at `http://localhost:<port>/` using its reported port.
+- If you need to log in as a fake user, open `http://localhost:<port>/users/sign_in?fakeUser=<fake-email>&callbackPath=<path>` where `<port>` is the reported web app port and `<fake-email>` is constructed from `"kilo-"`, my username (based on homedir), and the time (include seconds) and then `'@example.com'`. If you need an admin account, the email address must end in `@admin.example.com`. After logging in, wait for the creating your account spinner to complete before proceeding. The admin panels can be accessed from your profile via the account icon in the top-right corner, which opens a drop-down, allowing access to the admin panel.
+- Always set the `callbackPath` URL parameter to go directly to the page after logging in.
 - Dev services status and management:
   - `cat dev/logs/manifest.json` — static snapshot of started services and ports (written on `dev:start`)
   - `pnpm dev:status` — live status of running services with ports

packages/session-ingest-contracts/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@kilocode/session-ingest-contracts",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "lint": "pnpm -w exec oxlint --config .oxlintrc.json packages/session-ingest-contracts/src"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:"
+  }
+}

packages/session-ingest-contracts/src/index.ts

@@ -0,0 +1 @@
+export * from './rpc-contract';