@adea-ai/contracts 5.0.3 → 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 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** — opaque, prefix-qualified ULIDs (`req_`, `wsp_`,
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** — request/response contracts for the Control API.
17
- - **Envelopes** — standardized request/response wrappers with authentication
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** — deterministic test fixtures for consumers.
20
+ - **Fixtures**: deterministic test fixtures for consumers.
21
21
 
22
22
  ## Install
23
23
 
@@ -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 — its collation is locale-dependent (see the divergence fixture
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;
@@ -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 — its collation is locale-dependent (see the divergence fixture
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) {
@@ -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>;
@@ -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(MarketplacePluginReferenceContractSchema.extend({
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 — it selects among what harnesses
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 — the same service principal,
75
- * workspace and project — and inherit the parent's runtime, so a child never
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 — it selects among what harnesses
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 — the same service principal,
102
- * workspace and project — and inherit the parent's runtime, so a child never
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.
@@ -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",
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",