kata-context 0.1.0

package/.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/kata-statusline.js\""
+  }
+}

package/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

package/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Get package info
+        id: package
+        run: |
+          LOCAL_VERSION=$(node -p "require('./package.json').version")
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          echo "local_version=$LOCAL_VERSION" >> $GITHUB_OUTPUT
+          echo "package_name=$PACKAGE_NAME" >> $GITHUB_OUTPUT
+
+          # Get published version (returns empty if not published)
+          PUBLISHED_VERSION=$(npm view "$PACKAGE_NAME" version 2>/dev/null || echo "")
+          echo "published_version=$PUBLISHED_VERSION" >> $GITHUB_OUTPUT
+
+          echo "Local version: $LOCAL_VERSION"
+          echo "Published version: $PUBLISHED_VERSION"
+
+      - name: Check if should publish
+        id: check
+        run: |
+          LOCAL="${{ steps.package.outputs.local_version }}"
+          PUBLISHED="${{ steps.package.outputs.published_version }}"
+
+          if [ -z "$PUBLISHED" ]; then
+            echo "Package not yet published, will publish"
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+          elif [ "$LOCAL" != "$PUBLISHED" ]; then
+            echo "Version changed ($PUBLISHED -> $LOCAL), will publish"
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version unchanged ($LOCAL), skipping publish"
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to npm
+        if: steps.check.outputs.should_publish == 'true'
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        if: steps.check.outputs.should_publish == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.package.outputs.local_version }}
+          name: v${{ steps.package.outputs.local_version }}
+          generate_release_notes: true
+          make_latest: true

package/.planning/PROJECT.md

@@ -0,0 +1,103 @@
+# Kata Context
+
+## What This Is
+
+A standalone context policy engine for AI agents. Manages what goes in and out of the LLM context window — compaction, summarization, retrieval, and budget-aware windowing. Framework-agnostic infrastructure: works with any agent system, or none.
+
+## Core Value
+
+Given messages and a context budget, determine the optimal window to send to the model. Policy, not storage.
+
+## Current Milestone: v0.1.0 Core Setup
+
+**Goal:** Establish project foundation with TypeScript/Vercel scaffolding, linting, and testing infrastructure.
+
+**Target features:**
+- TypeScript project structure for Vercel serverless
+- Linting configuration (ESLint, Prettier)
+- Testing setup (Vitest or similar)
+- Development workflow (scripts, environment)
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+**Core Engine:**
+- [ ] Versioned context storage with full history
+- [ ] Basic compaction policy (configurable aggressiveness)
+- [ ] Budget-aware windowing (fit within token limit)
+- [ ] Context forking for exploration paths
+- [ ] Time-travel (jump to any version)
+
+**API & SDKs:**
+- [ ] Framework-agnostic REST API
+- [ ] Python SDK
+- [ ] TypeScript SDK
+
+**Storage:**
+- [ ] PostgreSQL with pgvector
+
+**Commercial MVP (1.0):**
+- [ ] Hosted API on Vercel (serverless)
+- [ ] Stripe integration for SaaS billing
+- [ ] Multi-tenancy and access control
+
+**Later:**
+- [ ] Summarization with structured schemas
+- [ ] Semantic retrieval for offloaded context (RAG)
+- [ ] Advanced policies (custom rules, per-context configuration)
+- [ ] Analytics and observability
+
+### Out of Scope
+
+- **Full agent framework** — We're infrastructure (Postgres), not framework (Rails). Use with any agent system.
+- **Tool execution/sandboxing** — Orthogonal concern. Use whatever tool layer you want.
+- **Agent orchestration** — Kata Orchestrator handles this. We're the context layer beneath it.
+- **Opinionated agent patterns** — No opinion on how you build agents.
+- **Letta fork/rebrand** — Fresh codebase. Study Letta for learnings, don't import code.
+
+## Context
+
+**Kata Ecosystem:**
+Kata Context is one layer in a vertically integrated stack. Kata Orchestrator is the first customer — currently uses markdown files in `.planning/` for state persistence. Works but is brittle (manual edits break workflows, parsing markdown is fragile). Kata Context replaces this with proper context management.
+
+**Why vertical integration:**
+1. Real requirements — not guessing what developers need. We are the developer.
+2. Proof of concept built-in — production multi-agent system running on Kata Context.
+3. Forces good design — if the API is awkward for Kata, it'll be awkward for everyone.
+
+**Prior Art:**
+- Letta — Full agent framework with bundled memory. Learning source for context window calculation, summarization approaches. Not forking — context layer is coupled to their agent model.
+- mem0, Zep — Similar space, but more opinionated. We're lower-level infrastructure.
+
+**Competitive Positioning:**
+The context layer you'd build yourself, but shouldn't have to. Infrastructure, not framework. Works with everything.
+
+## Constraints
+
+- **Tech stack**: Vercel ecosystem (serverless functions, Postgres via Neon with pgvector), TypeScript for server
+- **SDKs**: Python and TypeScript required — these are what developers actually use
+- **First customer**: Kata Orchestrator — API must support its workflows
+- **Solo developer**: One person building, so scope must stay tight
+- **Open source**: Public repo from day one, Apache 2.0 for core and SDKs
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+| -------- | --------- | ------- |
+| Standalone layer, not framework | Larger market, cleaner differentiation, smaller surface area | — Pending |
+| Fresh codebase, not Letta fork | Avoid rebrand complexity, build what we need | — Pending |
+| Vercel serverless deployment | Simplicity, TypeScript-native, scales automatically | — Pending |
+| PostgreSQL with pgvector | Battle-tested, embeddings built-in, Vercel Postgres available | — Pending |
+| TypeScript for server | Vercel-native, faster iteration than Rust, good enough perf for MVP | — Pending |
+| Open source from day one | Builds trust, consistency with other Kata projects, no awkward transition | — Pending |
+| Local beta first, then hosted MVP | Validate with self as customer before commercializing | — Pending |
+| Open core business model | Open source core for adoption, monetize hosted service | — Pending |
+| Small milestones (1-3 phases) | Shippable in a day, maintain momentum | — Pending |
+
+---
+*Last updated: 2025-01-29 after initialization*

