# Understanding Copilot SDK Factory Limits: maxConcurrentSubagents, timeoutSeconds, and maxAiCredits

> Learn about Copilot SDK Factory limits including maxConcurrentSubagents, timeoutSeconds, and maxAiCredits. Prevent runtime overconsumption by understanding these key constraints.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: deep-dive
- Published: 2026-08-02

---

**The Copilot SDK enforces resource constraints on Agent Factories through the `FactoryLimits` interface, validating `maxConcurrentSubagents`, `timeoutSeconds`, and `maxAiCredits` at registration time in [`nodejs/src/factory.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/factory.ts) to prevent runtime overconsumption.**

The github/copilot-sdk repository provides extension authors with a framework for building AI agents that spawn sub-agents and consume computational resources. Understanding Copilot SDK Factory limits is essential for preventing resource exhaustion and ensuring predictable behavior in production environments. These constraints are declared in the factory metadata and strictly validated when you register your factory using `defineFactory`.

## What Are Copilot SDK Factory Limits?

Agent Factories can spawn sub-agents, execute code for bounded durations, and consume AI credits during operation. To prevent runaway processes, the SDK requires authors to declare resource caps inside the **Factory Meta → limits** object. When you call `defineFactory` in [`nodejs/src/factory.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/factory.ts), the SDK deep-freezes the metadata and executes `validateLimits` to enforce compliance before registration succeeds.

The limits are TypeScript-defined in the `FactoryLimits` interface located at `nodejs/src/types.ts:L38-L49`. All numeric constraints must be positive when present, with specific upper bounds enforced by the validation logic.

## The Four Core Limit Parameters

The `FactoryLimits` interface exposes four distinct constraints that govern factory behavior throughout its lifecycle.

### maxConcurrentSubagents

The `maxConcurrentSubagents` parameter defines the maximum number of sub-agents permitted to run simultaneously at any given moment. According to the validation logic in `nodejs/src/factory.ts:L383-L387`, this value must be a **positive integer** when supplied. Attempting to register a factory with zero, negative numbers, or non-integer values triggers an immediate validation error.

### maxTotalSubagents

Distinct from concurrent limits, `maxTotalSubagents` establishes a lifetime ceiling on the total number of sub-agents that may be spawned over the factory's entire execution. This limit shares the same validation rules as `maxConcurrentSubagents`—it must be a **positive integer** if provided, enforced in the same code block at `nodejs/src/factory.ts:L383-L387`.

### timeoutSeconds

The `timeoutSeconds` parameter sets an upper bound on accumulated active-execution time for the factory and all its descendants. Active execution includes the extension body, subprocess waits, queued-agent waits, and sleep operations. The validation logic at `nodejs/src/factory.ts:L90-L104` requires this value to be a **finite, positive** number that cannot exceed Node.js's timer ceiling of `2,147,483.647` seconds (`MAX_FACTORY_TIMEOUT_SECONDS`).

### maxAiCredits

This soft ceiling constrains AI-credit consumption for the factory and its entire sub-agent tree. When specified, the value must be a **positive, finite** number that, when multiplied by `1,000,000,000` (nano-AI units), rounds to a safe integer as determined by `Number.isSafeInteger`. This validation occurs at `nodejs/src/factory.ts:L107-L118`. The SDK treats this as a post-paid soft limit, meaning enforcement happens after consumption occurs rather than blocking requests prospectively.

## Validation and Error Handling

When `defineFactory` processes your factory definition, it immediately deep-freezes the metadata object to prevent mutation, then runs `validateLimits` against your declared constraints. Any violation produces a descriptive `Error` that prevents registration, allowing you to catch configuration issues during development rather than production.

If you attempt to exceed the Node.js timeout ceiling, the SDK throws: `Factory limit "timeoutSeconds" must not exceed 2147483.647 seconds`.

## Practical Implementation Examples

### Defining a Factory with Resource Limits

