agentic-engineering-harness 0.6.5 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": {
@@ -14,12 +14,14 @@
     "policies",
     "schemas",
     "skills",
-    "docs"
+    "docs",
+    "scripts/link-self-bin.mjs"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
-    "prepare": "npm run build",
+    "prepare": "npm run build && node scripts/link-self-bin.mjs",
+    "aeh": "node ./dist/main.js",
     "dev": "tsx src/main.ts",
     "test": "vitest run",
     "test:watch": "vitest",

package/scripts/link-self-bin.mjs

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const binDir = path.join(root, "node_modules", ".bin");
+const entry = path.join(root, "dist", "main.js");
+
+try {
+  await fs.access(entry);
+} catch {
+  throw new Error(`Cannot link AEH self-development bin because ${entry} does not exist. Run npm run build first.`);
+}
+
+await fs.mkdir(binDir, { recursive: true });
+for (const name of ["aeh", "engineering-harness"]) await writeBin(name);
+
+async function writeBin(name) {
+  const sh = path.join(binDir, name);
+  const cmd = `${sh}.cmd`;
+  const ps1 = `${sh}.ps1`;
+  const relative = "../../dist/main.js";
+
+  await fs.rm(sh, { force: true });
+  await fs.writeFile(sh, `#!/bin/sh\nexec node \"$(dirname \"$0\")/${relative}\" \"$@\"\n`);
+  await fs.chmod(sh, 0o755);
+
+  await fs.rm(cmd, { force: true });
+  await fs.writeFile(cmd, `@ECHO OFF\r\nnode \"%~dp0\\..\\..\\dist\\main.js\" %*\r\n`);
+
+  await fs.rm(ps1, { force: true });
+  await fs.writeFile(ps1, `#!/usr/bin/env pwsh\n& node \"$PSScriptRoot/../../dist/main.js\" $args\nexit $LASTEXITCODE\n`);
+}
+
+if (process.env.AEH_SELF_BIN_VERBOSE === "1") console.log(`Linked repo-local AEH bins in ${binDir}`);

package/skills/engineering-workflow/SKILL.md

@@ -57,7 +57,9 @@ Do not wait for model compaction as the normal context lifecycle.
 - >=80%: proactive handoff to a fresh lead;
 - >=90%: mandatory handoff before additional engineering work.
 
-Use Paseo's current status/tool data when it exposes context usage, otherwise use `aeh context guard --agent "$PASEO_AGENT_ID"`. When AEH writes a `.harness/paseo/handoffs/*.json` artifact, use `/paseo-handoff` (preferred) or a fresh `create_agent`, point the new lead at that artifact and stop continuing the workflow in the old lead. Deterministic artifacts, not a prose replay of the whole chat, carry state across the handoff. Detached AEH operations and their top-level worker agents survive lead rotation.
+In a managed lead, prefer the injected `aeh_context_status` tool before broad work and again after completed-turn boundaries. It reads the current Paseo AgentSnapshot and applies AEH's thresholds to the canonical `lastUsage.contextWindowUsedTokens/contextWindowMaxTokens` fields. `NO_USAGE_YET` means the provider has not emitted usage yet; `USAGE_UNAVAILABLE` means those canonical fields are unavailable. Never infer pressure from generic input/output token counters.
+
+Use `aeh context guard --agent "$PASEO_AGENT_ID"` only as the non-interactive/compatibility fallback. When AEH writes a `.harness/paseo/handoffs/*.json` artifact, use `/paseo-handoff` (preferred) or a fresh `create_agent`, point the new lead at that artifact and stop continuing the workflow in the old lead. Deterministic artifacts, not a prose replay of the whole chat, carry state across the handoff. Detached AEH operations and their top-level worker agents survive lead rotation.
 
 ## Intent layer
 
@@ -138,6 +140,8 @@ Use durable operation state for progress rather than narrating terminal silence:
 
 Paseo workspaces used for operation grouping are local orchestration containers and do not imply Git branch/worktree delivery. Delivery workspaces remain a separate isolation decision and take precedence for workers when present.
 
+Paseo lifecycle/provider/context integration decisions are recorded under `.harness/telemetry/paseo.ndjson`; normal telemetry/OTLP receives the same events when enabled. Use these traces to distinguish SDK-native paths, negotiated fallbacks and intentional public-SDK parity gaps rather than inferring behavior from terminal output.
+
 ## Quality convergence and recovery
 
 After a sealed operation starts, do not reimplement Harness state machines in the lead. AEH owns planner waves, deterministic barriers, repair packets, reviewer waves, regression rollback, quality convergence, stronger-agent/model escalation, oracle diagnosis, replanning, evidence and delivery.

package/skills/paseo-orchestration/SKILL.md

@@ -7,6 +7,10 @@ purpose: Keep AEH leads thin by delegating through Paseo native/MCP tools and or
 
 Use this skill whenever an AEH lead, planner or coordinator delegates work through Paseo.
 
