@adea-ai/contracts 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,11 @@
1
1
  import { z } from 'zod';
2
2
  import { ServiceCallerAssertionSchema, ServiceScopeSchema } from './authentication.js';
3
3
  import { executionScopeFields, validateExecutionScopeFields } from './execution-scope.js';
4
- import { ModelIdSchema } from './decision-resolution.js';
4
+ import { DecisionLayerResolutionSchema, DecisionResolutionRequestSchema, ModelIdSchema, } from './decision-resolution.js';
5
5
  import { CorrelationMetadataSchema } from './envelopes.js';
6
6
  import { IdentifierSchemas } from './identifiers.js';
7
7
  import { CursorSchema } from './pagination.js';
8
+ import { SyncAppendRequestSchema, SyncAppendResponseSchema, SyncAuthorKeyIdSchema, SyncCommitResponseSchema, SyncDownloadRequestSchema, SyncDownloadResponseSchema, SyncLogPageSchema, SyncLogRequestSchema, SyncObjectRequestSchema, SyncReleaseResponseSchema, SyncUploadRequestSchema, SyncUploadResponseSchema, SyncUsageSchema, } from './device-sync.js';
8
9
  import { ContractVersionSchema } from './versioning.js';
9
10
  const TimestampSchema = z.iso.datetime();
10
11
  const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
@@ -103,6 +104,26 @@ export const ProfileResolutionRequestSchema = RequestContextSchema.extend({
103
104
  profileVersionId: IdentifierSchemas.profileVersionId.optional(),
104
105
  }),
105
106
  });
