@agimon-ai/doompi-loop 0.0.1-alpha.9 → 0.0.1-alpha.90

package/README.md

@@ -1,42 +1,104 @@
 # @agimon-ai/doompi-loop
 
-Generic multi-loop controller for Doompi.
+Send a prompt now, then repeat it at a bounded interval for the current session.
 
-Runs a prompt on a schedule. Loop is a minor mode: it toggles mid-session, stacks with
-the others, and reports itself on the shared `MODES` line.
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
 
-Part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi), a coding agent that loads
-only the skills and tools you name. This package is composed by Doompi and is not usually
-installed on its own.
+Several loops can coexist. Loop is a minor mode and remains active while at least one scheduled
+prompt belongs to the current session.
+
+> **Alpha:** launcher and scheduling contracts may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.85.0 and Pi TUI 0.85.0
 
 ## Install
 
+The seeded `modes.yaml` selects Loop in `default.packages`. Keep it there or select it through a
+layer; it is not fixed host infrastructure. For standalone Pi:
+
 ```bash
-npm install @agimon-ai/doompi-loop
+pi install npm:@agimon-ai/doompi-loop
 ```
 
-## How it loads
+## Start and manage loops
+
+Use `/loop` to start a loop and `/loops` to inspect or stop active loops. In DoomPi, `SPC l s` opens
+the start flow and `SPC l l` opens the list.
+
+The default interval is 300 seconds. Accepted intervals range from 30 to 3600 seconds. A loop runs
+its prompt once immediately, then schedules later passes.
+
+If Pi is busy, a due pass waits for the shared agent to become idle. Multiple due signals can
+coalesce rather than creating overlapping model turns. Stopping a loop prevents future passes but
+does not rewind side effects from a pass already sent.
+
+## Lifecycle and cost
+
+Loop state belongs to the session's `doom/loop-launchers` service; it is not a durable queue.
+Replacing or shutting down the session aborts pending launches and stops active timers. Resuming a
+transcript does not restart old loops.
 
-Doompi loads this unconditionally. It is core, not a layer, so it does not appear in
-`.doom/modes.yaml`: making it optional would only create broken configurations.
+Every pass can start another model turn and repeat tool or external side effects. Choose
+conservative intervals, make prompts idempotent where possible, and stop loops when the recurring
+work is complete.
 
-Extension entry: `@agimon-ai/doompi-loop/extensions/pi`
+## Web extension slots
 
-## Leader
+The Loop Activity section declares `loop.registration` for start controls and `loop.items` for
+session-scoped instance rows. Other web plugins may fill either slot; Loop owns the section shell and
+renders all registered fills without requiring a feature-specific dependency.
 
-`SPC l s` starts a loop, `SPC l l` lists and stops them, once the extension is loaded.
+## Extension authors: cross-extension launchers
 
-The built-in **Default loop** asks for a prompt and an interval, runs one pass immediately,
-and repeats while the session is open. Other extensions can register domain-specific loop
-launchers alongside it.
+Launcher definitions use the shared Cordis service. A consumer registers a launcher and returns its
+cleanup callback. Cordis removes that launcher when either package or the session unloads, then
+registers it again when the provider returns.
 
-## Entry points
+```ts
+import { DOOM_LOOP_LAUNCHERS_SERVICE, requireDoomLoopLaunchers } from '@agimon-ai/doompi-loop/loop-launchers';
+import type { Context } from '@deepseek-ai/cordis';
 
-| Import                                 |
-| -------------------------------------- |
-| `@agimon-ai/doompi-loop`               |
-| `@agimon-ai/doompi-loop/extensions/pi` |
+export function myLoopPlugin(ctx: Context): void {
+  ctx.inject([DOOM_LOOP_LAUNCHERS_SERVICE], (sessionContext) => {
+    const registration = requireDoomLoopLaunchers(sessionContext).register({
+      id: 'example.recurring-check',
+      source: '@example/doompi-recurring-check',
+      label: 'Recurring check',
+      async launch({ instanceId, signal }) {
+        signal.throwIfAborted();
+        // Start session work. The returned stop callback owns cleanup.
+        return { instanceId, stop: () => undefined };
+      },
+    });
+    return () => registration.dispose('Contributor unloaded.');
+  });
+}
+```
+
+Mount that plugin on the runner's shared Doom Cordis root. Loop owns the registry and default
+launcher. Consumers depend only on
+`@agimon-ai/doompi-loop/loop-launchers`; there is no process-global registry or
+session-ID lookup API.
+
+The package root exports the service contract
+types. Normal Pi activation uses the discovered `extensions/pi` entry.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
 
 ## License
 
 MIT
+
+Pi and server entries live directly in `src/extensions/`. They declare commands, minor mode owners, and optional services. The helpers own registration and cleanup; `onDispose` clears UI state, while session service disposal stops pending launches and timers. Services live in named folders and public exports remain flat.

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/doompi-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,gDAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/doompi-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}