@agjs/tsforge 0.1.9 → 0.1.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/cli.ts

@@ -629,6 +629,7 @@ const HELP = [
   "  /model [name]    list configured models (★ active), or switch to <name>",
   "  /sessions        list saved sessions (resume one with: tsforge --resume <id>)",
   "  /cost            rough conversation size (messages + ~tokens)",
+  "  /metrics         token totals + generation rate (tok/s) this session",
   "  /exit, /quit     leave the session",
   "",
   "Anything else is sent to the agent. It works with its tools; when it stops,",
@@ -1197,6 +1198,21 @@ async function repl(args: ICliArgs): Promise<number> {
         break;
       }
 
+      case "metrics": {
+        const m = session.metrics;
+
+        if (m.calls === 0) {
+          process.stdout.write("  no model calls yet\n");
+        } else {
+          process.stdout.write(
+            `  ${String(m.calls)} call(s) · ${String(m.promptTokens)} in / ${String(m.completionTokens)} out · ` +
+              `${String(m.lastTokensPerSecond)} tok/s last · ${String(m.avgTokensPerSecond)} tok/s avg\n`
+          );
+        }
+
+        break;
+      }
+
       default:
         process.stdout.write(`unknown command: ${line} (try /help)\n`);
     }
@@ -1217,6 +1233,7 @@ async function repl(args: ICliArgs): Promise<number> {
         elapsedMs: lastElapsedMs,
         status: lastStatus,
         scope: scopeLabel(session.scope) + (planMode ? " · PLAN" : ""),
+        tokensPerSecond: session.metrics.lastTokensPerSecond,
       })
     );
     process.stdout.write("› ");

package/src/config/external-plugins.ts

