@burtson-labs/agent-core 1.6.46 → 1.6.48

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export interface CreateAgentRuntimeOptions extends Partial<Omit<AgentRuntimeOpti
 export declare const createAgentRuntime: (options?: CreateAgentRuntimeOptions) => AgentRuntime;
 export * from './tools';
 export * from './graph';
+export * from './suggestions';
+export * from './lessons';
 export * from './mcp';
 export { redactSecrets, redactSecretsString, BUILTIN_SECRET_PATTERNS, type SecretPattern, type RedactionResult } from './security/secretPatterns';
 export { TelemetryExporter, resolveTelemetryConfig, TTFT_BUCKETS, DURATION_BUCKETS, type TelemetryConfig } from './telemetry/otlpExporter';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,yBAA0B,SAAQ,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC;IAC/F,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAS,yBAA8B,KAAG,YAO5E,CAAC;AAGF,cAAc,SAAS,CAAC;AAGxB,cAAc,SAAS,CAAC;AAKxB,cAAc,OAAO,CAAC;AAKtB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,yBAA0B,SAAQ,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC;IAC/F,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAS,yBAA8B,KAAG,YAO5E,CAAC;AAGF,cAAc,SAAS,CAAC;AAGxB,cAAc,SAAS,CAAC;AAExB,cAAc,eAAe,CAAC;AAE9B,cAAc,WAAW,CAAC;AAK1B,cAAc,OAAO,CAAC;AAKtB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -41,6 +41,10 @@ __exportStar(require("./tools"), exports);
 // Graph runtime (DAG of loop-wrapping nodes). Nothing in the framework
 // consumes it yet — hosts opt in explicitly; zero behavior change until then.
 __exportStar(require("./graph"), exports);
+// Next-prompt prediction (composer "what's next?" suggestions).
+__exportStar(require("./suggestions"), exports);
+// Learning memory — distill durable repo lessons from turns (host stores them).
+__exportStar(require("./lessons"), exports);
 // MCP — Model Context Protocol client (Phase 1: groundwork). See
 // docs/integration-playlist/mcp-roadmap.md. Off by default — hosts
 // that don't construct an McpClientPool get zero behavior change.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AACA,yDAAsD;AACtD,+EAAiF;AAGjF,gDAA8B;AAC9B,gDAA8B;AAC9B,uCAAkD;AAAzC,0GAAA,iBAAiB,OAAA;AAE1B,+DAIqC;AADnC,oHAAA,iBAAiB,OAAA;AAGnB,6EAG4C;AAF1C,qIAAA,2BAA2B,OAAA;AAI7B,uDAUgC;AAT9B,4GAAA,YAAY,OAAA;AAeP,MAAM,kBAAkB,GAAG,CAAC,UAAqC,EAAE,EAAgB,EAAE;IAC1F,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,QAAQ,GAAG,gBAAgB,IAAI,IAAI,oDAA2B,EAAE,CAAC;IACvE,OAAO,IAAI,2BAAY,CAAC;QACtB,QAAQ;QACR,GAAI,IAA8C;KACnD,CAAC,CAAC;AACL,CAAC,CAAC;AAPW,QAAA,kBAAkB,sBAO7B;AAEF,cAAc;AACd,0CAAwB;AACxB,uEAAuE;AACvE,8EAA8E;AAC9E,0CAAwB;AAExB,iEAAiE;AACjE,mEAAmE;AACnE,kEAAkE;AAClE,wCAAsB;AAEtB,wDAAwD;AACxD,mEAAmE;AACnE,4CAA4C;AAC5C,4DAMmC;AALjC,+GAAA,aAAa,OAAA;AACb,qHAAA,mBAAmB,OAAA;AACnB,yHAAA,uBAAuB,OAAA;AAKzB,iFAAiF;AACjF,iFAAiF;AACjF,yDAMkC;AALhC,iHAAA,iBAAiB,OAAA;AACjB,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,gHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AACA,yDAAsD;AACtD,+EAAiF;AAGjF,gDAA8B;AAC9B,gDAA8B;AAC9B,uCAAkD;AAAzC,0GAAA,iBAAiB,OAAA;AAE1B,+DAIqC;AADnC,oHAAA,iBAAiB,OAAA;AAGnB,6EAG4C;AAF1C,qIAAA,2BAA2B,OAAA;AAI7B,uDAUgC;AAT9B,4GAAA,YAAY,OAAA;AAeP,MAAM,kBAAkB,GAAG,CAAC,UAAqC,EAAE,EAAgB,EAAE;IAC1F,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,QAAQ,GAAG,gBAAgB,IAAI,IAAI,oDAA2B,EAAE,CAAC;IACvE,OAAO,IAAI,2BAAY,CAAC;QACtB,QAAQ;QACR,GAAI,IAA8C;KACnD,CAAC,CAAC;AACL,CAAC,CAAC;AAPW,QAAA,kBAAkB,sBAO7B;AAEF,cAAc;AACd,0CAAwB;AACxB,uEAAuE;AACvE,8EAA8E;AAC9E,0CAAwB;AACxB,gEAAgE;AAChE,gDAA8B;AAC9B,gFAAgF;AAChF,4CAA0B;AAE1B,iEAAiE;AACjE,mEAAmE;AACnE,kEAAkE;AAClE,wCAAsB;AAEtB,wDAAwD;AACxD,mEAAmE;AACnE,4CAA4C;AAC5C,4DAMmC;AALjC,+GAAA,aAAa,OAAA;AACb,qHAAA,mBAAmB,OAAA;AACnB,yHAAA,uBAAuB,OAAA;AAKzB,iFAAiF;AACjF,iFAAiF;AACjF,yDAMkC;AALhC,iHAAA,iBAAiB,OAAA;AACjB,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,gHAAA,gBAAgB,OAAA"}

