JuliusBrussee/caveman · error · Error

caveman agent: artifact maxInlineTokens must be a non-negati

Error message

caveman agent: artifact maxInlineTokens must be a non-negative integer

What it means

Thrown by the artifact() builder when maxInlineTokens is not a safe non-negative integer. maxInlineTokens caps how many tokens of an artifact may be inlined into model-visible context; the default when omitted is 1,200. Negative values, fractions, NaN, and non-numbers are rejected because the cap feeds deterministic token budgeting.

Source

Thrown at packages/agent/src/primitives.ts:383

  };
  return Object.freeze(definition);
}

export interface ArtifactDefinition {
  readonly kind: "artifact";
  readonly strategy: "verbatim" | "json-index" | "page";
  readonly maxInlineTokens: number;
  readonly recovery: "exact_ccr" | "source_ref";
}

export function artifact(options: {
  strategy?: ArtifactDefinition["strategy"];
  maxInlineTokens?: number;
  recovery?: ArtifactDefinition["recovery"];
} = {}): ArtifactDefinition {
  const maxInlineTokens = options.maxInlineTokens ?? 1_200;
  if (!Number.isSafeInteger(maxInlineTokens) || maxInlineTokens < 0) {
    throw new Error("caveman agent: artifact maxInlineTokens must be a non-negative integer");
  }
  return Object.freeze({
    kind: "artifact",
    strategy: options.strategy ?? "page",
    maxInlineTokens,
    recovery: options.recovery ?? "exact_ccr",
  });
}

export interface OutputDefinition<TSchemaValue extends TSchema | undefined = TSchema | undefined> {
  readonly kind: "output";
  readonly maxTokens: number;
  readonly schema?: TSchemaValue;
}

export function output<T extends TSchema | undefined = undefined>(options: {
  maxTokens: number;
  schema?: T;

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Pass a non-negative integer or omit maxInlineTokens to accept the 1,200 default
2. Round computed caps: maxInlineTokens: Math.max(0, Math.trunc(window * 0.1))
3. There is no 'unlimited' — pick the largest inline budget your context window actually affords

Example fix

// before
artifact({ strategy: 'page', maxInlineTokens: contextWindow * 0.05 });

// after
artifact({ strategy: 'page', maxInlineTokens: Math.max(0, Math.trunc(contextWindow * 0.05)) });

function toMaxInlineTokens(raw: unknown): number | undefined {
  if (raw === undefined) return undefined;
  const n = typeof raw === 'number' ? raw : Number(raw);
  if (!Number.isSafeInteger(n) || n < 0) throw new Error(`maxInlineTokens must be a non-negative integer, got ${String(raw)}`);
  return n;
}

function isMaxInlineTokens(value: unknown): value is number { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }

When it happens

Trigger: Calling artifact({ maxInlineTokens: -1 }), 0.5, NaN, Infinity, a numeric string '1200', or a value above 2^53-1. Note 0 is legal (artifact never inlined).

Common situations: Scaling the cap from a model context size (window * 0.1) and passing the raw fraction; reading the number from env/config as a string; using -1 as an 'unlimited' sentinel from other APIs.

Related errors

• caveman agent: output maxTokens must be a positive integer
• cave_compaction_option_invalid
• cave_provider_usage_incomplete
• caveman agent: memory recallBudget must be a non-negative in
• caveman agent: context ttlTurns must be a positive integer

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/b6b01703c1fb2be8. Report an issue: GitHub.