107
+ /**
108
+ * The decision layer (control-plane#558) over the public API. The envelope carries the request
109
+ * identity; `parameters` are the decision inputs. Every composition resolves with the same
110
+ * policy, so a desktop or VPS Local composition and managed cloud answer alike, and nothing here
111
+ * executes.
112
+ */
113
+ export const DecisionResolveRequestSchema = RequestContextSchema.extend({
114
+ operation: z.literal('decision.resolve'),
115
+ requestedAt: TimestampSchema,
116
+ parameters: DecisionResolutionRequestSchema.omit({
117
+ caller: true,
118
+ contractVersion: true,
119
+ requestId: true,
120
+ workspaceId: true,
121
+ projectId: true,
122
+ correlation: true,
123
+ requestedAt: true,
124
+ }),
125
+ });
126
+ export const DecisionResolveResponseSchema = successResponse(DecisionLayerResolutionSchema);
106
127
  export const ProfileResolutionResponseSchema = successResponse(z.object({
107
128
  profile: z.object({
108
129
  profileId: IdentifierSchemas.profileId,
@@ -209,32 +230,6 @@ export const CredentialListResponseSchema = successResponse(z
209
230
  nextCursor: CursorSchema.optional(),
210
231
  })
211
232
  .strict());
212
- // Hosted RuntimeNode credential revocation. Shares the connector credential scope
213
- // (`credential:write`) and envelope workspace binding; the credential ID is the
214
- // RuntimeNode `rgc_` identifier, which is distinct from connector credential IDs.
215
- const RuntimeNodeCredentialIdSchema = z
216
- .string()
217
- .min(8)
218
- .max(128)
219
- .regex(/^rgc_[A-Za-z0-9_-]+$/);
220
- export const RuntimeNodeCredentialRevokeRequestSchema = CredentialCommandContextSchema.extend({
221
- operation: z.literal('runtime-node-credential.revoke'),
222
- issuedAt: TimestampSchema,
223
- payload: z.object({ credentialId: RuntimeNodeCredentialIdSchema }).strict(),
224
- }).strict();
225
- export const RuntimeNodeCredentialRevocationResponseSchema = successResponse(z
226
- .object({
227
- credential: z
228
- .object({
229
- credentialId: RuntimeNodeCredentialIdSchema,
230
- nodeId: z.string().regex(/^rnr_[0-9A-HJKMNP-TV-Z]{26}$/),
231
- workspaceId: IdentifierSchemas.workspaceId,
232
- revocationVersion: z.number().int().positive(),
233
- revokedAt: TimestampSchema,
234
- })
235
- .strict(),
236
- })
237
- .strict());
238
233
  export const ProjectStateResolutionRequestSchema = RequestContextSchema.extend({
239
234
  operation: z.literal('project-state.resolve'),
240
235
  requestedAt: TimestampSchema,
@@ -1039,3 +1034,29 @@ export const CredentialApiFixtures = Object.freeze({
1039
1034
  response: { ...responseContext, data: { credentials: [credentialFixtureMetadata] } },
1040
1035
  },
1041
1036
  });
1037
+ // ---------------------------------------------------------------------------------------------
1038
+ // Encrypted device sync envelopes (adea-ai/control-plane#1566); the bodies live in device-sync.ts.
1039
+ const deviceSyncCommand = (operation, payload) => CommandContextSchema.extend({
1040
+ operation: z.literal(operation),
1041
+ issuedAt: TimestampSchema,
1042
+ payload,
1043
+ });
1044
+ const deviceSyncRead = (operation, parameters) => RequestContextSchema.extend({
1045
+ operation: z.literal(operation),
1046
+ requestedAt: TimestampSchema,
1047
+ parameters,
1048
+ });
1049
+ export const DeviceSyncUploadRequestSchema = deviceSyncCommand('device-sync.upload', SyncUploadRequestSchema.extend({ authorKeyId: SyncAuthorKeyIdSchema }).strict());
1050
+ export const DeviceSyncUploadResponseSchema = successResponse(SyncUploadResponseSchema);
1051
+ export const DeviceSyncCommitRequestSchema = deviceSyncCommand('device-sync.commit', SyncObjectRequestSchema);
1052
+ export const DeviceSyncCommitResponseSchema = successResponse(SyncCommitResponseSchema);
1053
+ export const DeviceSyncDownloadRequestSchema = deviceSyncRead('device-sync.download', SyncDownloadRequestSchema);
1054
+ export const DeviceSyncDownloadResponseSchema = successResponse(SyncDownloadResponseSchema);
1055
+ export const DeviceSyncReleaseRequestSchema = deviceSyncCommand('device-sync.release', SyncDownloadRequestSchema);
1056
+ export const DeviceSyncReleaseResponseSchema = successResponse(SyncReleaseResponseSchema);
1057
+ export const DeviceSyncAppendRequestSchema = deviceSyncCommand('device-sync.append', SyncAppendRequestSchema);
1058
+ export const DeviceSyncAppendResponseSchema = successResponse(SyncAppendResponseSchema);
1059
+ export const DeviceSyncLogRequestSchema = deviceSyncRead('device-sync.log', SyncLogRequestSchema);
1060
+ export const DeviceSyncLogResponseSchema = successResponse(SyncLogPageSchema);
1061
+ export const DeviceSyncUsageRequestSchema = deviceSyncRead('device-sync.usage', z.object({}).strict());
1062
+ export const DeviceSyncUsageResponseSchema = successResponse(SyncUsageSchema);
@@ -1,5 +1,4 @@
1
1
  import { z } from 'zod';
2
- import type { RuntimeConnectionDiscoveryReadModel } from './runtime-discovery.js';
3
2
  /**
4
3
  * Decision-layer contract (control-plane#558).
5
4
  *
@@ -11,10 +10,23 @@ import type { RuntimeConnectionDiscoveryReadModel } from './runtime-discovery.js
11
10
  * explicit user pin > project default > profile default > policy default.
12
11
  * Policy enforcement remains the PolicyDecisionPoint authorize() call; a
13
12
  * resolution selects, it never authorizes.
13
+ *
14
+ * Two surfaces sit on this one contract. The developer surface pins any
15
+ * subset of the outputs (`mode: 'customize'`). The consumer surface is
16
+ * `Agent: <profile>` plus `Mode: Auto | Customize`: Auto resolves every output
17
+ * from the profile, project and policy layers and carries no explicit pins;
18
+ * Customize is the developer surface. Explicit selection is authoritative: a
19
+ * pin the request cannot honor is denied, never replaced.
20
+ *
21
+ * Execution runs only on the user's own machines (a desktop or a VPS running
22
+ * the Local composition). Managed cloud resolves decisions but runs nothing,
23
+ * so every runtime is a Local runtime on a named host.
24
+ *
25
+ * Spec: docs/architecture/decision-558-resolution-contract.md.
14
26
  */
15
27
  export declare const DECISION_RESOLUTION_CONTRACT_VERSION: Readonly<{
16
28
  major: 1;
17
- minor: 0;
29
+ minor: 1;
18
30
  }>;
19
31
  export declare const HarnessIdSchema: z.ZodString;
20
32
  export declare const ModelIdSchema: z.ZodString;
@@ -39,6 +51,7 @@ export declare const SandboxResolutionSchema: z.ZodObject<{
39
51
  effectiveCapabilities: z.ZodArray<z.ZodString>;
40
52
  }, z.core.$strict>;
41
53
  export type SandboxResolution = z.output<typeof SandboxResolutionSchema>;
54
+ /** A delegation pin or default: the fan-out policy only, never an identity. */
42
55
  export declare const DelegationResolutionSchema: z.ZodObject<{
43
56
  fanOut: z.ZodEnum<{
44
57
  bounded: "bounded";
@@ -51,6 +64,56 @@ export declare const DelegationResolutionSchema: z.ZodObject<{
51
64
  }>;
52
65
  }, z.core.$strict>;
53
66
  export type DelegationResolution = z.output<typeof DelegationResolutionSchema>;
67
+ /**
68
+ * The delegation policy a resolution carries. Children resolve through the
69
+ * Control Plane identity of the parent request — the same service principal,
70
+ * workspace and project — and inherit the parent's runtime, so a child never
71
+ * moves to another machine. Their capabilities are bounded by the parent's
72
+ * effective sandbox capabilities. None of this is pinnable: the identity and
73
+ * the ceiling are derived, so a pin cannot widen them.
74
+ */
75
+ export declare const ResolvedDelegationSchema: z.ZodObject<{
76
+ fanOut: z.ZodEnum<{
77
+ bounded: "bounded";
78
+ none: "none";
79
+ }>;
80
+ maxChildren: z.ZodOptional<z.ZodNumber>;
81
+ promotion: z.ZodEnum<{
82
+ "auto-eligible": "auto-eligible";
83
+ "review-required": "review-required";
84
+ }>;
85
+ identity: z.ZodObject<{
86
+ servicePrincipalId: z.ZodString;
87
+ workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"workspace ID">, string>>;
88
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
89
+ }, z.core.$strict>;
90
+ childCeiling: z.ZodObject<{
91
+ runtimeDefinitionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"runtime-definition ID">, string>>;
92
+ capabilityNames: z.ZodArray<z.ZodString>;
93
+ }, z.core.$strict>;
94
+ }, z.core.$strict>;
95
+ export type ResolvedDelegation = z.output<typeof ResolvedDelegationSchema>;
96
+ /**
97
+ * Consumer `Mode`. `auto` resolves every output and refuses explicit pins;
98
+ * `customize` honors them. An absent mode is `customize`, the developer
99
+ * surface.
100
+ */
101
+ export declare const DecisionModeSchema: z.ZodEnum<{
102
+ auto: "auto";
103
+ customize: "customize";
104
+ }>;
105
+ export type DecisionMode = z.output<typeof DecisionModeSchema>;
106
+ /**
107
+ * A skill the request may resolve: a published, approved skill version and
108
+ * the capabilities it needs. When the request lists its available skills,
109
+ * every resolved skill must be one of them and its capabilities must be
110
+ * inside the resolved capability set.
111
+ */
112
+ export declare const AvailableSkillSchema: z.ZodObject<{
113
+ skillVersionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"skill-version ID">, string>>;
114
+ requiredCapabilities: z.ZodArray<z.ZodString>;
115
+ }, z.core.$strict>;
116
+ export type AvailableSkill = z.output<typeof AvailableSkillSchema>;
54
117
  /**
55
118
  * Every output the decision layer resolves. Pins make any subset explicit;
56
119
  * unpinned outputs still resolve.
@@ -109,19 +172,19 @@ export type ModelAccessEntitlement = z.output<typeof ModelAccessEntitlementSchem
109
172
  export declare const AvailableRuntimeSchema: z.ZodObject<{
110
173
  runtimeDefinitionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"runtime-definition ID">, string>>;
111
174
  kind: z.ZodEnum<{
112
- cloud: "cloud";
113
175
  local: "local";
114
- "self-hosted": "self-hosted";
176
+ }>;
177
+ host: z.ZodEnum<{
178
+ desktop: "desktop";
179
+ vps: "vps";
115
180
  }>;
116
181
  transport: z.ZodEnum<{
117
182
  "direct-local": "direct-local";
118
- "remote-gateway": "remote-gateway";
119
183
  }>;
120
184
  harnessIds: z.ZodArray<z.ZodString>;
121
185
  capabilities: z.ZodArray<z.ZodString>;
122
186
  }, z.core.$strict>;
123
187
  export type AvailableRuntime = z.output<typeof AvailableRuntimeSchema>;
124
- export declare function availableRuntimesFromDiscovery(models: readonly RuntimeConnectionDiscoveryReadModel[]): AvailableRuntime[];
125
188
  export declare const DecisionResolutionRequestSchema: z.ZodObject<{
126
189
  contractVersion: z.ZodObject<{
127
190
  major: z.ZodNumber;
@@ -140,6 +203,10 @@ export declare const DecisionResolutionRequestSchema: z.ZodObject<{
140
203
  }, z.core.$strip>;
141
204
  requestedAt: z.ZodISODateTime;
142
205
  objective: z.ZodString;
206
+ mode: z.ZodOptional<z.ZodEnum<{
207
+ auto: "auto";
208
+ customize: "customize";
209
+ }>>;
143
210
  agentProfile: z.ZodObject<{
144
211
  profileId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"profile ID">, string>>;
145
212
  profileVersionId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"profile-version ID">, string>>>;
@@ -147,13 +214,14 @@ export declare const DecisionResolutionRequestSchema: z.ZodObject<{
147
214
  availableRuntimes: z.ZodArray<z.ZodObject<{
148
215
  runtimeDefinitionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"runtime-definition ID">, string>>;
149
216
  kind: z.ZodEnum<{
150
- cloud: "cloud";
151
217
  local: "local";
152
- "self-hosted": "self-hosted";
218
+ }>;
219
+ host: z.ZodEnum<{
220
+ desktop: "desktop";
221
+ vps: "vps";
153
222
  }>;
154
223
  transport: z.ZodEnum<{
155
224
  "direct-local": "direct-local";
156
- "remote-gateway": "remote-gateway";
157
225
  }>;
158
226
  harnessIds: z.ZodArray<z.ZodString>;
159
227
  capabilities: z.ZodArray<z.ZodString>;
@@ -168,6 +236,10 @@ export declare const DecisionResolutionRequestSchema: z.ZodObject<{
168
236
  grantedCapabilityNames: z.ZodArray<z.ZodString>;
169
237
  }, z.core.$strict>;
170
238
  requiredCapabilities: z.ZodArray<z.ZodString>;
239
+ availableSkills: z.ZodOptional<z.ZodArray<z.ZodObject<{
240
+ skillVersionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"skill-version ID">, string>>;
241
+ requiredCapabilities: z.ZodArray<z.ZodString>;
242
+ }, z.core.$strict>>>;
171
243
  costLatencyPreference: z.ZodEnum<{
172
244
  balanced: "balanced";
173
245
  cost: "cost";
@@ -306,8 +378,10 @@ export declare const DecisionResolutionRequestSchema: z.ZodObject<{
306
378
  export type DecisionResolutionRequest = z.output<typeof DecisionResolutionRequestSchema>;
307
379
  /** Fail-closed denial codes; a denial never narrows silently. */
308
380
  export declare const DecisionResolutionDiagnosticSchema: z.ZodEnum<{
381
+ AUTO_MODE_EXPLICIT_PIN: "AUTO_MODE_EXPLICIT_PIN";
309
382
  CAPABILITY_BEYOND_GRANT: "CAPABILITY_BEYOND_GRANT";
310
383
  CONTEXT_PACKAGE_PIN_MISMATCH: "CONTEXT_PACKAGE_PIN_MISMATCH";
384
+ DELEGATION_BEYOND_POLICY: "DELEGATION_BEYOND_POLICY";
311
385
  HARNESS_MAP_CONFLICTS_WITH_PIN: "HARNESS_MAP_CONFLICTS_WITH_PIN";
312
386
  HARNESS_MAP_MODEL_ABSENT: "HARNESS_MAP_MODEL_ABSENT";
313
387
  HARNESS_MAP_MODEL_UNMAPPED: "HARNESS_MAP_MODEL_UNMAPPED";
@@ -315,6 +389,8 @@ export declare const DecisionResolutionDiagnosticSchema: z.ZodEnum<{
315
389
  MODEL_ACCESS_NOT_ENTITLED: "MODEL_ACCESS_NOT_ENTITLED";
316
390
  NO_COMPATIBLE_RUNTIME: "NO_COMPATIBLE_RUNTIME";
317
391
  NO_DEFAULT_MODEL: "NO_DEFAULT_MODEL";
392
+ SKILL_BEYOND_CAPABILITIES: "SKILL_BEYOND_CAPABILITIES";
393
+ SKILL_UNAVAILABLE: "SKILL_UNAVAILABLE";
318
394
  UNSUPPORTED_RUNTIME_PIN: "UNSUPPORTED_RUNTIME_PIN";
319
395
  }>;
320
396
  export type DecisionResolutionDiagnostic = z.output<typeof DecisionResolutionDiagnosticSchema>;
@@ -338,6 +414,10 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
338
414
  minor: z.ZodNumber;
339
415
  }, z.core.$strict>;
340
416
  resolvedAt: z.ZodISODateTime;
417
+ mode: z.ZodEnum<{
418
+ auto: "auto";
419
+ customize: "customize";
420
+ }>;
341
421
  resolution: z.ZodObject<{
342
422
  harness: z.ZodObject<{
343
423
  harnessId: z.ZodString;
@@ -346,8 +426,10 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
346
426
  modelId: z.ZodString;
347
427
  }, z.core.$strict>, z.ZodObject<{
348
428
  withheld: z.ZodEnum<{
429
+ AUTO_MODE_EXPLICIT_PIN: "AUTO_MODE_EXPLICIT_PIN";
349
430
  CAPABILITY_BEYOND_GRANT: "CAPABILITY_BEYOND_GRANT";
350
431
  CONTEXT_PACKAGE_PIN_MISMATCH: "CONTEXT_PACKAGE_PIN_MISMATCH";
432
+ DELEGATION_BEYOND_POLICY: "DELEGATION_BEYOND_POLICY";
351
433
  HARNESS_MAP_CONFLICTS_WITH_PIN: "HARNESS_MAP_CONFLICTS_WITH_PIN";
352
434
  HARNESS_MAP_MODEL_ABSENT: "HARNESS_MAP_MODEL_ABSENT";
353
435
  HARNESS_MAP_MODEL_UNMAPPED: "HARNESS_MAP_MODEL_UNMAPPED";
@@ -355,6 +437,8 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
355
437
  MODEL_ACCESS_NOT_ENTITLED: "MODEL_ACCESS_NOT_ENTITLED";
356
438
  NO_COMPATIBLE_RUNTIME: "NO_COMPATIBLE_RUNTIME";
357
439
  NO_DEFAULT_MODEL: "NO_DEFAULT_MODEL";
440
+ SKILL_BEYOND_CAPABILITIES: "SKILL_BEYOND_CAPABILITIES";
441
+ SKILL_UNAVAILABLE: "SKILL_UNAVAILABLE";
358
442
  UNSUPPORTED_RUNTIME_PIN: "UNSUPPORTED_RUNTIME_PIN";
359
443
  }>;
360
444
  }, z.core.$strict>]>;
@@ -367,13 +451,14 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
367
451
  runtime: z.ZodObject<{
368
452
  runtimeDefinitionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"runtime-definition ID">, string>>;
369
453
  kind: z.ZodEnum<{
370
- cloud: "cloud";
371
454
  local: "local";
372
- "self-hosted": "self-hosted";
455
+ }>;
456
+ host: z.ZodEnum<{
457
+ desktop: "desktop";
458
+ vps: "vps";
373
459
  }>;
374
460
  transport: z.ZodEnum<{
375
461
  "direct-local": "direct-local";
376
- "remote-gateway": "remote-gateway";
377
462
  }>;
378
463
  harnessIds: z.ZodArray<z.ZodString>;
379
464
  capabilities: z.ZodArray<z.ZodString>;
@@ -403,6 +488,15 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
403
488
  "auto-eligible": "auto-eligible";
404
489
  "review-required": "review-required";
405
490
  }>;
491
+ identity: z.ZodObject<{
492
+ servicePrincipalId: z.ZodString;
493
+ workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"workspace ID">, string>>;
494
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
495
+ }, z.core.$strict>;
496
+ childCeiling: z.ZodObject<{
497
+ runtimeDefinitionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"runtime-definition ID">, string>>;
498
+ capabilityNames: z.ZodArray<z.ZodString>;
499
+ }, z.core.$strict>;
406
500
  }, z.core.$strict>;
407
501
  }, z.core.$strict>;
408
502
  trace: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -415,8 +509,10 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
415
509
  value: z.ZodJSONSchema;
416
510
  }, z.core.$strict>>;
417
511
  diagnostics: z.ZodArray<z.ZodEnum<{
512
+ AUTO_MODE_EXPLICIT_PIN: "AUTO_MODE_EXPLICIT_PIN";
418
513
  CAPABILITY_BEYOND_GRANT: "CAPABILITY_BEYOND_GRANT";
419
514
  CONTEXT_PACKAGE_PIN_MISMATCH: "CONTEXT_PACKAGE_PIN_MISMATCH";
515
+ DELEGATION_BEYOND_POLICY: "DELEGATION_BEYOND_POLICY";
420
516
  HARNESS_MAP_CONFLICTS_WITH_PIN: "HARNESS_MAP_CONFLICTS_WITH_PIN";
421
517
  HARNESS_MAP_MODEL_ABSENT: "HARNESS_MAP_MODEL_ABSENT";
422
518
  HARNESS_MAP_MODEL_UNMAPPED: "HARNESS_MAP_MODEL_UNMAPPED";
@@ -424,6 +520,8 @@ export declare const DecisionLayerResolutionSchema: z.ZodObject<{
424
520
  MODEL_ACCESS_NOT_ENTITLED: "MODEL_ACCESS_NOT_ENTITLED";
425
521
  NO_COMPATIBLE_RUNTIME: "NO_COMPATIBLE_RUNTIME";
426
522
  NO_DEFAULT_MODEL: "NO_DEFAULT_MODEL";
523
+ SKILL_BEYOND_CAPABILITIES: "SKILL_BEYOND_CAPABILITIES";
524
+ SKILL_UNAVAILABLE: "SKILL_UNAVAILABLE";
427
525
  UNSUPPORTED_RUNTIME_PIN: "UNSUPPORTED_RUNTIME_PIN";
428
526
  }>>;
429
527
  resolutionDigest: z.ZodString;
@@ -14,8 +14,21 @@ import { ContractVersionSchema } from './versioning.js';
14
14
  * explicit user pin > project default > profile default > policy default.
15
15
  * Policy enforcement remains the PolicyDecisionPoint authorize() call; a
16
16
  * resolution selects, it never authorizes.
17
+ *
18
+ * Two surfaces sit on this one contract. The developer surface pins any
19
+ * subset of the outputs (`mode: 'customize'`). The consumer surface is
20
+ * `Agent: <profile>` plus `Mode: Auto | Customize`: Auto resolves every output
21
+ * from the profile, project and policy layers and carries no explicit pins;
22
+ * Customize is the developer surface. Explicit selection is authoritative: a
23
+ * pin the request cannot honor is denied, never replaced.
24
+ *
25
+ * Execution runs only on the user's own machines (a desktop or a VPS running
26
+ * the Local composition). Managed cloud resolves decisions but runs nothing,
27
+ * so every runtime is a Local runtime on a named host.
28
+ *
29
+ * Spec: docs/architecture/decision-558-resolution-contract.md.
17
30
  */
18
- export const DECISION_RESOLUTION_CONTRACT_VERSION = Object.freeze({ major: 1, minor: 0 });
31
+ export const DECISION_RESOLUTION_CONTRACT_VERSION = Object.freeze({ major: 1, minor: 1 });
19
32
  const TimestampSchema = z.iso.datetime();
20
33
  const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
21
34
  const CapabilityNameSchema = z
@@ -33,6 +46,15 @@ export const ModelIdSchema = z
33
46
  .min(1)
34
47
  .max(128)
35
48
  .regex(/^[a-z0-9][a-z0-9._/-]*$/i);
49
+ /**
50
+ * A model the decision layer resolves: the same spelling a provider model selection accepts
51
+ * (model-connections `providerModel`), so every selectable model can be pinned and resolved.
52
+ */
53
+ const DecisionModelIdSchema = z
54
+ .string()
55
+ .min(1)
56
+ .max(256)
57
+ .regex(/^[a-z0-9][a-z0-9._:/-]*$/i);
36
58
  /** Where a resolved output value came from. Precedence order is list order. */
37
59
  export const ResolutionSourceSchema = z.enum([
38
60
  'explicit-pin',
@@ -51,6 +73,7 @@ export const SandboxResolutionSchema = z
51
73
  effectiveCapabilities: z.array(CapabilityNameSchema).max(64),
52
74
  })
53
75
  .strict();
76
+ /** A delegation pin or default: the fan-out policy only, never an identity. */
54
77
  export const DelegationResolutionSchema = z
55
78
  .object({
56
79
  fanOut: z.enum(['none', 'bounded']),
@@ -67,6 +90,48 @@ export const DelegationResolutionSchema = z
67
90
  });
68
91
  }
69
92
  });
