@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/factory.d.ts

@@ -0,0 +1,225 @@
+/**
+ * `MastraFactory` — the single entry point to the whole Mastra Software Factory.
+ *
+ * The consumer's deploy entry constructs deployment-specific config instances
+ * (auth adapter, pubsub) and passes them here explicitly. The only provider
+ * defaults constructed here are Platform GitHub, GitLab, Jira, incident.io, and
+ * Linear integrations when Platform credentials exist and the caller did not
+ * provide those integrations.
+ *
+ * `prepare()` resolves feature readiness, threads every dependency explicitly,
+ * assembles the web routes/middleware, and returns the constructor args for
+ * `new Mastra(...)`. The literal `export const mastra = new Mastra(...)` must
+ * stay in the entry file — the deployer's `checkConfigExport` Babel plugin
+ * only marks the config valid when it finds that literal in the entry AST —
+ * so the factory produces args instead of the instance. `finalize()` runs the
+ * post-construct boot (controller init + workers).
+ *
+ * Integration readiness is derived from each instance's declared capabilities
+ * and the storage domains those capabilities require.
+ */
+import type { BuiltinToolId } from '@mastra/core/agent-controller';
+import type { PubSub } from '@mastra/core/events';
+import type { Knowledge } from '@mastra/core/knowledge';
+import type { Mastra } from '@mastra/core/mastra';
+import type { IMastraAuthProvider } from '@mastra/core/server';
+import type { FactoryStorage } from '@mastra/core/storage';
+import type { MastraVector } from '@mastra/core/vector';
+import type { FactorySandboxDescription } from '@mastra/core/workspace';
+import type { InstalledBoard } from './boards/index.js';
+import type { FactoryIntegration } from './integrations/base.js';
+import type { GithubRuleOverrides } from './integrations/github/default-rules.js';
+import type { MastraFactorySandboxOption } from './sandbox/session-sandbox.js';
+import type { FactorySecretEncryption } from './secret-encryption.js';
+import type { FactorySandboxStart } from './workspace.js';
+/** Constructor args for the `new Mastra(...)` literal in the deploy entry. */
+export type MastraArgs = NonNullable<ConstructorParameters<typeof Mastra>[0]>;
+export interface MastraFactoryConfig {
+    /**
+     * Auth provider instance — `MastraAuthStudio` (`@mastra/auth-studio`),
+     * `MastraAuthWorkos` (`@mastra/auth-workos`), `MastraAuthBetterAuth`
+     * (`@mastra/auth-better-auth`), or any custom `MastraAuthProvider`. Whatever
+     * instance is passed is the active provider; a passed instance is always
+     * honored as-is.
+     *
+     * Omitted → the factory defaults to `MastraAuthStudio`, proxying auth
+     * through the shared Mastra platform API. `MastraAuthStudio` resolves its
+     * own env (`MASTRA_SHARED_API_URL`, `MASTRA_ORGANIZATION_ID`,
+     * `MASTRA_COOKIE_DOMAIN`).
+     *
+     * Pass `null` to disable auth entirely (open server, local-dev behavior)
+     * without falling back to the default.
+     */
+    auth?: IMastraAuthProvider | null;
+    /**
+     * REQUIRED. Factory storage backend powering BOTH agent storage (threads,
+     * messages, memory, OM — via `getMastraStorage()`) and the app tables
+     * (projects/source-control/audit/intake — via the generic ops surface). Pass a
+     * `PgFactoryStorage` (`@mastra/pg`) for deployments or a
+     * `LibSQLFactoryStorage` (`@mastra/libsql`) for local dev — one backend,
+     * one connection, every feature on.
+     */
+    storage: FactoryStorage;
+    /**
+     * Vector store instance for recall search — `PgVector` (`@mastra/pg`) on
+     * the same database as `storage`. Omitted → the SDK mount's default vector
+     * store resolution applies.
+     */
+    vector?: MastraVector;
+    /**
+     * Host-owned Knowledge runtime. Factory registers this exact instance under `key` and uses that
+     * key for its read surfaces. Omitted leaves Mastra Code's experimental default wiring in place.
+     */
+    knowledge?: {
+        key: string;
+        instance: Knowledge;
+    };
+    /**
+     * Distributed event bus instance (e.g. `new RedisStreamsPubSub({ url })`).
+     * When set, streams/workflows/signals ride it across processes and the
+     * controller drops file-based thread locks in favor of pubsub-coordinated
+     * leases. Omitted → in-process default.
+     */
+    pubsub?: PubSub;
+    /**
+     * Browser-facing origin used to build integration OAuth/install callback
+     * URLs and to derive the auth redirect URI. On the platform the SPA is
+     * hosted separately, so this MUST be the public API origin.
+     * Default: `http://localhost:4111` (the local Factory server, which also
+     * serves the UI).
+     */
+    publicUrl?: string;
+    /**
+     * Allowed cross-origin SPA origins. The SPA may be served from a separate
+     * static host, so credentialed requests must be explicitly allowed.
+     */
+    allowedOrigins?: string[];
+    /**
+     * The host's sandbox: a FactorySandbox instance such as
+     * `new PlatformFactorySandbox({ ... })`, which owns the session sandbox
+     * constructor, the repo template and the schema of environment settings.
+     * A bare callback is also accepted and wrapped as a `provider: 'custom'`
+     * sandbox with no settings. Omitted → repository sandboxes are
+     * disabled.
+     */
+    sandbox?: MastraFactorySandboxOption;
+    /**
+     * When a session's sandbox boots: on the agent's first command (`'lazy'`,
+     * the default) or as soon as the session's workspace is first resolved
+     * (`'eager'`), so the boot overlaps the model's own latency.
+     */
+    sandboxStart?: FactorySandboxStart;
+    /**
+     * Agent controller built-in tools (e.g. `submit_plan`) removed from every
+     * Factory session, along with their prompt guidance. Use this when a custom
+     * board gates planning with its own phase transition, so the in-session plan
+     * approval cannot bypass that gate.
+     */
+    disableBuiltinTools?: BuiltinToolId[];
+    /** Background Factory dispatcher configuration. */
+    dispatcher?: MastraFactoryDispatcherConfig;
+    /**
+     * Deployment-stable secret for signing integration OAuth `state` values.
+     * Omitted → a per-process random secret, which is fine for single-process
+     * local development but rejected for integrations that declare
+     * `requiresStableStateSigner`.
+     */
+    stateSecret?: string;
+    /**
+     * Encryption boundary for persisted model credentials, custom-provider API
+     * keys, integration connections, and integration settings. Strongly
+     * recommended whenever auth is enabled — omitting it falls back to explicit
+     * plaintext compatibility with a boot-time warning.
+     */
+    secretEncryption?: FactorySecretEncryption;
+    /**
+     * Model providers that authenticate with the server process's own
+     * credentials instead of per-account credentials. With auth enabled, these
+     * providers are only usable when listed here; the stored-key flow is never
+     * offered for them. Supported: `'amazon-bedrock'` (AWS credential chain —
+     * `AWS_BEARER_TOKEN_BEDROCK` or access keys/profile/role plus `AWS_REGION`).
+     * Every signed-in account can then run these models on the deployment's
+     * credentials. Default: none.
+     */
+    deploymentModelProviders?: readonly string[];
+    /**
+     * Registered capability providers. The factory registers the pieces each
+     * `FactoryIntegration` instance provides — HTTP routes, storage domains,
+     * agent/session tools, intake, source control, and diagnostics — into the
+     * system. When Platform credentials are configured, missing `github`,
+     * `gitlab`, and `linear` integrations default to their Platform-backed
+     * implementations. Missing `jira` and `incidentio` integrations also default
+     * to their Platform-backed implementations, which discover visible `jira` and
+     * `incident-io` connections at runtime.
+     */
+    integrations?: FactoryIntegration[];
+    /**
+     * Operator-maintained provenance label stamped on transition audit rows,
+     * deferred decisions, and session kickoff headers so a row can be traced
+     * back to the deployment that produced it. Nothing branches on it.
+     * Default: `factory-config-v1`.
+     */
+    configVersion?: string;
+    /** Board definitions installed for this Factory instance. */
+    boards?: readonly InstalledBoard[];
+    /** Whether the built-in Work and Review boards are installed. Default: true. */
+    includeDefaultBoards?: boolean;
+    /**
+     * Platform-specific overrides.
+     */
+    platform?: {
+        /** Identifies Factory's own GitHub App writes so their webhook deliveries do not retrigger triage. */
+        githubAppSlug?: string;
+        /**
+         * Overrides for the `PlatformGithubIntegration` the factory installs itself
+         * when Platform credentials are present; these options are forwarded to its
+         * constructor. An explicit integration with id `github` in `integrations`
+         * takes precedence and makes this key a no-op, so the two are not meant to
+         * be used together.
+         */
+        github?: {
+            /** Replace an event handler, or disable it with null; omitted events keep defaults. */
+            rules?: GithubRuleOverrides;
+            /**
+             * GitHub App slug used to recognize Factory's own webhook writes. Falls
+             * back to `githubAppSlug` when omitted.
+             */
+            slug?: string;
+        };
+    };
+}
+export type { MastraFactorySandboxConfig, MastraFactorySandboxOption } from './sandbox/session-sandbox.js';
+export type { FactorySandboxStart } from './workspace.js';
+/**
+ * Per-process cap on concurrent background Factory dispatches. Omitted means
+ * the dispatcher default; this is a local replica budget, not a global queue
+ * limit shared across deployments.
+ */
+export interface MastraFactoryDispatcherConfig {
+    maxInFlight?: number;
+}
+export declare class MastraFactory {
+    #private;
+    constructor(config: MastraFactoryConfig);
+    /**
+     * The host sandbox's provider, settings schema (JSON Schema) and
+     * capabilities, as the environment route reports them. Undefined before
+     * `prepare()` and when sandboxes are disabled.
+     */
+    get sandboxDescription(): FactorySandboxDescription | undefined;
+    /**
+     * Resolve feature readiness, wire every dependency explicitly, and assemble
+     * everything needed to construct the server-owned Mastra. Returns the args
+     * for the `new Mastra(...)` literal that must live in the entry file.
+     */
+    prepare(): Promise<MastraArgs>;
+    /**
+     * Post-construct boot: initialize the controller (which inherits the
+     * constructed Mastra's storage) and start its workers. Call AFTER the entry
+     * has run `new Mastra(prepare()'s args)`.
+     */
+    finalize(): Promise<void>;
+    /** Stop Factory-owned background dispatch before the host process shuts down. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

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