@oobe-protocol-labs/synapse-client-sdk 1.0.8 → 1.2.0

package/dist/cjs/ai/tools/protocols/solana-programs/tools.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.solanaProgramsMethodNames = exports.solanaProgramsMethods = void 0;
+exports.createSolanaProgramsTools = createSolanaProgramsTools;
+/**
+ * @module ai/tools/protocols/solana-programs/tools
+ * @description Solana Native Programs — LangChain tool factory.
+ *
+ * Creates 16 instruction-building tools that encode Solana native
+ * program instructions (System, SPL Token, ATA, Compute Budget, Memo).
+ * These tools run locally — no RPC or REST calls needed.
+ *
+ * ```ts
+ * const programs = createSolanaProgramsTools();
+ * agent.tools.push(...programs.tools);
+ *
+ * // Agent can now build instructions:
+ * // "Transfer 1 SOL from <wallet> to <recipient>"
+ * // → calls solana_programs_systemTransfer tool
+ * ```
+ *
+ * @since 1.1.0
+ */
+const shared_1 = require("../shared");
+const schemas_1 = require("./schemas");
+const types_1 = require("../../../../core/types");
+const system_1 = require("../../../../programs/system");
+const spl_token_1 = require("../../../../programs/spl-token");
+const associated_token_1 = require("../../../../programs/associated-token");
+const compute_budget_1 = require("../../../../programs/compute-budget");
+const memo_1 = require("../../../../programs/memo");
+/* ═══════════════════════════════════════════════════════════════
+ *  Serialiser — TransactionInstruction → JSON-friendly output
+ * ═══════════════════════════════════════════════════════════════ */
+/** @internal Convert Uint8Array to base64 for JSON transport */
+function uint8ToBase64(data) {
+    // Node.js path (fastest)
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(data).toString('base64');
+    // Browser path
+    let binary = '';
+    for (let i = 0; i < data.length; i++)
+        binary += String.fromCharCode(data[i]);
+    return btoa(binary);
+}
+/** @internal Serialise a TransactionInstruction for LLM consumption */
+function serialiseInstruction(ix) {
+    return {
+        programId: ix.programId,
+        keys: ix.keys.map((k) => ({
+            pubkey: k.pubkey,
+            isSigner: k.isSigner,
+            isWritable: k.isWritable,
+        })),
+        data: uint8ToBase64(ix.data),
+    };
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Execution dispatcher — local instruction encoding
+ * ═══════════════════════════════════════════════════════════════ */
+function createProgramsExecutor() {
+    return async (method, input) => {
+        switch (method.name) {
+            // ── System Program ───────────────────────────────────────
+            case 'systemTransfer':
+                return serialiseInstruction(system_1.SystemProgram.transfer({
+                    from: (0, types_1.Pubkey)(input.from),
+                    to: (0, types_1.Pubkey)(input.to),
+                    lamports: BigInt(input.lamports),
+                }));
+            case 'systemCreateAccount':
+                return serialiseInstruction(system_1.SystemProgram.createAccount({
+                    from: (0, types_1.Pubkey)(input.from),
+                    newAccount: (0, types_1.Pubkey)(input.newAccount),
+                    lamports: BigInt(input.lamports),
+                    space: input.space,
+                    programId: (0, types_1.Pubkey)(input.programId),
+                }));
+            case 'systemAllocate':
+                return serialiseInstruction(system_1.SystemProgram.allocate({
+                    account: (0, types_1.Pubkey)(input.account),
+                    space: input.space,
+                }));
+            case 'systemAssign':
+                return serialiseInstruction(system_1.SystemProgram.assign({
+                    account: (0, types_1.Pubkey)(input.account),
+                    programId: (0, types_1.Pubkey)(input.programId),
+                }));
+            // ── SPL Token ────────────────────────────────────────────
+            case 'tokenTransfer':
+                return serialiseInstruction(spl_token_1.SplToken.transfer({
+                    source: (0, types_1.Pubkey)(input.source),
+                    destination: (0, types_1.Pubkey)(input.destination),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    amount: BigInt(input.amount),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenTransferChecked':
+                return serialiseInstruction(spl_token_1.SplToken.transferChecked({
+                    source: (0, types_1.Pubkey)(input.source),
+                    mint: (0, types_1.Pubkey)(input.mint),
+                    destination: (0, types_1.Pubkey)(input.destination),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    amount: BigInt(input.amount),
+                    decimals: input.decimals,
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenApprove':
+                return serialiseInstruction(spl_token_1.SplToken.approve({
+                    account: (0, types_1.Pubkey)(input.account),
+                    delegate: (0, types_1.Pubkey)(input.delegate),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    amount: BigInt(input.amount),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenRevoke':
+                return serialiseInstruction(spl_token_1.SplToken.revoke({
+                    account: (0, types_1.Pubkey)(input.account),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenMintTo':
+                return serialiseInstruction(spl_token_1.SplToken.mintTo({
+                    mint: (0, types_1.Pubkey)(input.mint),
+                    destination: (0, types_1.Pubkey)(input.destination),
+                    authority: (0, types_1.Pubkey)(input.authority),
+                    amount: BigInt(input.amount),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenBurn':
+                return serialiseInstruction(spl_token_1.SplToken.burn({
+                    account: (0, types_1.Pubkey)(input.account),
+                    mint: (0, types_1.Pubkey)(input.mint),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    amount: BigInt(input.amount),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            case 'tokenCloseAccount':
+                return serialiseInstruction(spl_token_1.SplToken.closeAccount({
+                    account: (0, types_1.Pubkey)(input.account),
+                    destination: (0, types_1.Pubkey)(input.destination),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    programId: input.programId ? (0, types_1.Pubkey)(input.programId) : undefined,
+                }));
+            // ── Associated Token Account ─────────────────────────────
+            case 'ataCreate':
+                return serialiseInstruction(associated_token_1.AssociatedToken.create({
+                    payer: (0, types_1.Pubkey)(input.payer),
+                    associatedToken: (0, types_1.Pubkey)(input.associatedToken),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    mint: (0, types_1.Pubkey)(input.mint),
+                    tokenProgramId: input.tokenProgramId ? (0, types_1.Pubkey)(input.tokenProgramId) : undefined,
+                }));
+            case 'ataCreateIdempotent':
+                return serialiseInstruction(associated_token_1.AssociatedToken.createIdempotent({
+                    payer: (0, types_1.Pubkey)(input.payer),
+                    associatedToken: (0, types_1.Pubkey)(input.associatedToken),
+                    owner: (0, types_1.Pubkey)(input.owner),
+                    mint: (0, types_1.Pubkey)(input.mint),
+                    tokenProgramId: input.tokenProgramId ? (0, types_1.Pubkey)(input.tokenProgramId) : undefined,
+                }));
+            // ── Compute Budget ───────────────────────────────────────
+            case 'setComputeUnitLimit':
+                return serialiseInstruction(compute_budget_1.ComputeBudget.setComputeUnitLimit({
+                    units: input.units,
+                }));
+            case 'setComputeUnitPrice':
+                return serialiseInstruction(compute_budget_1.ComputeBudget.setComputeUnitPrice({
+                    microLamports: BigInt(input.microLamports),
+                }));
+            // ── Memo ─────────────────────────────────────────────────
+            case 'addMemo':
+                return serialiseInstruction(memo_1.Memo.addMemo({
+                    message: input.message,
+                    signer: input.signer ? (0, types_1.Pubkey)(input.signer) : undefined,
+                }));
+            default:
+                throw new Error(`Unknown Solana program method: ${method.name}`);
+        }
+    };
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  createSolanaProgramsTools()
+ *
+ *  Public factory — the single entry-point for consumers.
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Create LangChain-compatible tools for Solana native programs.
+ *
+ * All 16 tools run locally — they encode instructions using the SDK's
+ * native binary encoders. No RPC or REST API calls are made.
+ *
+ * @param {SolanaProgramsToolsConfig & CreateProtocolToolsOpts} [config={}] - Tool options
+ * @returns {ProtocolToolkit} Toolkit with 16 instruction-building tools
+ *
+ * @example
+ * ```ts
+ * const programs = createSolanaProgramsTools();
+ * const agent = createAgent({ tools: programs.tools });
+ *
+ * // Agent builds a SOL transfer instruction:
+ * const result = await programs.toolMap.systemTransfer.invoke({
+ *   from: 'SenderWallet...',
+ *   to: 'ReceiverWallet...',
+ *   lamports: '1000000000',
+ * });
+ *
+ * // Cherry-pick:
+ * const transferTool = programs.toolMap.tokenTransferChecked;
+ * ```
+ *
+ * @since 1.1.0
+ */
+function createSolanaProgramsTools(config = {}) {
+    const { ...toolOpts } = config;
+    const execute = createProgramsExecutor();
+    return (0, shared_1.buildProtocolTools)(schemas_1.solanaProgramsMethods, execute, {
+        defaultPrefix: 'solana_programs_',
+        ...toolOpts,
+    });
+}
+/** Re-export schemas for direct access. */
+var schemas_2 = require("./schemas");
+Object.defineProperty(exports, "solanaProgramsMethods", { enumerable: true, get: function () { return schemas_2.solanaProgramsMethods; } });
+Object.defineProperty(exports, "solanaProgramsMethodNames", { enumerable: true, get: function () { return schemas_2.solanaProgramsMethodNames; } });
+//# sourceMappingURL=tools.js.map

package/dist/cjs/ai/tools/protocols/solana-programs/tools.js.map

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

package/dist/cjs/context/container.d.ts

@@ -0,0 +1,341 @@
+/**
+ * SynapseContext — IoC service container with scoping, middleware, and lifecycle management.
+ *
+ * This is the core runtime of the context provider system. It holds all
+ * service registrations and resolves them on demand, respecting lifecycle
+ * rules (singleton / transient / scoped), circular-dependency detection,
+ * and middleware chains.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { SynapseContext, createToken } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * interface Logger { log(msg: string): void; }
+ * const LOGGER = createToken<Logger>('Logger');
+ *
+ * const ctx = new SynapseContext();
+ * ctx.register(LOGGER, { useValue: console });
+ * const logger = ctx.resolve(LOGGER); // typed as Logger
+ * ```
+ *
+ * ## Scoping
+ *
+ * ```ts
+ * const scope = ctx.createScope('request-123');
+ * scope.register(REQUEST_ID, { useValue: '123' });
+ * scope.resolve(LOGGER);      // inherits from parent
+ * scope.resolve(REQUEST_ID);  // scoped value
+ * scope.dispose();
+ * ```
+ *
+ * @module context/container
+ * @since 1.2.0
+ */
+import type { ServiceToken, ServiceProvider, ServiceLifecycle, ServiceRegistration, ServiceResolver, ResolveMiddleware, ContextEvents } from './types';
+import { ServiceRef, RefRegistry, MemoryGuard, type MemoryGuardConfig, type ServiceBinding } from './refs';
+/**
+ * The main IoC service container.
+ *
+ * Provides type-safe dependency injection with support for:
+ * - Value, factory, class, alias, and async factory providers
+ * - Singleton, transient, and scoped lifecycles
+ * - Hierarchical scopes (child inherits parent registrations)
+ * - Circular dependency detection
+ * - Resolve middleware (logging, metrics, decoration)
+ * - Automatic disposal of services implementing `Disposable`
+ * - Event-driven observability
+ *
+ * @since 1.2.0
+ */
+export declare class SynapseContext implements ServiceResolver {
+    readonly scopeId: string;
+    private readonly parent?;
+    private readonly registry;
+    private readonly middlewares;
+    private readonly events;
+    private readonly resolutionStack;
+    private readonly children;
+    private disposed;
+    /** @internal Lazy ref registry — created on first acquireRef(). */
+    private _refRegistry?;
+    /** @internal Optional memory guard. */
+    private _memoryGuard?;
+    /**
+     * @param scopeId - Unique scope identifier (auto-generated for child scopes).
+     * @param parent  - Parent context for hierarchical resolution.
+     */
+    constructor(scopeId?: string, parent?: SynapseContext | undefined);
+    /** @internal Get or create the ref registry. */
+    private getRefRegistry;
+    /**
+     * Acquire a tracked, ref-counted reference to a service.
+     *
+     * Returns a {@link ServiceRef} that must be `.release()`'d when no
+     * longer needed. Multiple `acquireRef()` calls for the same singleton
+     * token return different refs to the **same** instance — the ref count
+     * tracks how many holders exist.
+     *
+     * @typeParam T - The service type.
+     * @param token - The service token to resolve.
+     * @returns A new `ServiceRef<T>` linked to this context's ref registry.
+     * @throws {ServiceNotFoundError} If no provider is registered for the token.
+     * @since 1.2.0
+     *
+     * @example
+     * ```ts
+     * // Component A
+     * const rpcRef = ctx.acquireRef(Tokens.RPC);
+     * await rpcRef.current.getBalance(pubkey);
+     *
+     * // Component B — same singleton, separate ref
+     * const rpcRef2 = ctx.acquireRef(Tokens.RPC);
+     * ctx.refCount(Tokens.RPC); // → 2
+     *
+     * // Cleanup
+     * rpcRef.release();   // ref count → 1
+     * rpcRef2.release();  // ref count → 0
+     * ```
+     */
+    acquireRef<T>(token: ServiceToken<T>): ServiceRef<T>;
+    /**
+     * Acquire tracked refs for multiple tokens at once.
+     *
+     * Returns a {@link ServiceBinding} whose `.services` proxy lazily
+     * resolves each token. A single `.release()` frees all refs.
+     *
+     * @param tokens - Record mapping property names to service tokens.
+     * @returns A binding with lazy services and batch release.
+     * @since 1.2.0
+     *
+     * @example
+     * ```ts
+     * const binding = ctx.bind({
+     *   rpc: Tokens.RPC,
+     *   das: Tokens.DAS,
+     *   programs: Tokens.PROGRAMS,
+     * });
+     *
+     * await binding.services.rpc.getBalance(pubkey);
+     * binding.release(); // releases all at once
+     * ```
+     */
+    bind<T extends Record<string, ServiceToken>>(tokens: T): ServiceBinding<T>;
+    /**
+     * Number of active (unreleased) refs for a specific token.
+     *
+     * Returns `0` if no refs have been acquired or the ref registry
+     * hasn't been initialized yet.
+     *
+     * @since 1.2.0
+     */
+    refCount(token: ServiceToken): number;
+    /**
+     * The ref registry for this context, if any refs have been acquired.
+     *
+     * Returns `undefined` if `acquireRef()` has never been called.
+     * @since 1.2.0
+     */
+    get refs(): RefRegistry | undefined;
+    /**
+     * Enable a memory guard with configurable thresholds.
+     *
+     * The guard monitors ref counts and emits pressure/leak events.
+     * Can only be called once per context.
+     *
+     * @param config - Guard thresholds.
+     * @returns The created `MemoryGuard`.
+     * @since 1.2.0
+     *
+     * @example
+     * ```ts
+     * const guard = ctx.enableMemoryGuard({
+     *   maxRefAgeMs: 30_000,
+     *   maxActiveRefs: 50,
+     *   checkIntervalMs: 10_000,
+     * });
+     *
+     * guard.onPressure(stats => console.warn('Memory pressure:', stats));
+     * guard.onLeak(leak => console.error('Leaked ref:', leak));
+     * ```
+     */
+    enableMemoryGuard(config?: MemoryGuardConfig): MemoryGuard;
+    /**
+     * The active memory guard, if enabled.
+     * @since 1.2.0
+     */
+    get memoryGuard(): MemoryGuard | undefined;
+    /**
+     * Register a service provider for a token.
+     *
+     * @param token    - The service token.
+     * @param provider - How to create the service.
+     * @param tags     - Optional tags for filtering.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * ctx.register(DB, { useFactory: r => new PostgresDB(r.resolve(CONFIG)) });
+     * ctx.register(LOGGER, { useValue: console }, ['core']);
+     * ctx.register(CACHE, { useClass: RedisCache, lifecycle: 'singleton' });
+     * ```
+     *
+     * @since 1.2.0
+     */
+    register<T>(token: ServiceToken<T>, provider: ServiceProvider<T>, tags?: string[]): this;
+    /**
+     * Register multiple services at once.
+     *
+     * @param registrations - Array of `{ token, provider, tags? }` descriptors.
+     * @returns `this` for chaining.
+     * @since 1.2.0
+     */
+    registerMany(registrations: ServiceRegistration[]): this;
+    /**
+     * Register a service only if the token is not already registered.
+     *
+     * Useful for default/fallback providers that should not override
+     * user-provided registrations.
+     *
+     * @since 1.2.0
+     */
+    registerIfMissing<T>(token: ServiceToken<T>, provider: ServiceProvider<T>, tags?: string[]): this;
+    /**
+     * Resolve a service synchronously.
+     *
+     * @throws {ServiceNotFoundError} If no provider is registered.
+     * @throws {CircularDependencyError} If a circular dependency is detected.
+     * @throws {AsyncProviderError} If the provider is async.
+     * @since 1.2.0
+     */
+    resolve<T>(token: ServiceToken<T>): T;
+    /**
+     * Resolve a service asynchronously.
+     *
+     * Required for services registered with `useAsyncFactory`.
+     * Also works for sync providers (wraps result in a resolved promise).
+     *
+     * @since 1.2.0
+     */
+    resolveAsync<T>(token: ServiceToken<T>): Promise<T>;
+    /**
+     * Try to resolve a service; return `undefined` if not registered.
+     * @since 1.2.0
+     */
+    tryResolve<T>(token: ServiceToken<T>): T | undefined;
+    /**
+     * Check if a token has a provider (searches parent scopes too).
+     * @since 1.2.0
+     */
+    has(token: ServiceToken): boolean;
+    /**
+     * Resolve all services whose registrations contain the given tag.
+     * @since 1.2.0
+     */
+    resolveByTag(tag: string): unknown[];
+    /**
+     * Create a child scope that inherits all parent registrations.
+     *
+     * Scoped services get fresh instances in the child scope.
+     * The child scope is tracked and disposed when the parent is disposed.
+     *
+     * @param scopeId - Unique identifier for the child scope.
+     * @returns A new `SynapseContext` linked to this parent.
+     * @since 1.2.0
+     *
+     * @example
+     * ```ts
+     * const reqScope = ctx.createScope(`request-${id}`);
+     * reqScope.register(REQUEST_CTX, { useValue: { id, user } });
+     * // ... handle request ...
+     * reqScope.dispose();
+     * ```
+     */
+    createScope(scopeId?: string): SynapseContext;
+    /**
+     * Add a resolve middleware.
+     *
+     * Middleware functions wrap every `resolve()` call. They execute in
+     * the order they are added (first-in, outermost).
+     *
+     * @param mw - Middleware function.
+     * @returns `this` for chaining.
+     * @since 1.2.0
+     *
+     * @example
+     * ```ts
+     * ctx.use((token, next) => {
+     *   console.time(token.name);
+     *   const result = next();
+     *   console.timeEnd(token.name);
+     *   return result;
+     * });
+     * ```
+     */
+    use(mw: ResolveMiddleware): this;
+    /**
+     * Subscribe to a container event.
+     * @since 1.2.0
+     */
+    on<K extends keyof ContextEvents>(event: K, handler: (payload: ContextEvents[K]) => void): this;
+    /**
+     * Unsubscribe from a container event.
+     * @since 1.2.0
+     */
+    off<K extends keyof ContextEvents>(event: K, handler: (payload: ContextEvents[K]) => void): this;
+    /**
+     * Dispose this context and all child scopes.
+     *
+     * Calls `.dispose()` on all singleton/scoped services that implement
+     * {@link Disposable}. After disposal, any call to `resolve()` throws.
+     *
+     * @returns Number of services disposed.
+     * @since 1.2.0
+     */
+    dispose(): Promise<number>;
+    /**
+     * Get all registered tokens (this scope only, not parent).
+     * @since 1.2.0
+     */
+    get tokens(): ServiceToken[];
+    /**
+     * Get all registered tokens across this scope and all parents.
+     * @since 1.2.0
+     */
+    get allTokens(): ServiceToken[];
+    /**
+     * Number of services registered in this scope.
+     * @since 1.2.0
+     */
+    get size(): number;
+    /**
+     * Whether this context has been disposed.
+     * @since 1.2.0
+     */
+    get isDisposed(): boolean;
+    /**
+     * Return a snapshot of registered services for debugging.
+     * @since 1.2.0
+     */
+    snapshot(): Array<{
+        token: string;
+        lifecycle: ServiceLifecycle;
+        resolved: boolean;
+        tags: string[];
+    }>;
+    /** @internal Synchronous resolution (no middleware). */
+    private doResolve;
+    /** @internal Async resolution. */
+    private doResolveAsync;
+    /** @internal Instantiate a sync provider. */
+    private instantiate;
+    /** @internal Find registry entry (local scope first, then parent). */
+    private findEntry;
+    /** @internal Get lifecycle for a token (for event emission). */
+    private getLifecycle;
+    /** @internal Apply middleware chain. */
+    private applyMiddleware;
+    /** @internal Guard against usage after disposal. */
+    private assertNotDisposed;
+}
+//# sourceMappingURL=container.d.ts.map

package/dist/cjs/context/container.d.ts.map

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