feat(agent): add deterministic base-agent orchestrator

CHANGELOG.md

@@ -49,6 +49,10 @@
 
 - Refresh Gittensor-aligned homepage
 
+- Add deterministic base-agent orchestrator
+
+- Add optional workers ai summaries
+
 
 
 ### Fixes

README.md

@@ -1,10 +1,10 @@
 # Gittensory
 
-Gittensory is a backend-only intelligence layer for Gittensor registered repositories.
+Gittensory is the deterministic base-agent layer for Gittensor OSS contribution mining.
 
-It helps miners and contributors make better decisions before they open work, and it helps maintainers review Gittensor-driven PRs with less noise. The product is the signal: role-aware contributor context, official Gittensor stats, local MCP preflight, queue health, collision risk, reviewability, and repo configuration quality.
+It helps miners and contributors make better decisions before they open work, and it helps maintainers review Gittensor-driven PRs with less noise. The product is the signal: role-aware contributor context, official Gittensor stats, local MCP preflight, queue health, collision risk, reviewability, repo configuration quality, and copilot-only next-action planning.
 
-Gittensory is not a Gittensor frontend, not a public leaderboard, and not an auto-close or auto-merge bot.
+Gittensory is not a Gittensor frontend, not a public leaderboard, and not an autonomous PR bot. V1 ranks, explains, preflights, and drafts public-safe packets; it does not edit code, open PRs, post comments, close, merge, or label without an explicit user or maintainer-triggered flow.
 
 ## What It Does
 
@@ -14,14 +14,21 @@ Gittensory is not a Gittensor frontend, not a public leaderboard, and not an aut
 - Generates public-safe PR packets that help contributors write cleaner submissions.
 - Gives maintainers private PR reviewability packets through the API/MCP, while the GitHub App stays public-safe.
 - Tracks repository intelligence: lane correctness, registry changes, queue health, label/config quality, collisions, bounties, and sync fidelity.
+- Runs deterministic base-agent plans that rank next actions, explain blockers, prepare PR packets, and record auditable run/action snapshots.
 
 ## Surfaces
 
 - Worker API: Cloudflare Workers + Hono + D1 + Queues.
-- MCP package: `@jsonbored/gittensory-mcp`, a local stdio wrapper for coding agents.
-- GitHub App: quiet PR inspection, public-safe sticky comments, and maintainer-configured labels only for officially confirmed Gittensor miners.
+- MCP package: `@jsonbored/gittensory-mcp`, a local stdio wrapper for coding agents and the first-class base-agent surface.
+- GitHub App: quiet PR inspection, public-safe sticky comments, maintainer-configured labels, and explicit `@gittensory` commands on installed repos.
 - Docs site: VitePress under `site/`, deployed at `https://gittensory.aethereal.dev/`.
 
+## AI Posture
+
+Gittensory's core decisions are deterministic. MCP users normally bring their own AI harness through Codex, Claude, Cursor, or another MCP client, while Gittensory supplies the structured Gittensor context those agents need.
+
+Cloudflare Workers AI is optional and disabled by default. When enabled, it can rewrite compact deterministic signal bundles into clearer prose, but it never receives source contents and all public output still passes through Gittensory's sanitizer.
+
 ## MCP Install
 
 Public npm:
@@ -33,6 +40,15 @@ gittensory-mcp doctor
 gittensory-mcp --stdio
 ```
 
+Base-agent CLI commands:
+
+```sh
+gittensory-mcp agent plan --login jsonbored --json
+gittensory-mcp agent packet --login jsonbored --json
+gittensory-mcp agent status <run-id> --json
+gittensory-mcp agent explain <run-id> --json
+```
+
 Local checkout:
 
 ```sh
@@ -91,6 +107,8 @@ wrangler secret put INTERNAL_JOB_TOKEN
 
 `GITHUB_PUBLIC_TOKEN` is a server-side token used to raise public GitHub API rate limits during registered-repo backfill. It is not a contributor token.
 
