golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(#3673): add dispatch.maxConcurrency axis and dispatch-capacity query (#4162)

Browse Source 
* test(#3673): add failing tests for dispatch.maxConcurrency axis and dispatch-capacity CLI route

Extends tests/host-integration.test.cjs with negotiateHostCapabilities
maxConcurrency negotiation coverage (test matrix rows 1-15, including a
fast-check property test) and a new #3673 dispatch-capacity CLI route
describe block spawning the real gsd-tools.cjs (rows 16-25). Extends
tests/host-integration-validator-parity.test.cjs with an all-19-descriptor
maxConcurrency presence/validity sweep (row 26) and adds a hostile-input
validator test to host-integration.test.cjs (row 27).

The dispatch.maxConcurrency field does not exist yet, so these tests fail.

* feat(#3673): add dispatch.maxConcurrency axis, negotiation, validator parity, and the dispatch-capacity query

Adds a numeric dispatch.maxConcurrency sub-field to the Host-Integration
Interface (ADR-1239 Phase 1), following the existing dispatch.isolation
sub-field pattern: DispatchCapability interface, SAFE_DEFAULTS/PROFILE_BASELINES
floors, and a negotiateHostCapabilities branch that passes through a positive
safe integer and fails closed to 1 otherwise (no engine-side reduction, per
the design doc's explicit rejection of a min(host,engine) rule).

capability-validator.cjs gains parity validation for the new field (optional,
positive safe integer or the "undocumented" sentinel — mirroring isolation's
"added after existing descriptors" treatment).

gsd-tools.cjs gains a new `query dispatch-capacity` route, a pure-read sibling
of `dispatch-isolation` with no side effects: live env
(GSD_DISPATCH_MAX_CONCURRENCY) > descriptor > fallback-to-1 precedence.

All 19 capabilities/*/capability.json descriptors now declare
dispatch.maxConcurrency: claude carries the one cited value (20, per
code.claude.com/docs/en/sub-agents); the other 18 carry "undocumented"
(not yet researched for this axis).

* docs(#3673): document dispatch.maxConcurrency and add its citation row to the capability matrix

Updates docs/reference/host-integration-interface.md's dispatch struct entry
(also backfilling the previously-undocumented isolation/backgroundDispatch
sub-fields found stale in the same table) and adds fail-closed/live-transport
precedence prose for the new maxConcurrency field.

Adds a dispatch.maxConcurrency row (with citation) to all 19 host sections in
docs/reference/host-integration-capability-matrix.md — required for
tests/host-integration-descriptors.test.cjs's kimi-code matrix-parity check,
which asserts every declared dispatch sub-axis is documented there.

Updates docs/how-to/add-or-update-a-host-integration.md's dispatch checklist
and example descriptor block to mention maxConcurrency (and, likewise
backfilling a stale gap, isolation/backgroundDispatch).

* fix(#3673): extract shared maxConcurrency validator, drop dead reserved-name check

Exports isPositiveSafeInteger from src/host-integration.cts as the single
source of truth for the dispatch.maxConcurrency positive-safe-integer
contract; negotiateHostCapabilities and gsd-tools.cjs's routeDispatchCapacity
now both call it instead of independently reimplementing the same predicate.

Also removes the __proto__/constructor/prototype reserved-name branch from
capability-validator.cjs's maxConcurrency check — copy-pasted from the
string-enum fields above it, but unreachable for a numeric field (the
generic positive-safe-integer branch already rejects any string) and absent
from maxDepth, the field the code's own comment claims to mirror.

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-09-01 21:39:12 -04:00
committed by GitHub
parent b848b23861
commit c0fd2e3f4c
28 changed files with 714 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
src/host-integration.cts
View File

@@ -99,6 +99,13 @@ interface DispatchCapability {
subagentToolkit: SubagentToolkit;
backgroundDispatch: boolean;
isolation: DispatchIsolation;
// ADR-1239 Phase 1 (#3673): a numeric dispatch sub-field — not an enum axis
// member (same "numeric dispatch sub-field, excluded from
// HOST_INTEGRATION_AXES" precedent as maxDepth above). How many same-wave
// executors this host can run concurrently. Fail-closed floor is 1
// (strictly sequential); there is no engine-side ceiling to reduce
// against (unlike maxDepth) — see negotiateHostCapabilities below.
maxConcurrency: number;
}
interface HostIntegrationAxes {
@@ -127,7 +134,7 @@ interface DegradationResult {
const SAFE_DEFAULTS: HostIntegrationAxes = {
embeddingMode: 'declarative',
commandSurface: 'prose-only',
dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false, isolation: 'none' },
dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false, isolation: 'none', maxConcurrency: 1 },
modelMode: 'passive',
hookBus: 'none',
stateIO: 'session-log-append',
@@ -141,7 +148,7 @@ const PROFILE_BASELINES: Readonly<Record<'programmatic-cli' | 'declarative-cli'
'programmatic-cli': Object.freeze({
embeddingMode: 'imperative',
commandSurface: 'slash-file',
dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' }),
dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none', maxConcurrency: 1 }),
modelMode: 'passive',
hookBus: 'host',
stateIO: 'filesystem',
@@ -152,7 +159,7 @@ const PROFILE_BASELINES: Readonly<Record<'programmatic-cli' | 'declarative-cli'
'declarative-cli': Object.freeze({
embeddingMode: 'declarative',
commandSurface: 'slash-file',
dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false, isolation: 'none' }),
dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false, isolation: 'none', maxConcurrency: 1 }),
modelMode: 'passive',
hookBus: 'host',
stateIO: 'filesystem',
@@ -163,7 +170,7 @@ const PROFILE_BASELINES: Readonly<Record<'programmatic-cli' | 'declarative-cli'
'ide': Object.freeze({
embeddingMode: 'imperative',
commandSurface: 'palette',
dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' }),
dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none', maxConcurrency: 1 }),
modelMode: 'active',
hookBus: 'engine',
stateIO: 'sandboxed-storage',
@@ -296,7 +303,7 @@ const DEFAULT_ENGINE: EngineCapabilities = {
axes: {
embeddingMode: 'imperative',
commandSurface: 'slash-file',
dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' },
dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none', maxConcurrency: 1 },
modelMode: 'active',
hookBus: 'host',
stateIO: 'filesystem',
@@ -318,6 +325,21 @@ interface NegotiationResult {
warnings: string[];
}
// ---------------------------------------------------------------------------
// isPositiveSafeInteger — shared predicate (#3673)
// ---------------------------------------------------------------------------
/**
* True iff `v` is a positive (>0) JS safe integer. Single source of truth for
* the dispatch.maxConcurrency contract: used by negotiateHostCapabilities
* below, and by gsd-core/bin/gsd-tools.cjs's routeDispatchCapacity (which
* requires this module's compiled output rather than reimplementing the
* predicate), so the two consumers cannot silently diverge.
*/
function isPositiveSafeInteger(v: unknown): boolean {
return typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
}
// ---------------------------------------------------------------------------
// negotiateHostCapabilities
// ---------------------------------------------------------------------------
@@ -423,6 +445,7 @@ function negotiateHostCapabilities(
let effectiveSubagentToolkit: SubagentToolkit;
let effectiveMaxDepth: number;
let effectiveIsolation: DispatchIsolation;
let effectiveMaxConcurrency: number;
if (hostDispatch === null) {
// Host didn't declare dispatch at all — fail-closed to most-restrictive values
@@ -434,6 +457,7 @@ function negotiateHostCapabilities(
effectiveSubagentToolkit = 'read-only';
effectiveMaxDepth = 0;
effectiveIsolation = 'none';
effectiveMaxConcurrency = 1;
} else {
// N1: observability warnings for 'undocumented' sentinel on dispatch fields
if (hostDispatch.namedDispatch === 'undocumented') {
@@ -501,6 +525,36 @@ function negotiateHostCapabilities(
const minDepth = Math.min(hDepthNum, eDepthNum);
effectiveMaxDepth = minDepth === Infinity ? -1 : minDepth;
// maxConcurrency (#3673, ADR-1239 Phase 1): a positive-safe-integer
// passthrough with a fail-closed floor of 1. UNLIKE maxDepth, there is no
// min(host, engine) reduction here — the design doc explicitly rejects an
// engine-side ceiling for this field (no competing intrinsic worker
// ceiling to cap against at the negotiation layer); a `--jobs N` cap is
// applied later, at the Phase 4 scheduler.
const hostMaxConcurrency = hostDispatch.maxConcurrency;
if (hostMaxConcurrency === UNDOCUMENTED) {
warnings.push(`dispatch.maxConcurrency is undocumented — degraded closed (1)`);
effectiveMaxConcurrency = 1;
} else if (isPositiveSafeInteger(hostMaxConcurrency)) {
effectiveMaxConcurrency = hostMaxConcurrency as number;
} else if (hostMaxConcurrency === undefined) {
warnings.push(`host did not declare 'dispatch.maxConcurrency' — treating as 1`);
effectiveMaxConcurrency = 1;
} else if (typeof hostMaxConcurrency !== 'number') {
warnings.push(`host dispatch.maxConcurrency is not a number — treating as 1`);
effectiveMaxConcurrency = 1;
} else if (!Number.isSafeInteger(hostMaxConcurrency)) {
if (Number.isInteger(hostMaxConcurrency)) {
warnings.push(`host dispatch.maxConcurrency is an unsafe integer — treating as 1`);
} else {
warnings.push(`host dispatch.maxConcurrency is not an integer — treating as 1`);
}
effectiveMaxConcurrency = 1;
} else {
warnings.push(`host dispatch.maxConcurrency is non-positive — treating as 1`);
effectiveMaxConcurrency = 1;
}
// If namedDispatch is false, cap maxDepth/nested/background/backgroundDispatch to 0/false/false/false (struct consistency)
if (!effectiveNamedDispatch) {
effectiveMaxDepth = 0;
@@ -518,6 +572,7 @@ function negotiateHostCapabilities(
subagentToolkit: effectiveSubagentToolkit,
backgroundDispatch: effectiveBackgroundDispatch,
isolation: effectiveIsolation,
maxConcurrency: effectiveMaxConcurrency,
};
// ---------------------------------------------------------------------------
@@ -938,6 +993,7 @@ export = {
EXTENSION_EVENT_SURFACES,
degradationFor,
profileOf,
isPositiveSafeInteger,
negotiateHostCapabilities,
shouldFlattenDispatch,
resolveDispatchType,