@portel/photon 1.4.1 → 1.6.0

package/dist/serv/middleware/tenant.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Tenant Resolution Middleware
+ *
+ * Resolves tenant from request (subdomain, path, or custom domain)
+ * and attaches to request context
+ */
+import type { Tenant, RequestContext } from '../types/index.js';
+export interface TenantStore {
+    /**
+     * Find tenant by slug
+     */
+    findBySlug(slug: string): Promise<Tenant | null>;
+    /**
+     * Find tenant by custom domain
+     */
+    findByCustomDomain(domain: string): Promise<Tenant | null>;
+    /**
+     * Find tenant by ID
+     */
+    findById(id: string): Promise<Tenant | null>;
+}
+export declare class MemoryTenantStore implements TenantStore {
+    private tenants;
+    private slugIndex;
+    private domainIndex;
+    /**
+     * Add a tenant to the store
+     */
+    add(tenant: Tenant): void;
+    findBySlug(slug: string): Promise<Tenant | null>;
+    findByCustomDomain(domain: string): Promise<Tenant | null>;
+    findById(id: string): Promise<Tenant | null>;
+}
+export interface TenantResolverConfig {
+    /** Base domain for subdomain resolution (e.g., 'serv.example.com') */
+    baseDomain: string;
+    /** Tenant store implementation */
+    store: TenantStore;
+    /** Path prefix for path-based tenant resolution */
+    pathPrefix?: string;
+}
+export declare class TenantResolver {
+    private config;
+    constructor(config: TenantResolverConfig);
+    /**
+     * Resolve tenant from HTTP request
+     */
+    resolve(request: {
+        host?: string;
+        url?: string;
+        headers?: {
+            host?: string;
+        };
+    }): Promise<Tenant | null>;
+    /**
+     * Extract subdomain from host
+     */
+    private extractSubdomain;
+    /**
+     * Extract tenant slug from URL path
+     */
+    private extractPathSlug;
+}
+export interface ContextBuilderConfig {
+    tenantResolver: TenantResolver;
+}
+export declare class RequestContextBuilder {
+    private tenantResolver;
+    constructor(config: ContextBuilderConfig);
+    /**
+     * Build request context from HTTP request
+     */
+    build(request: {
+        host?: string;
+        url?: string;
+        headers?: {
+            host?: string;
+            authorization?: string;
+        };
+    }): Promise<RequestContext | null>;
+}
+/**
+ * Extract tenant slug from URL for routing
+ */
+export declare function extractTenantSlug(url: string, pathPrefix?: string): string | null;
+/**
+ * Build tenant-specific URL
+ */
+export declare function buildTenantUrl(baseUrl: string, tenant: Tenant, path: string): string;
+/**
+ * Build resource URI for OAuth audience
+ */
+export declare function buildResourceUri(baseUrl: string, tenant: Tenant): string;
+//# sourceMappingURL=tenant.d.ts.map

package/dist/serv/middleware/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../../src/serv/middleware/tenant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMhE,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEjD;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9C;AAMD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,WAAW,CAAkC;IAErD;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQnB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMhD,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAM1D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGnD;AAMD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,EAAE,oBAAoB;IAOxC;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7B,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAyB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;OAEG;IACH,OAAO,CAAC,eAAe;CAUxB;AAMD,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,cAAc,CAAC;CAChC;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,cAAc,CAAiB;gBAE3B,MAAM,EAAE,oBAAoB;IAIxC;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACrD,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;CASnC;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,SAAa,GAAG,MAAM,GAAG,IAAI,CAQrF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/serv/middleware/tenant.js