+The production API origin is `https://api.gittensory.aethereal.dev`. The `workers.dev` deployment URL is treated as an internal fallback, not the public integration target.
+
 ## Canonical API
 
 Protected endpoints use `Authorization: Bearer <GITTENSORY_API_TOKEN>` or a Gittensory OAuth session where supported.
@@ -115,6 +133,12 @@ Protected endpoints use `Authorization: Bearer <GITTENSORY_API_TOKEN>` or a Gitt
 - `GET /v1/contributors/:login/profile`
 - `GET /v1/contributors/:login/decision-pack`
 - `GET /v1/contributors/:login/repos/:owner/:repo/decision`
+- `POST /v1/agent/runs`
+- `GET /v1/agent/runs/:id`
+- `POST /v1/agent/plan-next-work`
+- `POST /v1/agent/preflight-branch`
+- `POST /v1/agent/prepare-pr-packet`
+- `POST /v1/agent/explain-blockers`
 - `POST /v1/preflight/pr`
 - `POST /v1/preflight/local-diff`
 - `POST /v1/local/branch-analysis`
@@ -141,11 +165,12 @@ Required events:
 
 - Pull request
 - Issues
+- Issue comment
 - Repository
 
 If GitHub shows `Installation target`, select it. Gittensory should not block install health on event names that GitHub does not show in the app UI.
 
-Default GitHub App behavior is low-noise: non-miner, bot, and maintainer-associated PR authors produce no public output. Confirmed Gittensor miners get one sticky public-safe PR comment and the configured label, defaulting to `gittensor`. Private reviewability, scoring, wallet, hotkey, and reward/risk context never appears in public GitHub comments or checks.
+Default GitHub App behavior is low-noise: non-miner, bot, and maintainer-associated PR authors produce no public output. Confirmed Gittensor miners get one sticky public-safe PR comment and the configured label, defaulting to `gittensor`. Maintainers and authorized PR authors can explicitly invoke public-safe `@gittensory` commands. Private reviewability, scoring, wallet, hotkey, and reward/risk context never appears in public GitHub comments or checks.
 
 ## Docs
 

migrations/0010_agent_orchestrator.sql

