Switch to Pi

.env.example

@@ -1,9 +1,8 @@
-# required
-PROJECT_DIR=/abs/path/to/your/app
+# required — workspace root holding every project dir plus .pi-global/.
+# Mount as a Docker volume for restart-safe projects + registry.
+WORKSPACE_DIR=/abs/path/to/workspace
 
 # optional (with defaults)
-# SESSIONS_DIR=$PROJECT_DIR/data/sessions
-# AGENTS_FILE=.pi/AGENTS.md
 # AGENT_SERVER_HOST=127.0.0.1
 # AGENT_SERVER_PORT=4001
 

.github/workflows/contract.yml

@@ -0,0 +1,83 @@
+#
+# Contract gate for the agent-server OpenAPI surface.
+#
+# Two checks, both aimed at the one risk that matters here: pi (the upstream
+# engine whose types we forward) drifting silently into our published contract.
+#
+#   (1) Freshness  — regenerate the committed contract artifacts
+#                    (eventSchema.generated.json + openapi.json) and fail if the
+#                    working tree changed. Catches "bumped pi / edited a route
+#                    but forgot to regenerate + commit the contract".
+#
+#   (2) Breaking   — diff this PR's openapi.json against the base branch with
+#                    oasdiff and fail on breaking changes. Turns silent drift
+#                    into a reviewed, intentional event.
+#
+# The breaking-change check runs on pull_request because that's the only place
+# it can actually *block* a merge (via branch protection). The freshness check
+# also runs on push to main as a trunk safety net for direct pushes.
+#
+name: contract
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: contract-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # (1) The committed contract must be a faithful regeneration of the source.
+  freshness:
+    name: Contract artifacts are fresh
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Regenerate contract artifacts
+        # Order matters: the typia-generated event schema must be refreshed
+        # before the OpenAPI dump, which merges it in.
+        run: |
+          npm run gen:event-schema
+          npm run openapi
+
+      - name: Verify committed artifacts are up to date
+        run: |
+          if ! git diff --exit-code -- openapi.json src/contract/eventSchema.generated.json; then
+            echo "::error::Contract artifacts are stale. Run 'npm run gen:event-schema && npm run openapi' and commit the result."
+            exit 1
+          fi
+
+  # (2) No breaking changes may reach main without review.
+  # breaking:
+  #   name: No breaking contract changes
+  #   # Only meaningful on PRs, where it can gate the merge against the base branch.
+  #   if: github.event_name == 'pull_request'
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+
+  #     # oasdiff reads the base spec straight from git; fetch the base branch.
+  #     - run: git fetch --depth=1 origin ${{ github.base_ref }}
+
+  #     - name: Detect breaking changes (oasdiff)
+  #       uses: oasdiff/oasdiff-action/breaking@v0.0.56
+  #       with:
+  #         base: origin/${{ github.base_ref }}:openapi.json
+  #         revision: HEAD:openapi.json
+  #         # Fail only on definite breaking changes (ERR). Intentional breaks can
+  #         # be acknowledged via a `.oasdiff.yaml` err-ignore entry + a contract
+  #         # version bump in src/openapi.ts.
+  #         fail-on: ERR

.gitignore

@@ -1,6 +1,18 @@
 node_modules/
 dist/
+.gen/
 .env
 .env.local
 *.log
 .DS_Store
+
+# IDE
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+
+# Docs
+docs/misc/
+
+# Agents
+.pi/todos/

.husky/pre-commit

@@ -0,0 +1,46 @@
+# agent-server pre-commit: shared formatting + a typed, in-sync contract.
+#
+# Always (fast, always relevant):
+#   1. Biome format + lint (pi's conventions: tab/width-3, lineWidth 120).
+#      `--write` applies safe fixes; `--error-on-warnings` blocks on the rest.
+#   2. Typecheck (tsc --noEmit) — fail fast on type errors.
+#
+# Only when the contract could have changed (a staged `src/` file or a
+# dependency bump that might move pi's types):
+#   3. Regenerate the typia SSE event schema, then the merged OpenAPI dump,
+#      and re-stage the artifacts. On unrelated commits this is skipped — the
+#      CI freshness gate (.github/workflows/contract.yml) remains the
+#      authoritative net for any deviation that slips through.
+#
+# Finally, re-stage everything that was already staged (Biome may have
+# reformatted it). `set -e` aborts the commit on the first failing step.
+set -e
+
+# Snapshot what the user staged before Biome rewrites files in place.
+STAGED_FILES=$(git diff --cached --name-only)
+
+npm run check
+npm run typecheck
+
+# Does this commit touch anything that could change the published contract?
+contract_touched=0
+for file in $STAGED_FILES; do
+	case "$file" in
+		src/*.ts | src/**/*.ts | package.json | package-lock.json)
+			contract_touched=1
+			break
+			;;
+	esac
+done
+
+if [ "$contract_touched" -eq 1 ]; then
+	echo "Contract-relevant change staged — regenerating openapi.json + event schema..."
+	npm run gen:event-schema
+	npm run openapi
+	git add openapi.json src/contract/eventSchema.generated.json
+fi
+
+# Re-stage the previously-staged files (now possibly reformatted by Biome).
+for file in $STAGED_FILES; do
+	[ -f "$file" ] && git add -- "$file"
+done

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+	"recommendations": ["biomejs.biome"]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+	"window.title": "Agent-Server",
+
+	// Biome formats with real tab characters; these control how wide a tab
+	// renders so the editor matches biome.json's indentWidth (3).
+	"editor.tabSize": 4,
+	"editor.detectIndentation": false,
+
+	// Use Biome (see biome.json) as the single formatter on save so the editor
+	// matches the pre-commit hook (`biome check --write`) and avoids churn.
+	"editor.formatOnSave": true,
+	"editor.defaultFormatter": "biomejs.biome",
+	"[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
+	"[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
+	"[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
+	"[javascriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
+	"[json]": { "editor.defaultFormatter": "biomejs.biome" },
+	"[jsonc]": { "editor.defaultFormatter": "biomejs.biome" },
+	"editor.codeActionsOnSave": {
+		"source.organizeImports.biome": "explicit",
+		"quickfix.biome": "explicit"
+	}
+}