@ixo/oracle-runtime 0.0.1

package/dist/graph/middlewares/summarization-middleware.js

@@ -0,0 +1,62 @@
+import { summarizationMiddleware } from 'langchain';
+/**
+ * IXO-flavoured prompt instructing the summarizer to preserve identifiers
+ * verbatim (DIDs, room IDs, addresses, hashes, URLs, etc.). Replaces the
+ * default LangChain summary prompt without changing the wider trigger logic.
+ */
+const SUMMARY_PROMPT = `<role>
+Context Extraction Assistant
+</role>
+
+<primary_objective>
+Extract the most important context from the conversation history below. This extracted context will REPLACE the full conversation history, so capture everything the agent needs to continue working effectively.
+</primary_objective>
+
+<critical_identifiers>
+You MUST preserve ALL of the following VERBATIM — copy them exactly as they appear:
+- DIDs (decentralized identifiers, e.g. did:ixo:..., did:x:..., did:key:...)
+- Matrix Room IDs (e.g. !abc123:matrix.ixo.world)
+- Wallet/account addresses (e.g. ixo1..., cosmos1...)
+- Session IDs, thread IDs, or checkpoint IDs
+- Blockchain transaction hashes or entity IDs
+- Any URLs, endpoints, or API paths referenced
+- Block IDs (UUIDs) from document editing
+Do NOT paraphrase, abbreviate, or omit any of these identifiers.
+</critical_identifiers>
+
+<what_to_extract>
+1. **Active task**: What is the agent currently working on? What was the user's most recent request?
+2. **Key decisions & outcomes**: What has been decided or completed so far?
+3. **Pending actions**: What still needs to be done?
+4. **Important data**: Any structured data, configurations, or parameters the agent was working with
+5. **All identifiers**: Every DID, room ID, address, hash listed above — verbatim
+6. **Tool results**: Key outputs from tool calls that inform next steps
+7. **Errors or blockers**: Any issues encountered that are still relevant
+</what_to_extract>
+
+<format>
+Structure the extracted context clearly with sections. Be concise but complete — the agent will lose all context not captured here.
+Respond ONLY with the extracted context. No preamble, no explanation.
+</format>
+
+<messages>
+Messages to summarize:
+{messages}
+</messages>`;
+const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
+const DEFAULT_TRIGGER_MESSAGES = 20;
+const DEFAULT_KEEP_MESSAGES = 10;
+/**
+ * Wraps LangChain's built-in `summarizationMiddleware` with the IXO-specific
+ * summary prompt + prefix. Pass any compatible chat model — typically the
+ * cheap "routing" role.
+ */
+export const createSummarizationMiddleware = (options) => {
+    return summarizationMiddleware({
+        model: options.model,
+        summaryPrompt: SUMMARY_PROMPT,
+        summaryPrefix: SUMMARY_PREFIX,
+        trigger: { messages: options.triggerMessages ?? DEFAULT_TRIGGER_MESSAGES },
+        keep: { messages: options.keepMessages ?? DEFAULT_KEEP_MESSAGES },
+    });
+};

package/dist/graph/middlewares/tool-repetition-guard-middleware.d.ts

