@tangle-network/agent-interface 0.30.0 → 0.31.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.
@@ -12,8 +12,8 @@ export declare const agentCandidateModelSettlementCallSchema: z.ZodObject<{
12
12
  generationId: z.ZodString;
13
13
  traceSpanId: z.ZodString;
14
14
  status: z.ZodEnum<{
15
- succeeded: "succeeded";
16
15
  failed: "failed";
16
+ succeeded: "succeeded";
17
17
  }>;
18
18
  model: z.ZodString;
19
19
  startedAtMs: z.ZodNumber;
@@ -30,8 +30,8 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
30
30
  generationId: z.ZodString;
31
31
  traceSpanId: z.ZodString;
32
32
  status: z.ZodEnum<{
33
- succeeded: "succeeded";
34
33
  failed: "failed";
34
+ succeeded: "succeeded";
35
35
  }>;
36
36
  model: z.ZodString;
37
37
  startedAtMs: z.ZodNumber;
@@ -79,7 +79,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
79
79
  callId: string;
80
80
  generationId: string;
81
81
  traceSpanId: string;
82
- status: "succeeded" | "failed";
82
+ status: "failed" | "succeeded";
83
83
  model: string;
84
84
  startedAtMs: number;
85
85
  endedAtMs: number;
@@ -114,7 +114,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
114
114
  callId: string;
115
115
  generationId: string;
116
116
  traceSpanId: string;
117
- status: "succeeded" | "failed";
117
+ status: "failed" | "succeeded";
118
118
  model: string;
119
119
  startedAtMs: number;
120
120
  endedAtMs: number;
@@ -2266,7 +2266,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
2266
2266
  callId: string;
2267
2267
  generationId: string;
2268
2268
  traceSpanId: string;
2269
- status: "succeeded" | "failed";
2269
+ status: "failed" | "succeeded";
2270
2270
  model: string;
2271
2271
  startedAtMs: number;
2272
2272
  endedAtMs: number;
@@ -2301,7 +2301,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
2301
2301
  callId: string;
2302
2302
  generationId: string;
2303
2303
  traceSpanId: string;
2304
- status: "succeeded" | "failed";
2304
+ status: "failed" | "succeeded";
2305
2305
  model: string;
2306
2306
  startedAtMs: number;
2307
2307
  endedAtMs: number;
@@ -4991,7 +4991,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
4991
4991
  callId: string;
4992
4992
  generationId: string;
4993
4993
  traceSpanId: string;
4994
- status: "succeeded" | "failed";
4994
+ status: "failed" | "succeeded";
4995
4995
  model: string;
4996
4996
  startedAtMs: number;
4997
4997
  endedAtMs: number;
@@ -5026,7 +5026,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
5026
5026
  callId: string;
5027
5027
  generationId: string;
5028
5028
  traceSpanId: string;
5029
- status: "succeeded" | "failed";
5029
+ status: "failed" | "succeeded";
5030
5030
  model: string;
5031
5031
  startedAtMs: number;
5032
5032
  endedAtMs: number;
@@ -6342,7 +6342,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
6342
6342
  callId: string;
6343
6343
  generationId: string;
6344
6344
  traceSpanId: string;
6345
- status: "succeeded" | "failed";
6345
+ status: "failed" | "succeeded";
6346
6346
  model: string;
6347
6347
  startedAtMs: number;
6348
6348
  endedAtMs: number;
@@ -6377,7 +6377,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
6377
6377
  callId: string;
6378
6378
  generationId: string;
6379
6379
  traceSpanId: string;
6380
- status: "succeeded" | "failed";
6380
+ status: "failed" | "succeeded";
6381
6381
  model: string;
6382
6382
  startedAtMs: number;
6383
6383
  endedAtMs: number;
@@ -9249,7 +9249,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
9249
9249
  callId: string;
9250
9250
  generationId: string;
9251
9251
  traceSpanId: string;
9252
- status: "succeeded" | "failed";
9252
+ status: "failed" | "succeeded";
9253
9253
  model: string;
9254
9254
  startedAtMs: number;
9255
9255
  endedAtMs: number;
@@ -9284,7 +9284,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
9284
9284
  callId: string;
9285
9285
  generationId: string;
9286
9286
  traceSpanId: string;
9287
- status: "succeeded" | "failed";
9287
+ status: "failed" | "succeeded";
9288
9288
  model: string;
9289
9289
  startedAtMs: number;
9290
9290
  endedAtMs: number;
@@ -10600,7 +10600,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
10600
10600
  callId: string;
10601
10601
  generationId: string;
10602
10602
  traceSpanId: string;
10603
- status: "succeeded" | "failed";
10603
+ status: "failed" | "succeeded";
10604
10604
  model: string;
10605
10605
  startedAtMs: number;
10606
10606
  endedAtMs: number;
@@ -10635,7 +10635,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
10635
10635
  callId: string;
10636
10636
  generationId: string;
10637
10637
  traceSpanId: string;
10638
- status: "succeeded" | "failed";
10638
+ status: "failed" | "succeeded";
10639
10639
  model: string;
10640
10640
  startedAtMs: number;
10641
10641
  endedAtMs: number;
@@ -11242,6 +11242,10 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
11242
11242
  reviewDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11243
11243
  experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11244
11244
  candidateBundleDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11245
+ intent: z.ZodEnum<{
11246
+ "activate-candidate": "activate-candidate";
11247
+ "restore-baseline": "restore-baseline";
11248
+ }>;
11245
11249
  targets: z.ZodTuple<[z.ZodObject<{
11246
11250
  surface: z.ZodEnum<{
11247
11251
  prompt: "prompt";
@@ -11276,5 +11280,130 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
11276
11280
  fundingOwner: z.ZodString;
11277
11281
  authorizedBy: z.ZodString;
11278
11282
  authorizedAt: z.ZodISODateTime;
11283
+ expiresAt: z.ZodISODateTime;
11284
+ digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11285
+ }, z.core.$strict>;
11286
+ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
11287
+ kind: z.ZodLiteral<"agent-improvement-activation-result">;
11288
+ idempotencyKey: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11289
+ attemptedAt: z.ZodISODateTime;
11290
+ completedAt: z.ZodISODateTime;
11291
+ outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
11292
+ status: z.ZodLiteral<"applied">;
11293
+ transactionId: z.ZodString;
11294
+ targets: z.ZodTuple<[z.ZodObject<{
11295
+ surface: z.ZodEnum<{
11296
+ prompt: "prompt";
11297
+ tools: "tools";
11298
+ mcp: "mcp";
11299
+ subagents: "subagents";
11300
+ hooks: "hooks";
11301
+ skills: "skills";
11302
+ "agent-profile": "agent-profile";
11303
+ memory: "memory";
11304
+ code: "code";
11305
+ knowledge: "knowledge";
11306
+ }>;
11307
+ identity: z.ZodString;
11308
+ beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11309
+ afterDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11310
+ }, z.core.$strict>], z.ZodObject<{
11311
+ surface: z.ZodEnum<{
11312
+ prompt: "prompt";
11313
+ tools: "tools";
11314
+ mcp: "mcp";
11315
+ subagents: "subagents";
11316
+ hooks: "hooks";
11317
+ skills: "skills";
11318
+ "agent-profile": "agent-profile";
11319
+ memory: "memory";
11320
+ code: "code";
11321
+ knowledge: "knowledge";
11322
+ }>;
11323
+ identity: z.ZodString;
11324
+ beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11325
+ afterDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11326
+ }, z.core.$strict>>;
11327
+ }, z.core.$strict>, z.ZodObject<{
11328
+ status: z.ZodLiteral<"already-applied">;
11329
+ targets: z.ZodTuple<[z.ZodObject<{
11330
+ surface: z.ZodEnum<{
11331
+ prompt: "prompt";
11332
+ tools: "tools";
11333
+ mcp: "mcp";
11334
+ subagents: "subagents";
11335
+ hooks: "hooks";
11336
+ skills: "skills";
11337
+ "agent-profile": "agent-profile";
11338
+ memory: "memory";
11339
+ code: "code";
11340
+ knowledge: "knowledge";
11341
+ }>;
11342
+ identity: z.ZodString;
11343
+ currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11344
+ }, z.core.$strict>], z.ZodObject<{
11345
+ surface: z.ZodEnum<{
11346
+ prompt: "prompt";
11347
+ tools: "tools";
11348
+ mcp: "mcp";
11349
+ subagents: "subagents";
11350
+ hooks: "hooks";
11351
+ skills: "skills";
11352
+ "agent-profile": "agent-profile";
11353
+ memory: "memory";
11354
+ code: "code";
11355
+ knowledge: "knowledge";
11356
+ }>;
11357
+ identity: z.ZodString;
11358
+ currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11359
+ }, z.core.$strict>>;
11360
+ }, z.core.$strict>, z.ZodObject<{
11361
+ status: z.ZodLiteral<"conflict">;
11362
+ targets: z.ZodTuple<[z.ZodObject<{
11363
+ surface: z.ZodEnum<{
11364
+ prompt: "prompt";
11365
+ tools: "tools";
11366
+ mcp: "mcp";
11367
+ subagents: "subagents";
11368
+ hooks: "hooks";
11369
+ skills: "skills";
11370
+ "agent-profile": "agent-profile";
11371
+ memory: "memory";
11372
+ code: "code";
11373
+ knowledge: "knowledge";
11374
+ }>;
11375
+ identity: z.ZodString;
11376
+ currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11377
+ }, z.core.$strict>], z.ZodObject<{
11378
+ surface: z.ZodEnum<{
11379
+ prompt: "prompt";
11380
+ tools: "tools";
11381
+ mcp: "mcp";
11382
+ subagents: "subagents";
11383
+ hooks: "hooks";
11384
+ skills: "skills";
11385
+ "agent-profile": "agent-profile";
11386
+ memory: "memory";
11387
+ code: "code";
11388
+ knowledge: "knowledge";
11389
+ }>;
11390
+ identity: z.ZodString;
11391
+ currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11392
+ }, z.core.$strict>>;
11393
+ }, z.core.$strict>, z.ZodObject<{
11394
+ status: z.ZodLiteral<"expired">;
11395
+ }, z.core.$strict>, z.ZodObject<{
11396
+ status: z.ZodLiteral<"unsupported">;
11397
+ code: z.ZodString;
11398
+ message: z.ZodString;
11399
+ }, z.core.$strict>, z.ZodObject<{
11400
+ status: z.ZodLiteral<"failed">;
11401
+ code: z.ZodString;
11402
+ message: z.ZodString;
11403
+ }, z.core.$strict>, z.ZodObject<{
11404
+ status: z.ZodLiteral<"indeterminate">;
11405
+ code: z.ZodString;
11406
+ message: z.ZodString;
11407
+ }, z.core.$strict>], "status">;
11279
11408
  digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
11280
11409
  }, z.core.$strict>;
