@ixo/oracle-runtime 0.0.1

package/dist/plugins/composio/composio-tools.d.ts

@@ -0,0 +1,59 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+/**
+ * Minimal shape of a LangChain `DynamicStructuredTool` the composio session
+ * returns. The `schema` field is typed broadly because `DynamicStructuredTool`
+ * permits either a Zod schema or a raw JSON schema; at runtime the composio
+ * `LangchainProvider` always emits Zod (via `jsonSchemaToZodSchema`), but the
+ * structural interface stays wide so a non-conforming SDK shape doesn't crash
+ * the build. {@link toolSchema} narrows the value when wrapping each entry.
+ */
+export interface ComposioSessionTool {
+    readonly name: string;
+    readonly description: string;
+    readonly schema: unknown;
+    invoke(input: unknown): Promise<unknown>;
+}
+/**
+ * Factory that opens a Composio session for the current user and returns the
+ * dynamic tool list. Injected into the plugin so tests can stub the SDK out
+ * entirely.
+ */
+export type ComposioSessionFactory = (args: ComposioSessionFactoryArgs) => Promise<ComposioSessionTool[]>;
+export interface ComposioSessionFactoryArgs {
+    /** Resolved at boot from the plugin's configSchema. */
+    apiKey: string;
+    /** Resolved at boot from the plugin's configSchema. */
+    baseUrl: string;
+    /** UCAN invocation token, minted per request — forwarded as a header. */
+    ucanInvocation: string;
+    /** User identifier; composio uses it as the session `user_id`. */
+    userId: string;
+    /** Optional `x-ixo-network` header value forwarded to composio. */
+    network?: string;
+}
+/**
+ * Default {@link ComposioSessionFactory}: opens a real Composio session using
+ * `@composio/core` + `@composio/langchain`.
+ */
+export declare function createDefaultComposioSessionFactory(): ComposioSessionFactory;
+export interface CreateComposioToolsOptions {
+    apiKey: string;
+    baseUrl: string;
+    ucanInvocation: string;
+    userId: string;
+    network?: string;
+    /** Override the session factory — defaults to the real SDK client. */
+    sessionFactory?: ComposioSessionFactory;
+}
+/**
+ * Build the composio plugin's request-time tool list.
+ *
+ *   1. Opens a composio session via the configured factory.
+ *   2. Wraps each returned tool into a {@link PluginTool} that proxies args
+ *      to the session tool's `invoke`.
+ *
+ * Returns an empty list if the session factory yields no tools (e.g. the
+ * user has no connected accounts and composio omits the management tools).
+ */
+export declare function createComposioTools(opts: CreateComposioToolsOptions): Promise<PluginTool[]>;
+//# sourceMappingURL=composio-tools.d.ts.map

package/dist/plugins/composio/composio-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composio-tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/composio/composio-tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,2BAA2B,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,0BAA0B,KAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAEpC,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,IAAI,sBAAsB,CAiB5E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAiDD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,UAAU,EAAE,CAAC,CAavB"}

package/dist/plugins/composio/composio-tools.js