@@ -0,0 +1,24 @@
+import { type AgentMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types.js';
+export interface ToolRepetitionGuardMiddlewareOptions {
+    /**
+     * How many messages back to scan for a prior identical failed call.
+     * Default 20 — enough to catch in-turn loops without trawling whole histories.
+     */
+    lookback?: number;
+    /** Optional logger; defaults to a no-op. */
+    logger?: Logger;
+}
+/**
+ * Detects when the agent issues the same `(toolName, args)` pair after that
+ * exact call already failed inside the recent window, and short-circuits
+ * before the tool is invoked again. The short-circuit message quotes the
+ * earlier error and tells the model to change tools/args instead.
+ *
+ * Why this exists: in-turn retry loops where the LLM ignores a tool's error
+ * envelope and re-issues the identical call. The existing
+ * `toolRetryMiddleware` retries inside one call; this guard prevents the
+ * model from making the *next* identical call.
+ */
+export declare const createToolRepetitionGuardMiddleware: (options?: ToolRepetitionGuardMiddlewareOptions) => AgentMiddleware;
+//# sourceMappingURL=tool-repetition-guard-middleware.d.ts.map

package/dist/graph/middlewares/tool-repetition-guard-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-repetition-guard-middleware.d.ts","sourceRoot":"","sources":["../../../src/graph/middlewares/tool-repetition-guard-middleware.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,WAAW,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAQxD,MAAM,WAAW,oCAAoC;IACnD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mCAAmC,GAC9C,UAAS,oCAAyC,KACjD,eAiDF,CAAC"}

package/dist/graph/middlewares/tool-repetition-guard-middleware.js

@@ -0,0 +1,112 @@
+import { AIMessage, ToolMessage, } from '@langchain/core/messages';
+import { createMiddleware } from 'langchain';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * Detects when the agent issues the same `(toolName, args)` pair after that
+ * exact call already failed inside the recent window, and short-circuits
+ * before the tool is invoked again. The short-circuit message quotes the
+ * earlier error and tells the model to change tools/args instead.
+ *
+ * Why this exists: in-turn retry loops where the LLM ignores a tool's error
+ * envelope and re-issues the identical call. The existing
+ * `toolRetryMiddleware` retries inside one call; this guard prevents the
+ * model from making the *next* identical call.
+ */
+export const createToolRepetitionGuardMiddleware = (options = {}) => {
+    const logger = options.logger ?? NOOP_LOGGER;
+    const lookback = options.lookback ?? 20;
+    return createMiddleware({
+        name: 'ToolRepetitionGuardMiddleware',
+        wrapToolCall: async (toolCallRequest, handler) => {
+            const { toolCall, state } = toolCallRequest;
+            const toolName = toolCall.name ?? toolCallRequest.tool?.name;
+            if (!toolName)
+                return handler(toolCallRequest);
+            const argsKey = canonicalArgsKey(toolCall.args);
+            const messages = state.messages ?? [];
+            const start = Math.max(0, messages.length - lookback);
+            for (let i = messages.length - 1; i >= start; i--) {
+                const msg = messages[i];
+                if (!(msg instanceof ToolMessage))
+                    continue;
+                if (msg.status !== 'error')
+                    continue;
+                if (msg.name !== toolName)
+                    continue;
+                const priorArgs = findToolCallArgsById(messages, msg.tool_call_id);
+                if (priorArgs === undefined)
+                    continue;
+                if (canonicalArgsKey(priorArgs) !== argsKey)
+                    continue;
+                const priorError = toolMessageText(msg);
+                logger.warn(`Repetition guard: short-circuiting duplicate failed call to ${toolName}`, { toolName, priorError });
+                return new ToolMessage({
+                    content: [
+                        `You already called \`${toolName}\` with these exact arguments earlier in this turn and it failed with:`,
+                        '',
+                        priorError,
+                        '',
+                        'Do NOT repeat the same call. Read the error message, then either:',
+                        '- change the arguments to satisfy the constraint the error describes, OR',
+                        '- pick a different tool that fits the constraint.',
+                    ].join('\n'),
+                    tool_call_id: toolCall.id ?? '',
+                    name: toolName,
+                    status: 'error',
+                });
+            }
+            return handler(toolCallRequest);
+        },
+    });
+};
+function canonicalArgsKey(args) {
+    if (args === null || args === undefined)
+        return 'null';
+    if (typeof args !== 'object')
+        return JSON.stringify(args);
+    if (Array.isArray(args)) {
+        return `[${args.map(canonicalArgsKey).join(',')}]`;
+    }
+    const obj = args;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalArgsKey(obj[k])}`).join(',')}}`;
+}
+function toolMessageText(msg) {
+    const content = msg.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((block) => {
+            if (typeof block === 'string')
+                return block;
+            if (block && typeof block === 'object' && 'text' in block) {
+                const text = block.text;
+                return typeof text === 'string' ? text : '';
+            }
+            return '';
+        })
+            .join('\n');
+    }
+    return '';
+}
+function findToolCallArgsById(messages, callId) {
+    if (!callId)
+        return undefined;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (!AIMessage.isInstance(m))
+            continue;
+        const toolCalls = m.tool_calls;
+        if (!toolCalls)
+            continue;
+        const hit = toolCalls.find((tc) => tc.id === callId);
+        if (hit)
+            return hit.args;
+    }
+    return undefined;
+}