93
+ /**
94
+ * The delegation policy a resolution carries. Children resolve through the
95
+ * Control Plane identity of the parent request — the same service principal,
96
+ * workspace and project — and inherit the parent's runtime, so a child never
97
+ * moves to another machine. Their capabilities are bounded by the parent's
98
+ * effective sandbox capabilities. None of this is pinnable: the identity and
99
+ * the ceiling are derived, so a pin cannot widen them.
100
+ */
101
+ export const ResolvedDelegationSchema = z
102
+ .object({
103
+ fanOut: z.enum(['none', 'bounded']),
104
+ maxChildren: z.number().int().min(0).max(8).optional(),
105
+ promotion: z.enum(['review-required', 'auto-eligible']),
106
+ identity: z.strictObject({
107
+ servicePrincipalId: ServiceCallerAssertionSchema.shape.servicePrincipalId,
108
+ workspaceId: IdentifierSchemas.workspaceId,
109
+ projectId: IdentifierSchemas.projectId.optional(),
110
+ }),
111
+ childCeiling: z.strictObject({
112
+ runtimeDefinitionId: IdentifierSchemas.runtimeDefinitionId,
113
+ capabilityNames: z.array(CapabilityNameSchema).max(64),
114
+ }),
115
+ })
116
+ .strict();
117
+ /**
118
+ * Consumer `Mode`. `auto` resolves every output and refuses explicit pins;
119
+ * `customize` honors them. An absent mode is `customize`, the developer
120
+ * surface.
121
+ */
122
+ export const DecisionModeSchema = z.enum(['auto', 'customize']);
123
+ /**
124
+ * A skill the request may resolve: a published, approved skill version and
125
+ * the capabilities it needs. When the request lists its available skills,
126
+ * every resolved skill must be one of them and its capabilities must be
127
+ * inside the resolved capability set.
128
+ */
129
+ export const AvailableSkillSchema = z
130
+ .object({
131
+ skillVersionId: IdentifierSchemas.skillVersionId,
132
+ requiredCapabilities: z.array(CapabilityNameSchema).max(64),
133
+ })
134
+ .strict();
70
135
  /**
71
136
  * Every output the decision layer resolves. Pins make any subset explicit;
72
137
  * unpinned outputs still resolve.
@@ -74,7 +139,7 @@ export const DelegationResolutionSchema = z
74
139
  export const DecisionPinsSchema = z
75
140
  .object({
76
141
  harness: z.strictObject({ harnessId: HarnessIdSchema }).optional(),
77
- model: z.strictObject({ modelId: ModelIdSchema }).optional(),
142
+ model: z.strictObject({ modelId: DecisionModelIdSchema }).optional(),
78
143
  skills: z
79
144
  .strictObject({ skillVersionIds: z.array(IdentifierSchemas.skillVersionId).max(64) })
80
145
  .optional(),
@@ -98,40 +163,15 @@ export const ModelAccessEntitlementSchema = z.enum(['byok', 'provisioned', 'free
98
163
  export const AvailableRuntimeSchema = z
99
164
  .object({
100
165
  runtimeDefinitionId: IdentifierSchemas.runtimeDefinitionId,
101
- kind: z.enum(['local', 'self-hosted', 'cloud']),
102
- transport: z.enum(['direct-local', 'remote-gateway']),
166
+ // Every runtime is the Local composition. `host` names the machine
167
+ // class: the user's desktop or a VPS the user runs it on.
168
+ kind: z.enum(['local']),
169
+ host: z.enum(['desktop', 'vps']),
170
+ transport: z.enum(['direct-local']),
103
171
  harnessIds: z.array(HarnessIdSchema).max(16),
104
172
  capabilities: z.array(CapabilityNameSchema).max(64),
105
173
  })
106
174
  .strict();
107
- /**
108
- * Maps runtime-discovery read models onto the decision layer's runtime view
109
- * (#74 / M12 wiring). The discovery `family` is the harness family id — the
110
- * same kebab-case shape HarnessIdSchema requires — so a runtime advertising
111
- * family `pi` exposes harness id `pi`. Unavailable and revoked connections are
112
- * not offered to resolution; degraded ones remain selectable because policy
113
- * decides whether a degraded runtime is acceptable.
114
- */
115
- function runtimeKind(model) {
116
- // The discovery model's location is local_device | agent_hq_cloud; the
117
- // managed/external connection types resolve the remaining distinction.
118
- if (model.connectionType === 'managed_cloud')
119
- return 'cloud';
120
- if (model.connectionType === 'managed_local')
121
- return 'local';
122
- return model.location === 'local_device' ? 'local' : 'self-hosted';
123
- }
124
- export function availableRuntimesFromDiscovery(models) {
125
- return models
126
- .filter((model) => model.status === 'available' || model.status === 'degraded')
127
- .map((model) => AvailableRuntimeSchema.parse({
128
- runtimeDefinitionId: model.runtimeDefinitionId,
129
- kind: runtimeKind(model),
130
- transport: 'remote-gateway',
131
- harnessIds: [model.family],
132
- capabilities: [...model.capabilities],
133
- }));
134
- }
135
175
  export const DecisionResolutionRequestSchema = z