package/.planning/REQUIREMENTS.md

@@ -0,0 +1,61 @@
+# Requirements
+
+## v0.1.0 Core Setup
+
+### Project Initialization
+
+- [x] **INIT-01**: TypeScript configured with `strict: true` and `NodeNext` module resolution
+- [x] **INIT-02**: pnpm initialized as package manager with lock file
+- [x] **INIT-03**: Package.json includes dev, build, test, lint, and format scripts
+
+### Developer Tooling
+
+- [x] **TOOL-01**: Biome configured for linting and formatting
+- [x] **TOOL-02**: Vitest configured for TypeScript testing
+- [ ] **TOOL-03**: Pre-commit hooks enforce lint and format via Husky + lint-staged
+- [ ] **TOOL-04**: GitHub Actions CI runs lint and test on push/PR
+
+### Vercel Setup
+
+- [ ] **VERCEL-01**: `/api` directory structure for serverless functions
+- [ ] **VERCEL-02**: Health check endpoint at `/api/health.ts` returns status
+- [ ] **VERCEL-03**: Local `vercel build` succeeds without errors
+
+---
+
+## Future Requirements
+
+(Deferred to later milestones)
+
+- Database schema and connection (v0.2.0)
+- TypeScript SDK package (v0.3.0)
+- Python SDK package (v0.3.0)
+- Multi-tenancy and access control (v1.0)
+- Stripe integration (v1.0)
+
+## Out of Scope
+
+- **Docker configuration** — Vercel handles deployment; Docker adds complexity without value
+- **Complex folder structures** — Keep it simple for scaffolding; evolve as needed
+- **Full CD pipeline** — Manual deployment sufficient for v0.1.0; automate later
+- **Database setup** — Separate milestone for storage layer
+
+---
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| INIT-01 | Phase 1 | Complete |
+| INIT-02 | Phase 1 | Complete |
+| INIT-03 | Phase 1 | Complete |
+| TOOL-01 | Phase 1 | Complete |
+| TOOL-02 | Phase 1 | Complete |
+| TOOL-03 | Phase 2 | Pending |
+| TOOL-04 | Phase 2 | Pending |
+| VERCEL-01 | Phase 2 | Pending |
+| VERCEL-02 | Phase 2 | Pending |
+| VERCEL-03 | Phase 2 | Pending |
+
+---
+*Generated: 2026-01-29*

package/.planning/ROADMAP.md