+## Authority boundary
+
+Paseo is authoritative for agent lifecycle, agent snapshots, provider/model availability, context-window usage and generic orchestration tools. AEH is authoritative for engineering policy, SDD/contracts/seals, deterministic validation, detached operation state, quality convergence and acceptance. Do not reimplement Paseo snapshot/provider semantics by scraping CLI output, and do not move AEH acceptance policy into an LLM agent.
+
 ## Preferred control surface
 
 When Paseo tools are injected into the current agent, prefer them over shell commands for bounded conversational delegation:
@@ -17,18 +21,36 @@ When Paseo tools are injected into the current agent, prefer them over shell com
 - `cancel_agent` / `archive_agent` for lifecycle cleanup;
 - `update_agent` / `set_agent_mode` for supported runtime changes.
 
-When the optional AEH operation MCP server (`aeh operation mcp`) is injected, use its tools for long deterministic Harness workflows:
+When the AEH control MCP server (`aeh operation mcp`) is injected, use its tools for deterministic Harness policy/control:
 
 - `aeh_operation_start_audit`;
 - `aeh_operation_start_run`;
 - `aeh_operation_status`;
-- `aeh_operation_cancel`.
+- `aeh_operation_cancel`;
+- `aeh_context_status`.
+
+`aeh_context_status` reads the current Paseo AgentSnapshot and applies AEH context thresholds. It must be preferred over shell/log parsing. `NO_USAGE_YET` means the provider has not emitted a usage snapshot yet; `USAGE_UNAVAILABLE` means the current provider snapshot lacks the canonical context-window fields. Never invent a percentage from input/output token counters.
 
-These MCP tools call the same persistent detached operation controller as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` is the short non-blocking compatibility surface; do not replace it with a long synchronous `aeh audit`/`aeh run` from the conversational lead.
+These MCP tools call the same persistent detached operation controller/policy code as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` and `aeh context guard` are short compatibility surfaces; do not replace them with long synchronous `aeh audit`/`aeh run` from the conversational lead.
 
 Load `/paseo` when the exact current Paseo surface is needed. Use `/paseo-handoff` when responsibility, not merely a subtask, should move to a fresh agent. `/paseo-committee` and `/paseo-advisor` are analysis-only escalation tools and must not replace deterministic AEH gates.
 
-The Harness CLI/daemon adapter remains a deterministic compatibility path when native tools/SDK are unavailable. Do not hand-write `paseo run` shell loops from the lead unless AEH explicitly reports that it is using the CLI fallback.
+## SDK-first lifecycle
+
+AEH should use the public `@getpaseo/client` surface first for semantic operations:
+
+- provider/model preflight before creating agents;
+- `agents.ref(id).refetch()` for current snapshots;
+- `AgentSnapshot.lastUsage.contextWindowUsedTokens/contextWindowMaxTokens` for context pressure;
+- agent subscriptions for event-driven completion, with subscribe-before-refetch race closure;
+- provider snapshot/model/diagnostic APIs for early configuration failures.
+
+The CLI remains a compatibility/parity-gap surface, not a parallel source of truth. Two intentional external-controller CLI uses currently remain for Paseo 0.3.1:
+
+1. operation workspace creation requiring `--isolation local` plus user-visible `--title`, which the public SDK create contract does not yet expose with equivalent parity;
+2. external cleanup/stop where the public agent handle does not expose cancel/kill parity required by the deterministic controller.
+
+Do not replace those two bounded uses with internal `DaemonClient` imports. Their use must remain traceable and should disappear when the public SDK reaches parity.
 
 ## Visible execution graph
 
@@ -36,6 +58,12 @@ Real planner/reviewer/implementer/oracle sessions should be top-level Paseo agen
 
 Use `aeh paseo agents --operation <id>` (or Paseo's corresponding directory/status tools) to observe real participants without scraping terminal output.
 
+## Observability
+
+AEH persists integration decisions under `.harness/telemetry/paseo.ndjson` even when remote OTLP export is disabled. Relevant events include provider preflight, agent snapshot/context source, lifecycle transport, event-driven wait, SDK-to-CLI fallback, intentional workspace CLI use and cleanup CLI use. When normal Harness telemetry is enabled the same events also flow through the standard telemetry/OTLP path.
+
+A trace should answer: which transport was used, which source supplied state, whether a fallback was intentional or exceptional, why it happened, and which operation/agent/provider/model was affected.
+
 ## Lead discipline
 
 The lead owns intent, high-level routing, true ambiguity and final semantic acceptance. Delegate:
@@ -50,4 +78,4 @@ Return compact structured summaries to the lead. Do not paste raw logs or entire
 
 ## Context pressure
 
-Before broad engineering work, inspect the current agent status if Paseo exposes context usage. At the configured handoff threshold, create a deterministic AEH handoff artifact and use `/paseo-handoff` (preferred) or `create_agent` to continue in a fresh lead. Detached operations and their top-level workers remain valid across lead rotation. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.
+Before broad engineering work and after completed-turn boundaries, use `aeh_context_status` when injected. At the configured handoff threshold, create a deterministic AEH handoff artifact and use `/paseo-handoff` (preferred) or `create_agent` to continue in a fresh lead. Detached operations and their top-level workers remain valid across lead rotation. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.