@@ -0,0 +1,152 @@
+import { resolve } from "node:path";
+import { isRecord } from "../lib/guards";
+import { registerExternalPack } from "../rule-packs";
+import type { IRulePack } from "../rule-packs/rule-packs.types";
+
+/** One external plugin entry from tsforge.config.json `plugins`. */
+export interface IExternalPlugin {
+  /** Module specifier or path (relative paths resolve against the repo root). */
+  readonly path: string;
+  /** Named exports to load as rule packs. Omit to load every exported pack. */
+  readonly packs?: readonly string[];
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Type guard: a well-formed IRulePack (no `as` — every field is checked). */
+export function isRulePack(value: unknown): value is IRulePack {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  if (typeof value.id !== "string" || value.id.length === 0) {
+    return false;
+  }
+
+  if (typeof value.description !== "string") {
+    return false;
+  }
+
+  if (!isRecord(value.rules) || !isRecord(value.rulesConfig)) {
+    return false;
+  }
+
+  for (const severity of Object.values(value.rulesConfig)) {
+    if (severity !== "error" && severity !== "warn") {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Parse the `plugins` config field into validated entries. */
+export function parsePlugins(raw: unknown): IExternalPlugin[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const plugins: IExternalPlugin[] = [];
+
+  for (const item of raw) {
+    if (
+      !isRecord(item) ||
+      typeof item.path !== "string" ||
+      item.path.length === 0
+    ) {
+      continue;
+    }
+
+    const packs = Array.isArray(item.packs)
+      ? item.packs.filter((p): p is string => typeof p === "string")
+      : undefined;
+
+    plugins.push({
+      path: item.path,
+      ...(packs !== undefined && packs.length > 0 ? { packs } : {}),
+    });
+  }
+
+  return plugins;
+}
+
+/** Collect the candidate exports to validate from a loaded module. */
+function candidateExports(
+  mod: Record<string, unknown>,
+  names: readonly string[] | undefined
+): unknown[] {
+  if (names === undefined) {
+    return Object.values(mod);
+  }
+
+  return names.map((name) => mod[name]);
+}
+
+/**
+ * Dynamically import each plugin and collect its valid exported rule packs.
+ * Never throws — an unimportable module or an export that is not a valid pack is
+ * reported and skipped, so a broken plugin can't take down a run.
+ */
+export async function loadExternalPacks(
+  plugins: readonly IExternalPlugin[],
+  cwd: string,
+  report: (message: string) => void
+): Promise<IRulePack[]> {
+  const out: IRulePack[] = [];
+
+  for (const plugin of plugins) {
+    const specifier = plugin.path.startsWith(".")
+      ? resolve(cwd, plugin.path)
+      : plugin.path;
+
+    let mod: unknown;
+
+    try {
+      mod = await import(specifier);
+    } catch (err) {
+      report(`plugin '${plugin.path}' failed to load: ${errMessage(err)}`);
+
+      continue;
+    }
+
+    if (!isRecord(mod)) {
+      continue;
+    }
+
+    for (const candidate of candidateExports(mod, plugin.packs)) {
+      if (isRulePack(candidate)) {
+        out.push(candidate);
+        report(`plugin '${plugin.path}': loaded pack '${candidate.id}'`);
+      } else {
+        report(
+          `plugin '${plugin.path}': an export is not a valid rule pack — skipped`
+        );
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Load every configured plugin, register its packs in the rule-pack registry,
+ * and return the registered pack ids (to fold into the active pack list so the
+ * gate runs them). Never throws.
+ */
+export async function loadAndRegisterPlugins(
+  plugins: readonly IExternalPlugin[],
+  cwd: string,
+  report: (message: string) => void
+): Promise<string[]> {
+  const packs = await loadExternalPacks(plugins, cwd, report);
+  const ids: string[] = [];
+
+  for (const pack of packs) {
+    registerExternalPack(pack);
+    ids.push(pack.id);
+  }
+
+  return ids;
+}

package/src/config/tsforge-config.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { isRecord } from "../lib/guards";
 import { PACK_REGISTRY } from "../stack-detection";
 import { parseMcpServers, type IMcpServerConfig } from "../mcp";
+import { parsePlugins, type IExternalPlugin } from "./external-plugins";
 
 /**
  * User-defined configuration from tsforge.config.json
@@ -31,6 +32,13 @@ export interface ITsforgeProjectConfig {
    * interpolated from the environment at load time. Opt-in: absent ⇒ no MCP.
    */
   readonly mcpServers?: Readonly<Record<string, IMcpServerConfig>>;
+
+  /**
+   * External plugins providing extra rule packs, loaded without recompiling
+   * tsforge. Each entry names a module (or relative path) and, optionally, which
+   * exported packs to use. Opt-in: absent ⇒ only built-in packs.
+   */
+  readonly plugins?: readonly IExternalPlugin[];
 }
 
 function warnConfig(msg: string): void {
@@ -177,6 +185,7 @@ function buildConfigFields(
     packs?: { include?: readonly string[]; exclude?: readonly string[] };
     rules?: Record<string, "error" | "warn" | "off">;
     mcpServers?: Record<string, IMcpServerConfig>;
+    plugins?: readonly IExternalPlugin[];
   } = {};
 
   if (parsed.stack !== undefined) {
@@ -211,6 +220,14 @@ function buildConfigFields(
     }
   }
 
+  if (parsed.plugins !== undefined) {
+    const plugins = parsePlugins(parsed.plugins);
+
+    if (plugins.length > 0) {
+      configFields.plugins = plugins;
+    }
+  }
+
   return configFields;
 }
 

package/src/loop/loop.types.ts

@@ -51,6 +51,9 @@ export interface ILoopEvent {
   promptTokens?: number;
   completionTokens?: number;
   totalTokens?: number;
+  /** For `usage` events: output generation rate (completion tokens / second),
+   *  measured from the first streamed token to the call's end. */
+  tokensPerSecond?: number;
   /** For `usage` (and salvage-warning `tool`) events: whether THIS model call
    *  ran with thinking enabled — lets the analyzer correlate malformed-tool-call
    *  rate with the thinking mode (see analyze-malformed). */

package/src/loop/run.ts

@@ -191,20 +191,31 @@ function effectiveParserFor(
   return flags.legacyFeedback() ? parseEslintJson : parse;
 }
 
-/** Detect the stack and fold in tsforge.config.json pack/rule overrides. */
-async function resolveStackForRun(cwd: string): Promise<{
+/** Detect the stack and fold in tsforge.config.json pack/rule overrides, plus any
+ *  rule packs from configured external plugins. */
+async function resolveStackForRun(
+  cwd: string,
+  report: (message: string) => void
+): Promise<{
   stackProfile: Awaited<ReturnType<typeof detectStack>>;
   ruleOverrides: Readonly<Record<string, "error" | "warn" | "off">>;
 }> {
   const detectedProfile = await detectStack(cwd);
   const { loadTsforgeConfig, resolveActivePacks, normalizeRuleOverrides } =
     await import("../config/tsforge-config");
+  const { loadAndRegisterPlugins } = await import("../config/external-plugins");
   const cfg = await loadTsforgeConfig(cwd);
+  const activePacks = resolveActivePacks(detectedProfile.packs, cfg);
+  const externalIds =
+    cfg.plugins === undefined
+      ? []
+      : await loadAndRegisterPlugins(cfg.plugins, cwd, report);
 
   return {
     stackProfile: {
       ...detectedProfile,
-      packs: resolveActivePacks(detectedProfile.packs, cfg),
+      packs:
+        externalIds.length > 0 ? [...activePacks, ...externalIds] : activePacks,
     },
     ruleOverrides: normalizeRuleOverrides(cfg),
   };
@@ -268,7 +279,12 @@ export async function runTask(
   });
 
   // Detect stack once per run, early; tsforge.config.json may adjust it
-  const { stackProfile, ruleOverrides } = await resolveStackForRun(cwd);
+  const { stackProfile, ruleOverrides } = await resolveStackForRun(
+    cwd,
+    (message) => {
+      report({ kind: "tool", task: task.id, message });
+    }
+  );
 
   report({
     kind: "tool",

package/src/loop/session.ts

@@ -26,6 +26,7 @@ import {
   resolveActivePacks,
 } from "../config/tsforge-config";
 import { connectMcpServers } from "../mcp";
+import { loadAndRegisterPlugins } from "../config/external-plugins";
 import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
 import type { Reporter } from "./loop.types";
 import { CHAT_SYSTEM, COMPACT_SYSTEM } from "./prompt";
@@ -113,6 +114,20 @@ export interface ISendResult {
   turns: number;
 }
 
+/** Cumulative model-call metrics for a session — the basis for `/metrics`. */
+export interface ISessionMetrics {
+  /** Number of model calls made. */
+  readonly calls: number;
+  /** Total prompt (input) tokens billed across all calls. */
+  readonly promptTokens: number;
+  /** Total completion (output) tokens generated across all calls. */
+  readonly completionTokens: number;
+  /** Output generation rate averaged over all calls (tokens/second). */
+  readonly avgTokensPerSecond: number;
+  /** Output generation rate of the most recent call (tokens/second). */
+  readonly lastTokensPerSecond: number;
+}
+
 export interface ISendOptions {
   /** Caller cancellation (Ctrl-C). */
   signal?: AbortSignal;
@@ -338,6 +353,15 @@ export class Session {
    *  size of the context the model last saw (drives the status gauge and, soon,
    *  auto-compaction). */
   private lastUsage?: ITokenUsage;
+  /** Running totals behind the `metrics` getter. genMs is the summed generation
+   *  time (first-token→end) so the average rate is tokens/total-gen-seconds. */
+  private readonly metricsTotals = {
+    calls: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    genMs: 0,
+    lastTokensPerSecond: 0,
+  };
   /** Fast check run every few edits while building (e.g. tsc); "" = off. */
   private incrementalCheck: string;
   /** Per-send thinking override, set from ISendOptions for the duration of a
@@ -434,9 +458,25 @@ export class Session {
     // pack selection and rule-severity overrides.
     const detected = await detectStack(cfg.cwd);
     const projectConfig = await loadTsforgeConfig(cfg.cwd);
+    const activePacks = resolveActivePacks(detected.packs, projectConfig);
+    // Opt-in: load rule packs from external plugins and fold their ids into the
+    // active packs so the gate runs them. loadAndRegisterPlugins never throws.
+    const externalPackIds =
+      projectConfig.plugins === undefined
+        ? []
+        : await loadAndRegisterPlugins(
+            projectConfig.plugins,
+            cfg.cwd,
+            (message) => {
+              report({ kind: "tool", task: SESSION_ID, message });
+            }
+          );
     const stackProfile = {
       ...detected,
-      packs: resolveActivePacks(detected.packs, projectConfig),
+      packs:
+        externalPackIds.length > 0
+          ? [...activePacks, ...externalPackIds]
+          : activePacks,
     };
     const ruleOverrides = normalizeRuleOverrides(projectConfig);
 
@@ -490,6 +530,31 @@ export class Session {
     return this.lastUsage;
   }
 
+  /** Cumulative model-call metrics (tokens + generation rate) for this session. */
+  get metrics(): ISessionMetrics {
+    const t = this.metricsTotals;
+
+    return {
+      calls: t.calls,
+      promptTokens: t.promptTokens,
+      completionTokens: t.completionTokens,
+      avgTokensPerSecond:
+        t.genMs > 0 ? Math.round((t.completionTokens / t.genMs) * 1000) : 0,
+      lastTokensPerSecond: Math.round(t.lastTokensPerSecond),
+    };
+  }
+
+  /** Fold one call's usage + generation time into the running metrics totals. */
+  private recordUsage(usage: ITokenUsage, genMs: number): void {
+    this.lastUsage = usage;
+    this.metricsTotals.calls += 1;
+    this.metricsTotals.promptTokens += usage.promptTokens;
+    this.metricsTotals.completionTokens += usage.completionTokens;
+    this.metricsTotals.genMs += genMs;
+    this.metricsTotals.lastTokensPerSecond =
+      genMs > 0 ? (usage.completionTokens / genMs) * 1000 : 0;
+  }
+
   /** The real size of the context the model is currently holding — the prompt
    *  tokens of the last call (what auto-compaction watches), 0 before any call. */
   get contextTokens(): number {
@@ -940,6 +1005,8 @@ export class Session {
     const mcpSchemas = this.ctx.mcpRegistry?.toolSchemas() ?? [];
     const offeredTools =
       mcpSchemas.length > 0 ? [...baseTools, ...mcpSchemas] : baseTools;
+    const callStart = performance.now();
+    let firstTokenAt = 0;
     const res = await this.provider.complete(ctx.messages, {
       tools: offeredTools,
       temperature: this.cfg.temperature ?? 0,
@@ -950,6 +1017,12 @@ export class Session {
         : { thinkingTokenBudget: this.cfg.thinkingTokenBudget }),
       ...(signal === undefined ? {} : { signal }),
       onToken: (token, channel) => {
+        // Stamp the first token so tokens/sec measures generation rate (excluding
+        // prompt-processing / time-to-first-token), not total wall time.
+        if (firstTokenAt === 0) {
+          firstTokenAt = performance.now();
+        }
+
         // Stream EVERYTHING live — thinking, the tool calls being written, and
         // the answer itself (channel `content`), so the user watches the reply
         // arrive instead of staring at a frozen indicator. The renderer formats
@@ -960,17 +1033,23 @@ export class Session {
     });
 
     if (res.usage !== undefined) {
-      this.lastUsage = res.usage;
+      const ended = performance.now();
+      const genMs = firstTokenAt > 0 ? ended - firstTokenAt : ended - callStart;
+      const tps = genMs > 0 ? (res.usage.completionTokens / genMs) * 1000 : 0;
+
+      this.recordUsage(res.usage, genMs);
       // Logged (not shown) so the --log analyzer can compute tokens-to-solution.
       // `thinking` records THIS call's mode, so malformed-call rates can be
       // correlated with it (analyze-malformed).
       report({
         kind: "usage",
         task: SESSION_ID,
-        message: `tokens ${res.usage.promptTokens} in / ${res.usage.completionTokens} out`,
+        message: `tokens ${res.usage.promptTokens} in / ${res.usage.completionTokens} out · ${Math.round(tps)} tok/s`,
         promptTokens: res.usage.promptTokens,
         completionTokens: res.usage.completionTokens,
         totalTokens: res.usage.totalTokens,
+        tokensPerSecond: Math.round(tps),
+        ms: Math.round(genMs),
         ...(enableThinking === undefined ? {} : { thinking: enableThinking }),
       });
     }

package/src/render/ansi.ts

@@ -71,6 +71,10 @@ export function renderStatus(
     );
   }
 
+  if (info.tokensPerSecond !== undefined && info.tokensPerSecond > 0) {
+    bits.push(`${info.tokensPerSecond} tok/s`);
+  }
+
   bits.push(info.status, info.scope);
 
   return `${paint(`  ⎯ ${bits.join(" · ")}`, STYLE.dim, color)}\n`;

package/src/render/render.types.ts

@@ -18,4 +18,7 @@ export interface IStatusInfo {
   status: string;
   /** Editable scope label. */
   scope: string;
+  /** Output generation rate of the last model call (tokens/second); omitted or
+   *  0 before the first call. */
+  tokensPerSecond?: number;
 }

package/src/rule-packs/index.ts

@@ -1,5 +1,6 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
+import type { IRulePack } from "./rule-packs.types";
 import { bullmqPack } from "./bullmq";
 import { commentHygienePack } from "./comment-hygiene";
 import { codeFlowPack } from "./code-flow";
@@ -43,6 +44,31 @@ function isRulePackId(id: unknown): id is IRulePackId {
   return typeof id === "string" && id in RULE_PACKS;
 }
 
+/** Externally-registered rule packs (from tsforge.config.json `plugins`). Kept
+ *  separate from the built-in RULE_PACKS so a user pack can never shadow a
+ *  built-in by id; rule-name collisions still fail the build in
+ *  buildPackEslintConfig. */
+const EXTERNAL_PACKS = new Map<string, IRulePack>();
+
+/** Register an external rule pack so its id resolves in buildPackEslintConfig. */
+export function registerExternalPack(pack: IRulePack): void {
+  EXTERNAL_PACKS.set(pack.id, pack);
+}
+
+/** Drop all registered external packs (used by tests for isolation). */
+export function clearExternalPacks(): void {
+  EXTERNAL_PACKS.clear();
+}
+
+/** Resolve a pack id to its definition, built-ins first, then external packs. */
+function lookupPack(packId: string): IRulePack | undefined {
+  if (isRulePackId(packId)) {
+    return RULE_PACKS[packId];
+  }
+
+  return EXTERNAL_PACKS.get(packId);
+}
+
 /** Apply rule overrides: "off" drops a rule, error/warn replaces its severity. */
 function applyOverrides(
   mergedRulesConfig: Readonly<Record<string, "error" | "warn">>,
@@ -93,7 +119,7 @@ export function buildPackEslintConfig(
   const seenRuleNames = new Set<string>();
 
   for (const packId of packIds) {
-    const pack = isRulePackId(packId) ? RULE_PACKS[packId] : undefined;
+    const pack = lookupPack(packId);
 
     // Skip pack IDs known to stack-detection but absent from RULE_PACKS
     if (pack === undefined) {