@@ -0,0 +1,59 @@
+# Roadmap
+
+## Overview
+
+| Milestone | Phases | Status |
+|-----------|--------|--------|
+| v0.1.0 Core Setup | 1-2 | In Progress |
+
+---
+
+### v0.1.0 Core Setup (In Progress)
+
+#### Phase 1: Foundation
+
+**Goal**: Establish a working TypeScript development environment with linting, formatting, and testing.
+
+**Dependencies**: None (first phase)
+
+**Requirements**: INIT-01, INIT-02, INIT-03, TOOL-01, TOOL-02
+
+**Plans:** 2 plans
+
+Plans:
+- [x] 01-01-PLAN.md — Initialize pnpm project with dependencies and .gitignore
+- [x] 01-02-PLAN.md — Configure TypeScript, Biome, and Vitest tooling
+
+**Success Criteria** (what must be TRUE when this phase completes):
+1. Developer can run `pnpm install` and get all dependencies installed
+2. Developer can run `pnpm lint` and `pnpm format` with Biome checking TypeScript files
+3. Developer can run `pnpm test` and Vitest executes (even with no tests yet)
+4. Developer can run `pnpm build` and TypeScript compiles with strict mode enabled
+5. TypeScript module resolution uses `NodeNext` for Vercel compatibility
+
+#### Phase 2: Automation and Deployment
+
+**Goal**: Add git hooks, CI pipeline, and Vercel serverless structure with verification.
+
+**Dependencies**: Phase 1 (requires working lint/test commands)
+
+**Requirements**: TOOL-03, TOOL-04, VERCEL-01, VERCEL-02, VERCEL-03
+
+**Success Criteria** (what must be TRUE when this phase completes):
+1. Git commit triggers Husky pre-commit hook that runs lint-staged
+2. Pushing to GitHub triggers Actions workflow that runs lint and test
+3. `/api/health.ts` endpoint exists and returns a status response
+4. `vercel build` succeeds locally without errors
+5. Project structure follows Vercel Functions convention (`/api` directory)
+
+---
+
+## Progress
+
+| Phase | Name | Status | Requirements |
+|-------|------|--------|--------------|
+| 1 | Foundation | Complete | INIT-01, INIT-02, INIT-03, TOOL-01, TOOL-02 |
+| 2 | Automation and Deployment | Pending | TOOL-03, TOOL-04, VERCEL-01, VERCEL-02, VERCEL-03 |
+
+---
+*Generated: 2026-01-29*

package/.planning/STATE.md

@@ -0,0 +1,45 @@
+# State
+
+## Current Position
+
+Phase: 1 of 2 (Foundation)
+Plan: 2 of 2 in phase
+Status: Phase complete
+Last activity: 2026-01-29 - Completed 01-02-PLAN.md
+
+## Progress
+
+```
+v0.1.0 Core Setup
+[#####-----] Phase 1: Foundation (2/2 plans complete)
+[----------] Phase 2: Automation and Deployment (0/? plans)
+```
+
+## Accumulated Context
+
+### Decisions Made
+
+| ID | Decision | Rationale | Phase |
+|----|----------|-----------|-------|
+| esm-module-type | type: module in package.json | NodeNext module resolution requires ESM; Vercel serverless expects ESM | 01-01 |
+| exact-versions | --save-exact for all dependencies | Reproducible builds; avoids surprise breakage from minor updates | 01-01 |
+| license | Apache-2.0 | Matches PROJECT.md open source constraint | 01-01 |
+| biome-2-organize-imports | Use assist.actions.source.organizeImports | Biome 2.x moved organize imports to assist section; old schema key invalid | 01-02 |
+| biome-ignore-claude | Exclude .claude directory with includes pattern | Claude Code hooks directory contains external JS files that fail lint | 01-02 |
+| vitest-pass-no-tests | Enable passWithNoTests option | Clean CI builds when no test files exist yet | 01-02 |
+
+### Blockers
+(None)
+
+### Notes
+- First milestone - establishing project foundation
+- Kata Orchestrator is the first customer
+- Stack: pnpm 10.x, Node.js 24.x, TypeScript 5.9.x, Biome 2.3.x, Vitest 4.x
+- Engine warning on Node 23.6 is expected (project targets Node 24+)
+- Phase 1 Foundation complete: all developer workflow commands functional
+
+## Session Continuity
+
+Last session: 2026-01-29 11:15 UTC
+Stopped at: Completed 01-02-PLAN.md (Phase 1 complete)
+Resume file: .planning/phases/02-automation/02-01-PLAN.md

package/.planning/config.json

@@ -0,0 +1,20 @@
+{
+  "mode": "yolo",
+  "depth": "standard",
+  "parallelization": true,
+  "commit_docs": true,
+  "pr_workflow": true,
+  "model_profile": "quality",
+  "display": {
+    "statusline": true
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true
+  },
+  "github": {
+    "enabled": true,
+    "issueMode": "auto"
+  }
+}

