@ixo/oracle-runtime 0.0.1

package/dist/plugins/credits/token-limiter.js

@@ -0,0 +1,302 @@
+import crypto from 'node:crypto';
+import { z } from 'zod';
+/** Insufficient-balance error raised by `limit()`. */
+export class TokenLimiterError extends Error {
+    type;
+    limit;
+    currentBalance;
+    reset;
+    constructor(message, type, limit, reset, currentBalance) {
+        super(message);
+        this.type = type;
+        this.limit = limit;
+        this.reset = reset;
+        this.currentBalance = currentBalance;
+    }
+}
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+const KEY_PREFIX = 'token_limit:';
+const KEY_BALANCE = 'balance';
+const KEY_HELD_AMOUNTS = 'held_amounts';
+const KEY_SUBSCRIPTION_PAYLOAD = 'subscription_payload';
+const KEY_PENDING_CLAIM = 'pending_claim';
+// Atomic balance decrement + held-amount increment, with rollback on overdraft.
+const LIMIT_TOKENS_SCRIPT = `
+    local balanceKey = KEYS[1]
+    local heldAmountsKey = KEYS[2]
+    local userDid = ARGV[1]
+    local tokenCount = tonumber(ARGV[2])
+
+    local newBalance = tonumber(redis.call('INCRBYFLOAT', balanceKey, -tokenCount))
+
+    if newBalance < 0 then
+      redis.call('INCRBYFLOAT', balanceKey, tokenCount)
+      return {0, newBalance + tokenCount, 'INSUFFICIENT_BALANCE'}
+    end
+
+    redis.call('ZINCRBY', heldAmountsKey, tokenCount, userDid)
+
+    return {1, newBalance, 'SUCCESS'}
+  `;
+/**
+ * Per-user credit budget enforced against Redis. The runtime instantiates
+ * one `TokenLimiter` per oracle and shares it between the middleware (live
+ * deduction on the LLM hot path) and the subscription middleware (which
+ * mirrors the chain-side balance into Redis on every authenticated request).
+ *
+ * Costs are computed in three priority tiers:
+ *   1. provider-supplied USD cost (e.g. OpenRouter `usage.cost`)
+ *   2. cached per-model pricing × tokens
+ *   3. flat-rate `$0.75 / 1M tokens` fallback
+ */
+export class TokenLimiter {
+    redis;
+    network;
+    disableCredits;
+    lookupModelPricing;
+    logger;
+    static getSubscriptionPayloadKey(userDid) {
+        return `${KEY_PREFIX}${userDid}:${KEY_SUBSCRIPTION_PAYLOAD}`;
+    }
+    static getUserBalanceKey(userDid) {
+        return `${KEY_PREFIX}${userDid}:${KEY_BALANCE}`;
+    }
+    static getPendingClaimKey(userDid) {
+        return `${KEY_PREFIX}${userDid}:${KEY_PENDING_CLAIM}`;
+    }
+    static getHeldAmountsKey() {
+        return KEY_HELD_AMOUNTS;
+    }
+    /**
+     * Deterministic claim ID derived from `userDid + batchStartTime`. Retries
+     * for the same batch resolve to the same ID, preventing duplicate claims.
+     */
+    static generateClaimId(userDid, batchStartTime) {
+        const hash = crypto
+            .createHash('sha256')
+            .update(`${userDid}:${batchStartTime}`)
+            .digest('hex');
+        return `claim_${hash.slice(0, 32)}`;
+    }
+    constructor(options) {
+        this.redis = options.redis;
+        this.network = options.network;
+        this.disableCredits = options.disableCredits ?? false;
+        this.lookupModelPricing =
+            options.modelPricingLookup ?? (() => null);
+        this.logger = options.logger ?? NOOP_LOGGER;
+    }
+    /**
+     * Convert raw USD cost (e.g. OpenRouter `response_metadata.usage.cost`)
+     * into credits. On mainnet 1 USD = 1000 credits; devnet uses a 10x
+     * multiplier so micro-costs are visible during testing.
+     */
+    usdCostToCredits(usdCost) {
+        const isMainnet = this.network === 'mainnet';
+        const creditsPerUsd = isMainnet ? 1000 : 10_000;
+        const markup = isMainnet ? 1.6 : 4;
+        return Math.round(usdCost * creditsPerUsd * markup);
+    }
+    /**
+     * Cost in USD (post-markup) using the same 3-priority fallback as
+     * `creditsForUsage`. Exposed for callers that bill outside the agent
+     * graph (e.g. file-processing pre-flight charges).
+     */
+    calculateCostUsdWithMarkup(params) {
+        const markup = this.network === 'mainnet' ? 1.6 : 5;
+        if (params.providerCost != null && params.providerCost > 0) {
+            return params.providerCost * markup;
+        }
+        const pricing = params.model ? this.lookupModelPricing(params.model) : null;
+        if (pricing) {
+            const inputCost = (params.inputTokens / 1_000_000) * pricing.inputPricePerMillionTokens;
+            const outputCost = (params.outputTokens / 1_000_000) * pricing.outputPricePerMillionTokens;
+            return (inputCost + outputCost) * markup;
+        }
+        return (params.totalTokens / 1_000_000) * 0.75 * markup;
+    }
+    /** Flat-rate fallback: $0.75 per 1M tokens × network markup. */
+    llmTokenToCredits(tokenCount) {
+        const markup = this.network === 'mainnet' ? 1.6 : 5;
+        const costPerMillionTokens = 0.75 * markup;
+        const tokensPerMillion = this.network === 'mainnet' ? 1_000_000 : 1000;
+        return Math.round((tokenCount / tokensPerMillion) * costPerMillionTokens);
+    }
+    /**
+     * Credits using per-model pricing (separate input/output rates). Falls
+     * through to the flat-rate fallback when pricing is `null`.
+     */
+    llmTokenToCreditsWithPricing(inputTokens, outputTokens, pricing) {
+        if (!pricing) {
+            this.logger.log('[TokenLimiter] No pricing found, falling back to flat rate');
+            return this.llmTokenToCredits(inputTokens + outputTokens);
+        }
+        const markup = this.network === 'mainnet' ? 1.6 : 5;
+        const divisor = this.network === 'mainnet' ? 1_000_000 : 1000;
+        const inputCost = (inputTokens / divisor) * pricing.inputPricePerMillionTokens;
+        const outputCost = (outputTokens / divisor) * pricing.outputPricePerMillionTokens;
+        return Math.round((inputCost + outputCost) * markup);
+    }
+    /**
+     * Compute credit cost for a single completion using the standard 3-priority
+     * fallback. The middleware's `afterModel` hook calls this on every LLM
+     * response.
+     */
+    creditsForUsage(params) {
+        if (params.providerCost != null && params.providerCost > 0) {
+            const credits = this.usdCostToCredits(params.providerCost);
+            this.logger.log(`[TokenLimiter] Using provider cost: $${params.providerCost} → ${credits} credits`);
+            return credits;
+        }
+        const pricing = params.model ? this.lookupModelPricing(params.model) : null;
+        if (pricing) {
+            const credits = this.llmTokenToCreditsWithPricing(params.inputTokens, params.outputTokens, pricing);
+            this.logger.log(`[TokenLimiter] Using cached pricing for model=${params.model ?? 'unknown'} → ${credits} credits`);
+            return credits;
+        }
+        const credits = this.llmTokenToCredits(params.totalTokens);
+        this.logger.log(`[TokenLimiter] Using flat-rate fallback (model=${params.model ?? 'unknown'}) → ${credits} credits`);
+        return credits;
+    }
+    async setSubscriptionPayload(userDid, payload) {
+        await this.redis.set(TokenLimiter.getSubscriptionPayloadKey(userDid), JSON.stringify({
+            adminAddress: payload.adminAddress,
+            claimCollections: payload.claimCollections,
+            totalCredits: payload.totalCredits,
+        }));
+    }
+    async getSubscriptionPayload(userDid) {
+        const payload = await this.redis.get(TokenLimiter.getSubscriptionPayloadKey(userDid));
+        return payload
+            ? JSON.parse(payload)
+            : null;
+    }
+    async getUserHeldAmount(userDid) {
+        const result = await this.redis.zscore(KEY_HELD_AMOUNTS, userDid);
+        return result ? parseFloat(result) : 0;
+    }
+    async incrementUserHeldAmount(userDid, amount) {
+        await this.redis.zincrby(KEY_HELD_AMOUNTS, amount, userDid);
+    }
+    async deleteUserHeldAmount(userDid) {
+        await this.redis.zrem(KEY_HELD_AMOUNTS, userDid);
+    }
+    /**
+     * List users whose held amount is at or above `amount`. Result rows are
+     * `[did, heldAmount]` tuples.
+     */
+    async listUsersWithHeldAmount(amount) {
+        const raw = await this.redis.zrangebyscore(KEY_HELD_AMOUNTS, amount, '+inf', 'WITHSCORES');
+        const result = [];
+        for (let i = 0; i < raw.length; i += 2) {
+            result.push([raw[i], parseFloat(raw[i + 1])]);
+        }
+        return result;
+    }
+    /**
+     * Reconcile the Redis balance with the chain-side subscription balance.
+     * Subtracts any pending held amount to surface the user's actual usable
+     * balance. Throws when the held amount exceeds the chain balance (a
+     * sync error) unless credits are disabled.
+     */
+    async overrideUserBalance(userDid, balance) {
+        z.number().parse(balance);
+        const heldAmount = await this.getUserHeldAmount(userDid);
+        const newBalance = balance - heldAmount;
+        if (newBalance < 0) {
+            this.logger.error(`CRITICAL: Held amount (${heldAmount}) exceeds chain balance (${balance}) for user ${userDid}.`);
+            await this.redis.set(TokenLimiter.getUserBalanceKey(userDid), '0');
+            if (this.disableCredits) {
+                return '0';
+            }
+            throw new TokenLimiterError(`It looks like you have some usage pending that's higher than your current balance (${balance / 1000}). Please add more credits to your account to continue. If you think this is a mistake, please contact support. (Held: ${heldAmount / 1000})`, 'token', undefined, undefined, balance);
+        }
+        await this.redis.set(TokenLimiter.getUserBalanceKey(userDid), newBalance.toString());
+        this.logger.debug?.(`Overriding balance for user ${userDid} to current balance: ${newBalance}, held amount: ${heldAmount}, subscription balance: ${balance}`);
+        return newBalance.toString();
+    }
+    async getUserBalance(userDid) {
+        const balance = await this.redis.get(TokenLimiter.getUserBalanceKey(userDid));
+        return balance ? parseFloat(balance) : 0;
+    }
+    async getRemaining(userDid) {
+        return this.getUserBalance(userDid);
+    }
+    /**
+     * Decrement the user's balance by `credits` and add the same amount to
+     * their held-amount sorted-set entry, atomically via a Lua script.
+     * Throws `TokenLimiterError` when the balance would go negative.
+     */
+    async limit(userDid, credits) {
+        const balanceKey = TokenLimiter.getUserBalanceKey(userDid);
+        const heldAmountsKey = KEY_HELD_AMOUNTS;
+        try {
+            const result = (await this.redis.eval(LIMIT_TOKENS_SCRIPT, 2, balanceKey, heldAmountsKey, userDid, credits.toString()));
+            const [success, balance] = result;
+            if (success === 0) {
+                throw new TokenLimiterError(`Insufficient balance. Current balance: ${balance}`, 'token', credits, undefined, balance);
+            }
+            this.logger.debug?.(`Limited ${credits} credits for user ${userDid}, remaining: ${balance}`);
+            return { success: true, remaining: balance };
+        }
+        catch (error) {
+            if (error instanceof TokenLimiterError) {
+                throw error;
+            }
+            this.logger.error(`Failed to limit tokens for user ${userDid}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new TokenLimiterError('Failed to process token limit', 'token', credits);
+        }
+    }
+    async setPendingClaim(userDid, claimId, amount, batchStartTime) {
+        const now = Date.now();
+        const payload = {
+            claimId,
+            amount,
+            timestamp: now,
+            batchStartTime: batchStartTime ?? now,
+        };
+        await this.redis.set(TokenLimiter.getPendingClaimKey(userDid), JSON.stringify(payload), 'EX', 60 * 60);
+    }
+    async getPendingClaim(userDid) {
+        const data = await this.redis.get(TokenLimiter.getPendingClaimKey(userDid));
+        return data
+            ? JSON.parse(data)
+            : null;
+    }
+    async clearPendingClaim(userDid) {
+        await this.redis.del(TokenLimiter.getPendingClaimKey(userDid));
+    }
+    async updatePendingClaimAmount(userDid, newAmount) {
+        const pending = await this.getPendingClaim(userDid);
+        if (!pending) {
+            this.logger.warn(`Attempted to update pending claim amount for ${userDid}, but no pending claim exists`);
+            return;
+        }
+        await this.setPendingClaim(userDid, pending.claimId, newAmount, pending.batchStartTime);
+        this.logger.debug?.(`Updated pending claim ${pending.claimId} amount from ${pending.amount} to ${newAmount} for user ${userDid}`);
+    }
+    /**
+     * Return the existing pending-claim ID for `userDid`, refreshing the
+     * amount if the held amount changed; otherwise create a new claim entry
+     * with a deterministic ID.
+     */
+    async getOrCreatePendingClaim(userDid, currentHeldAmount) {
+        const pending = await this.getPendingClaim(userDid);
+        if (pending) {
+            if (pending.amount !== currentHeldAmount) {
+                this.logger.debug?.(`Held amount changed from ${pending.amount} to ${currentHeldAmount} for user ${userDid}. Updating pending claim.`);
+                await this.updatePendingClaimAmount(userDid, currentHeldAmount);
+            }
+            return pending.claimId;
+        }
+        const batchStartTime = Date.now();
+        const claimId = TokenLimiter.generateClaimId(userDid, batchStartTime);
+        await this.setPendingClaim(userDid, claimId, currentHeldAmount, batchStartTime);
+        this.logger.debug?.(`Created new pending claim ${claimId} for user ${userDid} with amount ${currentHeldAmount}`);
+        return claimId;
+    }
+}

package/dist/plugins/domain-indexer/domain-indexer-agent.d.ts

@@ -0,0 +1,7 @@
+import type { PluginSubAgent, PluginTool } from '../../plugin-api/types.js';
+/**
+ * Build the Domain Indexer sub-agent definition. Tools are supplied by the
+ * plugin and closed over `DOMAIN_INDEXER_URL` from the merged config.
+ */
+export declare function createDomainIndexerSubAgent(tools: PluginTool[]): PluginSubAgent;
+//# sourceMappingURL=domain-indexer-agent.d.ts.map

package/dist/plugins/domain-indexer/domain-indexer-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-indexer-agent.d.ts","sourceRoot":"","sources":["../../../src/plugins/domain-indexer/domain-indexer-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAyC5E;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,UAAU,EAAE,GAClB,cAAc,CAShB"}

package/dist/plugins/domain-indexer/domain-indexer-agent.js

@@ -0,0 +1,48 @@
+const formatToolDocs = (tools) => tools
+    .map((t) => {
+    const description = t.description?.trim() ?? 'No description provided.';
+    return `- \`${t.name}\`: ${description}`;
+})
+    .join('\n');
+const buildSystemPrompt = (tools) => `
+You are the Domain Indexer Agent. You are the specialist for searching the IXO Domain Indexer—treat it like Google for IXO entities (organizations, projects, DAOs, agents, compositions, events).
+
+Core expectations:
+- Always clarify the user’s goal and translate it into a concrete search query or DID lookup.
+- Never call tools with empty parameters; \`domain_indexer_search\` always needs a query, \`get_domain_card\` always needs a DID.
+- Explain what you are searching for, summarize the results, and cite relevant DIDs or entity names.
+- When multiple results appear, compare them briefly and suggest next steps.
+
+Task discipline:
+- You are a sub-agent invoked by the main agent. You receive a single task message — that is ALL the context you have.
+- If the task is unclear, ambiguous, or missing critical details (IDs, names, scope, what to do), do NOT guess. Instead, STOP immediately and return a clear message explaining what information you need. The main agent will ask the user and re-invoke you with a complete task.
+- Never loop or retry the same failing approach. If something fails twice, return the error and stop.
+- Complete the requested task and STOP. Do not do additional unrequested work.
+
+### Available Domain Indexer Tools
+${formatToolDocs(tools)}
+
+Workflow:
+1. Decide if you need search (find relevant entities) or a card lookup (get summary/overview/FAQ for a known DID).
+2. Provide detailed, structured tool inputs (query text, limits, filters, or DID).
+3. Parse the response—highlight summary, overview, FAQ, URLs, and keywords.
+4. Surface gaps or follow-ups — if more context is needed (from memory, portal, etc.), say so and the main agent will use the appropriate tools.
+`.trim();
+const buildDescription = (tools) => {
+    const names = tools.map((t) => t.name).join(', ');
+    return `Domain Indexer specialist using (${names}) to discover IXO entities, summaries, overviews, and FAQs.`;
+};
+/**
+ * Build the Domain Indexer sub-agent definition. Tools are supplied by the
+ * plugin and closed over `DOMAIN_INDEXER_URL` from the merged config.
+ */
+export function createDomainIndexerSubAgent(tools) {
+    return {
+        name: 'Domain Indexer Agent',
+        description: buildDescription(tools),
+        systemPrompt: buildSystemPrompt(tools),
+        tools,
+        model: 'subagent',
+        middlewares: [],
+    };
+}

package/dist/plugins/domain-indexer/domain-indexer-tools.d.ts

@@ -0,0 +1,8 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+/**
+ * Construct the two domain-indexer tools, closing over the configured base
+ * URL. Tools are pure HTTP wrappers — they don't need a `RuntimeContext`,
+ * so the handler ignores the second argument.
+ */
+export declare function createDomainIndexerTools(baseUrl: string): PluginTool[];
+//# sourceMappingURL=domain-indexer-tools.d.ts.map

package/dist/plugins/domain-indexer/domain-indexer-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-indexer-tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/domain-indexer/domain-indexer-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAiL5D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAgDtE"}

package/dist/plugins/domain-indexer/domain-indexer-tools.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper.js';
+const searchSchema = z.object({
+    query: z
+        .string()
+        .min(1, '❌ ERROR: Query is required and cannot be empty - this tool works like Google search, you MUST provide a search query')
+        .describe('🚨 MANDATORY PARAMETER - ALWAYS REQUIRED\n' +
+        'This tool works like Google search - you MUST provide a search query to find entities.\n' +
+        'The search query string. Cannot be empty or omitted. This is like typing into Google search.\n' +
+        'Examples:\n' +
+        '- User asks "What is IXO?" → Use query: "IXO"\n' +
+        '- User asks "Tell me about blockchain projects" → Use query: "blockchain projects"\n' +
+        '- User asks "What are carbon credits?" → Use query: "carbon credits"\n' +
+        "Extract the main search term from the user's question and use it as the query.\n" +
+        'This parameter is mandatory - you cannot search without a query, just like you cannot Google search without typing something.'),
+    limit: z
+        .number()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Optional: Maximum number of results to return (1-10, default: 10)'),
+    scopes: z
+        .string()
+        .optional()
+        .describe('Optional: Comma-separated list of scopes to search: domain_cards (default), agents, compositions, events. Use "domain_cards" to find organizations/projects/DAOs with summaries and FAQs.'),
+    filters: z.record(z.string(), z.string()).optional()
+        .describe(`Optional filters as key-value pairs. Examples:
+- {"dc.categories": "dao,project"} - Filter by categories
+- {"dc.entity_type": "dao"} - Filter by entity type
+- {"dc.has_url": "true"} - Only entities with URLs
+- {"dc.keywords": "blockchain,web3"} - Filter by keywords
+- {"agent.domain_card_id": "did:ixo:entity:ixoworld"} - Agents for specific entity
+For multiple values, use comma-separated strings. For booleans, use "true" or "false". For dates, use ISO format.`),
+});
+const cardSchema = z.object({
+    did: z
+        .string()
+        .min(1, '❌ ERROR: DID is required and cannot be empty')
+        .describe('REQUIRED: Domain card DID (Decentralized Identifier). Must be a non-empty string. Get this from search results (record.id) or user input. Example: "did:ixo:entity:ixoworld". This parameter is mandatory and cannot be omitted.'),
+});
+const SEARCH_DESCRIPTION = `🔍 This is like Google Search for entities and domains in the IXO ecosystem. You search using a query and you will find relevant entities.
+
+Think of this tool exactly like Google Search:
+- Google Search: You type a query → You get search results
+- Domain Indexer: You provide a query → You get entity results
+
+🚨 CRITICAL REQUIREMENT: You MUST provide the 'query' parameter. This tool works like Google search - you CANNOT search without a query. NEVER call this tool with empty arguments {}.
+
+✅ CORRECT EXAMPLES (like Google search):
+{"query": "IXO"}
+{"query": "blockchain impact"}
+{"query": "carbon credits", "limit": 5}
+{"query": "What is IXO?", "scopes": "domain_cards"}
+
+❌ WRONG (WILL FAIL - like trying to Google search with no query):
+{}
+{"limit": 5}
+{"scopes": "domain_cards"}
+
+The 'query' parameter is MANDATORY in every call - just like you can't Google search without typing something.
+
+WHAT IT DOES:
+- Searches the IXO domain indexer to find entities (organizations, projects, DAOs, agents, compositions, events)
+- Returns summaries, overviews, and FAQs for matching entities
+- Works like Google search: you provide a search query and get relevant results
+
+PRIMARY USE CASES:
+- When users ask "What is X?" or "Tell me about X" → Use query: "X" to find the entity
+- When users ask "What are the FAQs for X?" → Use query: "X" to find the entity and access its FAQ section
+- When users need information about an organization/project → Use query with the entity name or topic
+- When users ask about entities in the IXO ecosystem → Use query with relevant keywords
+
+WHAT IT RETURNS:
+- Entity records containing: name, description, summary, overview, FAQs, keywords, URLs, logos, contact info, location, and metadata
+- Search results include domain cards (organizations/projects/DAOs), agents, compositions (documents/resources), and events
+- Each result has a 'record' field with the entity data - look for 'summary', 'overview', and 'faq' fields in the record
+- Results are ranked by relevance using hybrid search (text + semantic similarity)
+
+WORKFLOW:
+1. User asks about something → Extract the search query (entity name, topic, or keywords)
+2. Call this tool with the query: {"query": "extracted search term"}
+3. Review the search results - each item has a 'record' field with entity data
+4. Check the 'record' for 'summary', 'overview', and 'faq' fields
+5. If you need more complete information, use get_domain_card with the entity's DID (found in record.id)
+
+FILTERS (optional):
+- Domain cards: dc.categories (comma-separated), dc.entity_type, dc.keywords, dc.issuer, dc.has_url (true/false), dc.has_logo (true/false), dc.valid_from_gte (ISO date), dc.valid_from_lte (ISO date), dc.bbox (minLng,minLat,maxLng,maxLat), dc.near (lng,lat), dc.radius (meters)
+- Agents: agent.domain_card_id, agent.has_url (true/false)
+- Compositions: comp.domain_card_id, comp.creator, comp.has_url (true/false)
+- Events: event.domain_card_id, event.from (ISO date), event.to (ISO date), event.location
+
+IMPORTANT: Always check the 'record' field in results for summary, overview, and faq data. These fields contain the curated information about the entity.`;
+const CARD_DESCRIPTION = `Get essential domain card details by DID (Decentralized Identifier) including summary, overview, FAQs, and key information. Returns only essential fields to optimize context usage.
+
+🚨 CRITICAL REQUIREMENT: You MUST provide the 'did' parameter. NEVER call this tool with empty arguments {}.
+
+✅ CORRECT EXAMPLES:
+{"did": "did:ixo:entity:ixoworld"}
+
+❌ WRONG (WILL FAIL):
+{}
+{"query": "IXO"}
+
+⚠️ REQUIRED PARAMETERS:
+- did (REQUIRED): The domain card DID (Decentralized Identifier) - MUST always be provided. Cannot be empty.
+
+PRIMARY USE CASES:
+- After using domain_indexer_search, use this to get the essential entity information including summary, overview, and FAQs
+- When you have a specific entity DID and need its summary, overview, or FAQs
+- When search results show partial information and you need the curated summary/overview/FAQ fields
+- When users specifically ask for FAQs, summaries, or overviews of a known entity
+
+WHAT IT RETURNS (filtered to essential fields only):
+- id: Entity DID
+- name: Entity name
+- description: Full description
+- summary: Brief summary of the entity (if available)
+- overview: Detailed overview/description (if available)
+- faq: Array of FAQ objects with question and answer fields
+- url: Entity website URL
+- keywords: Array of keywords
+- entity_type: Array of entity types
+
+WORKFLOW:
+1. First use domain_indexer_search to find entities
+2. Extract the DID from search results (record.id field)
+3. Use this tool with the DID to get essential information including summary, overview, and FAQs
+4. The response directly contains summary, overview, and faq fields at the top level
+
+IMPORTANT: This tool returns a filtered response with only essential fields (summary, overview, FAQ, and basic info) to avoid context overload. All fields are at the top level - no need to navigate nested objects.`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function projectDomainCard(card) {
+    const c = isRecord(card) ? card : {};
+    return {
+        id: c.id,
+        name: c.name,
+        description: c.description,
+        summary: c.summary,
+        overview: c.overview,
+        faq: c.faq ?? [],
+        url: c.url,
+        keywords: c.keywords ?? [],
+        entity_type: c.entity_type ?? [],
+    };
+}
+/**
+ * Construct the two domain-indexer tools, closing over the configured base
+ * URL. Tools are pure HTTP wrappers — they don't need a `RuntimeContext`,
+ * so the handler ignores the second argument.
+ */
+export function createDomainIndexerTools(baseUrl) {
+    const search = tool(async (rawArgs) => {
+        const params = searchSchema.parse(rawArgs);
+        const url = new URL('/search', baseUrl);
+        url.searchParams.set('q', params.query);
+        if (params.limit !== undefined) {
+            url.searchParams.set('limit', String(params.limit));
+        }
+        if (params.scopes)
+            url.searchParams.set('scopes', params.scopes);
+        for (const [k, v] of Object.entries(params.filters ?? {})) {
+            url.searchParams.set(k, v);
+        }
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            throw new Error(`Search failed: ${response.statusText}`);
+        }
+        return response.json();
+    }, {
+        name: 'domain_indexer_search',
+        description: SEARCH_DESCRIPTION,
+        schema: searchSchema,
+    });
+    const card = tool(async (rawArgs) => {
+        const { did } = cardSchema.parse(rawArgs);
+        const url = new URL(`/domain-cards/${did}`, baseUrl);
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            if (response.status === 404) {
+                return { error: 'Domain card not found' };
+            }
+            throw new Error(`Failed to fetch domain card: ${response.statusText}`);
+        }
+        const fullCard = await response.json();
+        return projectDomainCard(fullCard);
+    }, {
+        name: 'get_domain_card',
+        description: CARD_DESCRIPTION,
+        schema: cardSchema,
+    });
+    return [search, card];
+}

