@toolproof-core/lib 1.0.31 → 1.0.33

package/src/utils/creation/stepCreation.ts

@@ -1,35 +1,41 @@
 import type {
-    BranchStepIdJson,
-    BranchStepJson,
-    CaseJson,
-    ForStepIdJson,
-    ForStepJson,
-    ToolJson,
-    ToolStepIdJson,
-    ToolStepJson,
-    ResourceRoleIdJson,
-    WhileStepIdJson,
-    WhileStepJson,
+    BranchStep,
+    Case,
+    ForStep,
+    Tool,
+    ToolStep,
+    WhileStep,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../../artifacts/artifacts.js';
+import { getInputRoleNames, getOutputRoleNames } from '../roleSpec.js';
+
+type ToolStepId = string;
+type BranchStepId = string;
+type ForStepId = string;
+type WhileStepId = string;
+
+type ToolStepWithId = ToolStep & { id: ToolStepId };
+type BranchStepWithId = BranchStep & { id: BranchStepId };
+type ForStepWithId = ForStep & { id: ForStepId };
+type WhileStepWithId = WhileStep & { id: WhileStepId };
 
 export type LoopStepBuildIdentities =
     | {
         stepKind: typeof CONSTANTS.Enums.StepKind.for;
-        stepId: ForStepIdJson;
-        whatId: ToolStepIdJson;
-        whenId: ToolStepIdJson;
+        stepId: ForStepId;
+        whatId: ToolStepId;
+        whenId: ToolStepId;
     }
     | {
         stepKind: typeof CONSTANTS.Enums.StepKind.while;
-        stepId: WhileStepIdJson;
-        whatId: ToolStepIdJson;
-        whenId: ToolStepIdJson;
+        stepId: WhileStepId;
+        whatId: ToolStepId;
+        whenId: ToolStepId;
     };
 
 export type BranchCaseBuildIdentities = {
-    whatId: ToolStepIdJson;
-    whenId: ToolStepIdJson;
+    whatId: ToolStepId;
+    whenId: ToolStepId;
 };
 
 function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
@@ -38,30 +44,30 @@ function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
     }
 }
 
-function getRoleBindingSpec(tool: ToolJson): ToolStepJson['roleBindingSpec'] {
+function getRoleBindingSpec(tool: Tool): ToolStep['roleBindingSpec'] {
     return {
-        inputBindings: Object.keys(tool.roleSpec.inputRoleValueById) as ResourceRoleIdJson[],
-        outputBindings: Object.keys(tool.roleSpec.outputRoleValueById) as ResourceRoleIdJson[],
+        inputBindings: getInputRoleNames(tool),
+        outputBindings: getOutputRoleNames(tool),
     };
 }
 
 export function buildToolStepFromTool(
-    tool: ToolJson,
-    id: ToolStepIdJson,
-): ToolStepJson {
+    tool: Tool,
+    id: ToolStepId,
+): ToolStepWithId {
     return {
         id,
         stepKind: CONSTANTS.Enums.StepKind.tool,
         toolId: tool.id,
         roleBindingSpec: getRoleBindingSpec(tool),
-    };
+    } as ToolStepWithId;
 }
 
 export function buildLoopStepFromToolPair(
-    whatTool: ToolJson,
-    whenTool: ToolJson,
+    whatTool: Tool,
+    whenTool: Tool,
     identities: LoopStepBuildIdentities,
-): ForStepJson | WhileStepJson {
+): ForStep | WhileStep {
     const what = buildToolStepFromTool(whatTool, identities.whatId);
     const when = buildToolStepFromTool(whenTool, identities.whenId);
 
@@ -70,21 +76,21 @@ export function buildLoopStepFromToolPair(
             id: identities.stepId,
             stepKind: CONSTANTS.Enums.StepKind.for,
             case: { what, when },
-        };
+        } as ForStepWithId;
     }
 
     return {
         id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.while,
         case: { what, when },
-    };
+    } as WhileStepWithId;
 }
 
 export function buildBranchStepFromToolPairs(
-    cases: Array<{ whatTool: ToolJson; whenTool: ToolJson }>,
-    branchId: BranchStepIdJson,
+    cases: Array<{ whatTool: Tool; whenTool: Tool }>,
+    branchId: BranchStepId,
     caseIdentities: BranchCaseBuildIdentities[],
-): BranchStepJson {
+): BranchStepWithId {
     if (cases.length !== caseIdentities.length) {
         throw new Error('buildBranchStepFromToolPairs requires one id pair per case');
     }
@@ -98,7 +104,7 @@ export function buildBranchStepFromToolPairs(
 
         const what = buildToolStepFromTool(whatTool, identities.whatId);
         const when = buildToolStepFromTool(whenTool, identities.whenId);
-        return { what, when } satisfies CaseJson;
+        return { what, when } satisfies Case;
     });
 
     assertNonEmpty(resolved, 'buildBranchStepFromToolPairs requires at least one case');
