@smol-workflows/sdk 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hbc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @smol-workflows/sdk
+
+Minimal TypeScript SDK package for smol-workflow.
+
+The SDK provides types for workflow scripts. Runtime values are injected by the workflow runner.
+
+## User script contract
+
+A workflow script is an ES module.
+
+It must export metadata as `export const meta = {...}`. Metadata must include `name` and `description` and may include `whenToUse` and phase metadata. The SDK separates Dynamic Workflow metadata fields from SDK/engine-specific extensions such as phase-level `provider` hints:
+
+```ts
+import type { WorkflowMetadata } from "@smol-workflows/sdk";
+
+export const meta = {
+  name: "stock-investment-analysis",
+  description: "Analyze stocks and synthesize an investment report",
+  whenToUse: "Use when the user wants a multi-agent stock analysis workflow",
+  phases: [
+    { title: "Analyze", detail: "Break the question into research dimensions" },
+    { title: "Research", detail: "Run research agents in parallel", provider: "claude-code" },
+    { title: "Synthesize", detail: "Create the final report", model: "opus", provider: "pi" },
+  ],
+} satisfies WorkflowMetadata;
+```
+
+It must default export either:
+
+1. the final workflow result — preferred
+2. a workflow function — supported
+
+## Preferred: top-level ESM workflow
+
+The preferred style is to write normal top-level ESM code and default export the final result:
+
+```ts
+phase("Analyze");
+log("args", args);
+
+const result = await agent("Do the work");
+
+export default result;
+```
+
+This style relies on globals injected by the runner before the module is imported.
+
+Top-level `await` is valid in ESM, but top-level `return` is not. Use `export default` for the final result:
+
+```ts
+const result = await agent("Do the work");
+export default result;
+```
+
+Do not write:
+
+```ts
+const result = await agent("Do the work");
+return result;
+```
+
+## Supported: default workflow function
+
+A workflow may also default export a function:
+
+```ts
+import type { WorkflowHandler } from "@smol-workflows/sdk";
+
+const workflow: WorkflowHandler = async (input, ctx) => {
+  ctx.phase("Analyze");
+  ctx.log("args", ctx.args);
+
+  return await ctx.agent("Do the work");
+};
+
+export default workflow;
+```
+
+Or using globals:
+
+```ts
+export default async function workflow() {
+  phase("Analyze");
+  log("args", args);
+
+  return await agent("Do the work");
+}
+```
+
+## Input
+
+Workflow input is provided as an untyped argument map:
+
+```ts
+type WorkflowArgs = Record<string, unknown>;
+```
+
+In the preferred top-level ESM style, input is available as the global `args`:
+
+```ts
+log("args", args);
+```
+
+In the function style, the same value is available in three places:
+
+```ts
+export default async function workflow(input, ctx) {
+  input;    // workflow args
+  ctx.args; // workflow args
+  args;     // global workflow args
+}
+```
+
+The runner should treat this value as read-only from the script side.
+
+## Output
+
+In the preferred top-level ESM style, the workflow output is the default export:
+
+```ts
+const output = {
+  summary: "Done",
+  items: [1, 2, 3],
+};
+
+export default output;
+```
+
+In the function style, the workflow output is the value returned by the default workflow function:
+
+```ts
+export default async function workflow() {
+  return {
+    summary: "Done",
+    items: [1, 2, 3],
+  };
+}
+```
+
+Recommended output shape is JSON-serializable data.
+
+If an agent call uses `schema`, the SDK can infer the TypeScript result type from a literal JSON Schema:
+
+```ts
+import type { JSONSchema } from "@smol-workflows/sdk";
+
+const schema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+  },
+  required: ["summary"],
+  additionalProperties: false,
+} as const satisfies JSONSchema;
+
+const result = await agent("Summarize", { schema });
+if (result) {
+  result.summary; // string
+}
+
+export default result;
+```
+
+## Workflow tool input
+
+External Workflow tool invocations can be typed with `WorkflowToolInput`:
+
+```ts
+import type { WorkflowToolInput } from "@smol-workflows/sdk";
+
+const input: WorkflowToolInput = {
+  scriptPath: "./workflow.js",
+  args: { item: "alpha" },
+};
+```
+
+When multiple workflow sources are provided, runners should prefer `scriptPath` over `script` and `name`.
+
+## Runtime globals
+
+The runner injects these globals:
+
+- `args` — untyped workflow args
+- `agent(prompt, options?)` — AI call primitive; returns `null` if the run is skipped
+- `parallel(tasks)` — run tasks concurrently with a barrier; thrown tasks resolve to `null`
+- `pipeline(items, ...stages)` — run each item through stages without barriers between stages
+- `workflow(nameOrRef, args?)` — run another workflow inline as a sub-step
+- `budget` — shared output-token budget with `total`, `spent()`, and `remaining()`
+- `log(...values)` — write workflow logs
+- `phase(name)` — mark workflow phase
+- `SW.extra.sleep(ms)` / `ctx.extra.sleep(ms)` / `import { sleep } from "workflow:extra"` — pause workflow execution
+
+## Scripts
+
+- `npm run build` - compile TypeScript to `dist/`
+- `npm run typecheck` - type-check without emitting files
+- `npm run clean` - remove build output