@@ -0,0 +1,152 @@
+/**
+ * Tenant Resolution Middleware
+ *
+ * Resolves tenant from request (subdomain, path, or custom domain)
+ * and attaches to request context
+ */
+// ============================================================================
+// In-Memory Tenant Store (Development)
+// ============================================================================
+export class MemoryTenantStore {
+    tenants = new Map();
+    slugIndex = new Map();
+    domainIndex = new Map();
+    /**
+     * Add a tenant to the store
+     */
+    add(tenant) {
+        this.tenants.set(tenant.id, tenant);
+        this.slugIndex.set(tenant.slug, tenant.id);
+        if (tenant.settings.customDomain) {
+            this.domainIndex.set(tenant.settings.customDomain, tenant.id);
+        }
+    }
+    async findBySlug(slug) {
+        const id = this.slugIndex.get(slug);
+        if (!id)
+            return null;
+        return this.tenants.get(id) ?? null;
+    }
+    async findByCustomDomain(domain) {
+        const id = this.domainIndex.get(domain);
+        if (!id)
+            return null;
+        return this.tenants.get(id) ?? null;
+    }
+    async findById(id) {
+        return this.tenants.get(id) ?? null;
+    }
+}
+export class TenantResolver {
+    config;
+    constructor(config) {
+        this.config = {
+            pathPrefix: '/tenant/',
+            ...config,
+        };
+    }
+    /**
+     * Resolve tenant from HTTP request
+     */
+    async resolve(request) {
+        const host = request.host ?? request.headers?.host ?? '';
+        const url = request.url ?? '';
+        // 1. Try subdomain resolution (acme.serv.example.com)
+        const subdomain = this.extractSubdomain(host);
+        if (subdomain) {
+            const tenant = await this.config.store.findBySlug(subdomain);
+            if (tenant)
+                return tenant;
+        }
+        // 2. Try path-based resolution (/tenant/acme/...)
+        const pathSlug = this.extractPathSlug(url);
+        if (pathSlug) {
+            const tenant = await this.config.store.findBySlug(pathSlug);
+            if (tenant)
+                return tenant;
+        }
+        // 3. Try custom domain resolution
+        const tenant = await this.config.store.findByCustomDomain(host);
+        if (tenant)
+            return tenant;
+        return null;
+    }
+    /**
+     * Extract subdomain from host
+     */
+    extractSubdomain(host) {
+        // Remove port if present
+        const hostWithoutPort = host.split(':')[0];
+        // Check if it's a subdomain of our base domain
+        if (!hostWithoutPort.endsWith(`.${this.config.baseDomain}`)) {
+            return null;
+        }
+        // Extract subdomain
+        const subdomain = hostWithoutPort.slice(0, hostWithoutPort.length - this.config.baseDomain.length - 1);
+        // Validate: must be single-level and not empty
+        if (!subdomain || subdomain.includes('.')) {
+            return null;
+        }
+        return subdomain;
+    }
+    /**
+     * Extract tenant slug from URL path
+     */
+    extractPathSlug(url) {
+        const prefix = this.config.pathPrefix;
+        const pathStart = url.indexOf(prefix);
+        if (pathStart === -1)
+            return null;
+        const afterPrefix = url.slice(pathStart + prefix.length);
+        const slug = afterPrefix.split('/')[0];
+        return slug || null;
+    }
+}
+export class RequestContextBuilder {
+    tenantResolver;
+    constructor(config) {
+        this.tenantResolver = config.tenantResolver;
+    }
+    /**
+     * Build request context from HTTP request
+     */
+    async build(request) {
+        const tenant = await this.tenantResolver.resolve(request);
+        if (!tenant)
+            return null;
+        return {
+            tenant,
+            // Session and user are added by auth middleware
+        };
+    }
+}
+// ============================================================================
+// HTTP Middleware Helpers
+// ============================================================================
+/**
+ * Extract tenant slug from URL for routing
+ */
+export function extractTenantSlug(url, pathPrefix = '/tenant/') {
+    const pathStart = url.indexOf(pathPrefix);
+    if (pathStart === -1)
+        return null;
+    const afterPrefix = url.slice(pathStart + pathPrefix.length);
+    const slug = afterPrefix.split('/')[0];
+    return slug || null;
+}
+/**
+ * Build tenant-specific URL
+ */
+export function buildTenantUrl(baseUrl, tenant, path) {
+    if (tenant.settings.customDomain) {
+        return `https://${tenant.settings.customDomain}${path}`;
+    }
+    return `${baseUrl}/tenant/${tenant.slug}${path}`;
+}
+/**
+ * Build resource URI for OAuth audience
+ */
+export function buildResourceUri(baseUrl, tenant) {
+    return buildTenantUrl(baseUrl, tenant, '/mcp');
+}
+//# sourceMappingURL=tenant.js.map

