@trailstep/core 0.1.0 → 0.1.1

package/README.md

@@ -2,14 +2,34 @@
 
 `@trailstep/core` is the framework-neutral runtime package for TrailStep.
 
+Most workflow authors should start with [`@trailstep/authoring`](../authoring/README.md), which re-exports common authoring helpers and adds `defineWorkflow(...)`.
+
 ## Install
 
 ```bash
-pnpm add @trailstep/core
+npm install @trailstep/core
 ```
 
+Use the equivalent command for your package manager if you use `pnpm`, `yarn`, or `bun`.
+
 ## Public role
 
-Use this package for JSON object input/output validation, `runWorkflow`, continuation runtime primitives, events, retry state, and local run artifact handling.
+Use this package for low-level TrailStep runtime integration:
+
+- JSON-object input/output validation
+- continuation runtime primitives
+- `runWorkflow`
+- workflow events
+- retry state
+- provider contracts
+- local run artifact handling
+
+TrailStep's key runtime boundary is the step: each step can run as a focused unit of work, receive structured output, persist events, and return the next continuation.
+
+Runtime events are appended to `.trailstep/runs/<runName>/events.jsonl` by default. Set `TRAILSTEP_RUNS_ROOT` in CLI runs when you need artifacts somewhere else. Run directories are generated outputs for inspection and replay; do not manually edit them to recover workflow state.
+
+## More docs
 
-Runtime events are appended to `.trailstep/runs/<runName>/events.jsonl`. Run directories are generated outputs for inspection and replay; do not manually edit them to recover workflow state.
+- [Architecture](../../docs/architecture.md)
+- [Authoring workflows](../../docs/authoring-workflows.md)
+- [CLI reference](../../docs/cli-reference.md)

package/dist/index.d.ts