package/changelogs.md

@@ -0,0 +1,18 @@
+# Changelogs
+
+Track user-visible changes to `@smol-workflows/sdk`, especially public TypeScript types and workflow authoring APIs.
+
+## Unpublished
+
+No unpublished changes yet.
+
+## 0.1.0-alpha.0
+
+Initial SDK types for workflow authors.
+
+- Added workflow metadata types, including phase metadata and provider hints.
+- Added ambient global declarations for runtime-injected workflow APIs: `args`, `agent`, `parallel`, `pipeline`, `workflow`, `budget`, `log`, `phase`, and `SW`.
+- Added agent option types for `provider`, `model`, `schema`, `phase`, `label`, `isolation`, and `agentType`.
+- Added JSON Schema typing for structured agent outputs via `json-schema-to-ts`.
+- Added workflow handler/context types for function-style workflows.
+- Added `workflow:extra` virtual module declarations.

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import type { FromSchema } from "json-schema-to-ts";
+import type { JSONSchema } from "./json-schema.js";
+import type { PipelineFn } from "./pipeline.js";
+export type { JSONArray, JSONObject, JSONPrimitive, JSONSchema, JSONSchemaObject, JSONSchemaType, JSONValue, } from "./json-schema.js";
+export type { PipelineFn, PipelineStage } from "./pipeline.js";
+export type { WorkflowToolInput } from "./tool.js";
+/** A value that may be returned synchronously or asynchronously. */
+export type Awaitable<T> = T | Promise<T>;
+/** Untyped workflow arguments injected by the isolated workflow runner. */
+export type WorkflowArgs = Record<string, unknown>;
+/** Workflow phase metadata fields mirrored from the Dynamic Workflow reference. */
+export type DynamicWorkflowPhaseMetadata = {
+    /** Phase title. Must exactly match the corresponding `phase(...)` call. */
+    title: string;
+    /** Optional longer phase description. */
+    detail?: string;
+    /** Optional model hint for agent work in this phase. */
+    model?: string;
+};
+/** Workflow metadata fields mirrored from the Dynamic Workflow reference. */
+export type DynamicWorkflowMetadata = {
+    /** Stable workflow name or identifier. */
+    name: string;
+    /** Workflow description for display, tracing, and agent context. */
+    description: string;
+    /** Optional hint shown when listing or selecting workflows. */
+    whenToUse?: string;
+    /** Ordered list of phases the workflow may report with `phase(...)`. */
+    phases?: readonly DynamicWorkflowPhaseMetadata[];
+};
+/** Metadata describing a workflow phase for display, tracing, and agent context. */
+export type WorkflowPhaseMetadata = DynamicWorkflowPhaseMetadata & {
+    /** Optional provider hint for agent work in this phase. */
+    provider?: string;
+};
+/** Metadata exported by a workflow script as `meta`. */
+export type WorkflowMetadata = Omit<DynamicWorkflowMetadata, "phases"> & {
+    /** Ordered list of phases the workflow may report with `phase(...)`. */
+    phases?: readonly WorkflowPhaseMetadata[];
+};
+/** Writes a message to the workflow log. */
+export type WorkflowLogFn = (...args: unknown[]) => void;
+/** Reference to a workflow that can be run from another workflow. */
+export type WorkflowRef = string | {
+    scriptPath: string;
+};
+/** Runs another workflow inline as a sub-step. */
+export type WorkflowRunFn = <Output = unknown>(nameOrRef: WorkflowRef, args?: unknown) => Promise<Output>;
+/** Shared token budget exposed to workflow scripts. */
+export type WorkflowBudget = {
+    /** Target output-token budget, or `null` when no target was configured. */
+    total: number | null;
+    /** Output tokens spent across this workflow run and child workflows. */
+    spent(): number;
+    /** Remaining output-token budget, or `Infinity` when no target was configured. */
+    remaining(): number;
+};
+/** A unit of work passed to `parallel`. */
+export type ParallelTask<T = unknown> = () => Awaitable<T>;
+/** Preserves the tuple result types returned by a tuple of parallel tasks. */
+export type ParallelResults<Tasks extends readonly ParallelTask[]> = {
+    -readonly [Index in keyof Tasks]: Tasks[Index] extends ParallelTask<infer Result> ? Awaited<Result> | null : never;
+};
+/** Runs multiple tasks concurrently and returns their results in input order. Thrown tasks resolve to `null`. */
+export type ParallelFn = <const Tasks extends readonly ParallelTask[]>(tasks: Tasks) => Promise<ParallelResults<Tasks>>;
+/** Agent options mirrored from the Dynamic Workflow reference. */
+export type DynamicWorkflowAgentRunOptions<Schema extends JSONSchema = JSONSchema> = {
+    /** Optional display label for progress UIs and traces. */
+    label?: string;
+    /** Optional phase name used for tracing/grouping this agent run. */
+    phase?: string;
+    /** JSON Schema used to request and/or validate structured output. */
+    schema?: Schema;
+    /**
+     * Optional model override for this call.
+     *
+     * The accepted values are provider-specific. If omitted, the selected
+     * provider's default model is used.
+     */
+    model?: string;
+    /**
+     * Request a fresh git worktree for this agent run.
+     *
+     * The workflow engine creates the worktree from the workflow cwd's git
+     * repository using a temporary `smol-wf/agent-run/<id>` branch, passes that
+     * worktree as the provider cwd for this call, then removes it after the call.
+     */
+    isolation?: "worktree";
+    /** Optional provider-specific subagent/agent type, such as `Explore` or `code-reviewer`. */
+    agentType?: string;
+};
+/** Options for a single agent run supported by this SDK. */
+export type AgentRunOptions<Schema extends JSONSchema = JSONSchema> = DynamicWorkflowAgentRunOptions<Schema> & {
+    /**
+     * Optional agent provider override for this call.
+     *
+     * If omitted, the runner's default provider is used. Runners may support
+     * built-in provider names such as `debug`, `claude-code`, `codex`,
+     * `opencode`, or `pi`, and may also register custom provider names.
+     */
+    provider?: string;
+};
+/** An AI capability exposed to workflow scripts. */
+export type Agent = {
+    /** Runs the agent with a prompt and returns text output by default, or `null` if skipped. */
+    run(prompt: string): Promise<string | null>;
+    /** Runs the agent and infers structured output from the provided JSON Schema, or returns `null` if skipped. */
+    run<const Schema extends JSONSchema>(prompt: string, options: AgentRunOptions<Schema> & {
+        schema: Schema;
+    }): Promise<FromSchema<Schema> | null>;
+    /** Runs the agent with optional per-call options and an explicit output type, or returns `null` if skipped. */
+    run<Output = string>(prompt: string, options?: AgentRunOptions): Promise<Output | null>;
+};
+/** The global agent helper exposed to workflow scripts. */
+export type AgentRunFn = Agent["run"];
+/** Marks the current workflow phase for tracing and observability. */
+export type PhaseFn = (name: string) => void;
+/** Runtime helpers that are not part of the base workflow API. */
+export type WorkflowExtra = {
+    /** Pause workflow execution for at least `ms` milliseconds. */
+    sleep(ms: number): Promise<void>;
+};
+/** smol-workflows runtime namespace exposed to workflow scripts. */
+export type WorkflowRuntimeNamespace = {
+    extra: WorkflowExtra;
+};
+/** Explicit workflow capabilities passed as the second argument to a workflow. */
+export type WorkflowContext = {
+    args: WorkflowArgs;
+    agent: AgentRunFn;
+    parallel: ParallelFn;
+    pipeline: PipelineFn;
+    workflow: WorkflowRunFn;
+    budget: WorkflowBudget;
+    log: WorkflowLogFn;
+    phase: PhaseFn;
+    extra: WorkflowExtra;
+};
+/** The default export shape expected from a workflow script. */
+export type WorkflowHandler<Input = unknown, Output = unknown> = (input: Input, ctx: WorkflowContext) => Awaitable<Output>;
+declare module "workflow:extra" {
+    export const sleep: WorkflowExtra["sleep"];
+    const extra: WorkflowExtra;
+    export default extra;
+}
+declare global {
+    /** Global workflow arguments injected by the isolated workflow runner. */
+    var args: WorkflowArgs;
+    /** Global agent run helper injected by the isolated workflow runner. */
+    var agent: AgentRunFn;
+    /** Global parallel helper injected by the isolated workflow runner. */
+    var parallel: ParallelFn;
+    /** Global pipeline helper injected by the isolated workflow runner. */
+    var pipeline: PipelineFn;
+    /** Global child workflow helper injected by the isolated workflow runner. */
+    var workflow: WorkflowRunFn;
+    /** Global token budget helper injected by the isolated workflow runner. */
+    var budget: WorkflowBudget;
+    /** Global logger injected by the isolated workflow runner. */
+    var log: WorkflowLogFn;
+    /** Global phase helper injected by the isolated workflow runner. */
+    var phase: PhaseFn;
+    /** smol-workflows runtime namespace. */
+    var SW: WorkflowRuntimeNamespace;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/json-schema.d.ts

@@ -0,0 +1,68 @@
+/** A primitive JSON value. */
+export type JSONPrimitive = string | number | boolean | null;
+/** Any value that can be represented in JSON. */
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
+/** A JSON object with string keys and JSON-compatible values. */
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+/** A JSON array containing JSON-compatible values. */
+export type JSONArray = JSONValue[];
+/** Valid values for the JSON Schema `type` keyword. */
+export type JSONSchemaType = "null" | "boolean" | "object" | "array" | "number" | "integer" | "string";
+/**
+ * A JSON Schema document or subschema.
+ *
+ * Boolean schemas are supported: `true` accepts anything, `false` rejects everything.
+ */
+export type JSONSchema = boolean | JSONSchemaObject;
+/**
+ * A JSON Schema object using common JSON Schema keywords.
+ *
+ * This is intended for SDK typing and editor help, not as a complete validator.
+ */
+export type JSONSchemaObject = {
+    $id?: string;
+    $schema?: string;
+    $ref?: string;
+    $defs?: Record<string, JSONSchema>;
+    definitions?: Record<string, JSONSchema>;
+    title?: string;
+    description?: string;
+    default?: JSONValue;
+    examples?: readonly JSONValue[];
+    type?: JSONSchemaType | readonly JSONSchemaType[];
+    enum?: readonly JSONValue[];
+    const?: JSONValue;
+    properties?: Record<string, JSONSchema>;
+    patternProperties?: Record<string, JSONSchema>;
+    additionalProperties?: JSONSchema;
+    required?: readonly string[];
+    propertyNames?: JSONSchema;
+    minProperties?: number;
+    maxProperties?: number;
+    items?: JSONSchema | readonly JSONSchema[];
+    prefixItems?: readonly JSONSchema[];
+    additionalItems?: JSONSchema;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    allOf?: readonly JSONSchema[];
+    anyOf?: readonly JSONSchema[];
+    oneOf?: readonly JSONSchema[];
+    not?: JSONSchema;
+    if?: JSONSchema;
+    then?: JSONSchema;
+    else?: JSONSchema;
+    dependentSchemas?: Record<string, JSONSchema>;
+};
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"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"}