Configure your factory with explicit constraints to prevent resource exhaustion:

```typescript
import { defineFactory } from '@copilot/sdk';

export const myFactory = defineFactory({
  meta: {
    name: "example-factory",
    description: "Demo factory with limits",
    phases: [{ title: "setup" }, { title: "run" }],
    limits: {
      maxConcurrentSubagents: 3,   // at most 3 sub-agents concurrently
      maxTotalSubagents: 10,      // no more than 10 sub-agents overall
      timeoutSeconds: 60,         // max 1 minute of active execution
      maxAiCredits: 5,            // soft ceiling of 5 AI credits
    },
  },

  async run({ emit }) {
    // factory logic here…
  },
});

```

The SDK validates these limits at [`nodejs/src/factory.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/factory.ts) during the registration call. If any value violates the constraints—such as `timeoutSeconds` exceeding approximately 24.8 days—the factory registration fails immediately with a descriptive error message.

### Inspecting Limits at Runtime

You can retrieve factory metadata for UI display or logging purposes:

```typescript
import { getFactoryDefinition } from '@copilot/sdk';

const def = getFactoryDefinition(myFactory);
console.log(def.meta.limits);
/*
{
  maxConcurrentSubagents: 3,
  maxTotalSubagents: 10,
  timeoutSeconds: 60,
  maxAiCredits: 5,
}
*/

```

This approach leverages the deep-frozen metadata object returned by the SDK, ensuring you see the exact values validated at registration time.

## Summary

- **Resource constraints** in the Copilot SDK are declared via the `FactoryLimits` interface in [`nodejs/src/types.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts) and validated in [`nodejs/src/factory.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/factory.ts).
- **`maxConcurrentSubagents`** and **`maxTotalSubagents`** must be positive integers limiting simultaneous and total sub-agent counts respectively.
- **`timeoutSeconds`** caps active execution time at a maximum of `2,147,483.647` seconds and must be finite and positive.
- **`maxAiCredits`** imposes a soft ceiling on AI consumption, requiring values that convert safely to nano-AI units (multiplying by 1,000,000,000).
- **Validation occurs at registration** when `defineFactory` calls `validateLimits`, throwing errors for invalid configurations before runtime.

## Frequently Asked Questions

### What happens if I exceed maxConcurrentSubagents at runtime?

The Copilot SDK enforces `maxConcurrentSubagents` as a hard limit. When your factory attempts to spawn additional sub-agents beyond the declared concurrent maximum, the SDK blocks the creation request. This prevention occurs at the factory level, ensuring you never exceed the simultaneous execution threshold defined in your `FactoryLimits`.

### Is maxAiCredits a hard limit that stops execution immediately?

No, `maxAiCredits` operates as a **soft, post-paid ceiling**. The SDK tracks consumption throughout execution and enforces the limit retrospectively rather than blocking AI requests prospectively. You must still specify a positive, finite number that safely converts to nano-AI units (multiplied by 1,000,000,000) as validated in `nodejs/src/factory.ts:L107-L118`.

### What is the absolute maximum value for timeoutSeconds?

The validation logic at `nodejs/src/factory.ts:L90-L104` enforces a hard ceiling of `2,147,483.647` seconds (approximately 24.8 days), defined as `MAX_FACTORY_TIMEOUT_SECONDS`. This corresponds to Node.js's maximum timer duration. Values exceeding this threshold trigger a validation error during factory registration.

### Where are FactoryLimits defined in the source code?

The `FactoryLimits` TypeScript interface is defined in [`nodejs/src/types.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts) at lines 38-49, specifying the optional properties for `maxConcurrentSubagents`, `maxTotalSubagents`, `timeoutSeconds`, and `maxAiCredits`. The corresponding validation logic resides in [`nodejs/src/factory.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/factory.ts), with comprehensive test coverage available in [`nodejs/test/factory.test.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/factory.test.ts).