@@ -0,0 +1,55 @@
+CREATE TABLE agent_runs (
+  id TEXT PRIMARY KEY NOT NULL,
+  objective TEXT NOT NULL,
+  actor_login TEXT NOT NULL,
+  surface TEXT NOT NULL,
+  mode TEXT NOT NULL DEFAULT 'copilot',
+  status TEXT NOT NULL DEFAULT 'queued',
+  data_quality_status TEXT NOT NULL DEFAULT 'unknown',
+  error_summary TEXT,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX agent_runs_actor_updated_idx ON agent_runs (actor_login, updated_at);
+CREATE INDEX agent_runs_status_updated_idx ON agent_runs (status, updated_at);
+CREATE INDEX agent_runs_surface_updated_idx ON agent_runs (surface, updated_at);
+
+CREATE TABLE agent_actions (
+  id TEXT PRIMARY KEY NOT NULL,
+  run_id TEXT NOT NULL,
+  action_type TEXT NOT NULL,
+  target_repo_full_name TEXT,
+  target_pull_number INTEGER,
+  target_issue_number INTEGER,
+  status TEXT NOT NULL,
+  recommendation TEXT NOT NULL,
+  why_json TEXT NOT NULL DEFAULT '[]',
+  scoreability_impact TEXT,
+  risk_impact TEXT,
+  maintainer_impact TEXT,
+  blocked_by_json TEXT NOT NULL DEFAULT '[]',
+  rerun_when TEXT,
+  public_safe_summary TEXT NOT NULL,
+  approval_required INTEGER NOT NULL DEFAULT 1,
+  safety_class TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX agent_actions_run_action_idx ON agent_actions (run_id, action_type);
+CREATE INDEX agent_actions_target_repo_idx ON agent_actions (target_repo_full_name, created_at);
+
+CREATE TABLE agent_context_snapshots (
+  id TEXT PRIMARY KEY NOT NULL,
+  run_id TEXT NOT NULL,
+  decision_pack_version TEXT,
+  repo_signal_snapshot_ids_json TEXT NOT NULL DEFAULT '[]',
+  scoring_model_id TEXT,
+  freshness_warnings_json TEXT NOT NULL DEFAULT '[]',
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX agent_context_snapshots_run_created_idx ON agent_context_snapshots (run_id, created_at);

migrations/0011_workers_ai_usage.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS ai_usage_events (
+  id TEXT PRIMARY KEY,
+  feature TEXT NOT NULL,
+  actor TEXT,
+  route TEXT,
+  model TEXT NOT NULL,
+  status TEXT NOT NULL,
+  estimated_neurons INTEGER NOT NULL DEFAULT 0,
+  detail TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS ai_usage_events_feature_created_idx
+  ON ai_usage_events(feature, created_at);
+
+CREATE INDEX IF NOT EXISTS ai_usage_events_actor_created_idx
+  ON ai_usage_events(actor, created_at);

package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "type": "module",
-  "description": "GitHub-native advisory backend for Gittensor registered repositories.",
+  "description": "Deterministic base-agent backend for Gittensor OSS contribution mining.",
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",

packages/gittensory-mcp/CHANGELOG.md

@@ -3,6 +3,14 @@
 ## Unreleased
 
 
+### Features
+
+- Add deterministic base-agent orchestrator
+
+- Add optional workers ai summaries
+
+
+
 ### Fixes
 
 - Create GitHub releases for MCP tag publishes

packages/gittensory-mcp/README.md

@@ -1,8 +1,8 @@
 # @jsonbored/gittensory-mcp
 
-Local stdio MCP wrapper for Gittensory contributor intelligence.
+Local stdio MCP wrapper for the Gittensory base-agent layer.
 
-It inspects local git metadata and calls the Gittensory API for branch preflight, score blockers, reward/risk reasoning, contributor decision packs, and public-safe PR packets. It does not upload source contents in v1.
+It inspects local git metadata and calls the Gittensory API for branch preflight, score blockers, reward/risk reasoning, contributor decision packs, deterministic next-action planning, and public-safe PR packets. It does not upload source contents in v1.
 
 ## Status
 
@@ -38,6 +38,10 @@ gittensory-mcp init-client --print claude
 gittensory-mcp init-client --print cursor
 gittensory-mcp analyze-branch --login jsonbored --json
 gittensory-mcp preflight --login jsonbored --json
+gittensory-mcp agent plan --login jsonbored --json
+gittensory-mcp agent packet --login jsonbored --json
+gittensory-mcp agent status <run-id> --json
+gittensory-mcp agent explain <run-id> --json
 gittensory-mcp --stdio
 ```
 
@@ -62,6 +66,23 @@ gittensory-mcp login --github-token "$(gh auth token)"
 
 The wrapper stores a Gittensory session token, not a GitHub token.
 
+## Base-Agent Mode
+
+The agent commands are copilot-only. They rank, explain, preflight, and draft public-safe packets, but they do not edit code, open PRs, post comments, close, merge, or label from the local wrapper.
+
+```sh
+gittensory-mcp agent plan --login jsonbored --repo we-promise/sure --json
+gittensory-mcp agent packet --login jsonbored --repo we-promise/sure --base origin/main --json
+```
+
+The same capabilities are exposed to MCP clients as:
+
+- `gittensory_agent_plan_next_work`
+- `gittensory_agent_start_run`
+- `gittensory_agent_get_run`
+- `gittensory_agent_explain_next_action`
+- `gittensory_agent_prepare_pr_packet`
+
 ## Environment
 
 - `GITTENSORY_API_URL`