136
176
  .object({
137
177
  contractVersion: ContractVersionSchema,
@@ -142,6 +182,7 @@ export const DecisionResolutionRequestSchema = z
142
182
  correlation: CorrelationMetadataSchema,
143
183
  requestedAt: TimestampSchema,
144
184
  objective: z.string().min(1).max(4096),
185
+ mode: DecisionModeSchema.optional(),
145
186
  agentProfile: z.strictObject({
146
187
  profileId: IdentifierSchemas.profileId,
147
188
  profileVersionId: IdentifierSchemas.profileVersionId.optional(),
@@ -152,6 +193,7 @@ export const DecisionResolutionRequestSchema = z
152
193
  grantedCapabilityNames: z.array(CapabilityNameSchema).max(64),
153
194
  }),
154
195
  requiredCapabilities: z.array(CapabilityNameSchema).max(64),
196
+ availableSkills: z.array(AvailableSkillSchema).max(256).optional(),
155
197
  costLatencyPreference: z.enum(['cost', 'balanced', 'latency']),
156
198
  projectDefaults: DecisionPinsSchema,
157
199
  profileDefaults: DecisionPinsSchema,
@@ -167,6 +209,15 @@ export const DecisionResolutionDiagnosticSchema = z.enum([
167
209
  'HARNESS_UNAVAILABLE_ON_PINNED_RUNTIME',
168
210
  'NO_COMPATIBLE_RUNTIME',
169
211
  'CONTEXT_PACKAGE_PIN_MISMATCH',
212
+ // Consumer Auto mode carries no explicit pins; a pin is refused rather
213
+ // than silently ignored.
214
+ 'AUTO_MODE_EXPLICIT_PIN',
215
+ // A resolved skill that is not an available skill version, or that needs a
216
+ // capability outside the resolved set.
217
+ 'SKILL_UNAVAILABLE',
218
+ 'SKILL_BEYOND_CAPABILITIES',
219
+ // A delegation fan-out above the deployment's child ceiling.
220
+ 'DELEGATION_BEYOND_POLICY',
170
221
  // M12/#678 per-model harness mapping. A configured map is a policy, not a
171
222
  // fallback: an execution without a model, with a model the map does not
172
223
  // name, or whose mapped harness contradicts an explicit pin, is denied
@@ -189,11 +240,12 @@ export const DecisionLayerResolutionSchema = z
189
240
  workspaceId: IdentifierSchemas.workspaceId,
190
241
  contractVersion: ContractVersionSchema,
191
242
  resolvedAt: TimestampSchema,
243
+ mode: DecisionModeSchema,
192
244
  resolution: z
193
245
  .strictObject({
194
246
  harness: z.strictObject({ harnessId: HarnessIdSchema }),
195
247
  model: z.union([
196
- z.strictObject({ modelId: ModelIdSchema }),
248
+ z.strictObject({ modelId: DecisionModelIdSchema }),
197
249
  z.strictObject({ withheld: DecisionResolutionDiagnosticSchema }),
198
250
  ]),
199
251
  skills: z.strictObject({
@@ -206,7 +258,7 @@ export const DecisionLayerResolutionSchema = z
206
258
  mode: z.enum(['none', 'existing', 'author']),
207
259
  contextPackageId: IdentifierSchemas.contextPackageId.optional(),
208
260
  }),
209
- delegation: DelegationResolutionSchema,
261
+ delegation: ResolvedDelegationSchema,
210
262
  })
211
263
  .strict(),
212
264
  trace: z.record(z.string(), ResolvedOutputSchema),