package/dist/json-schema.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=json-schema.js.map

package/dist/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":""}

package/dist/pipeline.d.ts

@@ -0,0 +1,21 @@
+/** A value that may be returned synchronously or asynchronously. */
+export type Awaitable<T> = T | Promise<T>;
+/** A stage in a `pipeline` call. */
+export type PipelineStage<Previous = unknown, Item = unknown, Result = unknown> = (previous: Previous, item: Item, index: number) => Awaitable<Result>;
+/**
+ * Runs items through sequential stages without a barrier between stages.
+ *
+ * Each item advances to its next stage as soon as that item is ready. If a stage
+ * throws for an item, that item resolves to `null` and remaining stages are skipped.
+ */
+export type PipelineFn = {
+    <Item>(items: readonly Item[]): Promise<Item[]>;
+    <Item, Stage1>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>): Promise<Array<Awaited<Stage1> | null>>;
+    <Item, Stage1, Stage2>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>, stage2: PipelineStage<Awaited<Stage1>, Item, Stage2>): Promise<Array<Awaited<Stage2> | null>>;
+    <Item, Stage1, Stage2, Stage3>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>, stage2: PipelineStage<Awaited<Stage1>, Item, Stage2>, stage3: PipelineStage<Awaited<Stage2>, Item, Stage3>): Promise<Array<Awaited<Stage3> | null>>;
+    <Item, Stage1, Stage2, Stage3, Stage4>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>, stage2: PipelineStage<Awaited<Stage1>, Item, Stage2>, stage3: PipelineStage<Awaited<Stage2>, Item, Stage3>, stage4: PipelineStage<Awaited<Stage3>, Item, Stage4>): Promise<Array<Awaited<Stage4> | null>>;
+    <Item, Stage1, Stage2, Stage3, Stage4, Stage5>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>, stage2: PipelineStage<Awaited<Stage1>, Item, Stage2>, stage3: PipelineStage<Awaited<Stage2>, Item, Stage3>, stage4: PipelineStage<Awaited<Stage3>, Item, Stage4>, stage5: PipelineStage<Awaited<Stage4>, Item, Stage5>): Promise<Array<Awaited<Stage5> | null>>;
+    <Item, Stage1, Stage2, Stage3, Stage4, Stage5, Stage6>(items: readonly Item[], stage1: PipelineStage<Item, Item, Stage1>, stage2: PipelineStage<Awaited<Stage1>, Item, Stage2>, stage3: PipelineStage<Awaited<Stage2>, Item, Stage3>, stage4: PipelineStage<Awaited<Stage3>, Item, Stage4>, stage5: PipelineStage<Awaited<Stage4>, Item, Stage5>, stage6: PipelineStage<Awaited<Stage5>, Item, Stage6>): Promise<Array<Awaited<Stage6> | null>>;
+    <Item, Result = unknown>(items: readonly Item[], ...stages: readonly PipelineStage<unknown, Item, unknown>[]): Promise<Array<Result | null>>;
+};
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":""}

