@hasna/loops 0.3.5 → 0.3.7

package/dist/lib/executor.d.ts

@@ -18,6 +18,9 @@ export interface ExecutionMetadata {
     workflowName?: string;
     workflowRunId?: string;
     workflowStepId?: string;
+    goalId?: string;
+    goalObjective?: string;
+    goalNodeKey?: string;
 }
 export interface PreflightResult {
     command: string;

package/dist/lib/format.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutorResult, Loop, LoopRun, WorkflowEvent, WorkflowRun, WorkflowSpec, WorkflowStepRun } from "../types.js";
+import type { ExecutorResult, Goal, GoalRun, Loop, LoopRun, WorkflowEvent, WorkflowRun, WorkflowSpec, WorkflowStepRun } from "../types.js";
 export declare function redact(value: string | undefined, visible?: number): string | undefined;
 export declare function textOutputBlocks(value: Pick<LoopRun | WorkflowStepRun, "stdout" | "stderr">, opts?: {
     indent?: string;
@@ -10,3 +10,5 @@ export declare function publicWorkflow(workflow: WorkflowSpec): Record<string, u
 export declare function publicWorkflowRun(run: WorkflowRun): Record<string, unknown>;
 export declare function publicWorkflowStepRun(run: WorkflowStepRun, showOutput?: boolean): Record<string, unknown>;
 export declare function publicWorkflowEvent(event: WorkflowEvent): Record<string, unknown>;
+export declare function publicGoal(goal: Goal): Record<string, unknown>;
+export declare function publicGoalRun(run: GoalRun): Record<string, unknown>;

package/dist/lib/goal/model-factory.d.ts

@@ -0,0 +1,9 @@
+import type { LanguageModel } from "ai";
+export interface ResolveGoalModelOptions {
+    model?: string;
+    baseURL?: string;
+    apiKey?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const DEFAULT_GOAL_MODEL = "openai/gpt-4o-mini";
+export declare function resolveGoalModel(opts?: ResolveGoalModelOptions): LanguageModel;

package/dist/lib/goal/prompts.d.ts

@@ -0,0 +1,4 @@
+import type { Goal, GoalPlanNode, GoalSpec } from "./types.js";
+export declare function planPrompt(spec: GoalSpec): string;
+export declare function iterationPrompt(goal: Goal, readyNodes: GoalPlanNode[]): string;
+export declare function achievementPrompt(goal: Goal, nodes: GoalPlanNode[], evidence: string[]): string;

package/dist/lib/goal/runner.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from "../store.js";
+import type { GoalExecutorResult, GoalSpec, RunGoalOptions } from "./types.js";
+export declare function runGoal(store: Store, input: GoalSpec, opts?: RunGoalOptions): Promise<GoalExecutorResult>;

package/dist/lib/goal/status.d.ts

@@ -0,0 +1,9 @@
+import type { GoalPlan, GoalPlanNode, GoalPlanNodeStatus, GoalRollup, GoalStatus } from "./types.js";
+export declare function isTerminal(status: GoalStatus): boolean;
+export declare function nodeBudgetExhausted(node: GoalPlanNode): boolean;
+export declare function readyNodeKeys(plan: Pick<GoalPlan, "status" | "nodes">): string[];
+export declare function rollupSummary(nodes: Pick<GoalPlanNode, "status">[]): GoalRollup;
+export declare function assertGoalTransition(from: GoalStatus, to: GoalStatus): void;
+export declare function assertAcyclicNodes(nodes: Pick<GoalPlanNode, "key" | "dependsOn">[]): void;
+export declare function updateReadyFlags(nodes: GoalPlanNode[], planStatus: GoalPlan["status"]): GoalPlanNode[];
+export declare function normalizeNodeStatus(status: string): GoalPlanNodeStatus;

package/dist/lib/goal/types.d.ts

@@ -0,0 +1,120 @@
+import type { LanguageModel } from "ai";
+import type { ExecutableTarget, ExecutorResult } from "../../types.js";
+import type { Store } from "../store.js";
+export type GoalStatus = "active" | "paused" | "blocked" | "usageLimited" | "budgetLimited" | "complete" | "cancelled";
+export type GoalPlanNodeStatus = "pending" | GoalStatus;
+export type GoalPlanStatus = "active" | "paused" | "blocked" | "budgetLimited" | "complete" | "cancelled";
+export type GoalAutoExecute = "off" | "readyOnly" | "aiDirected";
+export declare const GOAL_TERMINAL: readonly ["budgetLimited", "complete", "cancelled"];
+export declare const GOAL_OBJECTIVE_MAX_CHARS = 4000;
+export interface GoalSpec {
+    objective: string;
+    tokenBudget?: number;
+    model?: string;
+    maxTurns?: number;
+    maxTokens?: number;
+    autoExecute?: GoalAutoExecute;
+}
+export interface Goal {
+    goalId: string;
+    planId: string;
+    objective: string;
+    status: GoalStatus;
+    tokenBudget?: number;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    createdAt: string;
+    updatedAt: string;
+    autoExecute: GoalAutoExecute;
+    maxTokens?: number;
+    sourceType?: string;
+    sourceId?: string;
+    loopId?: string;
+    loopRunId?: string;
+    workflowId?: string;
+    workflowRunId?: string;
+    workflowStepId?: string;
+}
+export interface GoalRollup {
+    total: number;
+    pending: number;
+    active: number;
+    paused: number;
+    blocked: number;
+    usageLimited: number;
+    budgetLimited: number;
+    complete: number;
+    cancelled: number;
+}
+export interface GoalPlanNode {
+    nodeId: string;
+    planId: string;
+    key: string;
+    sequence: number;
+    priority: number;
+    objective: string;
+    status: GoalPlanNodeStatus;
+    ready: boolean;
+    tokenBudget?: number;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    dependsOn: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalPlan {
+    planId: string;
+    goalId: string;
+    status: GoalPlanStatus;
+    autoExecute: GoalAutoExecute;
+    maxTokens?: number;
+    rollup: GoalRollup;
+    nodes: GoalPlanNode[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalRun {
+    runId: string;
+    goalId: string;
+    planId: string;
+    loopId?: string;
+    loopRunId?: string;
+    workflowId?: string;
+    workflowRunId?: string;
+    workflowStepId?: string;
+    turn: number;
+    phase: "plan" | "execute" | "validate" | "status";
+    status: GoalStatus | GoalPlanNodeStatus;
+    nodeKey?: string;
+    tokensUsed: number;
+    evidence?: Record<string, unknown>;
+    rawResponse?: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalExecutionContext {
+    loopId?: string;
+    loopName?: string;
+    loopRunId?: string;
+    scheduledFor?: string;
+    workflowId?: string;
+    workflowName?: string;
+    workflowRunId?: string;
+    workflowStepId?: string;
+}
+export interface RunGoalOptions {
+    store?: Store;
+    model?: LanguageModel;
+    target?: ExecutableTarget;
+    executeNode?: (node: GoalPlanNode, metadata: Record<string, string | undefined>) => Promise<ExecutorResult>;
+    env?: NodeJS.ProcessEnv;
+    daemonLeaseId?: string;
+    beforePersist?: () => void;
+    signal?: AbortSignal;
+    cancelPollMs?: number;
+    context?: GoalExecutionContext;
+}
+export interface GoalExecutorResult extends ExecutorResult {
+    goalId?: string;
+    goalRunId?: string;
+}

package/dist/lib/store.d.ts

@@ -1,4 +1,4 @@
-import type { CreateLoopInput, CreateWorkflowInput, Loop, LoopRun, LoopStatus, RunStatus, WorkflowEvent, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun } from "../types.js";
+import type { CreateLoopInput, CreateWorkflowInput, Goal, GoalAutoExecute, GoalPlanNode, GoalRun, GoalStatus, Loop, LoopRun, LoopStatus, RunStatus, WorkflowEvent, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun } from "../types.js";
 interface DaemonLeaseFence {
     daemonLeaseId?: string;
     now?: Date;
@@ -24,6 +24,36 @@ export interface CreateWorkflowRunInput {
     idempotencyKey?: string;
     daemonLeaseId?: string;
 }
+export interface CreateGoalInput {
+    objective: string;
+    tokenBudget?: number;
+    autoExecute?: GoalAutoExecute;
+    maxTokens?: number;
+    sourceType?: string;
+    sourceId?: string;
+    loopId?: string;
+    loopRunId?: string;
+    workflowId?: string;
+    workflowRunId?: string;
+    workflowStepId?: string;
+}
+export interface CreateGoalPlanNodeInput {
+    key: string;
+    objective: string;
+    dependsOn?: string[];
+    priority?: number;
+    tokenBudget?: number;
+}
+export interface RecordGoalEventInput {
+    goalId: string;
+    turn?: number;
+    phase: GoalRun["phase"];
+    status: GoalRun["status"];
+    nodeKey?: string;
+    tokensUsed?: number;
+    evidence?: Record<string, unknown>;
+    rawResponse?: unknown;
+}
 export declare class Store {
     private db;
     constructor(path?: string);
@@ -49,6 +79,33 @@ export declare class Store {
         limit?: number;
     }): WorkflowSpec[];
     archiveWorkflow(idOrName: string): WorkflowSpec;
+    createGoal(input: CreateGoalInput, opts?: DaemonLeaseFence): Goal;
+    getGoal(id: string): Goal | undefined;
+    requireGoal(id: string): Goal;
+    findGoalByLoop(idOrName: string): Goal | undefined;
+    findGoalByRunId(id: string): Goal | undefined;
+    findGoalByContext(context: {
+        loopRunId?: string;
+        workflowRunId?: string;
+        workflowStepId?: string;
+        sourceType?: string;
+        sourceId?: string;
+    }): Goal | undefined;
+    listGoals(opts?: {
+        status?: GoalStatus;
+        limit?: number;
+    }): Goal[];
+    createGoalPlanNodes(goalId: string, nodes: CreateGoalPlanNodeInput[], opts?: DaemonLeaseFence): GoalPlanNode[];
+    listGoalPlanNodes(goalIdOrPlanId: string): GoalPlanNode[];
+    updateGoalStatus(goalId: string, status: GoalStatus, opts?: DaemonLeaseFence): Goal;
+    addGoalUsage(goalId: string, tokens: number, timeUsedSeconds?: number, opts?: DaemonLeaseFence): Goal;
+    updateGoalPlanNode(goalId: string, key: string, patch: Partial<Pick<GoalPlanNode, "status" | "tokensUsed" | "timeUsedSeconds" | "ready">>, opts?: DaemonLeaseFence): GoalPlanNode;
+    recordGoalEvent(input: RecordGoalEventInput, opts?: DaemonLeaseFence): GoalRun;
+    listGoalRuns(opts?: {
+        goalId?: string;
+        runId?: string;
+        limit?: number;
+    }): GoalRun[];
     createWorkflowRun(input: CreateWorkflowRunInput): WorkflowRun;
     getWorkflowRun(id: string): WorkflowRun | undefined;
     requireWorkflowRun(id: string): WorkflowRun;