@hasna/loops 0.3.5 → 0.3.7

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { GoalSpec } from "./lib/goal/types.js";
+export type { Goal, GoalAutoExecute, GoalExecutorResult, GoalPlan, GoalPlanNode, GoalPlanNodeStatus, GoalPlanStatus, GoalRollup, GoalRun, GoalSpec, GoalStatus, } from "./lib/goal/types.js";
 export type LoopStatus = "active" | "paused" | "stopped" | "expired";
 export type RunStatus = "running" | "succeeded" | "failed" | "timed_out" | "abandoned" | "skipped";
 export type CatchUpPolicy = "none" | "latest" | "all";
@@ -79,6 +81,7 @@ export interface WorkflowStep {
     name?: string;
     description?: string;
     target: ExecutableTarget;
+    goal?: GoalSpec;
     dependsOn?: string[];
     continueOnFailure?: boolean;
     timeoutMs?: number;
@@ -90,6 +93,7 @@ export interface WorkflowSpec {
     description?: string;
     version: number;
     status: WorkflowStatus;
+    goal?: GoalSpec;
     steps: WorkflowStep[];
     createdAt: string;
     updatedAt: string;
@@ -97,6 +101,7 @@ export interface WorkflowSpec {
 export interface CreateWorkflowInput {
     name: string;
     description?: string;
+    goal?: GoalSpec;
     steps: WorkflowStep[];
     version?: number;
 }
@@ -108,6 +113,7 @@ export interface WorkflowRun {
     loopRunId?: string;
     scheduledFor?: string;
     idempotencyKey?: string;
+    goalRunId?: string;
     status: WorkflowRunStatus;
     startedAt?: string;
     finishedAt?: string;
@@ -132,6 +138,7 @@ export interface WorkflowStepRun {
     error?: string;
     accountProfile?: string;
     accountTool?: string;
+    goalRunId?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -151,6 +158,7 @@ export interface Loop {
     status: LoopStatus;
     schedule: ScheduleSpec;
     target: LoopTarget;
+    goal?: GoalSpec;
     machine?: LoopMachineRef;
     nextRunAt?: string;
     retryScheduledFor?: string;
@@ -181,6 +189,7 @@ export interface LoopRun {
     stdout?: string;
     stderr?: string;
     error?: string;
+    goalRunId?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -189,6 +198,7 @@ export interface CreateLoopInput {
     description?: string;
     schedule: ScheduleSpec;
     target: LoopTarget;
+    goal?: GoalSpec;
     machine?: LoopMachineRef;
     catchUp?: CatchUpPolicy;
     catchUpLimit?: number;

package/docs/TRANSCRIPT_LOOP_PATTERNS.md

@@ -0,0 +1,95 @@
+# Transcript-Driven Loop Patterns
+
+This guide turns long-form transcripts, meeting recordings, interviews, and product feedback videos into durable OpenLoops work. It pairs `iapp-transcriber` for media ingestion with OpenLoops workflows for recurring review, implementation, and verification.
+
+The pattern came from reviewing a Claude Code fireside chat transcript. The useful operational takeaway was not just "use agents more"; it was that recurring agents need narrow scope, evidence, review gates, and clear ROI. In OpenLoops terms, that means using workflows and goals to move from transcript insight to scheduled loop safely.
+
+## Baseline Workflow
+
+Start with the checked-in workflow template. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
+
+```bash
+mkdir -p /path/to/repo/.openloops
+cp /path/to/open-loops/docs/workflows/transcript-feedback-to-loops.json /path/to/repo/.openloops/transcript-feedback-to-loops.json
+loops workflows validate /path/to/repo/.openloops/transcript-feedback-to-loops.json --preflight
+loops workflows create /path/to/repo/.openloops/transcript-feedback-to-loops.json
+loops workflows run transcript-feedback-to-loops --show-output
+```
+
+The transcribe step writes `.openloops/transcripts/latest-transcript.json`. The transcript path is fixed so later agent steps read the same artifact the command step produced. Edit the copied workflow if you need a different artifact path. Set `TRANSCRIBER_PROVIDER` in the `transcribe-media` target env to choose another provider. For multi-speaker recordings, update the transcriber command to request diarization when the selected provider supports it. If no recurring loop candidates are generated, the validation step exits successfully after recording that there is nothing to validate.
+
+The workflow includes non-shell `check-transcriber` and `check-loops` command steps so `loops workflows validate --preflight` can catch those missing CLIs. Shell command bodies, provider credentials, and media access are still checked by the transcriber step at runtime.
+
+The ingestion template intentionally does not wrap the whole workflow in an OpenLoops goal. Goal wrappers execute the underlying target for each ready goal-plan node, which is useful for implementation workflows but too surprising for media ingestion. Use goals in the generated follow-up workflows after the transcript has been converted into a concrete backlog.
+
+Schedule the workflow only after a manual run produces useful backlog items:
+
+```bash
+loops create workflow transcript-feedback-weekly \
+  --workflow transcript-feedback-to-loops \
+  --cron "0 9 * * 1" \
+  --attempts 2 \
+  --retry-delay 10m \
+  --lease 2h
+```
+
+## Loop Candidates
+
+Transcript and feedback sources usually produce recurring work in a few durable categories:
+
+- Code review and security: scan recent changes, identify risky diffs, and open focused remediation PRs.
+- Customer or community feedback: summarize new feedback, cluster issues, and create small implementation tasks.
+- Maintenance PRs: remove stale tests, reduce duplication, update docs, and fix flaky workflows.
+- CI optimization: inspect slow jobs, propose changes, and validate runtime improvements with before/after evidence.
+- Knowledge capture: turn important discussions into reusable docs, prompts, or skills.
+
+Use an agent loop when judgment is needed. Use a command loop when the task is deterministic. Use a workflow when the loop needs ordered steps, separate accounts, or a validation gate.
+
+## Guardrails
+
+Only transcribe media you are authorized to access. Keep source metadata with transcript artifacts so reviewers can trace where an insight came from.
+
+Every loop candidate should name:
+
+- Cadence and trigger.
+- Allowed repository paths and whether writes are permitted.
+- Agent provider and account profile, if needed.
+- Verification command or evidence artifact.
+- Stop condition or archive condition.
+- Human review point before scheduling or merging changes.
+
+For loops that can mutate code, prefer a disposable worktree and prompts that explicitly limit write scope. Start with a one-shot smoke schedule before switching to a recurring cadence.
+
+## Example Follow-Up Loops
+
+Review and security loop:
+
+```bash
+loops create agent repo-review-daily \
+  --provider codewith \
+  --cron "0 8 * * 1-5" \
+  --cwd /path/to/repo \
+  --prompt "Review recent changes for correctness, security, and missing tests. Report concrete findings first. Do not modify files."
+```
+
+Maintenance PR loop:
+
+```bash
+loops create agent maintenance-pr-weekly \
+  --provider codewith \
+  --cron "0 10 * * 2" \
+  --cwd /path/to/repo \
+  --prompt "Find one small maintenance improvement, implement it, and run targeted verification. Keep changes scoped and reviewable."
+```
+
+CI optimization workflow loop:
+
+```bash
+loops workflows validate docs/workflows/generated/ci-optimization.json --preflight
+loops workflows create docs/workflows/generated/ci-optimization.json
+loops create workflow ci-optimization-monthly \
+  --workflow ci-optimization \
+  --cron "0 11 1 * *" \
+  --attempts 2 \
+  --retry-delay 15m
+```

package/docs/USAGE.md

@@ -24,8 +24,13 @@ Update:
 
 ```bash
 npm update -g @hasna/loops
+loops daemon stop
+loops daemon start
+loops daemon status
 ```
 
+Restart the daemon on every machine that runs scheduled loops; already-running daemon processes keep using the old package until restarted.
+
 From source:
 
 ```bash
@@ -155,6 +160,18 @@ Use `shell: true` only when you intentionally want shell parsing:
 { "type": "command", "command": "git status --short", "shell": true }
 ```
 
+## Transcript-Driven Loops
+
+OpenLoops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
+
+```bash
+loops workflows validate /path/to/repo/.openloops/transcript-feedback-to-loops.json --preflight
+loops workflows create /path/to/repo/.openloops/transcript-feedback-to-loops.json
+loops workflows run transcript-feedback-to-loops --show-output
+```
+
+See `docs/TRANSCRIPT_LOOP_PATTERNS.md` for transcript-to-loop guardrails and example schedules for review, maintenance, CI optimization, feedback triage, and knowledge-capture loops.
+
 ## Manage
 
 ```bash

package/docs/workflows/transcript-feedback-to-loops.json

@@ -0,0 +1,80 @@
+{
+  "name": "transcript-feedback-to-loops",
+  "description": "Turn an authorized media transcript into a reviewable backlog of recurring OpenLoops workflows.",
+  "version": 1,
+  "steps": [
+    {
+      "id": "check-transcriber",
+      "description": "Fail early if the transcriber CLI is unavailable to the workflow runner.",
+      "target": {
+        "type": "command",
+        "command": "transcriber",
+        "args": ["--version"],
+        "cwd": "/path/to/repo",
+        "timeoutMs": 30000
+      }
+    },
+    {
+      "id": "check-loops",
+      "description": "Fail early if the loops CLI is unavailable for generated workflow validation.",
+      "target": {
+        "type": "command",
+        "command": "loops",
+        "args": ["--version"],
+        "cwd": "/path/to/repo",
+        "timeoutMs": 30000
+      }
+    },
+    {
+      "id": "transcribe-media",
+      "description": "Use iapp-transcriber to download authorized media and write a structured transcript artifact.",
+      "dependsOn": ["check-transcriber"],
+      "target": {
+        "type": "command",
+        "command": "mkdir -p .openloops/transcripts && transcriber transcribe \"${TRANSCRIBER_SOURCE_URL:?set TRANSCRIBER_SOURCE_URL in workflow target.env}\" --provider \"${TRANSCRIBER_PROVIDER:-openai}\" --json > .openloops/transcripts/latest-transcript.json",
+        "shell": true,
+        "cwd": "/path/to/repo",
+        "env": {
+          "TRANSCRIBER_PROVIDER": "openai"
+        },
+        "timeoutMs": 3600000
+      }
+    },
+    {
+      "id": "extract-loop-backlog",
+      "description": "Extract recurring engineering loop candidates from the transcript.",
+      "dependsOn": ["transcribe-media"],
+      "target": {
+        "type": "agent",
+        "provider": "codewith",
+        "cwd": "/path/to/repo",
+        "timeoutMs": 1800000,
+        "prompt": "Read .openloops/transcripts/latest-transcript.json and create or update docs/loop-backlog.md. Extract only recurring work that is useful enough to schedule through OpenLoops. For each candidate include cadence, target provider, allowed write scope, expected artifacts, verification command, stop condition, and the specific transcript insight that justifies it. Prefer loops for code review/security, customer feedback triage, maintenance PRs, CI optimization, knowledge capture, and workflow hygiene."
+      }
+    },
+    {
+      "id": "author-loop-workflows",
+      "description": "Turn approved backlog items into workflow specs.",
+      "dependsOn": ["extract-loop-backlog"],
+      "target": {
+        "type": "agent",
+        "provider": "codewith",
+        "cwd": "/path/to/repo",
+        "timeoutMs": 1800000,
+        "prompt": "Use docs/loop-backlog.md to author or update workflow JSON specs under docs/workflows/generated. Each workflow must use deterministic command steps for checks, agent steps for judgment or code changes, and workflow or step goals only when the outcome needs planning. Keep prompts scoped to the target repo, name allowed paths, and include validation evidence."
+      }
+    },
+    {
+      "id": "validate-loop-workflows",
+      "description": "Validate generated workflow specs before scheduling.",
+      "dependsOn": ["author-loop-workflows", "check-loops"],
+      "target": {
+        "type": "command",
+        "command": "set -- docs/workflows/generated/*.json; [ -e \"$1\" ] || { echo \"no generated workflow specs found; nothing to validate\"; exit 0; }; for file do loops workflows validate \"$file\" --preflight; done",
+        "shell": true,
+        "cwd": "/path/to/repo",
+        "timeoutMs": 300000
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,10 @@
   },
   "dependencies": {
     "@hasna/machines": "0.0.49",
-    "commander": "^13.1.0"
+    "@openrouter/ai-sdk-provider": "2.9.1",
+    "ai": "6.0.204",
+    "commander": "^13.1.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",