@@ -750,6 +750,13 @@ export const agentImprovementReviewSchema = z
750
750
  })
751
751
  .strict()
752
752
  .refine(isCanonicalJsonValue, "review must contain only RFC 8785 JSON values");
753
+ const improvementActivationTargetSchema = z
754
+ .object({
755
+ surface: improvementSurfaceSchema,
756
+ identity: z.string().min(1).max(500),
757
+ expectedBaseDigest: sha256DigestSchema,
758
+ })
759
+ .strict();
753
760
  export const agentImprovementActivationSchema = z
754
761
  .object({
755
762
  kind: z.literal("agent-improvement-activation"),
@@ -757,26 +764,14 @@ export const agentImprovementActivationSchema = z
757
764
  reviewDigest: sha256DigestSchema,
758
765
  experimentDigest: sha256DigestSchema,
759
766
  candidateBundleDigest: sha256DigestSchema,
767
+ intent: z.enum(["activate-candidate", "restore-baseline"]),
760
768
  targets: z
761
- .tuple([
762
- z
763
- .object({
764
- surface: improvementSurfaceSchema,
765
- identity: z.string().min(1).max(500),
766
- expectedBaseDigest: sha256DigestSchema,
767
- })
768
- .strict(),
769
- ])
770
- .rest(z
771
- .object({
772
- surface: improvementSurfaceSchema,
773
- identity: z.string().min(1).max(500),
774
- expectedBaseDigest: sha256DigestSchema,
775
- })
776
- .strict()),
769
+ .tuple([improvementActivationTargetSchema])
770
+ .rest(improvementActivationTargetSchema),
777
771
  fundingOwner: z.string().min(1).max(500),
778
772
  authorizedBy: z.string().min(1).max(500),
779
773
  authorizedAt: z.iso.datetime(),
774
+ expiresAt: z.iso.datetime(),
780
775
  digest: sha256DigestSchema,
781
776
  })
