@adea-ai/contracts 5.0.2 → 5.0.4
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.
- package/README.md +4 -4
- package/dist/canonical-json.d.ts +1 -1
- package/dist/canonical-json.js +1 -1
- package/dist/control-api.d.ts +47 -0
- package/dist/control-api.js +55 -8
- package/dist/decision-resolution.d.ts +3 -3
- package/dist/decision-resolution.js +3 -3
- package/dist/envelopes.d.ts +6 -0
- package/dist/envelopes.js +6 -0
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -9,15 +9,15 @@ Plane domain, database, application, workflow, or adapter packages.
|
|
|
9
9
|
|
|
10
10
|
## What's inside
|
|
11
11
|
|
|
12
|
-
- **Canonical identifiers
|
|
12
|
+
- **Canonical identifiers**: opaque, prefix-qualified ULIDs (`req_`, `wsp_`,
|
|
13
13
|
`exe_`, …) with validation schemas. Consumers may validate and compare them
|
|
14
14
|
but must not derive database keys, timestamps, routing decisions, or
|
|
15
15
|
vendor-native identifiers from their contents.
|
|
16
|
-
- **Control API schemas
|
|
17
|
-
- **Envelopes
|
|
16
|
+
- **Control API schemas**: request/response contracts for the Control API.
|
|
17
|
+
- **Envelopes**: standardized request/response wrappers with authentication
|
|
18
18
|
and versioning metadata.
|
|
19
19
|
- **Pagination, versioning, and memory-writeback contracts.**
|
|
20
|
-
- **Fixtures
|
|
20
|
+
- **Fixtures**: deterministic test fixtures for consumers.
|
|
21
21
|
|
|
22
22
|
## Install
|
|
23
23
|
|
package/dist/canonical-json.d.ts
CHANGED
|
@@ -34,7 +34,7 @@ export declare function canonicalJsonStringify(value: unknown): string;
|
|
|
34
34
|
* Deterministic key comparator: orders strings by Unicode code point,
|
|
35
35
|
* independent of host locale/ICU. Use anywhere ordering feeds digests,
|
|
36
36
|
* selection, or cross-host stability guarantees. Never use localeCompare
|
|
37
|
-
* for these
|
|
37
|
+
* for these; its collation is locale-dependent (see the divergence fixture
|
|
38
38
|
* in the tests: ['a-b','ab','a_b','Aa','a!']).
|
|
39
39
|
*/
|
|
40
40
|
export declare function compareCodePointOrder(left: string, right: string): number;
|
package/dist/canonical-json.js
CHANGED
|
@@ -77,7 +77,7 @@ function serialize(value) {
|
|
|
77
77
|
* Deterministic key comparator: orders strings by Unicode code point,
|
|
78
78
|
* independent of host locale/ICU. Use anywhere ordering feeds digests,
|
|
79
79
|
* selection, or cross-host stability guarantees. Never use localeCompare
|
|
80
|
-
* for these
|
|
80
|
+
* for these; its collation is locale-dependent (see the divergence fixture
|
|
81
81
|
* in the tests: ['a-b','ab','a_b','Aa','a!']).
|
|
82
82
|
*/
|
|
83
83
|
export function compareCodePointOrder(left, right) {
|
package/dist/control-api.d.ts
CHANGED
|
@@ -737,6 +737,47 @@ export declare const MarketplaceCatalogResponseSchema: z.ZodObject<{
|
|
|
737
737
|
}, z.core.$strip>>;
|
|
738
738
|
}, z.core.$strip>;
|
|
739
739
|
}, z.core.$strip>;
|
|
740
|
+
export declare const MarketplaceInstallationListRequestSchema: z.ZodObject<{
|
|
741
|
+
caller: typeof ServiceCallerAssertionSchema;
|
|
742
|
+
contractVersion: typeof ContractVersionSchema;
|
|
743
|
+
requestId: typeof IdentifierSchemas.requestId;
|
|
744
|
+
workspaceId: typeof IdentifierSchemas.workspaceId;
|
|
745
|
+
projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
|
|
746
|
+
correlation: typeof CorrelationMetadataSchema;
|
|
747
|
+
operation: z.ZodLiteral<"marketplace.installation.list">;
|
|
748
|
+
requestedAt: typeof TimestampSchema;
|
|
749
|
+
parameters: z.ZodObject<{
|
|
750
|
+
workspaceIdentity: typeof MarketplaceIdentitySchema;
|
|
751
|
+
installedBy: z.ZodOptional<z.ZodString>;
|
|
752
|
+
limit: z.ZodOptional<z.ZodNumber>;
|
|
753
|
+
cursor: z.ZodOptional<typeof CursorSchema>;
|
|
754
|
+
}, z.core.$strip>;
|
|
755
|
+
}, z.core.$strip>;
|
|
756
|
+
export declare const MarketplaceInstallationListResponseSchema: z.ZodObject<{
|
|
757
|
+
contractVersion: typeof ContractVersionSchema;
|
|
758
|
+
requestId: typeof IdentifierSchemas.requestId;
|
|
759
|
+
correlation: typeof CorrelationMetadataSchema;
|
|
760
|
+
data: z.ZodObject<{
|
|
761
|
+
installations: z.ZodArray<z.ZodObject<{
|
|
762
|
+
pluginId: z.ZodString;
|
|
763
|
+
releaseId: z.ZodString;
|
|
764
|
+
canonicalContentDigest: typeof Sha256DigestSchema;
|
|
765
|
+
installationId: z.ZodOptional<z.ZodString>;
|
|
766
|
+
installationInstanceId: z.ZodOptional<z.ZodString>;
|
|
767
|
+
packageDigest: z.ZodOptional<z.ZodString>;
|
|
768
|
+
state: z.ZodEnum<{
|
|
769
|
+
installed: "installed";
|
|
770
|
+
"pending-authorization": "pending-authorization";
|
|
771
|
+
"rejected-by-policy": "rejected-by-policy";
|
|
772
|
+
superseded: "superseded";
|
|
773
|
+
unavailable: "unavailable";
|
|
774
|
+
}>;
|
|
775
|
+
}, z.core.$strict>>;
|
|
776
|
+
installationsPage: z.ZodObject<{
|
|
777
|
+
nextCursor: z.ZodOptional<z.ZodString>;
|
|
778
|
+
}, z.core.$strip>;
|
|
779
|
+
}, z.core.$strip>;
|
|
780
|
+
}, z.core.$strip>;
|
|
740
781
|
export declare const MarketplaceInstallRequestSchema: z.ZodObject<{
|
|
741
782
|
caller: typeof ServiceCallerAssertionSchema;
|
|
742
783
|
contractVersion: typeof ContractVersionSchema;
|
|
@@ -864,6 +905,8 @@ export type MarketplaceCatalogResponse = z.output<typeof MarketplaceCatalogRespo
|
|
|
864
905
|
export type MarketplaceInstallRequest = z.input<typeof MarketplaceInstallRequestSchema>;
|
|
865
906
|
export type MarketplaceInstallResponse = z.output<typeof MarketplaceInstallResponseSchema>;
|
|
866
907
|
export type MarketplaceInstallation = z.output<typeof MarketplaceInstallationSchema>;
|
|
908
|
+
export type MarketplaceInstallationListRequest = z.input<typeof MarketplaceInstallationListRequestSchema>;
|
|
909
|
+
export type MarketplaceInstallationListResponse = z.output<typeof MarketplaceInstallationListResponseSchema>;
|
|
867
910
|
export type MarketplaceInstallationLifecycleState = z.output<typeof MarketplaceInstallationLifecycleStateSchema>;
|
|
868
911
|
export type MarketplaceInstallationGetRequest = z.input<typeof MarketplaceInstallationGetRequestSchema>;
|
|
869
912
|
export type MarketplaceInstallationGetResponse = z.output<typeof MarketplaceInstallationGetResponseSchema>;
|
|
@@ -1300,6 +1343,10 @@ export interface ControlApiFixtureSet {
|
|
|
1300
1343
|
readonly request: ExecutionAcceptanceRequest;
|
|
1301
1344
|
readonly response: z.input<typeof ExecutionAcceptanceResponseSchema>;
|
|
1302
1345
|
};
|
|
1346
|
+
readonly marketplaceInstallationList: {
|
|
1347
|
+
readonly request: MarketplaceInstallationListRequest;
|
|
1348
|
+
readonly response: z.input<typeof MarketplaceInstallationListResponseSchema>;
|
|
1349
|
+
};
|
|
1303
1350
|
readonly marketplaceInstallationGet: {
|
|
1304
1351
|
readonly request: MarketplaceInstallationGetRequest;
|
|
1305
1352
|
readonly response: z.input<typeof MarketplaceInstallationGetResponseSchema>;
|
package/dist/control-api.js
CHANGED
|
@@ -317,24 +317,48 @@ export const MarketplaceCatalogRequestSchema = RequestContextSchema.extend({
|
|
|
317
317
|
cursor: CursorSchema.optional(),
|
|
318
318
|
}),
|
|
319
319
|
});
|
|
320
|
+
// One active installation as the catalog and installation list reads report it.
|
|
321
|
+
const MarketplaceActiveInstallationSchema = MarketplacePluginReferenceContractSchema.extend({
|
|
322
|
+
// Additive 3.x field: the handle for the installation get and
|
|
323
|
+
// uninstall operations.
|
|
324
|
+
installationId: z.string().min(1).max(128).optional(),
|
|
325
|
+
installationInstanceId: z.string().min(1).max(256).optional(),
|
|
326
|
+
packageDigest: Sha256DigestSchema.optional(),
|
|
327
|
+
state: z.enum(MarketplaceInstallationDecisionStates),
|
|
328
|
+
});
|
|
320
329
|
export const MarketplaceCatalogResponseSchema = successResponse(z.object({
|
|
321
330
|
catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
|
|
322
331
|
releaseId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
|
|
323
332
|
state: z.enum(['ready', 'stale']),
|
|
324
333
|
artifacts: MarketplaceArtifactsSchema,
|
|
325
334
|
installations: z
|
|
326
|
-
.array(
|
|
327
|
-
// Additive 3.x field: the handle for the installation get and
|
|
328
|
-
// uninstall operations.
|
|
329
|
-
installationId: z.string().min(1).max(128).optional(),
|
|
330
|
-
installationInstanceId: z.string().min(1).max(256).optional(),
|
|
331
|
-
packageDigest: Sha256DigestSchema.optional(),
|
|
332
|
-
state: z.enum(MarketplaceInstallationDecisionStates),
|
|
333
|
-
}))
|
|
335
|
+
.array(MarketplaceActiveInstallationSchema)
|
|
334
336
|
.max(100),
|
|
335
337
|
// Additive 3.x field; absent from servers that predate installation paging.
|
|
336
338
|
installationsPage: z.object({ nextCursor: CursorSchema.optional() }).optional(),
|
|
337
339
|
}));
|
|
340
|
+
// The workspace's active installations without the catalog: a page costs a few
|
|
341
|
+
// kilobytes instead of re-sending the catalog artifacts.
|
|
342
|
+
export const MarketplaceInstallationListRequestSchema = RequestContextSchema.extend({
|
|
343
|
+
operation: z.literal('marketplace.installation.list'),
|
|
344
|
+
requestedAt: TimestampSchema,
|
|
345
|
+
parameters: z.object({
|
|
346
|
+
workspaceIdentity: MarketplaceIdentitySchema,
|
|
347
|
+
// Only installations whose recorded installer (the install request's
|
|
348
|
+
// `workspaceIdentity.userId`) matches. Omitted, every active installation.
|
|
349
|
+
installedBy: z.string().min(1).max(128).optional(),
|
|
350
|
+
// At most `limit` (default and maximum 100) per page, oldest `updatedAt`
|
|
351
|
+
// first, continued with `installationsPage.nextCursor`.
|
|
352
|
+
limit: z.number().int().min(1).max(100).optional(),
|
|
353
|
+
cursor: CursorSchema.optional(),
|
|
354
|
+
}),
|
|
355
|
+
});
|
|
356
|
+
export const MarketplaceInstallationListResponseSchema = successResponse(z.object({
|
|
357
|
+
installations: z
|
|
358
|
+
.array(MarketplaceActiveInstallationSchema)
|
|
359
|
+
.max(100),
|
|
360
|
+
installationsPage: z.object({ nextCursor: CursorSchema.optional() }),
|
|
361
|
+
}));
|
|
338
362
|
export const MarketplaceInstallRequestSchema = CommandContextSchema.extend({
|
|
339
363
|
operation: z.literal('marketplace.install.request'),
|
|
340
364
|
issuedAt: TimestampSchema,
|
|
@@ -885,6 +909,29 @@ export const ControlApiFixtures = Object.freeze({
|
|
|
885
909
|
},
|
|
886
910
|
},
|
|
887
911
|
},
|
|
912
|
+
marketplaceInstallationList: {
|
|
913
|
+
request: {
|
|
914
|
+
...marketplaceRequestContext,
|
|
915
|
+
operation: 'marketplace.installation.list',
|
|
916
|
+
requestedAt: '2026-08-23T12:00:00.000Z',
|
|
917
|
+
parameters: { workspaceIdentity: marketplaceWorkspaceIdentity, limit: 1 },
|
|
918
|
+
},
|
|
919
|
+
response: {
|
|
920
|
+
...responseContext,
|
|
921
|
+
data: {
|
|
922
|
+
installations: [
|
|
923
|
+
{
|
|
924
|
+
installationId: marketplaceInstallation.installationId,
|
|
925
|
+
pluginId: marketplaceInstallation.pluginId,
|
|
926
|
+
releaseId: marketplaceInstallation.releaseId,
|
|
927
|
+
canonicalContentDigest: marketplaceInstallation.canonicalContentDigest,
|
|
928
|
+
state: 'installed',
|
|
929
|
+
},
|
|
930
|
+
],
|
|
931
|
+
installationsPage: { nextCursor: 'cur_0123456789abcdef' },
|
|
932
|
+
},
|
|
933
|
+
},
|
|
934
|
+
},
|
|
888
935
|
marketplaceInstallationGet: {
|
|
889
936
|
request: {
|
|
890
937
|
...marketplaceRequestContext,
|
|
@@ -4,7 +4,7 @@ import { z } from 'zod';
|
|
|
4
4
|
*
|
|
5
5
|
* The Control Plane owns the decision layer that resolves what runs: harness,
|
|
6
6
|
* model, skills, tools/capabilities, runtime, sandbox, context package, and
|
|
7
|
-
* delegation policy. Resolution is logistics
|
|
7
|
+
* delegation policy. Resolution is logistics; it selects among what harnesses
|
|
8
8
|
* expose; it never implements routing inside a harness's model semantics
|
|
9
9
|
* (owner standing directive, adea#400). Precedence for every output:
|
|
10
10
|
* explicit user pin > project default > profile default > policy default.
|
|
@@ -71,8 +71,8 @@ export declare const DelegationResolutionSchema: z.ZodObject<{
|
|
|
71
71
|
export type DelegationResolution = z.output<typeof DelegationResolutionSchema>;
|
|
72
72
|
/**
|
|
73
73
|
* The delegation policy a resolution carries. Children resolve through the
|
|
74
|
-
* Control Plane identity of the parent request
|
|
75
|
-
* workspace and project
|
|
74
|
+
* Control Plane identity of the parent request; the same service principal,
|
|
75
|
+
* workspace and project, and inherit the parent's runtime, so a child never
|
|
76
76
|
* moves to another machine. Their capabilities are bounded by the parent's
|
|
77
77
|
* effective sandbox capabilities. None of this is pinnable: the identity and
|
|
78
78
|
* the ceiling are derived, so a pin cannot widen them.
|
|
@@ -9,7 +9,7 @@ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
|
|
|
9
9
|
*
|
|
10
10
|
* The Control Plane owns the decision layer that resolves what runs: harness,
|
|
11
11
|
* model, skills, tools/capabilities, runtime, sandbox, context package, and
|
|
12
|
-
* delegation policy. Resolution is logistics
|
|
12
|
+
* delegation policy. Resolution is logistics; it selects among what harnesses
|
|
13
13
|
* expose; it never implements routing inside a harness's model semantics
|
|
14
14
|
* (owner standing directive, adea#400). Precedence for every output:
|
|
15
15
|
* explicit user pin > project default > profile default > policy default.
|
|
@@ -98,8 +98,8 @@ export const DelegationResolutionSchema = z
|
|
|
98
98
|
});
|
|
99
99
|
/**
|
|
100
100
|
* The delegation policy a resolution carries. Children resolve through the
|
|
101
|
-
* Control Plane identity of the parent request
|
|
102
|
-
* workspace and project
|
|
101
|
+
* Control Plane identity of the parent request; the same service principal,
|
|
102
|
+
* workspace and project, and inherit the parent's runtime, so a child never
|
|
103
103
|
* moves to another machine. Their capabilities are bounded by the parent's
|
|
104
104
|
* effective sandbox capabilities. None of this is pinnable: the identity and
|
|
105
105
|
* the ceiling are derived, so a pin cannot widen them.
|
package/dist/envelopes.d.ts
CHANGED
|
@@ -102,6 +102,12 @@ export declare const NormalizedErrorSchema: z.ZodObject<{
|
|
|
102
102
|
details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
103
103
|
}, z.core.$strip>;
|
|
104
104
|
export type NormalizedError = z.infer<typeof NormalizedErrorSchema>;
|
|
105
|
+
/**
|
|
106
|
+
* The code of a `429` answer: the caller spent its request budget. It is retryable, and the
|
|
107
|
+
* `Retry-After` header says how many seconds to wait first. Nothing ran, so the same request can
|
|
108
|
+
* be sent again as is.
|
|
109
|
+
*/
|
|
110
|
+
export declare const RATE_LIMITED_ERROR_CODE = "RATE_LIMITED";
|
|
105
111
|
export declare const ErrorResponseEnvelopeSchema: z.ZodObject<{
|
|
106
112
|
contractVersion: z.ZodObject<{
|
|
107
113
|
major: z.ZodNumber;
|
package/dist/envelopes.js
CHANGED
|
@@ -83,6 +83,12 @@ export const NormalizedErrorSchema = z.object({
|
|
|
83
83
|
.refine((details) => Object.keys(details).length <= 32)
|
|
84
84
|
.optional(),
|
|
85
85
|
});
|
|
86
|
+
/**
|
|
87
|
+
* The code of a `429` answer: the caller spent its request budget. It is retryable, and the
|
|
88
|
+
* `Retry-After` header says how many seconds to wait first. Nothing ran, so the same request can
|
|
89
|
+
* be sent again as is.
|
|
90
|
+
*/
|
|
91
|
+
export const RATE_LIMITED_ERROR_CODE = 'RATE_LIMITED';
|
|
86
92
|
export const ErrorResponseEnvelopeSchema = ResponseIdentitySchema.extend({
|
|
87
93
|
error: NormalizedErrorSchema,
|
|
88
94
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adea-ai/contracts",
|
|
3
|
-
"version": "5.0.
|
|
3
|
+
"version": "5.0.4",
|
|
4
4
|
"description": "Runtime-independent service boundary between Adea and the Control Plane: canonical identifiers, envelopes, Control API schemas, pagination, and versioning.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -40,6 +40,10 @@
|
|
|
40
40
|
"./device-sync": {
|
|
41
41
|
"types": "./dist/device-sync.d.ts",
|
|
42
42
|
"default": "./dist/device-sync.js"
|
|
43
|
+
},
|
|
44
|
+
"./primitives": {
|
|
45
|
+
"types": "./dist/primitives.d.ts",
|
|
46
|
+
"default": "./dist/primitives.js"
|
|
43
47
|
}
|
|
44
48
|
},
|
|
45
49
|
"publishConfig": {
|