@tangle-network/agent-interface 2.4.0 → 2.6.0

package/dist/agent-candidate-lineage-schema.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { AgentCandidateLineage } from "./agent-candidate.js";
 export declare const agentCandidateKnowledgeSchema: z.ZodObject<{
     candidate: z.ZodObject<{
         kind: z.ZodLiteral<"knowledge-improvement-candidate">;
@@ -10,6 +11,10 @@ export declare const agentCandidateKnowledgeSchema: z.ZodObject<{
         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     }, z.core.$strict>;
+    stateScope: z.ZodOptional<z.ZodObject<{
+        pagesDirectory: z.ZodString;
+        researchState: z.ZodBoolean;
+    }, z.core.$strict>>;
     snapshot: z.ZodObject<{
         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -120,9 +125,19 @@ export declare const agentCandidateMemoryPolicySchema: z.ZodDiscriminatedUnion<[
         byteLength: z.ZodNumber;
     }, z.core.$strict>>;
 }, z.core.$strict>], "mode">;
+/**
+ * Sources whose candidate was PRODUCED from a parent rather than supplied whole.
+ *
+ * One list, read by the lineage schema and by every experiment schema that gates on it. Three
+ * call sites branched on `optimizer || compound` independently, so adding a fourth generated
+ * source silently exempted it from the "name your baseline" rule in two of them.
+ */
+export declare const generatedCandidateSources: readonly ["optimizer", "compound", "frontier-author"];
+export declare function isGeneratedCandidateSource(source: AgentCandidateLineage["source"]): boolean;
 export declare const agentCandidateLineageSchema: z.ZodObject<{
     source: z.ZodEnum<{
         compound: "compound";
+        "frontier-author": "frontier-author";
         human: "human";
         import: "import";
         optimizer: "optimizer";

package/dist/agent-candidate-lineage-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
-import { addDuplicateIssues, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { addDuplicateIssues, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 export const agentCandidateKnowledgeSchema = z
     .object({
     candidate: z
@@ -15,6 +15,15 @@ export const agentCandidateKnowledgeSchema = z
         promotionPlanHash: sha256DigestSchema,
     })
         .strict(),
+    stateScope: z
+        .object({
+        pagesDirectory: z
+            .string()
+            .refine((value) => isSafeRelativePath(value, false), "pagesDirectory must be a canonical workspace-relative directory"),
+        researchState: z.boolean(),
+    })
+        .strict()
+        .optional(),
     snapshot: agentCandidateWorkspaceSnapshotEvidenceSchema,
     retrievalConfig: agentCandidateCapturedArtifactSchema.optional(),
     evaluation: agentCandidateCapturedArtifactSchema,
@@ -30,9 +39,30 @@ export const agentCandidateMemoryPolicySchema = z.discriminatedUnion("mode", [
     })
         .strict(),
 ]);
+/**
+ * Sources whose candidate was PRODUCED from a parent rather than supplied whole.
+ *
+ * One list, read by the lineage schema and by every experiment schema that gates on it. Three
+ * call sites branched on `optimizer || compound` independently, so adding a fourth generated
+ * source silently exempted it from the "name your baseline" rule in two of them.
+ */
+export const generatedCandidateSources = [
+    "optimizer",
+    "compound",
+    "frontier-author",
+];
+export function isGeneratedCandidateSource(source) {
+    return generatedCandidateSources.includes(source);
+}
 export const agentCandidateLineageSchema = z
     .object({
-    source: z.enum(["optimizer", "human", "import", "compound"]),
+    source: z.enum([
+        "optimizer",
+        "human",
+        "import",
+        "compound",
+        "frontier-author",
+    ]),
     parentDigests: z.array(sha256DigestSchema).optional(),
     runIds: z.array(z.string().min(1)).optional(),
     profileDiffIds: z.array(z.string().min(1)).optional(),
@@ -53,7 +83,9 @@ export const agentCandidateLineageSchema = z
             message: "compound candidates must name at least two distinct parents",
         });
     }
-    if (lineage.source === "optimizer" || lineage.source === "compound") {
+    // Every generated lineage names what it came from and the run that produced
+    // it, whoever generated it.
+    if (isGeneratedCandidateSource(lineage.source)) {
         if ((lineage.parentDigests?.length ?? 0) === 0) {
             ctx.addIssue({
                 code: "custom",
@@ -68,6 +100,13 @@ export const agentCandidateLineageSchema = z
                 message: "generated candidates must name their producing run",
             });
         }
+    }
+    // A development split exists only when an offline search produced the
+    // candidate. An agent that authors a profile inside a run has no held-out
+    // set to pin, so requiring one would force a fabricated digest into the
+    // evidence record. This branch is deliberately NOT the generated-source
+    // list above.
+    if (lineage.source === "optimizer" || lineage.source === "compound") {
         if (lineage.developmentSplitDigest === undefined) {
             ctx.addIssue({
                 code: "custom",

package/dist/agent-candidate-promotion-schema.d.ts

@@ -724,6 +724,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             }, z.core.$strict>;
+            stateScope: z.ZodOptional<z.ZodObject<{
+                pagesDirectory: z.ZodString;
+                researchState: z.ZodBoolean;
+            }, z.core.$strict>>;
             snapshot: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                 digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -1557,6 +1561,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             }, z.core.$strict>;
+            stateScope: z.ZodOptional<z.ZodObject<{
+                pagesDirectory: z.ZodString;
+                researchState: z.ZodBoolean;
+            }, z.core.$strict>>;
             snapshot: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                 digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -1672,6 +1680,7 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
     candidateLineage: z.ZodObject<{
         source: z.ZodEnum<{
             compound: "compound";
+            "frontier-author": "frontier-author";
             human: "human";
             import: "import";
             optimizer: "optimizer";
@@ -4313,6 +4322,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 }, z.core.$strict>;
+                stateScope: z.ZodOptional<z.ZodObject<{
+                    pagesDirectory: z.ZodString;
+                    researchState: z.ZodBoolean;
+                }, z.core.$strict>>;
                 snapshot: z.ZodObject<{
                     kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -5146,6 +5159,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 }, z.core.$strict>;
+                stateScope: z.ZodOptional<z.ZodObject<{
+                    pagesDirectory: z.ZodString;
+                    researchState: z.ZodBoolean;
+                }, z.core.$strict>>;
                 snapshot: z.ZodObject<{
                     kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -5261,6 +5278,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
         candidateLineage: z.ZodObject<{
             source: z.ZodEnum<{
                 compound: "compound";
+                "frontier-author": "frontier-author";
                 human: "human";
                 import: "import";
                 optimizer: "optimizer";
@@ -9332,6 +9350,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     }, z.core.$strict>;
+                    stateScope: z.ZodOptional<z.ZodObject<{
+                        pagesDirectory: z.ZodString;
+                        researchState: z.ZodBoolean;
+                    }, z.core.$strict>>;
                     snapshot: z.ZodObject<{
                         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -10165,6 +10187,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     }, z.core.$strict>;
+                    stateScope: z.ZodOptional<z.ZodObject<{
+                        pagesDirectory: z.ZodString;
+                        researchState: z.ZodBoolean;
+                    }, z.core.$strict>>;
                     snapshot: z.ZodObject<{
                         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -10280,6 +10306,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
             candidateLineage: z.ZodObject<{
                 source: z.ZodEnum<{
                     compound: "compound";
+                    "frontier-author": "frontier-author";
                     human: "human";
                     import: "import";
                     optimizer: "optimizer";
@@ -13642,6 +13669,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
             candidateLineage: z.ZodObject<{
                 source: z.ZodEnum<{
                     compound: "compound";
+                    "frontier-author": "frontier-author";
                     human: "human";
                     import: "import";
                     optimizer: "optimizer";

package/dist/agent-candidate-promotion-schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AGENT_IMPROVEMENT_SURFACES } from "./agent-candidate.js";
 import { agentCandidateBundleSchema } from "./agent-candidate-schema.js";
-import { agentCandidateLineageSchema } from "./agent-candidate-lineage-schema.js";
+import { agentCandidateLineageSchema, isGeneratedCandidateSource, } from "./agent-candidate-lineage-schema.js";
 import { agentCandidateBenchmarkSuiteInputsSchema } from "./agent-candidate-task-schema.js";
 import { canonicalCandidateDigest, isCanonicalJsonValue, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { refineAgentExecutionWithinLimits } from "./agent-execution-limits.js";
@@ -23,7 +23,7 @@ export const agentCandidateExperimentSchema = z
     .strict()
     .superRefine((experiment, ctx) => {
     const source = experiment.candidateLineage.source;
-    if ((source === "optimizer" || source === "compound") &&
+    if (isGeneratedCandidateSource(source) &&
         !experiment.candidateLineage.parentDigests?.includes(experiment.baseline.digest)) {
         ctx.addIssue({
             code: "custom",

package/dist/agent-candidate-schema.d.ts

@@ -728,6 +728,10 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         }, z.core.$strict>;
+        stateScope: z.ZodOptional<z.ZodObject<{
+            pagesDirectory: z.ZodString;
+            researchState: z.ZodBoolean;
+        }, z.core.$strict>>;
         snapshot: z.ZodObject<{
             kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
             digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

package/dist/agent-candidate.d.ts

@@ -227,8 +227,15 @@ export interface AgentCandidateKnowledgeRef {
     evidenceHash: Sha256Digest;
     promotionPlanHash: Sha256Digest;
 }
+/** Canonical selection of knowledge state included in the candidate hash. */
+export interface AgentCandidateKnowledgeStateScope {
+    pagesDirectory: string;
+    researchState: boolean;
+}
 export interface AgentCandidateKnowledge {
     candidate: AgentCandidateKnowledgeRef;
+    /** Absent scopes retain the knowledge provider's default selection. */
+    stateScope?: AgentCandidateKnowledgeStateScope;
     snapshot: AgentCandidateWorkspaceSnapshotEvidence;
     retrievalConfig?: AgentCandidateCapturedArtifact;
     evaluation: AgentCandidateCapturedArtifact;
@@ -281,7 +288,20 @@ export interface AgentCandidateFixedSpend {
 }
 /** Evidence and ancestry that produced the immutable candidate. */
 export interface AgentCandidateLineage {
-    source: "optimizer" | "human" | "import" | "compound";
+    /**
+     * Who produced this candidate.
+     *
+     * `frontier-author` is an agent that wrote another agent's profile — the same
+     * member {@link AgentProfileDiff}`.source.kind` already carries, so the two
+     * enums name one actor with one word. It covers a supervising agent authoring
+     * a child's full `AgentProfile` from inside a run, which `spawn_worker`
+     * exposes and a `driver` role promotes to a sub-supervisor.
+     *
+     * It carries `optimizer`'s parent and run requirements and not its
+     * `developmentSplitDigest`: there is no held-out split and no offline search
+     * behind a profile an agent wrote while working.
+     */
+    source: "optimizer" | "human" | "import" | "compound" | "frontier-author";
     parentDigests?: Sha256Digest[];
     runIds?: string[];
     profileDiffIds?: string[];

package/dist/agent-profile-improvement-schema.d.ts

@@ -236,6 +236,7 @@ export declare const agentProfileImprovementExperimentSchema: z.ZodObject<{
     candidateLineage: z.ZodObject<{
         source: z.ZodEnum<{
             compound: "compound";
+            "frontier-author": "frontier-author";
             human: "human";
             import: "import";
             optimizer: "optimizer";
@@ -768,6 +769,7 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
         candidateLineage: z.ZodObject<{
             source: z.ZodEnum<{
                 compound: "compound";
+                "frontier-author": "frontier-author";
                 human: "human";
                 import: "import";
                 optimizer: "optimizer";

package/dist/agent-profile-improvement-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { changedAgentProfileAxes } from "./profile-diff.js";
-import { agentCandidateLineageSchema } from "./agent-candidate-lineage-schema.js";
+import { agentCandidateLineageSchema, isGeneratedCandidateSource, } from "./agent-candidate-lineage-schema.js";
 import { canonicalCandidateDigest, isCanonicalJsonValue, omitTopLevelDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { refineAgentExecutionWithinLimits } from "./agent-execution-limits.js";
 import { agentCandidateBenchmarkGraderIdentitySchema, agentCandidateExecutionLimitsSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
@@ -189,7 +189,7 @@ export const agentProfileImprovementExperimentSchema = z
         });
     }
     const source = experiment.candidateLineage.source;
-    if ((source === "optimizer" || source === "compound") &&
+    if (isGeneratedCandidateSource(source) &&
         !experiment.candidateLineage.parentDigests?.includes(experiment.baseline.stateDigest)) {
         ctx.addIssue({
             code: "custom",

package/dist/profile-diff.d.ts

@@ -49,6 +49,11 @@ export interface AgentProfileDiff {
     description?: string;
     rationale?: string;
     source?: {
+        /**
+         * Who produced this change. `frontier-author` is an agent that wrote it —
+         * the same member {@link AgentCandidateLineage}`.source` carries, so the two
+         * enums name one actor with one word.
+         */
         kind: "trace" | "frontier-author" | "human" | "optimizer" | "compound";
         artifacts?: readonly string[];
         notes?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",