package/.planning/phases/01-foundation/01-01-PLAN.md

@@ -0,0 +1,158 @@
+---
+phase: 01-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - package.json
+  - pnpm-lock.yaml
+  - .gitignore
+autonomous: true
+
+must_haves:
+  truths:
+    - "pnpm install completes without errors"
+    - "package.json exists with type: module and all required scripts"
+    - "pnpm-lock.yaml exists (lockfile generated)"
+  artifacts:
+    - path: "package.json"
+      provides: "Project manifest with scripts and dependencies"
+      contains: "type.*module"
+    - path: "pnpm-lock.yaml"
+      provides: "Dependency lockfile"
+      min_lines: 10
+    - path: ".gitignore"
+      provides: "Git ignore patterns for Node.js project"
+      contains: "node_modules"
+  key_links:
+    - from: "package.json"
+      to: "node_modules"
+      via: "pnpm install"
+      pattern: "devDependencies"
+---
+
+<objective>
+Initialize the pnpm project with package.json, install dev dependencies, and configure .gitignore.
+
+Purpose: Establish the foundation for all other tooling (TypeScript, Biome, Vitest require deps installed first).
+Output: Working pnpm project with all dev dependencies installed.
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/01-foundation/01-RESEARCH.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Initialize pnpm and install dependencies</name>
+  <files>package.json, pnpm-lock.yaml</files>
+  <action>
+    1. Initialize pnpm project: `pnpm init`
+    2. Edit package.json to set:
+       - name: "kata-context"
+       - version: "0.1.0"
+       - type: "module" (CRITICAL for ESM/NodeNext)
+       - engines: { "node": ">=24.0.0" }
+       - scripts:
+         - "dev": "tsc --watch"
+         - "build": "tsc"
+         - "test": "vitest run"
+         - "test:watch": "vitest"
+         - "lint": "biome lint ."
+         - "format": "biome format --write ."
+         - "check": "biome check --write ."
+    3. Install dev dependencies with exact versions:
+       `pnpm add -D --save-exact typescript@5.9.3 @types/node@24.0.0 vitest@4.0.17 @biomejs/biome@2.3.11`
+
+    IMPORTANT: Use --save-exact to pin versions for reproducible builds.
+    IMPORTANT: Must include "type": "module" - NodeNext requires ESM.
+  </action>
+  <verify>
+    - `cat package.json | grep '"type": "module"'` returns match
+    - `cat package.json | grep '"lint"'` returns match
+    - `ls pnpm-lock.yaml` exists
+    - `pnpm install` completes without errors
+  </verify>
+  <done>
+    - package.json has type: "module", all 7 scripts, and 4 devDependencies
+    - pnpm-lock.yaml generated
+    - node_modules populated
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update .gitignore for Node.js project</name>
+  <files>.gitignore</files>
+  <action>
+    Update .gitignore to include standard Node.js patterns:
+
+    ```
+    # Dependencies
+    node_modules/
+
+    # Build output
+    dist/
+
+    # IDE
+    .idea/
+    *.swp
+    *.swo
+
+    # OS
+    .DS_Store
+    Thumbs.db
+
+    # Test coverage
+    coverage/
+
+    # Environment
+    .env
+    .env.local
+    .env.*.local
+
+    # Vercel
+    .vercel
+    ```
+
+    Preserve any existing entries (the file currently has ".secrets" on one line).
+  </action>
+  <verify>`grep "node_modules" .gitignore` returns match</verify>
+  <done>.gitignore includes node_modules, dist, coverage, and .env patterns</done>
+</task>
+
+</tasks>
+
+<verification>
+Run these commands to verify phase completion:
+
+```bash
+# Check package.json structure
+cat package.json | grep -E '"type"|"scripts"|"devDependencies"'
+
+# Verify lockfile exists
+ls -la pnpm-lock.yaml
+
+# Verify deps are installed
+ls node_modules/.bin/tsc node_modules/.bin/vitest node_modules/.bin/biome
+
+# Verify gitignore
+grep "node_modules" .gitignore
+```
+</verification>
+
+<success_criteria>
+1. `pnpm install` runs without errors
+2. package.json has type: "module"
+3. package.json has all 7 required scripts (dev, build, test, test:watch, lint, format, check)
+4. All 4 dev dependencies installed (typescript, @types/node, vitest, @biomejs/biome)
+5. pnpm-lock.yaml exists
+6. .gitignore includes node_modules and dist
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
+</output>