@@ -0,0 +1,88 @@
+import { Composio } from '@composio/core';
+import { LangchainProvider } from '@composio/langchain';
+import { z } from 'zod';
+/**
+ * Default {@link ComposioSessionFactory}: opens a real Composio session using
+ * `@composio/core` + `@composio/langchain`.
+ */
+export function createDefaultComposioSessionFactory() {
+    return async ({ apiKey, baseUrl, ucanInvocation, userId, network }) => {
+        const defaultHeaders = {
+            'x-ucan-invocation': ucanInvocation,
+        };
+        if (network)
+            defaultHeaders['x-ixo-network'] = network;
+        const composio = new Composio({
+            apiKey,
+            provider: new LangchainProvider(),
+            baseURL: baseUrl,
+            defaultHeaders,
+        });
+        const session = await composio.create(userId);
+        const tools = await session.tools();
+        return tools;
+    };
+}
+/**
+ * Permissive fallback schema for composio tools whose `schema` field is not
+ * a Zod schema (e.g. a raw JSON schema from a non-default provider). Used by
+ * {@link toolSchema} when narrowing fails so the agent still sees the tool
+ * with a valid descriptor — the composio backend itself validates args.
+ */
+const FALLBACK_ARGS_SCHEMA = z.record(z.string(), z.unknown());
+/**
+ * Narrow a composio session tool's `schema` field to a Zod schema.
+ *
+ * The default `LangchainProvider` always converts the upstream JSON Schema to
+ * a Zod schema, so this branch is the hot path. Custom providers that emit
+ * raw JSON Schema (rare) fall through to the permissive record schema so the
+ * tool is still discoverable.
+ */
+function toolSchema(schema) {
+    return schema instanceof z.ZodType ? schema : FALLBACK_ARGS_SCHEMA;
+}
+/**
+ * Wrap a single composio session tool as a {@link PluginTool}. The handler
+ * forwards the args through the underlying `invoke` and propagates errors so
+ * the agent surfaces a clean failure rather than a silent empty response.
+ */
+function wrapAsPluginTool(sessionTool) {
+    return {
+        name: sessionTool.name,
+        description: sessionTool.description,
+        schema: toolSchema(sessionTool.schema),
+        handler: async (args, ctx) => {
+            try {
+                return await sessionTool.invoke(args);
+            }
+            catch (error) {
+                const detail = error instanceof Error
+                    ? `${error.name}: ${error.message}`
+                    : String(error);
+                ctx.logger.error(`[composio] tool "${sessionTool.name}" failed: ${detail}`);
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Build the composio plugin's request-time tool list.
+ *
+ *   1. Opens a composio session via the configured factory.
+ *   2. Wraps each returned tool into a {@link PluginTool} that proxies args
+ *      to the session tool's `invoke`.
+ *
+ * Returns an empty list if the session factory yields no tools (e.g. the
+ * user has no connected accounts and composio omits the management tools).
+ */
+export async function createComposioTools(opts) {
+    const sessionFactory = opts.sessionFactory ?? createDefaultComposioSessionFactory();
+    const sessionTools = await sessionFactory({
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl,
+        ucanInvocation: opts.ucanInvocation,
+        userId: opts.userId,
+        network: opts.network,
+    });
+    return sessionTools.map(wrapAsPluginTool);
+}

package/dist/plugins/composio/composio-ucan.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * Mint a UCAN invocation token addressed to the composio-worker.
+ *
+ *   1. Resolves the composio-worker DID via `runCtx.ucan.resolveServiceDid`
+ *      (delegates the did:web lookup + cache to the Tier-0 UCAN service).
+ *   2. Mints an `ixo:sandbox` invocation using the user's signing key.
+ *
+ * Returns `null` when DID resolution fails, when minting throws, or when no
+ * signing material is available. Callers degrade silently — the composio
+ * client is simply not constructed and the plugin contributes no tools.
+ */
+export declare function mintComposioInvocation(runCtx: RuntimeContext, composioBaseUrl: string): Promise<string | null>;
+//# sourceMappingURL=composio-ucan.d.ts.map

package/dist/plugins/composio/composio-ucan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composio-ucan.d.ts","sourceRoot":"","sources":["../../../src/plugins/composio/composio-ucan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB"}

package/dist/plugins/composio/composio-ucan.js

@@ -0,0 +1,32 @@
+/**
+ * Mint a UCAN invocation token addressed to the composio-worker.
+ *
+ *   1. Resolves the composio-worker DID via `runCtx.ucan.resolveServiceDid`
+ *      (delegates the did:web lookup + cache to the Tier-0 UCAN service).
+ *   2. Mints an `ixo:sandbox` invocation using the user's signing key.
+ *
+ * Returns `null` when DID resolution fails, when minting throws, or when no
+ * signing material is available. Callers degrade silently — the composio
+ * client is simply not constructed and the plugin contributes no tools.
+ */
+export async function mintComposioInvocation(runCtx, composioBaseUrl) {
+    const composioDid = await runCtx.ucan.resolveServiceDid(composioBaseUrl);
+    if (!composioDid)
+        return null;
+    try {
+        // skipCache: the composio-worker enforces single-use replay protection
+        // per invocation CID (see composio-worker `lib/validation.ts`
+        // `createInvocationStore`, KV-backed, 120s default TTL). A cached
+        // invocation would be replayed on the second request and rejected with
+        // `401 REPLAY: Invocation has already been used`. Mint fresh every call.
+        const invocation = await runCtx.ucan.mintInvocation({ did: composioDid, capability: 'ixo:sandbox' }, { skipCache: true });
+        return invocation && invocation.length > 0 ? invocation : null;
+    }
+    catch (error) {
+        const detail = error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : String(error);
+        runCtx.logger.warn(`[composio] failed to mint UCAN invocation: ${detail}`);
+        return null;
+    }
+}

package/dist/plugins/composio/composio.plugin.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginManifest, PluginTool, RuntimeContext } from '../../plugin-api/types.js';
+import { type ComposioSessionFactory } from './composio-tools.js';
+export interface ComposioPluginOptions {
+    /**
+     * Override the session factory — primarily for tests so they can skip the
+     * real `@composio/core` client and the network call it makes.
+     */
+    sessionFactory?: ComposioSessionFactory;
+    /**
+     * Override the UCAN minting step — primarily for tests so they can return
+     * a fixed token without invoking the real UCAN service.
+     */
+    mintInvocation?: (runCtx: RuntimeContext, baseUrl: string) => Promise<string | null>;
+}
+/**
+ * Composio plugin.
+ *
+ * Tools are discovered dynamically per request: the plugin mints a UCAN
+ * invocation addressed to the composio-worker, opens a session for the
+ * current user, and exposes each returned tool to the agent.
+ *
+ * Auth is UCAN-only — no Matrix-OpenID fallback. If minting fails (no
+ * signing key, no cached delegation, did:web unresolved) the plugin
+ * contributes zero tools and the agent simply does not see composio that
+ * request. Visibility is `on-demand` so the plugin is discoverable via
+ * `list_capabilities` rather than burning prompt budget every call.
+ */
+export declare class ComposioPlugin extends OraclePlugin {
+    readonly name = "composio";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        COMPOSIO_API_KEY: z.ZodString;
+        COMPOSIO_BASE_URL: z.ZodDefault<z.ZodURL>;
+    }, z.core.$strip>;
+    readonly autoDetectHint = "COMPOSIO_API_KEY";
+    private readonly sessionFactoryOverride?;
+    private readonly mintInvocationOverride?;
+    constructor(opts?: ComposioPluginOptions);
+    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]>;
+}
+//# sourceMappingURL=composio.plugin.d.ts.map

package/dist/plugins/composio/composio.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composio.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/composio/composio.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAwD7B,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,IAAI,cAAc;IAE3B,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;;sBAAgB;IAE9C,SAAkB,cAAc,sBAAsB;IAEtD,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAyB;IACjE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAGZ;gBAEhB,IAAI,GAAE,qBAA0B;IAMnC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAIrC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAyC7E"}

package/dist/plugins/composio/composio.plugin.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { createComposioTools, } from './composio-tools.js';
+import { mintComposioInvocation } from './composio-ucan.js';
+const configSchema = z.object({
+    COMPOSIO_API_KEY: z.string().min(1, 'COMPOSIO_API_KEY must not be empty.'),
+    COMPOSIO_BASE_URL: z
+        .url('COMPOSIO_BASE_URL must be a valid HTTP(S) URL.')
+        .default('https://composio.ixo.earth'),
+});
+/**
+ * Sibling env vars the plugin reads but does not own. `NETWORK` is declared
+ * in the core base schema; the plugin forwards it as `x-ixo-network` when
+ * present so the composio-worker can route to the right IXO environment.
+ */
+const siblingEnvSchema = z.object({
+    NETWORK: z.string().optional(),
+});
+const manifest = {
+    title: 'Composio',
+    summary: 'External SaaS tools (Gmail, GitHub, Linear, Slack, Google Calendar, Notion, Jira, HubSpot, hundreds more) invoked on behalf of the user through Composio.',
+    whenToUse: [
+        'ALWAYS call `COMPOSIO_MANAGE_CONNECTIONS` first — before calling any other Composio tool — to verify the required toolkit is connected. If the response contains a `redirect_url`, show it as a clickable markdown link and stop; do not attempt the action.',
+        'User asks to send, read, or search emails (Gmail, Outlook).',
+        'User asks to create or modify issues, pull requests, or stars in a tracker (GitHub, Linear, Jira).',
+        'User asks to manage calendar events, files, or documents in a SaaS app.',
+        'No native skill covers the requested action — call `COMPOSIO_SEARCH_TOOLS` before giving up.',
+    ],
+    whenNotToUse: [
+        'A native skill or sub-agent already covers the action — prefer the skill.',
+        'Normal conversation or general question with no external SaaS interaction.',
+        'NEVER write, guess, or fabricate any URL yourself — the only valid auth link is the `redirect_url` returned by `COMPOSIO_MANAGE_CONNECTIONS`. Typing a link from memory is forbidden.',
+    ],
+    examples: [
+        {
+            user: 'Create a Linear issue for this bug',
+            thought: 'Must verify Linear is connected before touching any Linear tool.',
+            tool: 'COMPOSIO_MANAGE_CONNECTIONS',
+            args: { toolkit: 'linear' },
+        },
+        {
+            user: 'Send an email to the team',
+            thought: 'Must verify Gmail is connected before calling any Gmail tool.',
+            tool: 'COMPOSIO_MANAGE_CONNECTIONS',
+            args: { toolkit: 'gmail' },
+        },
+    ],
+    tags: ['composio', 'integration', 'saas', 'tools'],
+    category: 'integration',
+    visibility: 'on-demand',
+    stability: 'stable',
+};
+/**
+ * Composio plugin.
+ *
+ * Tools are discovered dynamically per request: the plugin mints a UCAN
+ * invocation addressed to the composio-worker, opens a session for the
+ * current user, and exposes each returned tool to the agent.
+ *
+ * Auth is UCAN-only — no Matrix-OpenID fallback. If minting fails (no
+ * signing key, no cached delegation, did:web unresolved) the plugin
+ * contributes zero tools and the agent simply does not see composio that
+ * request. Visibility is `on-demand` so the plugin is discoverable via
+ * `list_capabilities` rather than burning prompt budget every call.
+ */
+export class ComposioPlugin extends OraclePlugin {
+    name = 'composio';
+    version = '1.0.0';
+    manifest = manifest;
+    configSchema = configSchema;
+    autoDetectHint = 'COMPOSIO_API_KEY';
+    sessionFactoryOverride;
+    mintInvocationOverride;
+    constructor(opts = {}) {
+        super();
+        this.sessionFactoryOverride = opts.sessionFactory;
+        this.mintInvocationOverride = opts.mintInvocation;
+    }
+    autoDetect(env) {
+        return Boolean(env.COMPOSIO_API_KEY);
+    }
+    async getRequestTools(rtCtx) {
+        const parsed = configSchema.safeParse(rtCtx.config);
+        if (!parsed.success) {
+            rtCtx.logger.warn(`[composio] skipping — invalid configuration: ${parsed.error.issues
+                .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+                .join('; ')}`);
+            return [];
+        }
+        const siblings = siblingEnvSchema.safeParse(rtCtx.config);
+        const network = siblings.success ? siblings.data.NETWORK : undefined;
+        const mint = this.mintInvocationOverride ?? mintComposioInvocation;
+        const ucanInvocation = await mint(rtCtx, parsed.data.COMPOSIO_BASE_URL);
+        if (!ucanInvocation) {
+            rtCtx.logger.warn('[composio] skipping — UCAN invocation could not be minted.');
+            return [];
+        }
+        try {
+            return await createComposioTools({
+                apiKey: parsed.data.COMPOSIO_API_KEY,
+                baseUrl: parsed.data.COMPOSIO_BASE_URL,
+                ucanInvocation,
+                userId: rtCtx.user.did,
+                network,
+                sessionFactory: this.sessionFactoryOverride,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error
+                ? `${error.name}: ${error.message}`
+                : String(error);
+            rtCtx.logger.error(`[composio] failed to load tools: ${detail}`);
+            return [];
+        }
+    }
+}

package/dist/plugins/composio/index.d.ts

@@ -0,0 +1,4 @@
+export { ComposioPlugin, type ComposioPluginOptions, } from './composio.plugin.js';
+export { createComposioTools, createDefaultComposioSessionFactory, type ComposioSessionFactory, type ComposioSessionFactoryArgs, type ComposioSessionTool, type CreateComposioToolsOptions, } from './composio-tools.js';
+export { mintComposioInvocation } from './composio-ucan.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/composio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/composio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,mCAAmC,EACnC,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/plugins/composio/index.js

@@ -0,0 +1,3 @@
+export { ComposioPlugin, } from './composio.plugin.js';
+export { createComposioTools, createDefaultComposioSessionFactory, } from './composio-tools.js';
+export { mintComposioInvocation } from './composio-ucan.js';

package/dist/plugins/credits/claim-processing.module.d.ts

@@ -0,0 +1,28 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { Redis } from 'ioredis';
+import { type CreditsNetwork } from './token-limiter.js';
+/**
+ * Options for `ClaimProcessingModule.register`.
+ *
+ * `TokenLimiter` is stateless — it routes calls to Redis and holds no
+ * mutable state outside it. Two instances pointing at the same Redis are
+ * functionally identical, so this module builds its own from the supplied
+ * Redis client instead of trying to share a single instance across plugins.
+ */
+export interface ClaimProcessingModuleOptions {
+    /** Same `ioredis` client the credits plugin uses. */
+    redis: Redis;
+    /** Network — drives the credits-per-USD multiplier inside `TokenLimiter`. */
+    network: CreditsNetwork;
+    /** Whether `DISABLE_CREDITS` is set — relaxes the overdraft guard. */
+    disableCredits?: boolean;
+}
+/**
+ * NestJS module shipping the claim-processing cron service. Imported by the
+ * runtime via `CreditsPlugin.getNestModules()` when the plugin is loaded
+ * with a Redis client. Silent / agent-invisible — no controller, no tools.
+ */
+export declare class ClaimProcessingModule {
+    static register(opts: ClaimProcessingModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=claim-processing.module.d.ts.map

package/dist/plugins/credits/claim-processing.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-processing.module.d.ts","sourceRoot":"","sources":["../../../src/plugins/credits/claim-processing.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKrC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,KAAK,EAAE,KAAK,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,cAAc,CAAC;IACxB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBACa,qBAAqB;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,GAAG,aAAa;CAkBnE"}

package/dist/plugins/credits/claim-processing.module.js

@@ -0,0 +1,37 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var ClaimProcessingModule_1;
+import { Module } from '@nestjs/common';
+import { CLAIM_PROCESSING_TOKEN_LIMITER, ClaimProcessingService, } from './claim-processing.service.js';
+import { TokenLimiter } from './token-limiter.js';
+/**
+ * NestJS module shipping the claim-processing cron service. Imported by the
+ * runtime via `CreditsPlugin.getNestModules()` when the plugin is loaded
+ * with a Redis client. Silent / agent-invisible — no controller, no tools.
+ */
+let ClaimProcessingModule = ClaimProcessingModule_1 = class ClaimProcessingModule {
+    static register(opts) {
+        const tokenLimiter = new TokenLimiter({
+            redis: opts.redis,
+            network: opts.network,
+            disableCredits: opts.disableCredits ?? false,
+        });
+        const tokenLimiterProvider = {
+            provide: CLAIM_PROCESSING_TOKEN_LIMITER,
+            useValue: tokenLimiter,
+        };
+        return {
+            module: ClaimProcessingModule_1,
+            providers: [tokenLimiterProvider, ClaimProcessingService],
+            exports: [ClaimProcessingService],
+        };
+    }
+};
+ClaimProcessingModule = ClaimProcessingModule_1 = __decorate([
+    Module({})
+], ClaimProcessingModule);
+export { ClaimProcessingModule };

package/dist/plugins/credits/claim-processing.service.d.ts

@@ -0,0 +1,92 @@
+import { ConfigService } from '@nestjs/config';
+import { UcanService } from '../../modules/ucan/ucan.service.js';
+import { TokenLimiter } from './token-limiter.js';
+/** Token used to inject the credits-plugin TokenLimiter instance into the service. */
+export declare const CLAIM_PROCESSING_TOKEN_LIMITER: unique symbol;
+export interface UsageClaim {
+    amount: number;
+    oracleDid: string;
+    oracleEntityDid: string;
+    userDid: string;
+    service: string;
+    oracleName: string;
+}
+interface ClaimProcessingConfig {
+    ORACLE_DID: string;
+    ORACLE_ENTITY_DID: string;
+    ORACLE_NAME: string;
+    NETWORK: 'mainnet' | 'testnet' | 'devnet';
+    SQLITE_DATABASE_PATH: string;
+    MATRIX_ORACLE_ADMIN_ACCESS_TOKEN: string;
+    MATRIX_ACCOUNT_ROOM_ID?: string;
+    MATRIX_VALUE_PIN: string;
+    SECP_MNEMONIC: string;
+    SUBSCRIPTION_URL?: string;
+    DISABLE_CREDITS?: boolean;
+}
+/**
+ * Submits held-credit claims to the chain on a fixed cron. Pulls users with
+ * non-zero held amounts from the credits-plugin `TokenLimiter`, then runs a
+ * LangGraph `entrypoint`+`task` workflow per user:
+ *
+ *   1. submit intent (escrow payment)
+ *   2. sign + save the claim to Matrix
+ *   3. submit the claim on-chain
+ *   4. notify the subscription API
+ *
+ * Splits oversized batches against the oracle's per-claim max. Internal,
+ * agent-invisible — `claimProcessingPlugin` declares `visibility: 'silent'`
+ * and ships no tools.
+ */
+export declare class ClaimProcessingService {
+    private readonly configService;
+    private readonly ucanService;
+    private readonly logger;
+    private readonly denom;
+    private readonly claimProcessingCheckpointer;
+    private readonly claimProcessingDbPath;
+    private readonly tokenLimiter;
+    private readonly retryPolicy;
+    constructor(configService: ConfigService<ClaimProcessingConfig>, ucanService: UcanService, tokenLimiter?: TokenLimiter);
+    /**
+     * Slice `heldAmount` into chunks no larger than `maxAmount`. Used when the
+     * total held amount exceeds the oracle's per-claim ceiling.
+     */
+    private calculateSplits;
+    /** Step 1 of the workflow: pay the user's claim collection escrow. */
+    private submitIntentTask;
+    /** Step 2: build a signed claim and stash it in the oracle's Matrix room. */
+    private saveToMatrixTask;
+    /** Step 3: submit the signed claim on-chain against the user's collection. */
+    private submitToChainTask;
+    /** Step 4: notify the subscription API so it can update the user's balance. */
+    private sendToSubsApiTask;
+    /**
+     * Per-call factory so the langgraph `entrypoint` always picks up the
+     * checkpointer initialized in `constructor`.
+     */
+    private getProcessClaimWorkflow;
+    /**
+     * Cron-triggered processor — walks users above the minimum held-credits
+     * threshold, splits oversized batches against the oracle's per-claim max,
+     * and runs the 4-step claim workflow for each. Errors are logged and
+     * isolated per-user so one user's failure doesn't stall the batch.
+     */
+    processHeldAmount(): Promise<void>;
+    /**
+     * Invoke the LangGraph workflow for a single amount (full or split chunk)
+     * and reconcile the held-amount / pending-claim records on success.
+     */
+    private processAmount;
+}
+/**
+ * Submit a saved claim to the subscription-API webhook so the upstream
+ * service can mark it credited. Kept inline (rather than a separate file)
+ * since it's only used here and trivial.
+ */
+export declare function submitClaimToSubscriptionApi(subscriptionApiUrl: string, claimId: string): Promise<{
+    approved: boolean;
+    reason?: string;
+}>;
+export {};
+//# sourceMappingURL=claim-processing.service.d.ts.map

package/dist/plugins/credits/claim-processing.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-processing.service.d.ts","sourceRoot":"","sources":["../../../src/plugins/credits/claim-processing.service.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAY/C,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,sFAAsF;AACtF,eAAO,MAAM,8BAA8B,eAE1C,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,UAAU,qBAAqB;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gCAAgC,EAAE,MAAM,CAAC;IACzC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA0BD;;;;;;;;;;;;;GAaG;AACH,qBACa,sBAAsB;IAc/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAd9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAsB;IAClE,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAI1B;gBAGiB,aAAa,EAAE,aAAa,CAAC,qBAAqB,CAAC,EACnD,WAAW,EAAE,WAAW,EAGzC,YAAY,CAAC,EAAE,YAAY;IA0C7B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAevB,sEAAsE;IACtE,OAAO,CAAC,gBAAgB,CAgDtB;IAEF,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB,CA+DtB;IAEF,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB,CAwCvB;IAEF,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAkBvB;IAEF;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;;;;OAKG;IAEG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsIxC;;;OAGG;YACW,aAAa;CAyE5B;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BjD"}