myshell-tools 1.0.0 → 2.0.0

package/dist/core/classify.js

@@ -0,0 +1,80 @@
+/**
+ * src/core/classify.ts — pure task classification.
+ *
+ * Determines the orchestration tier and security risk level from a free-text
+ * task description using keyword/regex signals. No I/O, no time, no randomness.
+ *
+ * Honesty Contract: no fabricated confidence numbers are produced here.
+ * The rationale field names the matched signal so callers can audit decisions.
+ */
+// ---------------------------------------------------------------------------
+// Tier signal tables
+// ---------------------------------------------------------------------------
+/** Words that signal a manager-tier task (review, planning, architecture, security). */
+const MANAGER_WORDS = /\b(review|plan|design|architect|audit|security|threat|evaluate|assess|complex)\b/i;
+/** Words that signal a worker-tier task (read-only lookups, searches). */
+const WORKER_WORDS = /\b(find|search|grep|locate|list|read[-\s]only|lookup|scan|what\s+is)\b/i;
+// ---------------------------------------------------------------------------
+// Risk signal tables — highest match wins
+// ---------------------------------------------------------------------------
+/** Critical: auth / secrets / credentials / encryption artefacts. */
+const CRITICAL_RE = /\b(auth|credential|secret|password|token|key|encrypt|certificate)\b|\.env\b/i;
+/** High: payments, deploys, migrations, CI/CD, permissions, schema changes. */
+const HIGH_RE = /\b(login|payment|billing|deploy|migration|ci\/cd|permission|schema)\b/i;
+/** Medium: tests, configs, shared utilities, integrations. */
+const MEDIUM_RE = /\b(test|spec|config|integration|shared|util|lib)\b/i;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify a free-text `task` string into a {@link Classification}.
+ *
+ * Tier priority: manager > worker > ic (ic is the default).
+ * Risk priority: critical > high > medium > low (low is the default).
+ *
+ * @param task - The raw task description from the user.
+ */
+export function classify(task) {
+    // --- Tier ---
+    let tier;
+    let tierSignal;
+    if (MANAGER_WORDS.test(task)) {
+        tier = 'manager';
+        const m = task.match(MANAGER_WORDS);
+        tierSignal = m ? `manager keyword '${m[0].toLowerCase()}'` : 'manager keyword';
+    }
+    else if (WORKER_WORDS.test(task)) {
+        tier = 'worker';
+        const m = task.match(WORKER_WORDS);
+        tierSignal = m ? `worker keyword '${m[0].toLowerCase()}'` : 'worker keyword';
+    }
+    else {
+        tier = 'ic';
+        tierSignal = 'no tier keyword matched — defaulting to ic';
+    }
+    // --- Risk ---
+    let risk;
+    let riskSignal;
+    if (CRITICAL_RE.test(task)) {
+        risk = 'critical';
+        const m = task.match(CRITICAL_RE);
+        riskSignal = `critical keyword '${m ? m[0].toLowerCase() : 'unknown'}'`;
+    }
+    else if (HIGH_RE.test(task)) {
+        risk = 'high';
+        const m = task.match(HIGH_RE);
+        riskSignal = `high keyword '${m ? m[0].toLowerCase() : 'unknown'}'`;
+    }
+    else if (MEDIUM_RE.test(task)) {
+        risk = 'medium';
+        const m = task.match(MEDIUM_RE);
+        riskSignal = `medium keyword '${m ? m[0].toLowerCase() : 'unknown'}'`;
+    }
+    else {
+        risk = 'low';
+        riskSignal = 'no risk keyword matched — defaulting to low';
+    }
+    const rationale = `tier: ${tierSignal}; risk: ${riskSignal}`;
+    return { tier, risk, rationale };
+}
+//# sourceMappingURL=classify.js.map

package/dist/core/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/core/classify.ts"],"names":[],"mappings":"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"}

package/dist/core/escalate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/core/escalate.ts — pure escalation helpers.
+ *
+ * Provides utilities for determining the next tier in the escalation chain
+ * and selecting a cross-vendor reviewer.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+import type { Tier } from './types.js';
+import type { ProviderId } from '../providers/port.js';
+/**
+ * Return the next tier up from the given tier, or null if already at the top.
+ *
+ * Chain: worker → ic → manager → null
+ *
+ * @param tier - The current orchestration tier.
+ */
+export declare function nextTierUp(tier: Tier): Tier | null;
+/**
+ * Pick a reviewer provider from the available list, preferring cross-vendor
+ * review over same-vendor review.
+ *
+ * Algorithm:
+ *  1. If `available` is empty, return null.
+ *  2. Prefer a provider with a DIFFERENT id than `primary` (cross-vendor review).
+ *  3. If all available are the same vendor as primary, return `primary` if it
+ *     is in `available`, else return null.
+ *
+ * @param available - Provider IDs that are currently reachable.
+ * @param primary   - The provider ID that ran the IC work being reviewed.
+ */
+export declare function pickReviewer(available: ProviderId[], primary: ProviderId): ProviderId | null;

package/dist/core/escalate.js

