@ordewell/core 0.12.1 → 0.12.2

package/dist/plan-utils.d.mts

@@ -5,6 +5,28 @@ import 'child_process';
 import 'zod/v4';
 import './ModeResolver-CA2fUU9h.mjs';
 
+/**
+ * The tips an empty planner chat composer shows (#137), one table for every
+ * surface so the TUI and the webview agree on the wording and how often each
+ * comes round. A surface offers only the tips for the commands it answers.
+ */
+interface ComposerTip {
+    /** The built-in planner chat command the tip names, without its slash. */
+    command: string;
+    /** How many times per cycle the tip comes round. */
+    weight: number;
+    /** Short enough to fit after the prompt and caret on an 80-column terminal. */
+    text: string;
+}
+declare const COMPOSER_TIPS: readonly ComposerTip[];
+/**
+ * The tip for the `seq`-th time the composer has been empty, among those for
+ * the commands the surface answers, or null when it answers none of them. The
+ * same `seq` always gives the same tip, so the surface decides when a new one
+ * shows by when it moves `seq` on, and its rendering stays a function of state.
+ */
+declare function composerTip(seq: number, answers: ReadonlySet<string>): string | null;
+
 /** A name or a path on a line of Ordewell's: as it stands, or quoted where it would break that line. */
 declare function onOneLine(text: string): string;
 
@@ -22,4 +44,4 @@ declare function clampThinkingEffort(effort: string | undefined, variants: {
     id: string;
 }[]): string | undefined;
 
-export { clampThinkingEffort, onOneLine };
+export { COMPOSER_TIPS, type ComposerTip, clampThinkingEffort, composerTip, onOneLine };

package/dist/plan-utils.d.ts

@@ -5,6 +5,28 @@ import 'child_process';
 import 'zod/v4';
 import './ModeResolver-B64aUZXJ.js';
 
+/**
+ * The tips an empty planner chat composer shows (#137), one table for every
+ * surface so the TUI and the webview agree on the wording and how often each
+ * comes round. A surface offers only the tips for the commands it answers.
+ */
+interface ComposerTip {
+    /** The built-in planner chat command the tip names, without its slash. */
+    command: string;
+    /** How many times per cycle the tip comes round. */
+    weight: number;
+    /** Short enough to fit after the prompt and caret on an 80-column terminal. */
+    text: string;
+}
+declare const COMPOSER_TIPS: readonly ComposerTip[];
+/**
+ * The tip for the `seq`-th time the composer has been empty, among those for
+ * the commands the surface answers, or null when it answers none of them. The
+ * same `seq` always gives the same tip, so the surface decides when a new one
+ * shows by when it moves `seq` on, and its rendering stays a function of state.
+ */
+declare function composerTip(seq: number, answers: ReadonlySet<string>): string | null;
+
 /** A name or a path on a line of Ordewell's: as it stands, or quoted where it would break that line. */
 declare function onOneLine(text: string): string;
 
@@ -22,4 +44,4 @@ declare function clampThinkingEffort(effort: string | undefined, variants: {
     id: string;
 }[]): string | undefined;
 
-export { clampThinkingEffort, onOneLine };
+export { COMPOSER_TIPS, type ComposerTip, clampThinkingEffort, composerTip, onOneLine };

package/dist/plan-utils.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var plan_utils_exports = {};
 __export(plan_utils_exports, {
   CHECKPOINT_TRUNCATE_LENGTH: () => CHECKPOINT_TRUNCATE_LENGTH,
+  COMPOSER_TIPS: () => COMPOSER_TIPS,
   DEFAULT_RUNNERS: () => DEFAULT_RUNNERS,
   DELEGATION_OFFERED: () => DELEGATION_OFFERED,
   EMPTY_CONVERSATION: () => EMPTY_CONVERSATION,
@@ -83,6 +84,7 @@ __export(plan_utils_exports, {
   clampThinkingEffort: () => clampThinkingEffort,
   closeTurn: () => closeTurn,
   compactionText: () => compactionText,
+  composerTip: () => composerTip,
   confirmedOverride: () => confirmedOverride,
   contextMeterText: () => contextMeterText,
   contextMeterTitle: () => contextMeterTitle,
@@ -1248,6 +1250,36 @@ function parseCount(arg, min) {
   return n >= min ? n : null;
 }
 
+// src/services/composerTips.ts
+var COMPOSER_TIPS = [
+  // The per-runner model allowlist (ADR-0003) is the easiest command to miss.
+  { command: "allowlist", weight: 3, text: "Tip: Use /allowlist to limit which models the planner assigns per runner." },
+  { command: "planner", weight: 1, text: "Tip: Use /planner to pick the planner's harness, model and effort." },
+  { command: "runners", weight: 1, text: "Tip: Use /runners to turn runners on or off." },
+  { command: "settings", weight: 1, text: "Tip: Use /settings for autonomy, supervisor, merging, autorun and more." },
+  { command: "help", weight: 1, text: "Tip: Use /help to list every command." }
+];
+function tipCycle(tips) {
+  const total = tips.reduce((sum, tip) => sum + Math.max(0, tip.weight), 0);
+  if (total === 0) return [];
+  const slots = new Array(total).fill(void 0);
+  const order = tips.map((tip, index) => ({ tip, index })).filter(({ tip }) => tip.weight > 0).sort((a, b) => b.tip.weight - a.tip.weight || a.index - b.index);
+  for (const { tip } of order) {
+    const free = slots.flatMap((slot, at) => slot === void 0 ? [at] : []);
+    for (let k = 0; k < tip.weight; k++) {
+      slots[free[Math.floor((k + 0.5) * free.length / tip.weight)]] = tip;
+    }
+  }
+  const cycle = slots.filter((tip) => tip !== void 0);
+  const start = cycle.indexOf(order[0].tip);
+  return [...cycle.slice(start), ...cycle.slice(0, start)];
+}
+function composerTip(seq, answers) {
+  const cycle = tipCycle(COMPOSER_TIPS.filter((tip) => answers.has(tip.command)));
+  if (cycle.length === 0) return null;
+  return cycle[(seq % cycle.length + cycle.length) % cycle.length].text;
+}
+
 // src/models/Usage.ts
 function partedPromptUsage(parts) {
   const reported2 = [parts.uncached, parts.cacheRead, parts.cacheWrite].filter((n) => n !== void 0);
@@ -3379,6 +3411,7 @@ function accountLimitsTitle(snapshot, time) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CHECKPOINT_TRUNCATE_LENGTH,
+  COMPOSER_TIPS,
   DEFAULT_RUNNERS,
   DELEGATION_OFFERED,
   EMPTY_CONVERSATION,
@@ -3431,6 +3464,7 @@ function accountLimitsTitle(snapshot, time) {
   clampThinkingEffort,
   closeTurn,
   compactionText,
+  composerTip,
   confirmedOverride,
   contextMeterText,
   contextMeterTitle,