@@ -107,17 +113,17 @@ export function buildBranchStepFromToolPairs(
         id: branchId,
         stepKind: CONSTANTS.Enums.StepKind.branch,
         cases: resolved,
-    };
+    } as BranchStepWithId;
 }
 
 export function cloneForStepWithIdentities(
-    forStep: ForStepJson,
+    forStep: ForStep,
     identities: {
-        stepId: ForStepIdJson;
-        whatId: ToolStepIdJson;
-        whenId: ToolStepIdJson;
+        stepId: ForStepId;
+        whatId: ToolStepId;
+        whenId: ToolStepId;
     },
-): ForStepJson {
+): ForStepWithId {
     return {
         id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.for,
@@ -131,17 +137,17 @@ export function cloneForStepWithIdentities(
                 id: identities.whenId,
             },
         },
-    };
+    } as ForStepWithId;
 }
 
 export function cloneWhileStepWithIdentities(
-    whileStep: WhileStepJson,
+    whileStep: WhileStep,
     identities: {
-        stepId: WhileStepIdJson;
-        whatId: ToolStepIdJson;
-        whenId: ToolStepIdJson;
+        stepId: WhileStepId;
+        whatId: ToolStepId;
+        whenId: ToolStepId;
     },
-): WhileStepJson {
+): WhileStepWithId {
     return {
         id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.while,
@@ -155,5 +161,5 @@ export function cloneWhileStepWithIdentities(
                 id: identities.whenId,
             },
         },
-    };
+    } as WhileStepWithId;
 }

package/src/utils/extractData.ts

