@agimon-ai/po-loop 0.0.0-alpha.0

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@agimon-ai/po-loop",
+  "version": "0.0.0-alpha.0",
+  "description": "Session-scoped recurring prompt scheduler and loop controls for Pi coding agents.",
+  "keywords": [
+    "ai",
+    "automation",
+    "coding-agent",
+    "developer-tools",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "po",
+    "prompt-scheduler",
+    "recurring-tasks"
+  ],
+  "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/po/issues"
+  },
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/po.git",
+    "directory": "packages/minor/po-loop"
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "src/prompts",
+    "src/types/loopView.ts",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "jsnext:main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
+    "./extensions/web": {
+      "import": "./dist/extensions/web.mjs"
+    },
+    "./loopLaunchers": {
+      "types": "./dist/loopLaunchers.d.mts",
+      "import": "./dist/loopLaunchers.mjs",
+      "require": "./dist/loopLaunchers.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agimon-ai/po-core": "0.0.0-alpha.0",
+    "@agimon-ai/po-minor-mode": "0.0.0-alpha.0",
+    "@agimon-ai/po-ui": "0.0.0-alpha.0",
+    "@agimon-ai/po-web-components": "0.0.0-alpha.0",
+    "@deepseek-ai/cordis": "4.0.4",
+    "croner": "10.0.1",
+    "typebox": "1.3.34"
+  },
+  "devDependencies": {
+    "@agimon-ai/po-build": "0.0.0-alpha.0",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@types/node": "26.6.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "poServer": {
+    "entry": "./generated/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/apiContracts.mjs"
+    }
+  },
+  "poWeb": {
+    "pluginId": "loop",
+    "channels": [],
+    "client": "./dist/extensions/web.mjs",
+    "scopes": [
+      "session"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.web.json",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt ."
+  }
+}

package/src/prompts/po-use-loop/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: po-use-loop
+description: Create, inspect, and stop session-scoped interval, cron, and extension-contributed loops.
+---
+
+# Use Doom Pi Loop
+
+Enable the Loop minor mode to expose `loop_list`, `loop_start`, and `loop_stop` to the agent. Enabling the mode does not create a loop. Disabling it hides agent tools but leaves existing loops and manual Activity controls available.
+
+## Agent configuration
+
+Call `loop_list` first. It returns the available launcher IDs, their input schemas, and active instance IDs. Providers without an input schema require manual setup and cannot be started by an agent tool.
+
+An interval loop runs immediately when the session can accept a prompt, then every 30 to 3600 seconds:
+
+```json
+{
+  "launcherId": "po.default",
+  "input": { "prompt": "Check the current build status and report changes.", "intervalSeconds": 300 }
+}
+```
+
+A cron loop runs at its next scheduled minute, not immediately. Supply a five-field cron expression and an optional IANA timezone. The default timezone is UTC:
+
+```json
+{
+  "launcherId": "po.cron",
+  "input": { "prompt": "Summarize the work remaining today.", "cron": "0 9 * * 1-5", "timezone": "Australia/Brisbane" }
+}
+```
+
+Pass either configuration to `loop_start`. Stop one instance with `loop_stop` and its exact `instanceId`. Extension launchers, such as Agiflow project dispatch, use their own schemas from `loop_list`; do not guess their configuration fields.
+
+## Manual controls
+
+Activity's Loops group lists this session's loops whenever the Loop package is loaded, even with the minor mode off, and each row has a stop control. Loops are set by asking the agent while the minor mode is active. `/loops` lists instances, and `/loops stop <instanceId>` stops one.
+
+## Cost and lifecycle
+
+Several loops can coexist, but built-in loops do not deliberately overlap prompts on the same agent. The CLI coalesces due passes while busy and retries after the agent settles. The server skips busy ticks and checks again at the next scheduled tick.
+
+Every pass can start a model turn and repeat tool calls or external side effects. Prefer idempotent checks and conservative schedules. Stop loops when the recurring work is complete.
+
+Loops are session-scoped, not a durable job queue. Replacing or shutting down the session stops timers; reopening a transcript does not restart them or replay missed ticks. Stopping prevents future submissions but does not undo or cancel a prompt already submitted.

package/src/types/loopView.ts

@@ -0,0 +1,73 @@
+/** The browser-only status that carries active Loop instances into the activity dock. */
+export const LOOP_VIEW_STATUS_KEY = 'doom-loop-instances';
+
+export type LoopStatusState = 'starting' | 'running' | 'stopping';
+
+/** The small, serializable Loop view the cockpit needs for one activity row. */
+export interface LoopStatusItem {
+  readonly instanceId: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly state: LoopStatusState;
+}
+
+interface LoopStatusSource {
+  readonly instanceId: string;
+  readonly launcherLabel: string;
+  readonly label?: string;
+  readonly detail?: string;
+  readonly state: LoopStatusState;
+}
+
+const ANSI = new RegExp(String.raw`\u001b\[[0-9;]*m`, 'gu');
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isState(value: unknown): value is LoopStatusState {
+  return value === 'starting' || value === 'running' || value === 'stopping';
+}
+
+/** Projects runtime snapshots into the JSON status consumed by the web plugin. */
+export function formatLoopStatusView(instances: readonly LoopStatusSource[]): string {
+  if (instances.length === 0) return '';
+  return JSON.stringify(
+    instances.map((instance) => ({
+      instanceId: instance.instanceId,
+      label: instance.label ?? instance.launcherLabel,
+      detail: instance.detail ?? instance.instanceId,
+      state: instance.state,
+    })),
+  );
+}
+
+/** Reads a Loop status without letting malformed session data crash the activity dock. */
+export function parseLoopStatusView(raw: string | undefined): LoopStatusItem[] | undefined {
+  if (raw === undefined) return undefined;
+  const text = raw.replace(ANSI, '').trim();
+  if (text === '') return undefined;
+
+  try {
+    const value: unknown = JSON.parse(text);
+    if (!Array.isArray(value) || value.length === 0) return undefined;
+    const items: LoopStatusItem[] = [];
+    for (const item of value) {
+      if (
+        !isRecord(item) ||
+        typeof item.instanceId !== 'string' ||
+        item.instanceId.trim() === '' ||
+        typeof item.label !== 'string' ||
+        item.label.trim() === '' ||
+        typeof item.detail !== 'string' ||
+        !isState(item.state)
+      ) {
+        return undefined;
+      }
+      items.push({ instanceId: item.instanceId, label: item.label, detail: item.detail, state: item.state });
+    }
+    return items;
+  } catch {
+    return undefined;
+  }
+}