@kuralle-agents/core 0.8.5 → 0.10.0

package/README.md

@@ -27,6 +27,7 @@ One tagless primitive — `defineAgent` — derives behavior from the fields you
 - **`createFactMemoryService`** — cross-session fact memory (LLM merge-on-ingest) keyed by `userId` on any persistent block store.
 - **Built-in guardrails** — `createPromptInjectionGuard`, `createPiiInputGuard`/`OutputGuard`, `createModerationGuard`, `createGroundingValidator` (see `guides/GUARDRAILS.md`).
 - **Simulation eval** — `simulateConversation` + `createJudge` + `runSimulationSuite`: persona-driven simulated users scored by an LLM judge.
+- **Pending-input drain-and-merge** — `setPendingUserInput` / `consumeAllPendingUserInput`: mid-turn messages enqueue; the next `awaitUser` drains the FIFO into one merged turn (pair with `@kuralle-agents/messaging` `inboundCoalescing` for WhatsApp bursts).
 
 ## Usage
 
@@ -46,8 +47,7 @@ const agent = defineAgent({
   id: 'support',
   instructions: 'You are a helpful support agent.',
   model: openai('gpt-4o-mini'),
-  tools: buildToolSet({ echo }),   // model-visible
-  tools: { echo },           // durable executor
+  tools: { echo },   // durable effect tools — model-visible AND executor-registered
 });
 
 const runtime = createRuntime({ agents: [agent], defaultAgentId: 'support' });

package/dist/index.d.ts

@@ -118,4 +118,5 @@ export type { RunContext, ToolContext, ActionContext } from './types/run-context
 export type { AnyTool } from './types/effectTool.js';
 export { createRuntime, Runtime, type HarnessConfig, type RunOptions, } from './runtime/Runtime.js';
 export type { RuntimeLike } from './runtime/RuntimeLike.js';