package/dist/tool.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parameters accepted by an external Workflow tool invocation.
+ *
+ * This mirrors the Dynamic Workflow reference. When multiple workflow sources are
+ * provided, runners should prefer `scriptPath` over `script` and `name`.
+ */
+export type WorkflowToolInput = {
+    /** Inline workflow script source. */
+    script?: string;
+    /** Path to a workflow script file on disk. Takes precedence over `script` and `name`. */
+    scriptPath?: string;
+    /** Name of a saved workflow, typically resolved from `.claude/workflows/`. */
+    name?: string;
+    /** Value passed to the workflow as its `args` global. */
+    args?: unknown;
+    /** Prior workflow run ID to resume from, when supported by the runner. */
+    resumeFromRunId?: string;
+};
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC"}

package/dist/tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":""}

package/dist/workflow-extra.d.ts

@@ -0,0 +1,5 @@
+declare module "workflow:extra" {
+    const sleep: import("./index.js").WorkflowExtra["sleep"];
+}
+export {};
+//# sourceMappingURL=workflow-extra.d.ts.map

package/dist/workflow-extra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-extra.d.ts","sourceRoot":"","sources":["../src/workflow-extra.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,gBAAgB,CAAC;IACvB,MAAM,KAAK,EAAE,OAAO,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACjE"}

package/dist/workflow-extra.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow-extra.js.map

package/dist/workflow-extra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-extra.js","sourceRoot":"","sources":["../src/workflow-extra.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@smol-workflows/sdk",
+  "version": "0.1.0-alpha.0",
+  "description": "TypeScript SDK and workflow runtime types for smol-workflow.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "changelogs.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "json-schema-to-ts": "3.1.1"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  }
+}