package/dist/plugins/domain-indexer/domain-indexer.plugin.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginContext, PluginManifest, PluginSubAgent } from '../../plugin-api/types.js';
+/**
+ * Domain Indexer plugin. Exposes a sub-agent (`call_domain_indexer_agent`)
+ * that searches the IXO Domain Indexer and resolves entities by DID.
+ *
+ * The base URL is derived from `NETWORK` by default and can be overridden
+ * with `DOMAIN_INDEXER_URL` (e.g. for a local mirror or staging build).
+ */
+export declare class DomainIndexerPlugin extends OraclePlugin {
+    readonly name = "domain-indexer";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        DOMAIN_INDEXER_URL: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    getSubAgents(ctx: PluginContext): PluginSubAgent[];
+}
+//# sourceMappingURL=domain-indexer.plugin.d.ts.map

package/dist/plugins/domain-indexer/domain-indexer.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-indexer.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/domain-indexer/domain-indexer.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EAEV,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,2BAA2B,CAAC;AAsEnC;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,QAAQ,iBAAY;IAC7B,SAAkB,YAAY;;sBAAgB;IAErC,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,EAAE;CAK5D"}

package/dist/plugins/domain-indexer/domain-indexer.plugin.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { createDomainIndexerSubAgent } from './domain-indexer-agent.js';
+import { createDomainIndexerTools } from './domain-indexer-tools.js';
+/**
+ * Default Domain Indexer endpoints per IXO network. Selected at boot from
+ * the core `NETWORK` env var. Operators can override with the optional
+ * `DOMAIN_INDEXER_URL` env var (useful for local/staging deployments).
+ */
+const DOMAIN_INDEXER_URLS = {
+    mainnet: 'https://domain-indexer.ixo.earth',
+    testnet: 'https://domain-indexer.testnet.ixo.earth',
+    devnet: 'https://domain-indexer.devnet.ixo.earth',
+};
+const configSchema = z.object({
+    DOMAIN_INDEXER_URL: z.string().url().optional(),
+});
+const networkSchema = z.enum(['mainnet', 'testnet', 'devnet']);
+function resolveDomainIndexerUrl(config) {
+    const override = configSchema.safeParse(config);
+    if (override.success && override.data.DOMAIN_INDEXER_URL) {
+        return override.data.DOMAIN_INDEXER_URL;
+    }
+    const network = networkSchema.safeParse(config.NETWORK);
+    if (network.success) {
+        return DOMAIN_INDEXER_URLS[network.data];
+    }
+    throw new Error('domain-indexer: could not resolve base URL. Set DOMAIN_INDEXER_URL or ensure NETWORK is one of mainnet|testnet|devnet.');
+}
+const manifest = {
+    title: 'Domain Indexer',
+    summary: 'Domain analysis and entity lookup across the IXO ecosystem — organizations, projects, DAOs, DIDs.',
+    whenToUse: [
+        'User asks "what is X?" or "tell me about X" for an organization, project, DAO, or DID.',
+        'User needs the summary, overview, or FAQ of an IXO entity.',
+        'Looking up a domain card by its DID.',
+        'Discovering entities by topic, category, or keyword.',
+    ],
+    whenNotToUse: [
+        'General web search unrelated to IXO entities (use Firecrawl).',
+        'Personal memory or past-conversation recall (use Memory).',
+        'Page editing or workspace pages (use Editor) — pages are NOT entities.',
+    ],
+    examples: [
+        {
+            user: 'Tell me about did:ixo:entity:abc123.',
+            thought: 'IXO DID lookup — delegate to call_domain_indexer_agent.',
+            tool: 'call_domain_indexer_agent',
+        },
+        {
+            user: 'Find DAOs working on climate.',
+            thought: 'Discovery by topic across IXO entities.',
+            tool: 'call_domain_indexer_agent',
+        },
+    ],
+    tags: ['ixo', 'entities', 'search', 'dids'],
+    category: 'data',
+    visibility: 'always',
+    stability: 'stable',
+};
+/**
+ * Domain Indexer plugin. Exposes a sub-agent (`call_domain_indexer_agent`)
+ * that searches the IXO Domain Indexer and resolves entities by DID.
+ *
+ * The base URL is derived from `NETWORK` by default and can be overridden
+ * with `DOMAIN_INDEXER_URL` (e.g. for a local mirror or staging build).
+ */
+export class DomainIndexerPlugin extends OraclePlugin {
+    name = 'domain-indexer';
+    version = '1.0.0';
+    manifest = manifest;
+    configSchema = configSchema;
+    getSubAgents(ctx) {
+        const baseUrl = resolveDomainIndexerUrl(ctx.config);
+        const tools = createDomainIndexerTools(baseUrl);
+        return [createDomainIndexerSubAgent(tools)];
+    }
+}