@@ -1,117 +1,75 @@
 import type {
-    RawStrategyJson,
-    ToolIdJson,
-    ToolJson,
-    ToolStepIdJson,
-    ToolStepJson,
-    StepJson,
-    ResourceRoleIdJson,
-    ResourceRoleJson,
-    ResourceIdJson,
-    ResourceTypeIdJson,
-    ResourceJson,
+    RoleName,
+    RoleValue,
+    Strategy,
+    ToolId,
+    Tool,
+    ToolStep,
+    ResourceId,
+    ResourceTypeId,
+    Resource,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../artifacts/artifacts.js';
+import {
+    extractToolStepsFromStrategy,
+    getInputRoleEntries,
+    getOutputRoleEntries,
+    toToolRoleDescriptor,
+    type ToolRoleDescriptor,
+} from './roleSpec.js';
 
 
-export function extractToolIdsFromRawStrategy(rawStrategy: RawStrategyJson): ToolIdJson[] {
+export function extractToolIdsFromRawStrategy(rawStrategy: Strategy): ToolId[] {
     const toolSteps = extractToolStepsFromRawStrategy(rawStrategy);
-    const ids = new Set<ToolIdJson>();
+    const ids = new Set<ToolId>();
     for (const jStep of toolSteps) {
         ids.add(jStep.toolId);
     }
     return Array.from(ids);
 }
 
-export function extractToolStepsFromRawStrategy(rawStrategy: RawStrategyJson): ToolStepJson[] {
-    const toolSteps: ToolStepJson[] = [];
-    const seen = new Set<ToolStepIdJson>();
-
-    const addToolStep = (toolStep: ToolStepJson) => {
-        if (seen.has(toolStep.id)) {
-            throw new Error(`Duplicate tool step id encountered: ${toolStep.id}`);
-        }
-        seen.add(toolStep.id);
-        toolSteps.push(toolStep);
-    };
-
-    const visitStep = (step: StepJson) => {
-        switch (step.stepKind) {
-            case CONSTANTS.Enums.StepKind.tool: {
-                addToolStep(step);
-                return;
-            }
-            case CONSTANTS.Enums.StepKind.branch: {
-                for (const conditional of step.cases) {
-                    addToolStep(conditional.when);
-                    addToolStep(conditional.what);
-                }
-                return;
-            }
-            case CONSTANTS.Enums.StepKind.while:
-            case CONSTANTS.Enums.StepKind.for: {
-                addToolStep(step.case.when);
-                addToolStep(step.case.what);
-                return;
-            }
-            default: {
-                const _exhaustive: never = step;
-                return _exhaustive;
-            }
-        }
-    };
-
-    for (const step of rawStrategy.steps) {
-        visitStep(step);
-    }
-
-    return toolSteps;
+export function extractToolStepsFromRawStrategy(rawStrategy: Strategy): ToolStep[] {
+    return extractToolStepsFromStrategy(rawStrategy);
 }
 
 
-export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, toolMap: Map<ToolIdJson, ToolJson>): Map<ResourceRoleIdJson, ResourceRoleJson> {
-    const roleMap = new Map<ResourceRoleIdJson, ResourceRoleJson>();
+export function extractRoleMapFromRawStrategy(rawStrategy: Strategy, toolMap: Map<ToolId, Tool>): Map<RoleName, ToolRoleDescriptor> {
+    const roleMap = new Map<RoleName, ToolRoleDescriptor>();
     const toolIds = extractToolIdsFromRawStrategy(rawStrategy);
 
     for (const toolId of toolIds) {
         const tool = toolMap.get(toolId);
         if (!tool) continue;
 
-        for (const [rid, role] of Object.entries(tool.roleSpec.inputRoleValueById)) {
-            roleMap.set(rid as ResourceRoleIdJson, {
-                id: rid as ResourceRoleIdJson,
-                ...role,
-            });
+        for (const entry of getInputRoleEntries(tool)) {
+            roleMap.set(entry[0], toToolRoleDescriptor(entry));
         }
-        for (const [rid, role] of Object.entries(tool.roleSpec.outputRoleValueById)) {
-            roleMap.set(rid as ResourceRoleIdJson, {
-                id: rid as ResourceRoleIdJson,
-                ...role,
-            });
+        for (const entry of getOutputRoleEntries(tool)) {
+            roleMap.set(entry[0], toToolRoleDescriptor(entry));
         }
     }
 
     return roleMap;
 }
 
-export function extractSingleNonErrorOutputTypeId(tool: ToolJson): ResourceTypeIdJson | null {
+export function extractSingleNonErrorOutputTypeId(tool: Tool): ResourceTypeId | null {
     const errorRoleId = CONSTANTS.Cosmos.ROLE_ErrorOutput;
-    const outputEntries = Object.entries(tool.roleSpec.outputRoleValueById).filter(([roleId]) => roleId !== errorRoleId);
+    const outputEntries = getOutputRoleEntries(tool).filter(([roleName]) => roleName !== errorRoleId);
     if (!outputEntries || !outputEntries[0] || outputEntries.length !== 1) {
         throw new Error(`Tool ${tool.id} must have exactly one non-error output role to be branchable/loopable`);
     } // ATTENTION_PUREIFY
-    const outputRole = outputEntries[0][1];
+    const outputRole = outputEntries[0][1] as RoleValue;
     return outputRole.resourceTypeId;
 }
 
 
 
-export function extractResourceMapForType<TResource extends ResourceJson = ResourceJson>(
-    resourcesByType: Partial<Record<ResourceTypeIdJson, TResource[]>>,
-    resourceTypeId: ResourceTypeIdJson
-): Map<ResourceIdJson, TResource> {
+export function extractResourceMapForType<TResource extends Resource = Resource>(
+    resourcesByType: Partial<Record<ResourceTypeId, TResource[]>>,
+    resourceTypeId: ResourceTypeId
+): Map<ResourceId, TResource> {
     const resources = resourcesByType[resourceTypeId] ?? [];
-    const map = new Map<ResourceIdJson, TResource>();
+    const map = new Map<ResourceId, TResource>();
 
     for (const resource of resources) {
         map.set(resource.id, resource);
@@ -124,10 +82,10 @@ export function extractResourceMapForType<TResource extends ResourceJson = Resou
 export function extractIdKeyedNucleusMapForType<
     TKey extends string = string,
     TNucleus extends { id: string | number | boolean } = { id: string | number | boolean },
-    TResource extends ResourceJson = ResourceJson
+    TResource extends Resource = Resource
 >(
-    resourcesByType: Partial<Record<ResourceTypeIdJson, TResource[]>>,
-    resourceTypeId: ResourceTypeIdJson,
+    resourcesByType: Partial<Record<ResourceTypeId, TResource[]>>,
+    resourceTypeId: ResourceTypeId,
 ): Map<TKey, TNucleus> {
     const resourceMap = extractResourceMapForType<TResource>(resourcesByType, resourceTypeId);
     const out = new Map<TKey, TNucleus>();

package/src/utils/parallelizeSteps.ts

@@ -1,17 +1,23 @@
 import type {
-    BranchStepJson,
-    ForStepJson,
-    ToolStepIdJson,
-    ToolStepJson,
-    ResourceRoleIdJson,
-    StepJson,
-    StrategyStateJson,
-    WhileStepJson,
+    BranchStep,
+    ForStep,
+    ToolStep,
+    Step,
+    WhileStep,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../artifacts/artifacts.js';
+import type { StrategyState } from './strategyState.js';
 
+type ToolStepId = string;
+type ToolStepWithId = ToolStep & { id: ToolStepId };
 
-export function getIndependentThreads(steps: StepJson[], strategyState: StrategyStateJson): StepJson[][] {
+function getToolStepId(toolStep: ToolStep | undefined): ToolStepId | undefined {
+    const maybeId = (toolStep as Partial<ToolStepWithId> | undefined)?.id;
+    return typeof maybeId === 'string' ? maybeId : undefined;
+}
+
+
+export function getIndependentThreads(steps: Step[], strategyState: StrategyState): Step[][] {
     type OwnerIndex = number;
 
     const getOwnerLabel = (ownerIndex: OwnerIndex) => {
@@ -20,49 +26,50 @@ export function getIndependentThreads(steps: StepJson[], strategyState: Strategy
     };
 
     // Map each toolStep.id (including macro-nested tool steps) to owning top-level step index.
-    const toolStepIdToOwner = new Map<ToolStepIdJson, OwnerIndex>();
-    const ownerToToolStepIds = new Map<OwnerIndex, ToolStepIdJson[]>();
-    const toolStepById = new Map<ToolStepIdJson, ToolStepJson>();
+    const toolStepIdToOwner = new Map<ToolStepId, OwnerIndex>();
+    const ownerToToolStepIds = new Map<OwnerIndex, ToolStepId[]>();
+    const toolStepById = new Map<ToolStepId, ToolStepWithId>();
 
-    const addToolStep = (toolStep: ToolStepJson | undefined, ownerIndex: OwnerIndex) => {
-        if (!toolStep?.id) return;
+    const addToolStep = (toolStep: ToolStep | undefined, ownerIndex: OwnerIndex) => {
+        const toolStepId = getToolStepId(toolStep);
+        if (!toolStepId || !toolStep) return;
 
-        const existingOwner = toolStepIdToOwner.get(toolStep.id);
+        const existingOwner = toolStepIdToOwner.get(toolStepId);
         if (existingOwner !== undefined) {
             throw new Error(
-                `Duplicate toolStep.id '${toolStep.id}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
+                `Duplicate toolStep.id '${toolStepId}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
             );
         }
 
-        toolStepIdToOwner.set(toolStep.id, ownerIndex);
-        toolStepById.set(toolStep.id, toolStep);
+        toolStepIdToOwner.set(toolStepId, ownerIndex);
+        toolStepById.set(toolStepId, toolStep as ToolStepWithId);
         const bucket = ownerToToolStepIds.get(ownerIndex) ?? [];
-        bucket.push(toolStep.id);
+        bucket.push(toolStepId);
         ownerToToolStepIds.set(ownerIndex, bucket);
     };
 
     steps.forEach((step, ownerIndex) => {
         if (step.stepKind === CONSTANTS.Enums.StepKind.tool) {
-            addToolStep(step as ToolStepJson, ownerIndex);
+            addToolStep(step as ToolStep, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.for) {
-            const loop = step as ForStepJson;
+            const loop = step as ForStep;
             addToolStep(loop.case?.what, ownerIndex);
             addToolStep(loop.case?.when, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.while) {
-            const loop = step as WhileStepJson;
+            const loop = step as WhileStep;
             addToolStep(loop.case?.what, ownerIndex);
             addToolStep(loop.case?.when, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.branch) {
-            const branch = step as BranchStepJson;
+            const branch = step as BranchStep;
             for (const caseItem of branch.cases ?? []) {
                 addToolStep(caseItem?.what, ownerIndex);
                 addToolStep(caseItem?.when, ownerIndex);
@@ -94,20 +101,22 @@ export function getIndependentThreads(steps: StepJson[], strategyState: Strategy
         const bucket = strategyState?.[toolStepId] ?? ({} as any);
 
         for (const inputRoleId of inputBindings) {
-            const entry = bucket?.[inputRoleId as ResourceRoleIdJson] as any;
-            if (!entry || entry.resourceShellKind !== 'internalInputPotential') continue;
+            const entry = bucket?.[inputRoleId] as any;
+            if (!entry || entry.strategyStateInputKind !== 'referenceInput') continue;
 
-            const creatorToolStepId = entry?.creationContext?.toolStepId as ToolStepIdJson | undefined;
+            const creatorToolStepId = typeof entry?.toolStepPath === 'string'
+                ? entry.toolStepPath as ToolStepId
+                : undefined;
             if (!creatorToolStepId) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.toolStepId for role '${inputRoleId}'`
+                    `Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing toolStepPath for role '${inputRoleId}'`
                 );
             }
 
             const producerOwner = toolStepIdToOwner.get(creatorToolStepId);
             if (producerOwner === undefined) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepId '${creatorToolStepId}' not found in strategy steps`
+                    `Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepPath '${creatorToolStepId}' not found in strategy steps`
                 );
             }
 

package/src/utils/resolveResourceChain.ts

@@ -1,65 +1,51 @@
 import type {
-    CreationContextJson,
-    ExternalInputPotentialShellJson,
-    InternalInputPotentialShellJson,
-    OutputPotentialShellJson,
-    ResourceJson,
-    ResourcePotentialJson,
-    StrategyStateJson,
+    CreationContext,
+    ExternalInput,
+    ReferenceInput,
+    StrategyStateInputEntry,
+    ValueInput,
 } from '@toolproof-core/schema';
-import { CONSTANTS } from '../artifacts/artifacts.js';
+import { getStrategyStateEntry, type StrategyState } from './strategyState.js';
 
 export type ResolveResult =
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.materialized; entry: ResourceJson; path: CreationContextJson[] }
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.externalInputPotential; entry: ExternalInputPotentialShellJson; path: CreationContextJson[] }
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.outputPotential; entry: OutputPotentialShellJson; path: CreationContextJson[] }
-    | { status: 'unresolved'; reason: 'not-found' | 'cycle' | 'depth-exceeded'; path: CreationContextJson[] };
+    | { status: 'valueInput'; entry: ValueInput; path: CreationContext[] }
+    | { status: 'externalInput'; entry: ExternalInput; path: CreationContext[] }
+    | { status: 'unresolved'; reason: 'not-found' | 'cycle' | 'depth-exceeded'; path: CreationContext[] };
 
 export function resolveResourceChain(
-    strategyState: StrategyStateJson,
-    start: CreationContextJson,
+    strategyState: StrategyState,
+    start: CreationContext,
     opts?: { maxDepth?: number }
 ): ResolveResult {
     const maxDepth = opts?.maxDepth ?? 50;
     const visited = new Set<string>();
-    const path: CreationContextJson[] = [];
-    let current: CreationContextJson = start;
+    const path: CreationContext[] = [];
+    let current: CreationContext = start;
 
     for (let depth = 0; depth <= maxDepth; depth++) {
         path.push(current);
-        const visitKey = `${current.toolStepId}::${current.resourceRoleId}`;
+        const visitKey = `${current.toolStepPath}::${current.roleName}`;
         if (visited.has(visitKey)) {
             return { status: 'unresolved', reason: 'cycle', path };
         }
         visited.add(visitKey);
 
-        const bucket = strategyState[current.toolStepId];
-        if (!bucket) return { status: 'unresolved', reason: 'not-found', path };
-        const entry = bucket[current.resourceRoleId] as (
-            | ResourceJson
-            | ResourcePotentialJson
-            | undefined
-        );
+        const entry = getStrategyStateEntry(strategyState, current) as StrategyStateInputEntry | undefined;
         if (!entry) return { status: 'unresolved', reason: 'not-found', path };
 
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.materialized) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.materialized, entry: entry as ResourceJson, path };
+        if (entry.strategyStateInputKind === 'valueInput') {
+            return { status: 'valueInput', entry: entry, path };
         }
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.externalInputPotential) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.externalInputPotential, entry: entry as ExternalInputPotentialShellJson, path };
-        }
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.outputPotential) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.outputPotential, entry: entry as OutputPotentialShellJson, path };
+        if (entry.strategyStateInputKind === 'externalInput') {
+            return { status: 'externalInput', entry: entry, path };
         }
 
-        // internalInputPotential: follow ref backwards
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.internalInputPotential) {
-            current = (entry as InternalInputPotentialShellJson).creationContext;
-            continue;
-        }
+        current = {
+            toolStepPath: (entry as ReferenceInput).toolStepPath,
+            roleName: (entry as ReferenceInput).roleName,
+        };
+        continue;
 
-        // Unknown case
-        return { status: 'unresolved', reason: 'not-found', path };
     }
 
     return { status: 'unresolved', reason: 'depth-exceeded', path };

package/src/utils/roleSpec.ts

@@ -0,0 +1,80 @@
+import type {
+    RoleName,
+    RoleValue,
+    Strategy,
+    Step,
+    Tool,
+    ToolStep,
+} from '@toolproof-core/schema';
+
+export interface ToolRoleDescriptor extends RoleValue {
+    id: RoleName;
+    name: string;
+}
+
+export function getInputRoleEntries(tool: Tool): Array<[RoleName, RoleValue]> {
+    return Object.entries(tool.roleSpec.inputRoleValueByName) as Array<[RoleName, RoleValue]>;
+}
+
+export function getOutputRoleEntries(tool: Tool): Array<[RoleName, RoleValue]> {
+    return Object.entries(tool.roleSpec.outputRoleValueByName) as Array<[RoleName, RoleValue]>;
+}
+
+export function getInputRoleNames(tool: Tool): RoleName[] {
+    return getInputRoleEntries(tool).map(([roleName]) => roleName);
+}
+
+export function getOutputRoleNames(tool: Tool): RoleName[] {
+    return getOutputRoleEntries(tool).map(([roleName]) => roleName);
+}
+
+export function toToolRoleDescriptor([roleName, roleValue]: [RoleName, RoleValue]): ToolRoleDescriptor {
+    return {
+        id: roleName,
+        name: roleName,
+        ...roleValue,
+    };
+}
+
+export function extractToolStepsFromStrategy(strategy: Strategy): ToolStep[] {
+    const toolSteps: ToolStep[] = [];
+
+    const visitStep = (step: Step) => {
+        switch (step.stepKind) {
+            case 'tool': {
+                toolSteps.push(step);
+                return;
+            }
+            case 'branch': {
+                for (const conditional of step.cases) {
+                    toolSteps.push(conditional.when, conditional.what);
+                }
+                return;
+            }
+            case 'while':
+            case 'for': {
+                toolSteps.push(step.case.when, step.case.what);
+                return;
+            }
+            default: {
+                const _exhaustive: never = step;
+                return _exhaustive;
+            }
+        }
+    };
+
+    if ('steps' in strategy) {
+        for (const step of strategy.steps) {
+            visitStep(step);
+        }
+        return toolSteps;
+    }
+
+    for (const threadSteps of strategy.stepsByThreadIndex) {
+        for (const step of threadSteps) {
+            visitStep(step);
+        }
+    }
+
+    return toolSteps;
+}