@@ -0,0 +1,57 @@
+/**
+ * src/core/escalate.ts — pure escalation helpers.
+ *
+ * Provides utilities for determining the next tier in the escalation chain
+ * and selecting a cross-vendor reviewer.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+// ---------------------------------------------------------------------------
+// Tier chain
+// ---------------------------------------------------------------------------
+/**
+ * Return the next tier up from the given tier, or null if already at the top.
+ *
+ * Chain: worker → ic → manager → null
+ *
+ * @param tier - The current orchestration tier.
+ */
+export function nextTierUp(tier) {
+    switch (tier) {
+        case 'worker':
+            return 'ic';
+        case 'ic':
+            return 'manager';
+        case 'manager':
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Reviewer selection
+// ---------------------------------------------------------------------------
+/**
+ * Pick a reviewer provider from the available list, preferring cross-vendor
+ * review over same-vendor review.
+ *
+ * Algorithm:
+ *  1. If `available` is empty, return null.
+ *  2. Prefer a provider with a DIFFERENT id than `primary` (cross-vendor review).
+ *  3. If all available are the same vendor as primary, return `primary` if it
+ *     is in `available`, else return null.
+ *
+ * @param available - Provider IDs that are currently reachable.
+ * @param primary   - The provider ID that ran the IC work being reviewed.
+ */
+export function pickReviewer(available, primary) {
+    if (available.length === 0)
+        return null;
+    // Prefer a different vendor (cross-vendor review is the goal)
+    const crossVendor = available.find((id) => id !== primary);
+    if (crossVendor !== undefined)
+        return crossVendor;
+    // All available are same vendor — return primary if it's in the list
+    if (available.includes(primary))
+        return primary;
+    return null;
+}
+//# sourceMappingURL=escalate.js.map

package/dist/core/escalate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalate.js","sourceRoot":"","sources":["../../src/core/escalate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAU;IACnC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC;QACd,KAAK,IAAI;YACP,OAAO,SAAS,CAAC;QACnB,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,SAAuB,EAAE,OAAmB;IACvE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,8DAA8D;IAC9D,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;IAC3D,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAElD,qEAAqE;IACrE,IAAI,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAEhD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * src/core/index.ts — public surface of the pure orchestration core.
+ */
+export { orchestrate } from './orchestrate.js';
+export { classify } from './classify.js';
+export { route } from './route.js';
+export { assess } from './assess.js';
+export { buildPrompt } from './prompt.js';
+export { DEFAULT_POLICY } from './policy.js';
+export { nextTierUp, pickReviewer } from './escalate.js';
+export { buildReviewPrompt, parseReviewVerdict } from './review.js';
+export type { ReviewVerdict } from './review.js';
+export type { Tier, Risk, Classification, RouteDecision, Assessment, Clock, SessionEntry, SessionWriter, LedgerEntry, LedgerWriter, Policy, OrchestrateDeps, CoreEvent, } from './types.js';

package/dist/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * src/core/index.ts — public surface of the pure orchestration core.
+ */
+export { orchestrate } from './orchestrate.js';
+export { classify } from './classify.js';
+export { route } from './route.js';
+export { assess } from './assess.js';
+export { buildPrompt } from './prompt.js';
+export { DEFAULT_POLICY } from './policy.js';
+export { nextTierUp, pickReviewer } from './escalate.js';
+export { buildReviewPrompt, parseReviewVerdict } from './review.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/core/orchestrate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * src/core/orchestrate.ts — the bounded escalation + review loop.
+ *
+ * Implements the Phase-2 multi-tier loop:
+ *   classify → route → run IC → (optionally) cross-vendor review → assess →
+ *   escalate/retry/accept → final
+ *
+ * Control-flow overview:
+ *   1. Classify the task.
+ *   2. If no providers → notice(error) + final(false); return.
+ *   3. Append user session entry once.
+ *   4. Loop (≤ maxAttempts):
+ *      a. Route to provider+model for currentTier.
+ *      b. Yield tier-start → stream provider events → yield tier-done.
+ *      c. Provider failure → escalate to manager (or break if already there).
+ *      d. If IC tier + shouldReview(classification, assessment):
+ *         run cross-vendor reviewer at manager tier.
+ *         approve → accept; revise → retry IC with notes; escalate → escalate tier.
+ *      e. Low-confidence / escalate signal → nextTierUp → continue.
+ *      f. All good → yield final(success:true); return.
+ *   5. Loop exhausted or broke on failure → yield final(success:false).
+ *
+ * Purity rules (enforced by test/arch/guards.test.ts):
+ *  - No imports of fs / path / child_process
+ *  - No console.* calls
+ *  - No Date.now() / Math.random() / new Date() — use deps.clock
+ *  - No process.exit() — only src/cli.ts may terminate the process
+ */
+import type { CoreEvent, OrchestrateDeps } from './types.js';
+/**
+ * Orchestrate a task through the bounded escalation + review loop.
+ *
+ * Yields a sequence of {@link CoreEvent} objects.
+ * The interface/render layer drives the generator and surfaces events to
+ * the user.
+ *
+ * @param task   - The raw user task description.
+ * @param deps   - Injected dependencies (providers, clock, session, ledger, policy, …).
+ * @param signal - AbortSignal; when aborted the generator stops and yields a
+ *                 notice(warn, 'cancelled') followed by final(success:false).
+ */
+export declare function orchestrate(task: string, deps: OrchestrateDeps, signal: AbortSignal): AsyncGenerator<CoreEvent>;