package/dist/lessons.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Learning memory — the distiller half.
+ *
+ * After a turn, the host may make ONE cheap model call asking: did anything
+ * DURABLE and REPO-GENERAL happen here worth remembering for future tasks?
+ * ("this project uses pnpm, not npm"; "tests for src/api live in test/api";
+ * "the build fails unless you run codegen first"). Most turns yield nothing —
+ * the point is to accrue a SMALL set of high-signal, reusable facts about a
+ * specific repo, not a diary. Those facts are stored (see host-kit's lesson
+ * store) and injected on future turns so the agent gets better at THIS repo
+ * over time.
+ *
+ * This module is the shared, host-agnostic core: build the (small) prompt,
+ * parse the reply into a lesson or nothing. Pure + fully unit-testable, same
+ * split as the planner and next-prompt suggestions. The host owns the model
+ * call, the persistence, and the opt-in gate (off by default — it's an extra
+ * call per turn, and a store the model writes to deserves a deliberate opt-in).
+ */
+export interface LessonTurn {
+    /** The user's prompt for the turn. */
+    prompt: string;
+    /** The assistant's final response. */
+    assistantResponse: string;
+    /** Tool names used this turn, in order (optional but sharpens distillation). */
+    toolsUsed?: string[];
+    /** Whether the turn succeeded, if the host knows (a failure often teaches
+     *  the most durable lesson — "X doesn't work here, do Y"). */
+    outcome?: 'ok' | 'error';
+}
+/** The sentinel a well-behaved model returns when nothing is worth storing. */
+export declare const NO_LESSON = "NONE";
+export declare function buildLessonPrompt(turn: LessonTurn): string;
+/**
+ * Parse the distiller reply into a lesson, or null when nothing was learned.
+ * Never throws. Filters NONE, empties, over-long/paragraph replies, and the
+ * "here's a lesson:" preamble the model sometimes adds.
+ */
+export declare function parseLesson(text: string): string | null;
+/** Normalize a lesson for dedup comparison (lowercase, collapse whitespace,
+ *  drop trailing punctuation). Two lessons that normalize equal are dupes. */
+export declare function normalizeLesson(lesson: string): string;
+//# sourceMappingURL=lessons.d.ts.map