package/.planning/phases/01-foundation/01-01-SUMMARY.md

@@ -0,0 +1,123 @@
+---
+phase: 01-foundation
+plan: 01
+subsystem: build-tooling
+tags: [pnpm, package.json, gitignore, dependencies]
+
+dependency-graph:
+  requires: []
+  provides:
+    - package.json with type: module and scripts
+    - pnpm lockfile
+    - node_modules with dev dependencies
+    - gitignore patterns for Node.js
+  affects:
+    - 01-02-PLAN.md (TypeScript, Biome, Vitest configuration)
+    - 02-01-PLAN.md (git hooks, CI)
+
+tech-stack:
+  added:
+    - typescript@5.9.3
+    - "@types/node@24.0.0"
+    - vitest@4.0.17
+    - "@biomejs/biome@2.3.11"
+  patterns:
+    - ESM with type: module
+    - Exact version pinning with --save-exact
+
+key-files:
+  created:
+    - package.json
+    - pnpm-lock.yaml
+  modified:
+    - .gitignore
+
+decisions:
+  - id: esm-module-type
+    choice: "type: module in package.json"
+    rationale: "NodeNext module resolution requires ESM; Vercel serverless expects ESM"
+  - id: exact-versions
+    choice: "--save-exact for all dependencies"
+    rationale: "Reproducible builds; avoids surprise breakage from minor updates"
+  - id: license
+    choice: "Apache-2.0"
+    rationale: "Matches PROJECT.md open source constraint"
+
+metrics:
+  duration: ~2 minutes
+  completed: 2026-01-29
+---
+
+# Phase 01 Plan 01: Initialize pnpm Project Summary
+
+**One-liner:** pnpm project with ESM, 4 pinned dev deps, 7 scripts, and Node.js gitignore patterns.
+
+## What Was Done
+
+### Task 1: Initialize pnpm and install dependencies
+- Ran `pnpm init` to create base package.json
+- Configured package.json with:
+  - name: kata-context
+  - version: 0.1.0
+  - type: module (critical for NodeNext ESM)
+  - engines: node >= 24.0.0
+  - 7 scripts: dev, build, test, test:watch, lint, format, check
+  - Apache-2.0 license
+- Installed exact versions of dev dependencies:
+  - typescript@5.9.3
+  - @types/node@24.0.0
+  - vitest@4.0.17
+  - @biomejs/biome@2.3.11
+- **Commit:** `ef0e502`
+
+### Task 2: Update .gitignore for Node.js project
+- Preserved existing `.secrets/` entry
+- Added standard Node.js patterns:
+  - node_modules/, dist/, coverage/
+  - IDE patterns (.idea/, *.swp, *.swo)
+  - OS patterns (.DS_Store, Thumbs.db)
+  - Environment patterns (.env, .env.local, .env.*.local)
+  - Vercel patterns (.vercel)
+- **Commit:** `1a22794`
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Verification Results
+
+All verification commands passed:
+- `cat package.json | grep '"type": "module"'` - matched
+- `cat package.json | grep '"lint"'` - matched
+- `ls pnpm-lock.yaml` - exists
+- `pnpm install` - completed successfully (engine warning expected on Node 23.6)
+- `ls node_modules/.bin/{tsc,vitest,biome}` - all present
+- `grep "node_modules" .gitignore` - matched
+
+## Success Criteria Status
+
+| Criterion | Status |
+|-----------|--------|
+| pnpm install runs without errors | PASS |
+| package.json has type: module | PASS |
+| package.json has all 7 required scripts | PASS |
+| All 4 dev dependencies installed | PASS |
+| pnpm-lock.yaml exists | PASS |
+| .gitignore includes node_modules and dist | PASS |
+
+## Next Phase Readiness
+
+Phase 01 Plan 02 can proceed. This plan provides:
+- package.json with scripts ready for TypeScript, Biome, Vitest
+- Dependencies installed and available in node_modules/.bin/
+- .gitignore ready for dist/ output
+
+No blockers or concerns for next plan.
+
+## Artifacts
+
+| Path | Purpose | Lines |
+|------|---------|-------|
+| package.json | Project manifest with scripts and dependencies | 28 |
+| pnpm-lock.yaml | Dependency lockfile | ~1000 |
+| .gitignore | Git ignore patterns for Node.js project | 28 |