feat(harness-sdk): the kilo harness SDK

.github/workflows/ci.yml

@@ -26,6 +26,10 @@ jobs:
       # on a transient GitHub API failure (it sets no outputs when it fails).
       kilocode_backend: ${{ steps.filter.outputs.kilocode_backend || steps.filter_retry.outputs.kilocode_backend }}
       cloud_agent_next: ${{ steps.filter.outputs.cloud_agent_next || steps.filter_retry.outputs.cloud_agent_next }}
+      # harness-sdk is detected by its own step pair below: the shared pair's
+      # filter set is pinned byte-for-byte by scripts/changes-filter-retry.test.mjs
+      # and must stay exactly as origin/main wrote it.
+      harness_sdk: ${{ steps.filter_harness.outputs.harness_sdk || steps.filter_harness_retry.outputs.harness_sdk }}
       workspace_matrix: ${{ steps.workspaces.outputs.matrix }}
     steps:
       - uses: useblacksmith/checkout@41cdeedae8edb2e684ba22896a5fd2a3cb85db6b # v1
@@ -115,6 +119,25 @@ jobs:
               - 'pnpm-lock.yaml'
             cloud_agent_next:
               - 'services/cloud-agent-next/**'
+      # The harness-sdk filter runs as its own attempt/retry pair: it cannot
+      # drift from the shared pair above, whose filter set is pinned by
+      # scripts/changes-filter-retry.test.mjs.
+      - name: Detect harness-sdk changes
+        id: filter_harness
+        continue-on-error: true
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          filters: |
+            harness_sdk:
+              - 'packages/harness-sdk/**'
+      - name: Detect harness-sdk changes (retry)
+        id: filter_harness_retry
+        if: steps.filter_harness.outcome == 'failure'
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          filters: |
+            harness_sdk:
+              - 'packages/harness-sdk/**'
       - name: Detect changed workspaces with tests
         id: workspaces
         run: |
@@ -394,6 +417,35 @@ jobs:
       - name: Run cloud-agent-next tests
         run: pnpm --filter cloud-agent-next test:all
 
+  harness-sdk:
+    needs: [changes, typecheck, lint, format-check, drizzle-check]
+    if: needs.changes.outputs.harness_sdk == 'true'
+    runs-on: ${{ vars.RUNNER_DEFAULT_LABEL || 'ubuntu-latest' }}
+    timeout-minutes: 15
+    steps:
+      - uses: useblacksmith/checkout@41cdeedae8edb2e684ba22896a5fd2a3cb85db6b # v1
+        with:
+          lfs: true
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+
+      - name: Setup Node
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Everything but the timing gate, which needs a machine nobody else is
+      # using. The migration check is why this job exists: the store's SQL is
+      # inlined into the bundle, and nothing at run time notices when the
+      # inlined copy stops matching the schema.
+      - name: Check harness-sdk
+        run: pnpm --filter @kilocode/harness-sdk check:ci
+
   workspace-tests:
     needs: [changes, typecheck, lint, format-check, drizzle-check]
     if: ${{ needs.changes.outputs.workspace_matrix != '[]' }}
@@ -431,7 +483,17 @@ jobs:
   notify-main-failure:
     if: ${{ always() && github.ref == 'refs/heads/main' && contains(join(needs.*.result, ','), 'failure') }}
     needs:
-      [typecheck, lint, format-check, drizzle-check, test, build, cloud-agent-next, workspace-tests]
+      [
+        typecheck,
+        lint,
+        format-check,
+        drizzle-check,
+        test,
+        build,
+        cloud-agent-next,
+        harness-sdk,
+        workspace-tests,
+      ]
     runs-on: ${{ vars.RUNNER_DEFAULT_LABEL || 'ubuntu-latest' }}
     timeout-minutes: 5
     steps:

.gitignore

@@ -14,6 +14,7 @@ node_modules/
 /out/
 /build
 packages/trpc/dist/
+packages/harness-sdk/dist/
 **/wrapper/dist/
 *.tsbuildinfo
 next-env.d.ts

apps/web/AGENTS.md

@@ -21,3 +21,13 @@ When `subscriptionSchedules.create()` uses `from_subscription`, do not set `meta
 ## Database-Backed APIs
 
 For database-backed API work, consult `packages/db/AGENTS.md` for shared PostgreSQL data-contract requirements.
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

packages/harness-sdk/.gitignore

@@ -0,0 +1,3 @@
+# `e2e/readme-check.ts` is typechecked, never run — but it names a database at
+# module scope, so running it by hand leaves this behind.
+sessions.db

packages/harness-sdk/.oxlintrc.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "../../node_modules/oxlint/configuration_schema.json",
+  "plugins": ["oxc", "typescript", "unicorn", "import", "promise", "node", "vitest"],
+  "options": {
+    "typeAware": true
+  },
+  "categories": {
+    "correctness": "error",
+    "suspicious": "error",
+    "pedantic": "error",
+    "perf": "error",
+    "style": "error"
+  },
+  "env": {
+    "builtin": true,
+    "node": true,
+    "es2024": true
+  },
+  "rules": {
+    "no-console": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/consistent-type-imports": "error",
+    "typescript/explicit-module-boundary-types": "error",
+    "typescript/no-non-null-assertion": "error",
+    "typescript/no-unnecessary-type-assertion": "error",
+    "typescript/no-floating-promises": "error",
+    "typescript/no-misused-promises": "error",
+    "unicorn/filename-case": [
+      "error",
+      {
+        "case": "kebabCase"
+      }
+    ],
+    "import/no-named-export": "off",
+    "import/no-default-export": "error",
+    "no-ternary": "off",
+    "new-cap": [
+      "error",
+      {
+        "capIsNewExceptions": ["Tag", "GenericTag", "TaggedError", "TaggedClass"]
+      }
+    ],
+    "sort-imports": "off",
+    "vitest/no-importing-vitest-globals": "off",
+    "vitest/prefer-to-be-truthy": "off",
+    "id-length": "off",
+    "import/consistent-type-specifier-style": "off",
+    "max-classes-per-file": "off",
+    "sort-keys": "off",
+    "no-magic-numbers": "off",
+    "promise/prefer-await-to-then": "off",
+    "require-await": "off",
+    "typescript/require-await": "off",
+    "unicorn/no-array-callback-reference": "off",
+    "import/prefer-default-export": "off",
+    "func-names": "off",
+    "unicorn/no-array-method-this-argument": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.ts", "**/*-fixture.ts"],
+      "rules": {
+        "typescript/explicit-module-boundary-types": "off",
+        "import/max-dependencies": "off"
+      }
+    },
+    {
+      "files": ["src/index.test.ts"],
+      "rules": {
+        "import/no-namespace": "off"
+      }
+    },
+    {
+      "files": ["src/index.ts"],
+      "rules": {
+        "unicorn/require-module-specifiers": "off"
+      }
+    },
+    {
+      "files": [
+        "src/plugins/store/node.ts",
+        "src/plugins/store/*.test.ts",
+        "src/plugins/conformance.test.ts",
+        "src/core/resume-fixture.ts",
+        "src/core/image.test.ts"
+      ],
+      "rules": {
+        "import/no-nodejs-modules": "off",
+        "unicorn/no-null": "off"
+      }
+    }
+  ]
+}