heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/fleet-handlers.mjs

@@ -0,0 +1,37 @@
+// heyspex_fleet_queue_* handlers (thin wrappers over fleet-queue-tools.mjs). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeFleetQueueClaim, executeFleetQueueComplete, executeFleetQueueList, executeFleetQueueSubmit, resolveFleetToken } from './fleet-queue-tools.mjs';
+import { consoleFetch } from './console-transport.mjs';
+
+export async function handleFleetQueueSubmit(args = {}) {
+  const result = await executeFleetQueueSubmit({ consoleFetch, args, fleetToken: resolveFleetToken() });
+  return {
+    isError: !!result.error,
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export async function handleFleetQueueClaim(args = {}) {
+  const result = await executeFleetQueueClaim({ consoleFetch, args, fleetToken: resolveFleetToken() });
+  return {
+    isError: !!result.error,
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export async function handleFleetQueueComplete(args = {}) {
+  const result = await executeFleetQueueComplete({ consoleFetch, args, fleetToken: resolveFleetToken() });
+  return {
+    isError: !!result.error,
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export async function handleFleetQueueList(args = {}) {
+  const result = await executeFleetQueueList({ consoleFetch, args, fleetToken: resolveFleetToken() });
+  return {
+    isError: !!result.error,
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}

package/vendor/heyspex-mcp/fleet-queue-tools.mjs

@@ -66,32 +66,88 @@ function bearerHeaders(fleetToken) {
 }
 
 /**
- * HS-FS7X (interim only — full fix is the unstarted [[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]]
- * child tasks). This route writes to the Neon-backed `/api/fleet/queue`, but
+ * HS-FS7X — SUBMIT REFUSES WHILE NO RUNNER DRAINS THE NEON QUEUE.
+ *
+ * This tool writes to the Neon-backed `/api/fleet/queue`, but
  * `dev-factory/lib/fleet-queue-runner.mjs` — the only thing that actually
  * claims and executes queued work — still reads exclusively from the legacy
- * file-backed queue (`dev-factory/lib/fleet-queue.mjs`). A submit through this
- * tool therefore succeeds and is durably recorded, but nothing will ever pick
- * it up. Every success return carries this warning so a caller cannot mistake
- * "accepted" for "will run" until the runner is repointed at Neon.
+ * file-backed queue (`dev-factory/lib/fleet-queue.mjs`). Work submitted here
+ * would be durably recorded and never executed.
+ *
+ * It previously returned `{ id, position, warning }`. That was not enough: a
+ * warning riding along on a SUCCESS shape is still a success —
+ * `handleFleetQueueSubmit` sets `isError: !!result.error`, so the MCP client
+ * saw a green tool call and an agent that submits and moves on never learned
+ * the work was dropped. So the submit now REFUSES before the round trip and
+ * writes nothing at all — same shape as the argument refusal in
+ * [[HS-IRX0-5KFT-DIAG-record-wip-silently-drops-the-summary]]: refuse at the
+ * boundary, because a queue with no consumer cannot refuse on your behalf.
+ *
+ * Repointing the runner at Neon is a separate BUILD, already owned by
+ * [[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]] (HS-ZXKF: runner -> queue
+ * API; HS-HQP1: make fleet-queue.mjs actually select a backend). When that
+ * lands, delete this gate. Meanwhile a machine whose runner genuinely does
+ * drain Neon opts back in with HEYSPEX_FLEET_QUEUE_RUNNER_READY=1 — an
+ * explicit, per-machine assertion, never something a caller can set per-call.
+ */
+export const NEON_QUEUE_RUNNER_READY_ENV = 'HEYSPEX_FLEET_QUEUE_RUNNER_READY';
+
+export const NEON_QUEUE_NO_RUNNER_MESSAGE =
+  'Refusing to submit — nothing was submitted. The Neon fleet queue has NO runner reading it: ' +
+  'dev-factory/lib/fleet-queue-runner.mjs still reads only the legacy JSONL file queue ' +
+  '(dev-factory/lib/fleet-queue.mjs), so anything accepted here would be durably recorded and ' +
+  'NEVER executed. Track: [[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]] (HS-ZXKF repoints the ' +
+  'runner; HS-HQP1 makes the fleet-queue facade select a backend). To run work now, enqueue against ' +
+  'dev-factory/lib/fleet-queue.mjs directly — that is the queue the runner reads. If this ' +
+  'machine’s ' +
+  `runner really does drain the Neon queue, set ${NEON_QUEUE_RUNNER_READY_ENV}=1 to re-enable submits.`;
+
+/**
+ * True only when this machine asserts its runner drains the Neon fleet queue.
+ * Defaults to false: the safe answer to "will this run?" is "no".
+ *
+ * @param {Record<string, string|undefined>} [env]
  */
-export const NEON_QUEUE_NO_RUNNER_WARNING =
-  'Neon fleet queue has NO runner reading it yet — dev-factory/lib/fleet-queue-runner.mjs ' +
-  'still only reads the legacy JSONL file queue. This item is durably recorded in Neon but ' +
-  'will NOT execute until HS-XOCK-60Z1 (fleet-queue Neon port) lands. Track: ' +
-  '[[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]].';
+export function neonQueueRunnerReady(env = process.env) {
+  const raw = env?.[NEON_QUEUE_RUNNER_READY_ENV];
+  if (typeof raw !== 'string') return false;
+  const v = raw.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
 
 /**
  * `heyspex_fleet_queue_submit` — POST /api/fleet/queue. `kind` defaults to
  * "task" when omitted (the API requires a kind string).
  *
- * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null }} ctx
+ * HS-FS7X: refuses outright (writing nothing) unless this machine asserts a
+ * runner actually drains the Neon queue — see NEON_QUEUE_NO_RUNNER_MESSAGE.
+ *
+ * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null, env?: Record<string, string|undefined> }} ctx
  */
-export async function executeFleetQueueSubmit({ consoleFetch, args = {}, fleetToken = null }) {
+export async function executeFleetQueueSubmit({
+  consoleFetch,
+  args = {},
+  fleetToken = null,
+  env = process.env,
+}) {
   const lane = typeof args.lane === 'string' ? args.lane.trim() : '';
   if (!lane) {
     return { error: 'INVALID_ARGS', message: 'lane is required' };
   }
+
+  // HS-FS7X: refuse BEFORE the round trip. Accepting work into a queue with no
+  // consumer and returning `{ id, position }` told the caller it would run.
+  if (!neonQueueRunnerReady(env)) {
+    return {
+      error: 'NO_RUNNER',
+      message: NEON_QUEUE_NO_RUNNER_MESSAGE,
+      lane,
+      submitted: false,
+      track: 'HS-XOCK-60Z1',
+      override_env: NEON_QUEUE_RUNNER_READY_ENV,
+    };
+  }
+
   const kind = typeof args.kind === 'string' && args.kind.trim() ? args.kind.trim() : 'task';
 
   const body = {
@@ -120,7 +176,6 @@ export async function executeFleetQueueSubmit({ consoleFetch, args = {}, fleetTo
     id: result.body?.id ?? null,
     position: result.body?.position ?? null,
     lane,
-    warning: NEON_QUEUE_NO_RUNNER_WARNING,
   };
 }
 

package/vendor/heyspex-mcp/focus-tools.mjs

@@ -0,0 +1,190 @@
+// Focus pin and focus-area tools (heyspex_pin_get/pin_set, set/get/clear_focus_areas,
+// resolve_focus_intent) plus the Neon focus-pin injector the on-deck brief uses. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Focus-areas CRUD — [[HS-TASK-1GQ5]] / [[HS-EPIC-7WJN]] / [[HS-MIL-AFOC]].
+// Agent-controllable roadmap focus: distinct from the on-deck pin tools above
+// (heyspex_pin_get/set, the `focus_pin` table). These write the `focus_areas`
+// control plane (tag-band) via the console route, which tier-dispatches Neon vs
+// the free-tier `.heyspex/focus-areas.yaml`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { consoleFetch, controlError, controlOk } from './console-transport.mjs';
+import { detectAgentIdentity, getConfig } from './mcp-config.mjs';
+import { buildDegradedFocusResult, resolveFocusIntentLexical } from './plan-ground.mjs';
+
+/**
+ * Fetch the Neon layer-1 focus pin (the console-set fuse pin) and inject its
+ * spec_id into args as `neon_pin_spec_id`, so the synchronous on-deck resolver
+ * can let it win precedence #1 over the file's layer-2 `spec_path`.
+ *
+ * Why this exists: per [[heyspex-is-saas-cloud-primary-both-tiers]] the focus
+ * pin lives in Neon `focus_pin` on a Neon-up machine; the file `pin:` block is
+ * dormant. So vendor /hs-next — which reads the file synchronously — was blind to
+ * a console-set pin (the documented FCPN paid-tier soak gap). We do the one async
+ * read here, at the handler boundary, and thread the result down as a sync option.
+ *
+ * Best-effort: any unreachable / non-OK (incl. free-tier 402) / empty response
+ * leaves args untouched, so the resolver falls back to the file focus. Never
+ * throws, never blocks /hs-next. Skipped when `ignore_focus` or an explicit
+ * `spec_id` (direct lookup, no focus) is set. The GET response is
+ * `{ pin: FocusPinRow | null }` with camelCase keys (`pin.specId`).
+ */
+export async function injectNeonFocusPin(args = {}) {
+  if (args.ignore_focus === true || args.ignore_focus === 'true') return args;
+  if (args.spec_id) return args;
+  let next = args;
+  try {
+    // Both focus layers live in Neon on a Neon-up machine (the file is dormant):
+    // layer-1 pin in `focus_pin`, layer-2 selection in `focus_selection`
+    // ([[HS-TASK-FCPN]] + [[HS-TASK-FSEL]]). Fetch both, thread the ids into the
+    // sync resolver. Responses are `{ pin }` / `{ selection }` with camelCase keys.
+    const [pinRes, selRes] = await Promise.all([
+      consoleFetch('/api/control/pin'),
+      consoleFetch('/api/control/focus-selection'),
+    ]);
+    const pinId = pinRes && pinRes.ok ? pinRes.body?.pin?.specId : null;
+    if (typeof pinId === 'string' && pinId) next = { ...next, neon_pin_spec_id: pinId };
+    const selPath = selRes && selRes.ok ? selRes.body?.selection?.specPath : null;
+    if (typeof selPath === 'string' && selPath) {
+      next = { ...next, neon_selection_spec_path: selPath };
+    }
+  } catch {
+    // Swallow — fall back to the file focus. Focus is a steering nicety, not a
+    // correctness gate; an unreachable console must not break /hs-next.
+  }
+  return next;
+}
+
+export async function handlePinGet(_args = {}) {
+  const result = await consoleFetch('/api/control/pin');
+  if (!result.ok) return controlError(result, 'PIN_GET_FAILED');
+  return controlOk(result.body);
+}
+
+/**
+ * Set or clear the on-deck pin — [[HS-EPIC-NCPS]] focus_pin / [[HS-EPIC-CLMW]]
+ * `hs pin set` / `hs pin clear`. PUT /api/control/pin. Omit/null
+ * spec_id clears (mirrors the endpoint's null-clears contract).
+ */
+export async function handlePinSet(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const pinnedBy =
+    typeof args.pinned_by === 'string' && args.pinned_by.trim()
+      ? args.pinned_by.trim()
+      : identity.agent;
+  const clearing = args.spec_id === undefined || args.spec_id === null;
+  const body = clearing
+    ? { spec_id: null, pinned_by: pinnedBy }
+    : {
+        spec_id: args.spec_id,
+        pinned_by: pinnedBy,
+        ...(args.ttl_ms !== undefined ? { ttl_ms: args.ttl_ms } : {}),
+      };
+  const result = await consoleFetch('/api/control/pin', { method: 'PUT', body });
+  if (!result.ok) return controlError(result, 'PIN_SET_FAILED', { spec_id: args.spec_id ?? null });
+  return controlOk(result.body);
+}
+
+/** `heyspex_set_focus_areas` → PUT /api/scheduler/focus-areas. */
+export async function handleSetFocusAreas(args = {}) {
+  const tags = Array.isArray(args.tags)
+    ? args.tags.map((t) => String(t).trim()).filter(Boolean)
+    : [];
+  if (tags.length === 0) {
+    return controlError(
+      { ok: false, status: 0, url: '', body: null },
+      'FOCUS_AREAS_INVALID',
+      { reason: 'tags must be a non-empty array of known-tag strings' },
+    );
+  }
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const body = {
+    rationale: typeof args.rationale === 'string' ? args.rationale : '',
+    tags,
+    updated_by: `${identity.agent} · ${identity.sessionId}`,
+    ...(typeof args.expires_at === 'string' ? { expires_at: args.expires_at } : {}),
+    ...(typeof args.replace === 'boolean' ? { replace: args.replace } : {}),
+  };
+  const result = await consoleFetch('/api/scheduler/focus-areas', { method: 'PUT', body });
+  if (!result.ok) return controlError(result, 'FOCUS_AREAS_SET_FAILED');
+  return controlOk(result.body);
+}
+
+/** `heyspex_get_focus_areas` → GET /api/scheduler/focus-areas. */
+export async function handleGetFocusAreas(_args = {}) {
+  const result = await consoleFetch('/api/scheduler/focus-areas');
+  if (!result.ok) return controlError(result, 'FOCUS_AREAS_GET_FAILED');
+  return controlOk(result.body);
+}
+
+/** `heyspex_clear_focus_areas` → DELETE /api/scheduler/focus-areas. */
+export async function handleClearFocusAreas(_args = {}) {
+  const result = await consoleFetch('/api/scheduler/focus-areas', { method: 'DELETE' });
+  if (!result.ok) return controlError(result, 'FOCUS_AREAS_CLEAR_FAILED');
+  return controlOk(result.body);
+}
+
+/**
+ * `heyspex_resolve_focus_intent` — Phase-B lexical resolver ([[HS-TASK-JZEJ]] /
+ * [[HS-EPIC-OOPW]]). Runs lexical wide-recall through the console search
+ * endpoint and returns a wide candidate window ({ spec, tags, why }[]) for the
+ * calling agent's LLM to rerank into focus tags — HeySpex hosts no reranker. No
+ * embeddings (Gate B = NO,
+ * [[retrieval-substrate-lexical-not-embeddings-gate-b-no]]). Retrieval is
+ * bounded `GET /api/search` / `GET /api/specs?tag=` pages, never a vault walk
+ * ([[HS-YIR1-8KK5-TASK-planning-grounding-retrieves-through]]). An
+ * empty/no-match window is returned (not an error) so the caller can fall back
+ * to heyspex_list_known_tags + exact-tag NLU.
+ *
+ * Graceful degradation ([[HS-TASK-09I3]] / focus-intent-routing §6): if the
+ * lexical recall primitive is unreachable or throws (console down, 401, 5xx),
+ * the resolver core returns a `degraded` marker rather
+ * than raising. The try/catch here is belt-and-suspenders — a throw outside the
+ * core's own guard must still resolve to a graceful degraded result so the MCP
+ * tool never 500s a focus pivot.
+ */
+export async function handleResolveFocusIntent(args = {}) {
+  const { vaultRoot } = getConfig();
+  let result;
+  try {
+    result = await resolveFocusIntentLexical(vaultRoot, {
+      utterance: args.utterance,
+      top_k: args.top_k,
+    });
+  } catch (err) {
+    result = buildDegradedFocusResult(args.utterance, err);
+  }
+  return controlOk(result);
+}
+
+/**
+ * Persist the /hs-push-next layer-2 focus selection to Neon `focus_selection`
+ * via the console endpoint (so the console On-Deck AND vendor /hs-next, both of
+ * which read Neon, see it). There is NO `.heyspex/focus.yaml` fallback
+ * ([[no-fallbacks-by-default]]; the focus.yaml-fallback incident) — Neon is the
+ * only focus store. If the console is unreachable the push itself still
+ * succeeds (the spec files were written); the focus pin just isn't set, and we
+ * say so on stderr rather than writing a stale file. Returns true iff focus was
+ * persisted.
+ */
+export async function writeFocusSelectionVendor(vaultRoot, specPath, reason) {
+  try {
+    const res = await consoleFetch('/api/control/focus-selection', {
+      method: 'PUT',
+      body: { spec_path: specPath, kind: 'epic', picked_by: 'human', reason: reason ?? null },
+    });
+    if (res && res.ok) return true;
+    console.error(
+      `[hs-push] focus not pinned — console returned ${res?.status ?? 'no response'} for PUT /api/control/focus-selection. ` +
+        'Neon is required (no focus.yaml fallback); re-pin once the console is reachable.',
+    );
+  } catch (err) {
+    console.error(
+      `[hs-push] focus not pinned — console unreachable (${err?.message ?? err}). ` +
+        'Neon is required (no focus.yaml fallback); re-pin once the console is reachable.',
+    );
+  }
+  return false;
+}

package/vendor/heyspex-mcp/folder-trust-store.mjs

@@ -0,0 +1,59 @@
+/**
+ * Machine-local folder-trust store I/O — plain ESM.
+ *
+ * `~/.heyspex/trusted-folders.json` ([[HS-ZBEB-8CMW-TASK-folder-trust-for-spexcode-first-run]])
+ * is read by two fronts that cannot share a TypeScript import:
+ *   - `spex-console/src/lib/cli/folder-trust.ts` (the CLI/`hs chat`/`hs trust` home — TypeScript,
+ *     run through tsx) — its own decision functions (`resolveFolderTrust`, `recordFolderTrust`,
+ *     `revokeFolderTrust`, …) stay there; it imports and RE-EXPORTS the I/O functions below
+ *     rather than re-implementing them.
+ *   - `vendor/heyspex-mcp/config-settings.mjs` (the settings capability's core — plain ESM, no
+ *     TypeScript toolchain available) — reads this store directly to answer
+ *     `heyspex_settings_get("agent_behaviors.spexcode.trusted_folders")`
+ *     ([[HS-25AJ-8CMW-TASK-folder-trust-revoke-through-the]]).
+ *
+ * This file is the ONE place this I/O is implemented — never duplicated. Storage contract
+ * (realpath-keyed, `{ trusted, decidedAt }` entries) is documented in full in folder-trust.ts's
+ * own header; this file only carries the read/write/list primitives, not the trust decision
+ * logic itself.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** `~/.heyspex/trusted-folders.json`, relative to a home directory. */
+export const TRUST_STORE_REL = path.join('.heyspex', 'trusted-folders.json');
+
+/** Resolve the real trust-store path for a given home directory (defaults to `os.homedir()`). */
+export function trustStorePath(home = os.homedir()) {
+  return path.join(home, TRUST_STORE_REL);
+}
+
+/** Read the trust store from disk. A missing/corrupt/unreadable file reads as an empty store
+ *  (fail open to "nothing answered yet", never a crash). */
+export function readTrustStore(filePath = trustStorePath()) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Write the trust store to disk, creating `~/.heyspex/` if needed. */
+export function writeTrustStore(store, filePath = trustStorePath()) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+}
+
+/** List every stored trust decision as a flat array — the read-only listing surface both
+ *  `hs trust list` and the `agent_behaviors.spexcode.trusted_folders` settings-capability
+ *  computed key format their output from. */
+export function listTrustedFolders(store) {
+  return Object.entries(store).map(([key, entry]) => ({
+    path: key,
+    trusted: entry.trusted,
+    decidedAt: entry.decidedAt,
+  }));
+}