package/dist/graph/middlewares/tool-validation-middleware.d.ts

@@ -0,0 +1,24 @@
+import { type AgentMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types.js';
+export interface ToolValidationMiddlewareOptions {
+    /**
+     * Tool names whose dangling `ToolMessage` outputs should be stripped before
+     * the next model call. These are typically sub-agent tools whose responses
+     * are summarised by their parent agent rather than being interpreted by the
+     * model directly.
+     */
+    skipToolNames?: string[];
+    /** Optional logger; defaults to a no-op. */
+    logger?: Logger;
+}
+/**
+ * Catches tool validation errors (Zod / schema mismatches) and turns them
+ * into a `ToolMessage` describing the failure, so the model can recover
+ * instead of the graph crashing.
+ *
+ * Also strips `ToolMessage`s for tools listed in `skipToolNames` from the
+ * state before the next model call — used today for sub-agent tools whose
+ * structured output is consumed by their callers, not the LLM.
+ */
+export declare const createToolValidationMiddleware: (options?: ToolValidationMiddlewareOptions) => AgentMiddleware;
+//# sourceMappingURL=tool-validation-middleware.d.ts.map

package/dist/graph/middlewares/tool-validation-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-validation-middleware.d.ts","sourceRoot":"","sources":["../../../src/graph/middlewares/tool-validation-middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAiC,MAAM,WAAW,CAAC;AAChF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAQxD,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,GACzC,UAAS,+BAAoC,KAC5C,eAuDF,CAAC"}

package/dist/graph/middlewares/tool-validation-middleware.js

@@ -0,0 +1,61 @@
+import { createMiddleware, ToolMessage } from 'langchain';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * Catches tool validation errors (Zod / schema mismatches) and turns them
+ * into a `ToolMessage` describing the failure, so the model can recover
+ * instead of the graph crashing.
+ *
+ * Also strips `ToolMessage`s for tools listed in `skipToolNames` from the
+ * state before the next model call — used today for sub-agent tools whose
+ * structured output is consumed by their callers, not the LLM.
+ */
+export const createToolValidationMiddleware = (options = {}) => {
+    const logger = options.logger ?? NOOP_LOGGER;
+    const skipToolNames = new Set(options.skipToolNames ?? []);
+    return createMiddleware({
+        name: 'ToolValidationMiddleware',
+        wrapToolCall: async (toolCallRequest, handler) => {
+            const { toolCall } = toolCallRequest;
+            try {
+                return await handler(toolCallRequest);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : '';
+                const isSchemaError = errorMessage.includes('did not match expected schema') ||
+                    errorMessage.includes('Received tool input did not match') ||
+                    errorMessage.includes('schema') ||
+                    (error instanceof Error && error.name === 'ZodError');
+                if (!isSchemaError)
+                    throw error;
+                const toolName = toolCall.name ?? toolCallRequest.tool?.name ?? '';
+                logger.warn(`Tool validation error for ${toolName}: ${errorMessage}`, {
+                    toolName,
+                    toolArgs: toolCall.args,
+                    error: errorMessage,
+                });
+                return new ToolMessage({
+                    content: `Error: The tool "${toolName}" was called with invalid parameters. ${errorMessage}. Please check the tool's required parameters and try again with the correct format.`,
+                    tool_call_id: toolCall.id ?? '',
+                    name: toolName,
+                });
+            }
+        },
+        beforeModel(state) {
+            if (skipToolNames.size === 0)
+                return state;
+            const toolMessage = state.messages.find((message) => message.type === 'tool');
+            if (toolMessage?.name && skipToolNames.has(toolMessage.name)) {
+                logger.log(`Tool validation middleware: ${toolMessage.name} is a skip-listed tool, removing tool messages before next model call`);
+                return {
+                    ...state,
+                    messages: state.messages.filter((message) => message.type !== 'tool'),
+                };
+            }
+            return state;
+        },
+    });
+};

package/dist/graph/prompt-composer.d.ts

@@ -0,0 +1,69 @@
+import type { OracleIdentity, UserContextData } from '../plugin-api/types.js';
+import type { UserPreferences } from './state.js';
+/**
+ * Composer inputs. Each field maps 1:1 to a slot in the base template.
+ * Plugins populate them via their middlewares (e.g. operationalMode comes
+ * from a plugin that reads task-execution context); the runtime just stitches.
+ */
+export interface ComposePromptInput {
+    identity: OracleIdentity;
+    /** Pre-rendered Tier-1 capability block. Empty string when no eager plugins. */
+    capabilityBlock: string;
+    /** Operational-mode block — typically a multi-line string. */
+    operationalMode: string;
+    /** Editor block — empty string when no editor session is active. */
+    editorSection: string;
+    /** Composio guidance block — empty when composio isn't loaded. */
+    composioContext: string;
+    /** Slack-specific formatting constraints. Empty string for non-slack clients. */
+    slackFormattingConstraints: string;
+    /** Per-key user-secret bullet list (e.g. `- _USER_SECRET_FOO`). Empty when none. */
+    userSecretsContext: string;
+    /** User preferences rendered as bullets. Empty when not set. */
+    userPreferencesContext: string;
+    /** Memory-engine context blocks. */
+    userContext: UserContextData | undefined;
+    /** Time context (timezone + current time). */
+    timeContext: string;
+    /** Currently-viewed entity DID, if any. */
+    currentEntityDid: string;
+    /** Optional override of the oracle name (e.g. user preference `agentName`). */
+    oracleNameOverride?: string;
+    /** Degraded-services notice appended after the main prompt body. */
+    degradedServicesBlock?: string;
+}
+/**
+ * The Slack constraints text. Identical to apps/app — kept here so the
+ * runtime owns its own copy and the prompt composer is self-contained.
+ */
+export declare const SLACK_FORMATTING_CONSTRAINTS_CONTENT = "## Slack Formatting\n\nSlack doesn't render markdown tables. When responding in a Slack session:\n- Use bullet lists with bold labels (\"\u2022 **Name:** value\") instead of tables\n- Use numbered lists for sequential data\n- When delegating to sub-agents, ask them for list-based formatting (no tables)\n\n";
+/** Render user preferences as a bullet list for the prompt. */
+export declare function formatUserPreferences(prefs?: UserPreferences): string;
+/**
+ * Build the oracle identity preamble. When `identity.prompt.opening` is set
+ * it replaces the generated text verbatim; otherwise the composer assembles
+ * a sentence from `name`/`org`/`description`. Never claims the oracle is a
+ * "companion" or "skills-native" — those framings belong to specific plugins.
+ */
+export declare function buildOracleSection(input: {
+    oracleName: string;
+    orgName?: string;
+    description?: string;
+    customOpening?: string;
+}): string;
+/**
+ * Compose the runtime's system prompt. Slots split into:
+ *   - **identity** — from `OracleConfig` (custom opening or generated).
+ *   - **capabilities** — author note (config.prompt.capabilities) + Tier-1 block.
+ *   - **operating principles** — fixed + optional `communicationStyle` from config.
+ *   - **working with files** — runtime-universal (FileProcessingService).
+ *   - **context** — only populated memory sub-sections render; empty ones skipped.
+ *   - **operational mode / composio / editor / slack** — existing plugin hooks.
+ */
+export declare function composePrompt(input: ComposePromptInput): Promise<string>;
+/**
+ * Format a (timezone, currentTime) pair into a stable prompt block. Public so
+ * forks driving their own `composePrompt` calls can re-use it.
+ */
+export declare function formatTimeContext(timezone: string | undefined, currentTime: string | undefined): string;
+//# sourceMappingURL=prompt-composer.d.ts.map

package/dist/graph/prompt-composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-composer.d.ts","sourceRoot":"","sources":["../../src/graph/prompt-composer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAclD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,0BAA0B,EAAE,MAAM,CAAC;IACnC,oFAAoF;IACpF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,oCAAoC;IACpC,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;IACzC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,eAAO,MAAM,oCAAoC,wTAOhD,CAAC;AAwHF,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,CAWrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAmBT;AAsHD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAMR"}