package/dist/lessons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.d.ts","sourceRoot":"","sources":["../src/lessons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;kEAC8D;IAC9D,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;CAC1B;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAwB1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAevD;AAED;8EAC8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/lessons.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Learning memory — the distiller half.
+ *
+ * After a turn, the host may make ONE cheap model call asking: did anything
+ * DURABLE and REPO-GENERAL happen here worth remembering for future tasks?
+ * ("this project uses pnpm, not npm"; "tests for src/api live in test/api";
+ * "the build fails unless you run codegen first"). Most turns yield nothing —
+ * the point is to accrue a SMALL set of high-signal, reusable facts about a
+ * specific repo, not a diary. Those facts are stored (see host-kit's lesson
+ * store) and injected on future turns so the agent gets better at THIS repo
+ * over time.
+ *
+ * This module is the shared, host-agnostic core: build the (small) prompt,
+ * parse the reply into a lesson or nothing. Pure + fully unit-testable, same
+ * split as the planner and next-prompt suggestions. The host owns the model
+ * call, the persistence, and the opt-in gate (off by default — it's an extra
+ * call per turn, and a store the model writes to deserves a deliberate opt-in).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_LESSON = void 0;
+exports.buildLessonPrompt = buildLessonPrompt;
+exports.parseLesson = parseLesson;
+exports.normalizeLesson = normalizeLesson;
+/** The sentinel a well-behaved model returns when nothing is worth storing. */
+exports.NO_LESSON = 'NONE';
+function buildLessonPrompt(turn) {
+    const tools = turn.toolsUsed?.length ? `\nTools used: ${turn.toolsUsed.join(', ')}` : '';
+    const outcome = turn.outcome ? `\nOutcome: ${turn.outcome}` : '';
+    const clip = (s, n) => (s.length > n ? s.slice(0, n) + '…' : s);
+    return [
+        'You maintain a small memory of DURABLE facts about THIS specific repository, to help future coding tasks.',
+        'Look at the turn below and decide: did it reveal a fact that is (a) specific to this repo, (b) still true next week, and (c) genuinely useful for a future task?',
+        '',
+        'Good lessons (store these):',
+        '- "This project uses pnpm; npm install breaks the workspace."',
+        '- "Tests for src/api/* live in test/api/* and must be updated alongside."',
+        '- "The build needs `pnpm codegen` run before `pnpm build`."',
+        '',
+        'NOT lessons (never store these):',
+        '- Anything about this ONE task ("added a clamp function") — that\'s history, not a durable fact.',
+        '- Generic programming advice true of any repo.',
+        '- Anything you are not confident is actually true of this repo.',
+        '',
+        `Reply with ONE short sentence (the lesson, max ~140 chars) OR exactly "${exports.NO_LESSON}" if nothing durable was learned. Most turns are "${exports.NO_LESSON}". No preamble, no quotes, no markdown.`,
+        '',
+        '--- turn ---',
+        `User: ${clip(turn.prompt, 500)}`,
+        `Assistant: ${clip(turn.assistantResponse, 800)}${tools}${outcome}`,
+    ].join('\n');
+}
+/**
+ * Parse the distiller reply into a lesson, or null when nothing was learned.
+ * Never throws. Filters NONE, empties, over-long/paragraph replies, and the
+ * "here's a lesson:" preamble the model sometimes adds.
+ */
+function parseLesson(text) {
+    let s = (text ?? '').trim();
+    if (!s)
+        return null;
+    // Strip a leading "lesson:" / "fact:" label if present.
+    s = s.replace(/^\s*(lesson|fact|answer)\s*:\s*/i, '').trim();
+    // Strip surrounding quotes/backticks/markdown bullet.
+    s = s.replace(/^[-*]\s+/, '').replace(/^["'`]+|["'`]+$/g, '').trim();
+    if (!s)
+        return null;
+    // Explicit "nothing to learn" in any casing/punctuation.
+    if (/^none[.!]?$/i.test(s))
+        return null;
+    // A model that ignored instructions and wrote a paragraph isn't a lesson.
+    if (s.length > 200)
+        return null;
+    // Refuse suspiciously generic non-facts.
+    if (/^(no|n\/a|nothing|not applicable|no lesson)\b/i.test(s))
+        return null;
+    return s;
+}
+/** Normalize a lesson for dedup comparison (lowercase, collapse whitespace,
+ *  drop trailing punctuation). Two lessons that normalize equal are dupes. */
+function normalizeLesson(lesson) {
+    return lesson.toLowerCase().replace(/\s+/g, ' ').replace(/[.!]+$/g, '').trim();
+}
+//# sourceMappingURL=lessons.js.map

package/dist/lessons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.js","sourceRoot":"","sources":["../src/lessons.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAiBH,8CAwBC;AAOD,kCAeC;AAID,0CAEC;AAvDD,+EAA+E;AAClE,QAAA,SAAS,GAAG,MAAM,CAAC;AAEhC,SAAgB,iBAAiB,CAAC,IAAgB;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,OAAO;QACL,2GAA2G;QAC3G,kKAAkK;QAClK,EAAE;QACF,6BAA6B;QAC7B,+DAA+D;QAC/D,2EAA2E;QAC3E,6DAA6D;QAC7D,EAAE;QACF,kCAAkC;QAClC,kGAAkG;QAClG,gDAAgD;QAChD,iEAAiE;QACjE,EAAE;QACF,0EAA0E,iBAAS,qDAAqD,iBAAS,yCAAyC;QAC1L,EAAE;QACF,cAAc;QACd,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;QACjC,cAAc,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,OAAO,EAAE;KACpE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,wDAAwD;IACxD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,kCAAkC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,sDAAsD;IACtD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,yDAAyD;IACzD,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,0EAA0E;IAC1E,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAChC,yCAAyC;IACzC,IAAI,gDAAgD,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,CAAC,CAAC;AACX,CAAC;AAED;8EAC8E;AAC9E,SAAgB,eAAe,CAAC,MAAc;IAC5C,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACjF,CAAC"}

package/dist/suggestions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Next-prompt prediction — the "what will you ask next?" composer feature.
+ *
+ * After a turn completes, a host may make ONE cheap, separate model call to
+ * suggest the user's likely next prompts, rendered as selectable chips (IDE)
+ * or a hint line (CLI). This module is the shared, host-agnostic core: it
+ * builds the (small) prompt and parses the reply. The host owns the model
+ * call + rendering, so CLI and extension share identical behavior.
+ *
+ * Mirrors the planner's split (buildPlannerPrompt / parseGraphProposal): pure
+ * functions, no IO, fully unit-testable. Deliberately tiny — this is a
+ * latency- and token-sensitive path that runs after every eligible turn, so
+ * the prompt is short and the reply is capped.
+ *
+ * Cost-gating is the host's job and defaults OFF (an extra call per turn is
+ * exactly the kind of opt-in cost the framework keeps off by default).
+ */
+export interface SuggestionTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface SuggestionPromptOptions {
+    /** How many suggestions to ask for. Default 3; clamped to 1..5. */
+    count?: number;
+    /** Recently touched files, to bias suggestions toward the actual work. */
+    recentFiles?: string[];
+    /** Max chars of each turn we include (keeps the prompt cheap). Default 600. */
+    perTurnChars?: number;
+}
+/** Build the suggestion prompt from the tail of the conversation. */
+export declare function buildSuggestionsPrompt(conversation: SuggestionTurn[], opts?: SuggestionPromptOptions): string;
+/**
+ * Parse suggestions from the model reply. Accepts a ```json fence or a bare
+ * array; tolerates prose around it. Never throws — returns [] on anything
+ * unparseable, deduped, trimmed, and capped.
+ */
+export declare function parseSuggestions(text: string, max?: number): string[];
+//# sourceMappingURL=suggestions.d.ts.map

package/dist/suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.ts","sourceRoot":"","sources":["../src/suggestions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,cAAc,EAAE,EAC9B,IAAI,GAAE,uBAA4B,GACjC,MAAM,CAuBR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAyBhE"}

package/dist/suggestions.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Next-prompt prediction — the "what will you ask next?" composer feature.
+ *
+ * After a turn completes, a host may make ONE cheap, separate model call to
+ * suggest the user's likely next prompts, rendered as selectable chips (IDE)
+ * or a hint line (CLI). This module is the shared, host-agnostic core: it
+ * builds the (small) prompt and parses the reply. The host owns the model
+ * call + rendering, so CLI and extension share identical behavior.
+ *
+ * Mirrors the planner's split (buildPlannerPrompt / parseGraphProposal): pure
+ * functions, no IO, fully unit-testable. Deliberately tiny — this is a
+ * latency- and token-sensitive path that runs after every eligible turn, so
+ * the prompt is short and the reply is capped.
+ *
+ * Cost-gating is the host's job and defaults OFF (an extra call per turn is
+ * exactly the kind of opt-in cost the framework keeps off by default).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSuggestionsPrompt = buildSuggestionsPrompt;
+exports.parseSuggestions = parseSuggestions;
+/** Build the suggestion prompt from the tail of the conversation. */
+function buildSuggestionsPrompt(conversation, opts = {}) {
+    const count = Math.min(5, Math.max(1, opts.count ?? 3));
+    const perTurnChars = opts.perTurnChars ?? 600;
+    // Only the last few turns matter for "what's next"; keep it small.
+    const tail = conversation.slice(-4).map((t) => {
+        const body = t.content.length > perTurnChars ? t.content.slice(0, perTurnChars) + '…' : t.content;
+        return `${t.role === 'user' ? 'User' : 'Assistant'}: ${body}`;
+    });
+    const filesLine = opts.recentFiles?.length
+        ? `\nRecently touched: ${opts.recentFiles.slice(0, 8).join(', ')}`
+        : '';
+    return [
+        `You suggest the user's likely NEXT prompts in a coding assistant. Based on the exchange below, output ${count} short, concrete follow-ups the user would plausibly type next — the natural next steps (run the tests, commit, explain a change, handle an edge case, etc.).`,
+        '',
+        'Rules:',
+        `- Each suggestion is an imperative the USER would type (e.g. "run the tests", "commit with a message", "add error handling to the parser"). Not questions you'd ask them.`,
+        '- Short: 3-8 words. Specific to what just happened, not generic.',
+        `- Output ONLY a JSON array of ${count} strings in a \`\`\`json fence. Nothing else.`,
+        filesLine,
+        '',
+        'Recent exchange:',
+        ...tail,
+    ].join('\n');
+}
+/**
+ * Parse suggestions from the model reply. Accepts a ```json fence or a bare
+ * array; tolerates prose around it. Never throws — returns [] on anything
+ * unparseable, deduped, trimmed, and capped.
+ */
+function parseSuggestions(text, max = 5) {
+    const raw = extractJsonArray(text);
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of parsed) {
+        if (typeof item !== 'string')
+            continue;
+        const s = item.trim().replace(/^["'`]|["'`]$/g, '').trim();
+        // Drop empties, over-long entries, and question-shaped items (we want
+        // user imperatives, not the model interviewing the user).
+        if (!s || s.length > 80)
+            continue;
+        const key = s.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/** First ```json (or ```) fenced array, else the first bracket-balanced [...]. */
+function extractJsonArray(text) {
+    const fence = /```(?:json)?\s*(\[[\s\S]*?\])\s*```/.exec(text);
+    if (fence)
+        return fence[1].trim();
+    const start = text.indexOf('[');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === '[')
+            depth += 1;
+        else if (ch === ']') {
+            depth -= 1;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=suggestions.js.map

package/dist/suggestions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burtson-labs/agent-core",
-  "version": "1.6.46",
+  "version": "1.6.48",
   "author": {
     "name": "Burtson Labs",
     "email": "team@burtson.ai",