782
777
  .strict()
@@ -789,7 +784,112 @@ export const agentImprovementActivationSchema = z
789
784
  message: "activation targets must be unique by surface and identity",
790
785
  });
791
786
  }
787
+ if (Date.parse(activation.expiresAt) <= Date.parse(activation.authorizedAt)) {
788
+ ctx.addIssue({
789
+ code: "custom",
790
+ path: ["expiresAt"],
791
+ message: "activation expiry must follow its authorization time",
792
+ });
793
+ }
792
794
  if (!isCanonicalJsonValue(activation)) {
793
795
  ctx.addIssue({ code: "custom", message: "activation must contain only RFC 8785 JSON values" });
794
796
  }
795
797
  });
798
+ const improvementActivationTargetTransitionSchema = z
799
+ .object({
800
+ surface: improvementSurfaceSchema,
801
+ identity: z.string().min(1).max(500),
802
+ beforeDigest: sha256DigestSchema,
803
+ afterDigest: sha256DigestSchema,
804
+ })
805
+ .strict();
806
+ const improvementActivationTargetStateSchema = z
807
+ .object({
808
+ surface: improvementSurfaceSchema,
809
+ identity: z.string().min(1).max(500),
810
+ currentDigest: sha256DigestSchema,
811
+ })
812
+ .strict();
813
+ const improvementActivationOutcomeSchema = z.discriminatedUnion("status", [
814
+ z
815
+ .object({
816
+ status: z.literal("applied"),
817
+ transactionId: z.string().min(1).max(500),
818
+ targets: z
819
+ .tuple([improvementActivationTargetTransitionSchema])
820
+ .rest(improvementActivationTargetTransitionSchema),
821
+ })
822
+ .strict(),
823
+ z
824
+ .object({
825
+ status: z.literal("already-applied"),
826
+ targets: z
827
+ .tuple([improvementActivationTargetStateSchema])
828
+ .rest(improvementActivationTargetStateSchema),
829
+ })
830
+ .strict(),
831
+ z
832
+ .object({
833
+ status: z.literal("conflict"),
834
+ targets: z
835
+ .tuple([improvementActivationTargetStateSchema])
836
+ .rest(improvementActivationTargetStateSchema),
837
+ })
838
+ .strict(),
839
+ z.object({ status: z.literal("expired") }).strict(),
840
+ z
841
+ .object({
842
+ status: z.literal("unsupported"),
843
+ code: z.string().min(1).max(100),
844
+ message: z.string().min(1).max(2_000),
845
+ })
846
+ .strict(),
847
+ z
848
+ .object({
849
+ status: z.literal("failed"),
850
+ code: z.string().min(1).max(100),
851
+ message: z.string().min(1).max(2_000),
852
+ })
853
+ .strict(),
854
+ z
855
+ .object({
856
+ status: z.literal("indeterminate"),
857
+ code: z.string().min(1).max(100),
858
+ message: z.string().min(1).max(2_000),
859
+ })
860
+ .strict(),
861
+ ]);
862
+ export const agentImprovementActivationResultSchema = z
863
+ .object({
864
+ kind: z.literal("agent-improvement-activation-result"),
865
+ idempotencyKey: sha256DigestSchema,
866
+ attemptedAt: z.iso.datetime(),
867
+ completedAt: z.iso.datetime(),
868
+ outcome: improvementActivationOutcomeSchema,
869
+ digest: sha256DigestSchema,
870
+ })
871
+ .strict()
872
+ .superRefine((result, ctx) => {
873
+ if (Date.parse(result.completedAt) < Date.parse(result.attemptedAt)) {
874
+ ctx.addIssue({
875
+ code: "custom",
876
+ path: ["completedAt"],
877
+ message: "activation completion cannot predate its attempt",
878
+ });
879
+ }
880
+ const targets = "targets" in result.outcome ? result.outcome.targets : [];
881
+ const identities = targets.map((target) => `${target.surface}\u0000${target.identity}`);
882
+ if (new Set(identities).size !== identities.length) {
883
+ ctx.addIssue({
884
+ code: "custom",
885
+ path: ["outcome", "targets"],
886
+ message: "activation outcome targets must be unique by surface and identity",
887
+ });
888
+ }
889
+ if (!isCanonicalJsonValue(result)) {
890
+ ctx.addIssue({
891
+ code: "custom",
892
+ message: "activation result must contain only RFC 8785 JSON values",
893
+ });
894
+ }
895
+ });
@@ -1023,7 +1023,7 @@ export declare const agentCandidateRunReceiptSchema: z.ZodObject<{
1023
1023
  callId: string;
1024
1024
  generationId: string;
1025
1025
  traceSpanId: string;
1026
- status: "succeeded" | "failed";
1026
+ status: "failed" | "succeeded";
1027
1027
  model: string;
1028
1028
  startedAtMs: number;
1029
1029
  endedAtMs: number;
@@ -1058,7 +1058,7 @@ export declare const agentCandidateRunReceiptSchema: z.ZodObject<{
1058
1058
  callId: string;
1059
1059
  generationId: string;
1060
1060
  traceSpanId: string;
1061
- status: "succeeded" | "failed";
1061
+ status: "failed" | "succeeded";
1062
1062
  model: string;
1063
1063
  startedAtMs: number;
1064
1064
  endedAtMs: number;
@@ -806,6 +806,7 @@ export interface AgentImprovementActivationTarget {
806
806
  /** Current target state that activation is allowed to replace. */
807
807
  expectedBaseDigest: Sha256Digest;
808
808
  }
809
+ export type AgentImprovementActivationIntent = "activate-candidate" | "restore-baseline";
809
810
  /** Authority receipt permitting activation of one already-measured candidate. */
810
811
  export interface AgentImprovementActivation {
811
812
  kind: "agent-improvement-activation";
@@ -813,10 +814,56 @@ export interface AgentImprovementActivation {
813
814
  reviewDigest: Sha256Digest;
814
815
  experimentDigest: Sha256Digest;
815
816
  candidateBundleDigest: Sha256Digest;
817
+ intent: AgentImprovementActivationIntent;
816
818
  targets: [AgentImprovementActivationTarget, ...AgentImprovementActivationTarget[]];
817
819
  fundingOwner: string;
818
820
  authorizedBy: string;
819
821
  authorizedAt: string;
822
+ expiresAt: string;
823
+ digest: Sha256Digest;
824
+ }
825
+ export interface AgentImprovementActivationTargetTransition {
826
+ surface: AgentImprovementSurface;
827
+ identity: string;
828
+ beforeDigest: Sha256Digest;
829
+ afterDigest: Sha256Digest;
830
+ }
831
+ export interface AgentImprovementActivationTargetState {
832
+ surface: AgentImprovementSurface;
833
+ identity: string;
834
+ currentDigest: Sha256Digest;
835
+ }
836
+ export type AgentImprovementActivationOutcome = {
837
+ /** Every target changed atomically from the authorized state to the requested bundle. */
838
+ status: "applied";
839
+ transactionId: string;
840
+ targets: [
841
+ AgentImprovementActivationTargetTransition,
842
+ ...AgentImprovementActivationTargetTransition[]
843
+ ];
844
+ } | {
845
+ /** No write occurred; targets are already desired or no longer match the authorized base. */
846
+ status: "already-applied" | "conflict";
847
+ targets: [
848
+ AgentImprovementActivationTargetState,
849
+ ...AgentImprovementActivationTargetState[]
850
+ ];
851
+ } | {
852
+ status: "expired";
853
+ } | {
854
+ /** `failed` proves no write; `indeterminate` means commit state must be reconciled. */
855
+ status: "unsupported" | "failed" | "indeterminate";
856
+ code: string;
857
+ message: string;
858
+ };
859
+ /** Immutable outcome of one idempotent, transaction-wide activation attempt. */
860
+ export interface AgentImprovementActivationResult {
861
+ kind: "agent-improvement-activation-result";
862
+ /** The activation digest is also its stable retry key. */
863
+ idempotencyKey: Sha256Digest;
864
+ attemptedAt: string;
865
+ completedAt: string;
866
+ outcome: AgentImprovementActivationOutcome;
820
867
  digest: Sha256Digest;
821
868
  }
822
869
  /** Complete execution of one exact experiment attempt. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/agent-interface",
3
- "version": "0.30.0",
3
+ "version": "0.31.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "license": "MIT",