package/dist/serv/middleware/tenant.js.map

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

package/dist/serv/runtime/executor.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SERV Photon Executor
+ *
+ * Executes photons with SERV context (session, OAuth, tenant isolation).
+ * Wraps the PhotonLoader with SERV-specific input/output handling.
+ */
+import type { Session, Tenant } from '../types/index.js';
+import type { OAuthFlowHandler } from '../auth/oauth.js';
+import type { TokenVault } from '../vault/token-vault.js';
+import { OAuthContext, OAuthElicitationRequired, type OAuthAsk } from './oauth-context.js';
+export interface ExecutorConfig {
+    oauthFlow: OAuthFlowHandler;
+    tokenVault: TokenVault;
+}
+export interface ExecutionContext {
+    session: Session;
+    tenant: Tenant;
+    photonId: string;
+}
+export interface ExecutionResult {
+    success: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * SERV Photon Executor
+ *
+ * Provides a SERV-aware execution environment for photons:
+ * - OAuth token management via yields
+ * - Session-scoped execution
+ * - Tenant isolation
+ */
+export declare class PhotonExecutor {
+    private config;
+    constructor(config: ExecutorConfig);
+    /**
+     * Create an OAuth context for a photon execution
+     */
+    createOAuthContext(context: ExecutionContext): OAuthContext;
+    /**
+     * Create an input provider with OAuth support
+     *
+     * @param context - Execution context
+     * @param fallbackProvider - Provider for non-OAuth asks
+     */
+    createInputProvider(context: ExecutionContext, fallbackProvider?: (ask: Record<string, unknown>) => Promise<unknown>): (ask: OAuthAsk | Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Format an error for MCP response
+     */
+    formatError(error: unknown): ExecutionResult;
+}
+/**
+ * Check if an error is an OAuth elicitation request
+ */
+export declare function isOAuthElicitationError(error: unknown): error is OAuthElicitationRequired;
+/**
+ * Format OAuth elicitation error for MCP tool response
+ *
+ * Returns a structured error that MCP clients can understand
+ * and potentially auto-handle (e.g., opening auth URL in browser).
+ */
+export declare function formatElicitationToolResponse(error: OAuthElicitationRequired): {
+    content: Array<{
+        type: 'text';
+        text: string;
+        annotations?: {
+            mimeType?: string;
+        };
+    }>;
+    isError: boolean;
+};
+//# sourceMappingURL=executor.d.ts.map

package/dist/serv/runtime/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/serv/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,wBAAwB,EAExB,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAM5B,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAMD;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAIlC;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY;IAU3D;;;;;OAKG;IACH,mBAAmB,CACjB,OAAO,EAAE,gBAAgB,EACzB,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GACpE,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC;IAKhE;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe;CAiB7C;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,wBAAwB,GAAG;IAC9E,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACrC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,CAwBA"}

package/dist/serv/runtime/executor.js

@@ -0,0 +1,105 @@
+/**
+ * SERV Photon Executor
+ *
+ * Executes photons with SERV context (session, OAuth, tenant isolation).
+ * Wraps the PhotonLoader with SERV-specific input/output handling.
+ */
+import { OAuthContext, OAuthElicitationRequired, createOAuthInputProvider, } from './oauth-context.js';
+// ============================================================================
+// Photon Executor
+// ============================================================================
+/**
+ * SERV Photon Executor
+ *
+ * Provides a SERV-aware execution environment for photons:
+ * - OAuth token management via yields
+ * - Session-scoped execution
+ * - Tenant isolation
+ */
+export class PhotonExecutor {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Create an OAuth context for a photon execution
+     */
+    createOAuthContext(context) {
+        return new OAuthContext({
+            session: context.session,
+            photonId: context.photonId,
+            tenantId: context.tenant.id,
+            oauthFlow: this.config.oauthFlow,
+            tokenVault: this.config.tokenVault,
+        });
+    }
+    /**
+     * Create an input provider with OAuth support
+     *
+     * @param context - Execution context
+     * @param fallbackProvider - Provider for non-OAuth asks
+     */
+    createInputProvider(context, fallbackProvider) {
+        const oauthContext = this.createOAuthContext(context);
+        return createOAuthInputProvider(oauthContext, fallbackProvider);
+    }
+    /**
+     * Format an error for MCP response
+     */
+    formatError(error) {
+        if (error instanceof OAuthElicitationRequired) {
+            return {
+                success: false,
+                error: error.toMCPError().error,
+            };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: {
+                code: 'EXECUTION_ERROR',
+                message,
+            },
+        };
+    }
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Check if an error is an OAuth elicitation request
+ */
+export function isOAuthElicitationError(error) {
+    return error instanceof OAuthElicitationRequired;
+}
+/**
+ * Format OAuth elicitation error for MCP tool response
+ *
+ * Returns a structured error that MCP clients can understand
+ * and potentially auto-handle (e.g., opening auth URL in browser).
+ */
+export function formatElicitationToolResponse(error) {
+    const elicitationInfo = {
+        type: 'oauth_elicitation',
+        provider: error.provider,
+        scopes: error.scopes,
+        url: error.elicitationUrl,
+        id: error.elicitationId,
+        message: error.message,
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(elicitationInfo, null, 2),
+                annotations: { mimeType: 'application/json' },
+            },
+            {
+                type: 'text',
+                text: `\n\n---\n🔐 **Authorization Required**\n\nThis tool needs access to ${error.provider}.\n\nPlease visit this URL to authorize:\n${error.elicitationUrl}\n\nAfter authorization, retry the tool request.`,
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/serv/runtime/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/serv/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,GAEzB,MAAM,oBAAoB,CAAC;AA2B5B,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IACjB,MAAM,CAAiB;IAE/B,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,kBAAkB,CAAC,OAAyB;QAC1C,OAAO,IAAI,YAAY,CAAC;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE;YAC3B,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;SACnC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CACjB,OAAyB,EACzB,gBAAqE;QAErE,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACtD,OAAO,wBAAwB,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAc;QACxB,IAAI,KAAK,YAAY,wBAAwB,EAAE,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,KAAK;aAChC,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI,EAAE,iBAAiB;gBACvB,OAAO;aACR;SACF,CAAC;IACJ,CAAC;CACF;AAED,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,KAAK,YAAY,wBAAwB,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAA+B;IAQ3E,MAAM,eAAe,GAAG;QACtB,IAAI,EAAE,mBAAmB;QACzB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,EAAE,KAAK,CAAC,cAAc;QACzB,EAAE,EAAE,KAAK,CAAC,aAAa;QACvB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;IAEF,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9C,WAAW,EAAE,EAAE,QAAQ,EAAE,kBAAkB,EAAE;aAC9C;YACD;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,uEAAuE,KAAK,CAAC,QAAQ,6CAA6C,KAAK,CAAC,cAAc,kDAAkD;aAC/M;SACF;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,8 @@
+/**
+ * SERV Runtime Module
+ *
+ * Provides execution context for photons running in SERV.
+ */
+export { OAuthContext, OAuthElicitationRequired, createOAuthInputProvider, type OAuthAsk, type OAuthResponse, type OAuthContextConfig, type OAuthInputProvider, } from './oauth-context.js';
+export { PhotonExecutor, isOAuthElicitationError, formatElicitationToolResponse, type ExecutorConfig, type ExecutionContext, type ExecutionResult, } from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/serv/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/serv/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,6BAA6B,EAC7B,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}

package/dist/serv/runtime/index.js

@@ -0,0 +1,10 @@
+/**
+ * SERV Runtime Module
+ *
+ * Provides execution context for photons running in SERV.
+ */
+// OAuth Context
+export { OAuthContext, OAuthElicitationRequired, createOAuthInputProvider, } from './oauth-context.js';
+// Executor
+export { PhotonExecutor, isOAuthElicitationError, formatElicitationToolResponse, } from './executor.js';
+//# sourceMappingURL=index.js.map

package/dist/serv/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/serv/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gBAAgB;AAChB,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,GAKzB,MAAM,oBAAoB,CAAC;AAE5B,WAAW;AACX,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,6BAA6B,GAI9B,MAAM,eAAe,CAAC"}

package/dist/serv/runtime/oauth-context.d.ts

@@ -0,0 +1,121 @@
+/**
+ * OAuth Runtime Context for SERV
+ *
+ * Provides OAuth token access within photon execution context.
+ * Enables photons to request OAuth tokens via yield-based elicitation.
+ */
+import type { Session } from '../types/index.js';
+import type { TokenVault } from '../vault/token-vault.js';
+import type { OAuthFlowHandler } from '../auth/oauth.js';
+/**
+ * OAuth token request yield
+ * When a photon needs an OAuth token, it yields this
+ */
+export interface OAuthAsk {
+    ask: 'oauth';
+    /** OAuth provider ID (e.g., 'google', 'github') */
+    provider: string;
+    /** Required OAuth scopes */
+    scopes: string[];
+    /** Human-readable message explaining why auth is needed */
+    message?: string;
+}
+/**
+ * OAuth ask response - either a token or an elicitation request
+ */
+export interface OAuthResponse {
+    /** Whether the token is available */
+    success: boolean;
+    /** The access token (if available) */
+    token?: string;
+    /** Elicitation required - redirect user to this URL */
+    elicitationUrl?: string;
+    /** Elicitation ID for tracking */
+    elicitationId?: string;
+    /** Error message if something went wrong */
+    error?: string;
+}
+/**
+ * MCP Elicitation Error
+ *
+ * When a photon needs user authorization, this error is returned
+ * following the MCP elicitation protocol.
+ */
+export declare class OAuthElicitationRequired extends Error {
+    readonly code = "OAUTH_ELICITATION_REQUIRED";
+    readonly elicitationUrl: string;
+    readonly elicitationId: string;
+    readonly provider: string;
+    readonly scopes: string[];
+    constructor(options: {
+        elicitationUrl: string;
+        elicitationId: string;
+        provider: string;
+        scopes: string[];
+        message?: string;
+    });
+    /**
+     * Convert to MCP error response format
+     */
+    toMCPError(): {
+        error: {
+            code: string;
+            message: string;
+            data: {
+                elicitation: {
+                    type: 'oauth';
+                    url: string;
+                    id: string;
+                    provider: string;
+                    scopes: string[];
+                };
+            };
+        };
+    };
+}
+export interface OAuthContextConfig {
+    session: Session;
+    photonId: string;
+    tenantId: string;
+    oauthFlow: OAuthFlowHandler;
+    tokenVault: TokenVault;
+}
+/**
+ * OAuth context for photon execution
+ *
+ * Provides a way for photons to request OAuth tokens during execution.
+ * Integrates with SERV's OAuth flow handler to manage grants and elicitations.
+ */
+export declare class OAuthContext {
+    private session;
+    private photonId;
+    private tenantId;
+    private oauthFlow;
+    private tokenVault;
+    constructor(config: OAuthContextConfig);
+    /**
+     * Request an OAuth token
+     *
+     * @param provider - OAuth provider ID
+     * @param scopes - Required scopes
+     * @returns Token if available, or throws OAuthElicitationRequired
+     */
+    requestToken(provider: string, scopes: string[]): Promise<string>;
+    /**
+     * Handle an OAuth ask yield
+     *
+     * @param ask - The OAuth ask yield from the photon
+     * @returns OAuth response
+     */
+    handleOAuthAsk(ask: OAuthAsk): Promise<OAuthResponse>;
+}
+export type OAuthInputProvider = (ask: OAuthAsk | Record<string, unknown>) => Promise<unknown>;
+/**
+ * Create an input provider that handles OAuth asks
+ *
+ * Wraps the standard input provider to add OAuth token handling.
+ * When an 'oauth' ask is received, it checks for existing grants
+ * or initiates an elicitation flow.
+ */
+export declare function createOAuthInputProvider(oauthContext: OAuthContext, fallbackProvider?: (ask: Record<string, unknown>) => Promise<unknown>): OAuthInputProvider;
+//# sourceMappingURL=oauth-context.d.ts.map

package/dist/serv/runtime/oauth-context.d.ts.map

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