-export { userInputToText, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './runtime/userInput.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './runtime/userInput.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './runtime/channels/inputBuffer.js';

package/dist/index.js

@@ -59,4 +59,5 @@ export { parseConfirmation } from './flow/confirmParse.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export { DURABLE_RUNS_KEY } from './runtime/durable/types.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';
-export { userInputToText, hasMediaParts, transcribeAudioParts, } from './runtime/userInput.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, } from './runtime/userInput.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './runtime/channels/inputBuffer.js';

package/dist/runtime/channels/TextDriver.js

@@ -2,7 +2,7 @@ import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
-import { consumePendingUserInput } from './inputBuffer.js';
+import { consumeAllPendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
@@ -167,7 +167,7 @@ export class TextDriver {
         return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
-        const input = consumePendingUserInput(ctx.session);
+        const input = consumeAllPendingUserInput(ctx.session) ?? '';
         return { type: 'message', input };
     }
     resolveTools(resolved, ctx) {

package/dist/runtime/channels/index.d.ts

@@ -4,4 +4,4 @@ export type { TextDriverConfig } from './TextDriver.js';
 export { VoiceDriver } from './VoiceDriver.js';
 export type { VoiceDriverConfig } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -5,4 +5,4 @@ export { TextDriver, buildNodePrompt } from './TextDriver.js';
 // the primary primitive; cascaded voice runs over text (see livekit-plugin).
 export { VoiceDriver } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/inputBuffer.d.ts

@@ -1,6 +1,9 @@
 import type { Session } from '../../types/session.js';
-import type { UserInputContent } from '../userInput.js';
+import { type UserInputContent } from '../userInput.js';
 export declare function setPendingUserInput(session: Session, input: UserInputContent): void;
+/** Dequeue one pending input. Built-in drivers drain the full queue via {@link consumeAllPendingUserInput}. */
 export declare function consumePendingUserInput(session: Session): UserInputContent;
+/** Drain the pending-input FIFO and merge into one turn (mid-turn enqueue-merge). */
+export declare function consumeAllPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function peekPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function hasPendingUserInput(session: Session): boolean;

package/dist/runtime/channels/inputBuffer.js

@@ -1,3 +1,4 @@
+import { mergeUserInputContents } from '../userInput.js';
 const PENDING_INPUT_KEY = '__v2_pendingUserInput';
 function queue(session) {
     const v = session.workingMemory[PENDING_INPUT_KEY];
@@ -10,6 +11,7 @@ function queue(session) {
 export function setPendingUserInput(session, input) {
     session.workingMemory[PENDING_INPUT_KEY] = [...queue(session), input];
 }
+/** Dequeue one pending input. Built-in drivers drain the full queue via {@link consumeAllPendingUserInput}. */
 export function consumePendingUserInput(session) {
     const q = queue(session);
     const next = q.shift() ?? '';
@@ -19,6 +21,12 @@ export function consumePendingUserInput(session) {
         session.workingMemory[PENDING_INPUT_KEY] = q;
     return next;
 }
+/** Drain the pending-input FIFO and merge into one turn (mid-turn enqueue-merge). */
+export function consumeAllPendingUserInput(session) {
+    const q = queue(session);
+    delete session.workingMemory[PENDING_INPUT_KEY];
+    return mergeUserInputContents(q);
+}
 export function peekPendingUserInput(session) {
     return queue(session)[0];
 }

package/dist/runtime/index.d.ts

@@ -3,6 +3,6 @@ export type { RuntimeLike } from './RuntimeLike.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
 export { TextDriver, VoiceDriver } from './channels/index.js';
 export type { VoiceDriverConfig } from './channels/index.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
-export { userInputToText, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -4,9 +4,9 @@ export { TextDriver, VoiceDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to
 // implement awaitUser the same FIFO-aware way the built-in drivers do (the
 // buffer is an ordered queue since 0.3.13/H3, not a single slot).
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 // Multimodal user input — `UserInputContent` is the runtime's accepted user-turn
 // shape (text or AI SDK file/image/audio parts). Helpers project to text and
 // transcribe audio so ingress adapters (web/messaging) can build it uniformly.
-export { userInputToText, hasMediaParts, transcribeAudioParts, } from './userInput.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, } from './userInput.js';
 export { isAbortSignal, } from '../types/index.js';

package/dist/runtime/userInput.d.ts

@@ -10,6 +10,8 @@ import { type UserContent, type TranscriptionModel } from 'ai';
  * input buffer are all persisted through the `SessionStore` (JSON/Redis/Postgres).
  */
 export type UserInputContent = UserContent;
+/** Merge multiple user inputs into one turn (ingress coalescing / mid-turn drain). */
+export declare function mergeUserInputContents(items: UserInputContent[]): UserInputContent | undefined;
 /** Text projection of user input — for confirm-gate parsing, choice matching, and
  *  extraction hints. Non-text parts are dropped. A plain string returns as-is. */
 export declare function userInputToText(input: UserInputContent): string;

package/dist/runtime/userInput.js

@@ -23,6 +23,26 @@ function audioSource(data) {
     }
     return data;
 }
+/** Merge multiple user inputs into one turn (ingress coalescing / mid-turn drain). */
+export function mergeUserInputContents(items) {
+    if (items.length === 0)
+        return undefined;
+    if (items.length === 1)
+        return items[0];
+    const parts = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            if (item.length > 0)
+                parts.push({ type: 'text', text: item });
+        }
+        else {
+            parts.push(...item);
+        }
+    }
+    if (parts.length === 0)
+        return '';
+    return parts;
+}
 /** Text projection of user input — for confirm-gate parsing, choice matching, and
  *  extraction hints. Non-text parts are dropped. A plain string returns as-is. */
 export function userInputToText(input) {

package/dist/tools/fs/createFsTool.js

@@ -122,7 +122,11 @@ export function createFsTool(opts) {
     const { fs, readOnly = DEFAULT_READ_ONLY, timeoutMs } = opts;
     return defineTool({
         name: 'workspace',
-        description: 'Explore and edit the agent workspace. Ops: ls, cat, grep, find, read, write, edit.',
+        description: 'Explore and edit the agent workspace. Cheapest first: ls/find to locate files, ' +
+            'grep for exact terms, names, codes, or keywords (returns matching lines only), ' +
+            'cat/read for full file contents. Prefer grep over semantic knowledge search when ' +
+            'the user mentions an exact term or identifier — it is faster, cheaper, and exact. ' +
+            'Ops: ls, cat, grep, find, read, write, edit.',
         timeoutMs,
         input: workspaceInput,
         execute: async (args) => {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.8.5",
+  "version": "0.10.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/realtime-audio": "0.8.5"
+    "@kuralle-agents/realtime-audio": "0.10.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"