@@ -40,10 +40,26 @@ interface ResolveTimeoutPolicyOptions {
 declare function resolveTimeoutPolicy(options: ResolveTimeoutPolicyOptions): TimeoutPolicy;
 declare function validateTimeoutPolicy(input: unknown): TimeoutPolicy;
 
+type TrailStepCustomProviderModelOverrideSupport = {
+    readonly supported: true;
+    readonly flag?: string;
+} | {
+    readonly supported: false;
+};
+type TrailStepCustomProviderThinkingOverrideSupport = {
+    readonly supported: true;
+    readonly flag?: string;
+    readonly levels: readonly WorkflowAgentThinking[];
+} | {
+    readonly supported: false;
+    readonly levels?: readonly [];
+};
 interface TrailStepCustomProviderConfig {
     readonly binary: string;
     readonly args?: readonly string[];
     readonly interactiveArgs?: readonly string[];
+    readonly model?: TrailStepCustomProviderModelOverrideSupport;
+    readonly thinking?: TrailStepCustomProviderThinkingOverrideSupport;
     readonly cwd?: string;
     readonly env?: Readonly<Record<string, string>>;
 }
@@ -517,6 +533,73 @@ interface ProviderWorkingProcessResult {
  * `stdin` is set. Injectable for tests.
  */
 type ProviderWorkingRunner = (request: ProviderWorkingProcessRequest) => ProviderWorkingProcessResult | Promise<ProviderWorkingProcessResult>;
+type ProviderPromptFileReferenceStyle = "at-prefixed-argument";
+type ProviderPromptInputSpec = {
+    readonly kind: "prompt-file";
+    readonly reference: ProviderPromptFileReferenceStyle;
+} | {
+    readonly kind: "inline-prompt";
+};
+type ProviderOutputStyle = "stdout-json-envelope" | "stdout-jsonl-transcript" | "provider-output-file";
+interface ProviderOutputParsingMetadata {
+    readonly resultField?: string;
+}
+interface ProviderOutputSpec {
+    readonly style: ProviderOutputStyle;
+    readonly parsing?: ProviderOutputParsingMetadata;
+}
+type ProviderModelDiscoveryOutputParser = "pi-list-models-table";
+interface ProviderModelDiscoverySpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly outputParser: ProviderModelDiscoveryOutputParser;
+}
+type ProviderModelOverrideSupport = {
+    readonly supported: true;
+    readonly flag: string;
+    readonly discovery?: ProviderModelDiscoverySpec;
+} | {
+    readonly supported: false;
+};
+type ProviderThinkingOverrideSupport = {
+    readonly supported: true;
+    readonly flag: string;
+    readonly levels: readonly WorkflowAgentThinking[];
+} | {
+    readonly supported: false;
+    readonly levels?: readonly [];
+};
+interface ProviderWorkingRepairInvocationSpec {
+    readonly supported: boolean;
+    readonly resumeFlag?: string;
+    readonly promptDelivery?: "stdin" | "prompt-file";
+}
+interface ProviderWorkingInvocationSpec {
+    readonly command: string;
+    readonly prompt: ProviderPromptInputSpec;
+    readonly baseArgs: readonly string[];
+    readonly output: ProviderOutputSpec;
+    readonly repair?: ProviderWorkingRepairInvocationSpec;
+}
+type ProviderInteractiveInvocationSpec = {
+    readonly supported: true;
+    readonly command: string;
+    readonly requiresSystemPromptFile?: boolean;
+    readonly systemPromptFileFlag?: string;
+    readonly modelFlag?: string;
+    readonly permissionBypassFlag?: string;
+} | {
+    readonly supported: false;
+    readonly reason?: string;
+};
+interface ProviderSpec {
+    readonly id: string;
+    readonly displayName: string;
+    readonly model: ProviderModelOverrideSupport;
+    readonly thinking: ProviderThinkingOverrideSupport;
+    readonly working: ProviderWorkingInvocationSpec;
+    readonly interactive: ProviderInteractiveInvocationSpec;
+}
 /** Request shape for a built-in provider's interactive (human-in-the-loop) invocation. */
 interface ProviderInteractiveRequest {
     readonly prompt: string;
@@ -558,6 +641,7 @@ interface ProviderWorkingRepairRequest {
  */
 interface ProviderAdapter {
     readonly id: string;
+    readonly spec: ProviderSpec;
     /** Non-interactive invocation: writes `request.outputFile` itself before resolving. */
     runWorking(request: ProviderWorkingRequest, runner?: ProviderWorkingRunner): Promise<void>;
     /**
@@ -626,4 +710,4 @@ declare function selectRecentFailedRunSummaries(summaries: readonly RunSummary[]
 }): RunSummary[];
 declare function newestFirst(left: RunSummary, right: RunSummary): number;
 
-export { type AgentAdapter, type AgentAdapterObject, type AgentAdapterRequest, type AgentAdapterSelection, type AgentMessage, type AgentModelTarget, type AgentPrompt, type AgentTool, type ContinuationResult, type ContinuationStepConfig, type DeprecationEntry, type DeprecationManifest, type DeprecationStatus, type DeprecationTargetPackage, Document, type DoneNode, type Event, type FailNode, type Failure, type FindDeprecationsAsOfQuery, type InteractiveProcessRequest, type InteractiveProcessResult, type InteractiveProcessRunner, type JsonSchemaObject, type LatestUnresolvedFailure, type PlainObject, type PromptOptions, type PromptTemplateSource, type ProviderAdapter, type ProviderInteractiveRequest, type ProviderRegistryKey, type ProviderWorkingProcessRequest, type ProviderWorkingProcessResult, type ProviderWorkingRequest, type ProviderWorkingRunner, type ResolveAgentTargetsOptions, type ResolveRetryPolicyOptions, type ResolveTimeoutPolicyOptions, type Result, type RetryPolicy, type RetryPolicyInput, type RunSummary, type RunSummaryStatus, type RunWorkflowOptions, type Schema, type ShapeInput, type ShapeObject, type ShapePrimitive, type StepConfig, type StepContinuation, type StepErrorContinuation, type StepFactory, type StepNode, type SubPromptFactory, type SubPromptOptions, type TimeoutPolicy, type TimeoutPolicyInput, type TrailStepAgentMappings, type TrailStepAgentTarget, type TrailStepConfig, type TrailStepCustomProviderConfig, TrailStepFailureError, type TrailStepSettings, type TrailStepWorkflowConfig, type Workflow, type WorkflowAgentRole, type WorkflowAgentSize, type WorkflowAgentThinking, type WorkingAgentProcessRequest, type WorkingAgentProcessResult, type WorkingAgentProcessRunner, defaultRunsRoot, deprecationManifest, document, done, fail, findDeprecationsAsOf, isDoneNode, isFailNode, isStepNode, jsonSchema, list, listRunSummaries, loadFragments, newestFirst, normalizeShape, parseTrailStepConfig, promptSections, promptTemplate, providerRegistry, readRunEvents, readRunState, resolveAgentTargets, resolveRetryPolicy, resolveTimeoutPolicy, runWorkflow, section, selectLatestUnresolvedFailure, selectRecentFailedRunSummaries, shape, state, step, subPrompt, validateRetryPolicy, validateTimeoutPolicy, writeRunState };
+export { type AgentAdapter, type AgentAdapterObject, type AgentAdapterRequest, type AgentAdapterSelection, type AgentMessage, type AgentModelTarget, type AgentPrompt, type AgentTool, type ContinuationResult, type ContinuationStepConfig, type DeprecationEntry, type DeprecationManifest, type DeprecationStatus, type DeprecationTargetPackage, Document, type DoneNode, type Event, type FailNode, type Failure, type FindDeprecationsAsOfQuery, type InteractiveProcessRequest, type InteractiveProcessResult, type InteractiveProcessRunner, type JsonSchemaObject, type LatestUnresolvedFailure, type PlainObject, type PromptOptions, type PromptTemplateSource, type ProviderAdapter, type ProviderInteractiveInvocationSpec, type ProviderInteractiveRequest, type ProviderModelDiscoveryOutputParser, type ProviderModelDiscoverySpec, type ProviderModelOverrideSupport, type ProviderOutputParsingMetadata, type ProviderOutputSpec, type ProviderOutputStyle, type ProviderPromptFileReferenceStyle, type ProviderPromptInputSpec, type ProviderRegistryKey, type ProviderSpec, type ProviderThinkingOverrideSupport, type ProviderWorkingInvocationSpec, type ProviderWorkingProcessRequest, type ProviderWorkingProcessResult, type ProviderWorkingRepairInvocationSpec, type ProviderWorkingRequest, type ProviderWorkingRunner, type ResolveAgentTargetsOptions, type ResolveRetryPolicyOptions, type ResolveTimeoutPolicyOptions, type Result, type RetryPolicy, type RetryPolicyInput, type RunSummary, type RunSummaryStatus, type RunWorkflowOptions, type Schema, type ShapeInput, type ShapeObject, type ShapePrimitive, type StepConfig, type StepContinuation, type StepErrorContinuation, type StepFactory, type StepNode, type SubPromptFactory, type SubPromptOptions, type TimeoutPolicy, type TimeoutPolicyInput, type TrailStepAgentMappings, type TrailStepAgentTarget, type TrailStepConfig, type TrailStepCustomProviderConfig, type TrailStepCustomProviderModelOverrideSupport, type TrailStepCustomProviderThinkingOverrideSupport, TrailStepFailureError, type TrailStepSettings, type TrailStepWorkflowConfig, type Workflow, type WorkflowAgentRole, type WorkflowAgentSize, type WorkflowAgentThinking, type WorkingAgentProcessRequest, type WorkingAgentProcessResult, type WorkingAgentProcessRunner, defaultRunsRoot, deprecationManifest, document, done, fail, findDeprecationsAsOf, isDoneNode, isFailNode, isStepNode, jsonSchema, list, listRunSummaries, loadFragments, newestFirst, normalizeShape, parseTrailStepConfig, promptSections, promptTemplate, providerRegistry, readRunEvents, readRunState, resolveAgentTargets, resolveRetryPolicy, resolveTimeoutPolicy, runWorkflow, section, selectLatestUnresolvedFailure, selectRecentFailedRunSummaries, shape, state, step, subPrompt, validateRetryPolicy, validateTimeoutPolicy, writeRunState };