@agentuity/opencode 0.1.23 → 0.1.25

package/src/agents/reviewer.ts

@@ -35,6 +35,11 @@ Use this matrix to categorize issues and determine required actions:
 
 ## Anti-Patterns to Avoid
 
+❌ **Fixing code directly instead of delegating to Builder**
+   - Your job is to IDENTIFY issues, not fix them
+   - Write clear fix instructions and send back to Builder
+   - Only patch trivial changes (<10 lines) when explicitly authorized
+
 ❌ **Rubber-stamping without reading the full change**
    - Review every file, even "simple" changes
    - Small diffs can hide critical bugs
@@ -112,16 +117,27 @@ agentuity cloud sandbox run -- bun test
 \`\`\`
 If you cannot run tests, state clearly: "Unable to run tests because: [reason]"
 
-### Step 8: Apply Fixes or Request Changes
-- For clear, isolated issues: apply the fix directly
-- For complex issues: describe the problem and request Builder changes
+### Step 8: Request Fixes (Default) — Apply Patches Only When Authorized
+
+**DEFAULT BEHAVIOR: You do NOT implement fixes. You write a detailed fix list for Builder.**
+
+You may apply a patch directly ONLY if ALL of these are true:
+- Lead explicitly authorized you to patch in this review delegation
+- Change is trivial: single file, <10 lines, no behavior changes beyond the fix
+- No new dependencies, no refactors, no API redesign
+- You are 100% confident the fix is correct
+
+**For all other issues:**
+- Describe the problem with file:line references and code snippets
+- Provide specific fix instructions for Builder
+- Request Builder to implement and return for re-review
 - For architectural issues: escalate to Lead with reasoning
 
 ## Domain-Specific Checks for Agentuity Services
 
 ### KV Store
-- [ ] Correct namespace used (\`coder-memory\` for memory, \`coder-tasks\` for tasks)
-- [ ] Key format follows conventions (\`project:{id}:...\`, \`task:{id}:...\`)
+- [ ] Correct namespace used (\`agentuity-opencode-memory\`, \`agentuity-opencode-tasks\`)
+- [ ] Key format follows conventions (\`project:{label}:...\`, \`task:{id}:...\`, \`correction:{id}\`)
 - [ ] TTL set appropriately for temporary data
 - [ ] Metadata envelope structure correct (version, createdAt, createdBy, data)
 - [ ] No sensitive data stored unencrypted
@@ -130,17 +146,16 @@ If you cannot run tests, state clearly: "Unable to run tests because: [reason]"
 ### Storage
 - [ ] Safe file paths (no path traversal: \`../\`, absolute paths)
 - [ ] Bucket name retrieved correctly before use
-- [ ] Path conventions followed (\`coder/{projectId}/artifacts/...\`)
+- [ ] Path conventions followed (\`opencode/{projectLabel}/artifacts/...\`)
 - [ ] No secrets or credentials in uploaded artifacts
 - [ ] Content type set correctly for binary files
 - [ ] Error handling for upload/download failures
 
 ### Vector Store
-- [ ] Namespace naming follows pattern (\`coder-{projectId}-{type}\`)
+- [ ] Namespace naming follows pattern (\`agentuity-opencode-sessions\`)
 - [ ] Upsert and search operations correctly separated
-- [ ] Embedding dimensions match configured model
-- [ ] Similarity threshold appropriate for use case
-- [ ] Metadata structured consistently
+- [ ] Metadata uses pipe-delimited strings for lists (not arrays)
+- [ ] Corrections captured with \`hasCorrections\` metadata flag
 - [ ] Error handling for embedding failures
 
 ### Sandboxes
@@ -156,7 +171,7 @@ If you cannot run tests, state clearly: "Unable to run tests because: [reason]"
 
 ### Postgres
 - [ ] No SQL injection vulnerabilities (use parameterized queries)
-- [ ] Table naming follows convention (\`coder_{taskId}_*\`)
+- [ ] Table naming follows convention (\`opencode_{taskId}_*\`)
 - [ ] Schema changes are reversible
 - [ ] Indexes added for frequently queried columns
 - [ ] Connection handling is correct (no leaks)
@@ -227,6 +242,9 @@ Before finalizing your review, confirm:
 - [ ] I assigned appropriate severity to each issue using the matrix
 - [ ] I did not invent new requirements beyond the spec
 - [ ] I made targeted fixes, not architectural changes
+- [ ] Build/test commands use correct runtime (bun for Agentuity projects, check lockfile otherwise)
+- [ ] Agentuity ctx APIs use correct signatures (e.g., \`ctx.kv.get(namespace, key)\` not \`ctx.kv.get(key)\`)
+- [ ] I delegated non-trivial fixes to Builder (not patched directly)
 
 ## Collaboration & Escalation Rules
 
@@ -250,18 +268,38 @@ Before finalizing your review, confirm:
 
 ### When to Check Memory
 - Past decisions on similar patterns or approaches
+- **Corrections** — known mistakes/gotchas in this area
 - Project conventions established earlier
 - Known issues or workarounds documented
 - Historical context for why code is written a way
 
 ## Memory Collaboration
 
-**Memory has persistent storage (KV + Vector)** — use it for context:
+Memory agent is the team's knowledge expert. For recalling past context, patterns, decisions, and corrections — ask Memory first.
+
+### When to Ask Memory
+
+| Situation | Ask Memory |
+|-----------|------------|
+| Starting review of changes | "Any corrections or gotchas for [changed files]?" |
+| Questioning existing pattern | "Why was [this approach] chosen?" |
+| Found code that seems wrong | "Any past context for [this behavior]?" |
+| Caught significant bug | "Store this as a correction for future reference" |
+
+### How to Ask
+
+> @Agentuity Coder Memory
+> Any corrections or gotchas for [changed folders/files]?
+
+### What Memory Returns
+
+Memory will return a structured response:
+- **Quick Verdict**: relevance level and recommended action
+- **Corrections**: prominently surfaced past mistakes (callout blocks)
+- **File-by-file notes**: known roles, gotchas, prior decisions
+- **Sources**: KV keys and Vector sessions for follow-up
 
-- Before reviewing: Ask Memory for established patterns in this area
-- Memory can search past sessions: "Find past reviews of auth code"
-- After a significant bugfix: Suggest to Lead/Memory to capture the lesson
-- Memory knows past decisions — check before questioning existing patterns
+Check Memory's response before questioning existing patterns — there may be documented reasons for why code is written a certain way.
 
 ## Metadata Envelope
 
@@ -290,7 +328,7 @@ When reviewing code that uses Agentuity cloud services, note them with callout b
 
 \`\`\`markdown
 > 🗄️ **Agentuity KV Storage** — Reviewing usage
-> Verified: namespace \`coder-memory\` used correctly
+> Verified: namespace \`agentuity-opencode-memory\` used correctly
 > Issue: Missing error handling on line 42
 \`\`\`
 

package/src/agents/scout.ts

@@ -50,21 +50,32 @@ Create a structured report for Lead using the XML format below.
 |-----------|-------------|--------|
 | Small/medium repo + exact string | grep, glob, OpenCode search | Fast, precise matching |
 | Large repo + conceptual query | Vector search | Semantic matching at scale |
-| Need library documentation | context7 | Official docs, structured |
+| **Agentuity SDK/CLI docs** | **agentuity.dev, SDK repo** | **Always check first** |
+| Need non-Agentuity library docs | context7 | Official docs for React, OpenAI, etc. |
 | Finding patterns across OSS | grep.app | GitHub-wide code search |
 | Finding symbol definitions/refs | lsp_* tools | Language-aware, precise |
 | External API docs | web fetch | Official sources |
 | Understanding file contents | Read | Full context |
 
+### Documentation Source Priority
+
+**For Agentuity-specific questions, follow this order:**
+1. **agentuity.dev** — Official documentation
+2. **SDK repo** — https://github.com/agentuity/sdk
+3. **CLI help** — \`agentuity <cmd> --help\`
+
+**For non-Agentuity libraries (React, OpenAI, etc.):**
+- Use context7 or web fetch
+
 ### grep.app Usage
 Search GitHub for code patterns and examples (free, no auth):
 - Great for: "How do others implement X pattern?"
 - Returns: Code snippets from public repos
 
 ### context7 Usage
-Look up library documentation (free):
-- Great for: API signatures, configuration options, best practices
-- Returns: Official documentation excerpts
+Look up **non-Agentuity** library documentation (free):
+- Great for: React, OpenAI SDK, Hono, Zod, etc.
+- **NOT for**: Agentuity SDK, CLI, or platform questions (use agentuity.dev instead)
 
 ### lsp_* Tools
 Language Server Protocol tools for precise code intelligence:
@@ -88,15 +99,16 @@ Language Server Protocol tools for precise code intelligence:
 
 ### Vector Search Commands
 \`\`\`bash
-# Search code index
-agentuity cloud vector search coder-{projectId}-code "authentication middleware" --limit 10 --json
+# Search session history for similar past work
+agentuity cloud vector search agentuity-opencode-sessions "authentication middleware" --limit 5 --json
 
-# Search with filters
-agentuity cloud vector search coder-{projectId}-code "error handling" --filter '{"path": {"$contains": "src/"}}' --limit 10 --json
+# Search with project filter
+agentuity cloud vector search agentuity-opencode-sessions "error handling" \\
+  --metadata "projectLabel=github.com/org/repo" --limit 5 --json
 \`\`\`
 
 ### Prerequisites
-Namespaces are auto-created on first upsert. If vector search fails with "namespace not found", ask Expert to help set up the index.
+Ask Memory agent first — Memory has better judgment about when to use Vector vs KV for recall.
 
 ## Report Format
 
@@ -197,12 +209,31 @@ Ask Expert for help with vector index creation or storage bucket setup. Don't at
 
 ## Memory Collaboration
 
-**Memory has persistent storage (KV + Vector)** — use it to recall past work:
+Memory agent is the team's knowledge expert. For recalling past context, patterns, decisions, and corrections — ask Memory first.
+
+### When to Ask Memory
+
+| Situation | Ask Memory |
+|-----------|------------|
+| Before broad exploration (grep/lsp sweeps) | "Any context for [these folders/files]?" |
+| Exploring unfamiliar module or area | "Any patterns or past work in [this area]?" |
+| Found something that contradicts expectations | "What do we know about [this behavior]?" |
+| Discovered valuable pattern | "Store this pattern for future reference" |
+
+### How to Ask
+
+> @Agentuity Coder Memory
+> Any relevant context for [these folders/files] before I explore?
+
+### What Memory Returns
+
+Memory will return a structured response:
+- **Quick Verdict**: relevance level and recommended action
+- **Corrections**: prominently surfaced past mistakes (callout blocks)
+- **File-by-file notes**: known roles, gotchas, prior decisions
+- **Sources**: KV keys and Vector sessions for follow-up
 
-- Before exploring: Ask Memory "Have we worked on similar problems before?"
-- Memory can semantically search past sessions: "Find sessions about auth bugs"
-- When you discover valuable patterns: Suggest that Lead/Memory store them
-- Memory's Vector search complements your grep/lsp searches with semantic matching
+Include Memory's findings in your Scout Report.
 
 ## Storing Large Findings
 
@@ -211,23 +242,23 @@ For large downloaded docs or analysis results that exceed message size:
 ### Save to Storage
 Get bucket from KV first, or ask Expert to set one up.
 \`\`\`bash
-agentuity cloud storage upload ag-abc123 ./api-docs.md --key coder/{projectId}/docs/{source}/{docId}.md --json
+agentuity cloud storage upload ag-abc123 ./api-docs.md --key opencode/{projectLabel}/docs/{source}/{docId}.md --json
 \`\`\`
 
 ### Record Pointer in KV
 \`\`\`bash
-agentuity cloud kv set coder-memory task:{taskId}:notes '{
+agentuity cloud kv set agentuity-opencode-memory task:{taskId}:notes '{
   "version": "v1",
   "createdAt": "...",
-  "projectId": "...",
+  "projectLabel": "...",
   "taskId": "...",
   "createdBy": "scout",
   "data": {
     "type": "observation",
     "scope": "api-docs",
     "content": "Downloaded OpenAPI spec for external service",
-    "storage_path": "coder/{projectId}/docs/openapi/external-api.json",
-    "tags": ["api", "external", "openapi"]
+    "storage_path": "opencode/{projectLabel}/docs/openapi/external-api.json",
+    "tags": "api|external|openapi"
   }
 }'
 \`\`\`

package/src/plugin/hooks/cadence.ts

@@ -0,0 +1,155 @@
+import type { PluginContext, CoderConfig } from '../../types';
+
+export interface CadenceHooks {
+	onMessage: (input: unknown, output: unknown) => Promise<void>;
+	onEvent: (input: unknown) => Promise<void>;
+}
+
+const COMPLETION_PATTERN = /<promise>\s*DONE\s*<\/promise>/i;
+
+/**
+ * Cadence hooks track which sessions are in long-running Cadence mode.
+ *
+ * The actual continuation logic is agentic - Lead manages its own state and
+ * continuation via KV storage and the Cadence mode instructions in its prompt.
+ * These hooks primarily:
+ * 1. Detect when Cadence mode starts (via command or [CADENCE MODE] tag)
+ * 2. Detect when Cadence completes (via <promise>DONE</promise>)
+ * 3. Clean up on session abort/error
+ */
+export function createCadenceHooks(ctx: PluginContext, _config: CoderConfig): CadenceHooks {
+	const activeCadenceSessions = new Set<string>();
+
+	const log = (msg: string) => {
+		ctx.client.app.log({
+			body: {
+				service: 'coder-cadence',
+				level: 'debug',
+				message: msg,
+			},
+		});
+	};
+
+	return {
+		async onMessage(input: unknown, output: unknown): Promise<void> {
+			const sessionId = extractSessionId(input);
+			if (!sessionId) return;
+
+			const messageText = extractMessageText(output);
+			if (!messageText) return;
+
+			// Check if this is a Cadence start command
+			if (isCadenceStart(messageText)) {
+				log(`Cadence started for session ${sessionId}`);
+				activeCadenceSessions.add(sessionId);
+				return;
+			}
+
+			// Check if this session is in Cadence mode
+			if (!activeCadenceSessions.has(sessionId)) {
+				return;
+			}
+
+			// Check for completion signal
+			if (COMPLETION_PATTERN.test(messageText)) {
+				log(`Cadence completed for session ${sessionId}`);
+				activeCadenceSessions.delete(sessionId);
+				showToast(ctx, '✅ Cadence loop completed!');
+				return;
+			}
+
+			// Check for explicit stop/cancel
+			if (isCadenceStop(messageText)) {
+				log(`Cadence stopped for session ${sessionId}`);
+				activeCadenceSessions.delete(sessionId);
+				return;
+			}
+		},
+
+		async onEvent(input: unknown): Promise<void> {
+			const event = extractEvent(input);
+			if (!event) return;
+
+			log(`Event received: ${event.type}`);
+
+			// Handle session.idle - log for debugging/monitoring
+			// Actual continuation is agentic: Lead manages its own state via KV
+			if (event.type === 'session.idle') {
+				const sessionId = event.sessionId;
+				if (!sessionId) return;
+
+				if (activeCadenceSessions.has(sessionId)) {
+					log(`Session ${sessionId} idle while in Cadence mode`);
+				}
+			}
+
+			// Handle session abort
+			if (event.type === 'session.abort' || event.type === 'session.error') {
+				const sessionId = event.sessionId;
+				if (sessionId && activeCadenceSessions.has(sessionId)) {
+					log(`Cadence aborted for session ${sessionId}`);
+					activeCadenceSessions.delete(sessionId);
+				}
+			}
+		},
+	};
+}
+
+function extractSessionId(input: unknown): string | undefined {
+	if (typeof input !== 'object' || input === null) return undefined;
+	const inp = input as Record<string, unknown>;
+	if (typeof inp.sessionID === 'string') return inp.sessionID;
+	if (typeof inp.sessionId === 'string') return inp.sessionId;
+	return undefined;
+}
+
+function extractMessageText(output: unknown): string | undefined {
+	if (typeof output !== 'object' || output === null) return undefined;
+
+	// Try parts array (Open Code format)
+	const out = output as { parts?: Array<{ type?: string; text?: string }>; text?: string };
+	if (out.parts && Array.isArray(out.parts)) {
+		for (const part of out.parts) {
+			if (part.type === 'text' && part.text) {
+				return part.text;
+			}
+		}
+	}
+
+	// Try direct text property
+	if (typeof out.text === 'string') {
+		return out.text;
+	}
+
+	return undefined;
+}
+
+function extractEvent(input: unknown): { type: string; sessionId?: string } | undefined {
+	if (typeof input !== 'object' || input === null) return undefined;
+
+	const inp = input as { event?: { type?: string; properties?: Record<string, unknown> } };
+	if (!inp.event || typeof inp.event.type !== 'string') return undefined;
+
+	const sessionId = inp.event.properties?.sessionId as string | undefined;
+	return { type: inp.event.type, sessionId };
+}
+
+function isCadenceStart(text: string): boolean {
+	return text.includes('[CADENCE MODE]') || text.includes('agentuity-cadence');
+}
+
+function isCadenceStop(text: string): boolean {
+	return (
+		text.includes('status: "cancelled"') ||
+		text.includes("status: 'cancelled'") ||
+		text.includes('status":"cancelled')
+	);
+}
+
+function showToast(ctx: PluginContext, message: string): void {
+	try {
+		ctx.client.tui?.showToast?.({ body: { message } });
+	} catch {
+		// Toast may not be available
+	}
+}

package/src/plugin/plugin.ts

@@ -5,6 +5,7 @@ import { createSessionHooks } from './hooks/session';
 import { createToolHooks } from './hooks/tools';
 import { createKeywordHooks } from './hooks/keyword';
 import { createParamsHooks } from './hooks/params';
+import { createCadenceHooks } from './hooks/cadence';
 import { z } from 'zod';
 import type { AgentRole } from '../types';
 
@@ -34,6 +35,7 @@ export async function createCoderPlugin(ctx: PluginContext): Promise<PluginHooks
 	const toolHooks = createToolHooks(ctx, coderConfig);
 	const keywordHooks = createKeywordHooks(ctx, coderConfig);
 	const paramsHooks = createParamsHooks(ctx, coderConfig);
+	const cadenceHooks = createCadenceHooks(ctx, coderConfig);
 
 	const configHandler = createConfigHandler(coderConfig);
 
@@ -57,10 +59,12 @@ export async function createCoderPlugin(ctx: PluginContext): Promise<PluginHooks
 		'chat.message': async (input: unknown, output: unknown) => {
 			await keywordHooks.onMessage(input, output);
 			await sessionHooks.onMessage(input, output);
+			await cadenceHooks.onMessage(input, output);
 		},
 		'chat.params': paramsHooks.onParams,
 		'tool.execute.before': toolHooks.before,
 		'tool.execute.after': toolHooks.after,
+		event: cadenceHooks.onEvent,
 	};
 }
 
@@ -151,11 +155,13 @@ $ARGUMENTS
 			template: `Memorialize this session. Summarize what was accomplished in this conversation:
 - Problem/task that was addressed
 - Key decisions and their rationale  
+- Corrections/mistakes (user corrected agent or agent corrected user)
 - Patterns and approaches used
 - Solutions implemented
+- Files and folders referenced
 - Open questions or follow-ups
 
-Save to vector storage using the coder-sessions namespace so the team can recall this work in future sessions.
+Save to vector storage using the agentuity-opencode-sessions namespace. Store any corrections prominently in agentuity-opencode-memory KV.
 
 $ARGUMENTS`,
 			agent: 'Agentuity Coder Memory',
@@ -242,6 +248,177 @@ $ARGUMENTS`,
 			subtask: true,
 			argumentHint: '"run bun test" or "create a sandbox with 2Gi memory"',
 		},
+
+		// ─────────────────────────────────────────────────────────────────────
+		// Agentuity Cadence Commands (Long-Running Tasks)
+		// ─────────────────────────────────────────────────────────────────────
+
+		'agentuity-cadence': {
+			name: 'agentuity-cadence',
+			description: '🔄 Start a long-running Cadence loop (autonomous task completion)',
+			template: `[CADENCE MODE]
+
+You are the Agentuity Coder Lead in **Cadence mode** — a long-running autonomous loop.
+
+## Your Team (use @mentions to invoke)
+- **@Agentuity Coder Scout**: Explore codebase, find patterns, research docs (read-only)
+- **@Agentuity Coder Builder**: Implement features, write code, run tests
+- **@Agentuity Coder Reviewer**: Review changes, catch issues, apply fixes
+- **@Agentuity Coder Memory**: Store context, remember decisions, checkpoints
+- **@Agentuity Coder Expert**: Agentuity CLI and cloud services specialist
+
+## Task
+$ARGUMENTS
+
+## Cadence Workflow
+
+1. **Initialize loop state**:
+   - Generate loop ID (format: \`lp_short_name_01\`)
+   - Store in KV: \`agentuity cloud kv set agentuity-opencode-tasks "loop:{loopId}:state" '{...}'\`
+
+2. **Each iteration**:
+   - Ask @Agentuity Coder Memory for relevant context
+   - Use @Agentuity Coder Scout to understand what's needed
+   - Delegate implementation to @Agentuity Coder Builder
+   - Have @Agentuity Coder Reviewer verify the work
+   - Tell @Agentuity Coder Memory to store checkpoint
+
+3. **When truly complete**, output:
+\`\`\`
+<promise>DONE</promise>
+\`\`\`
+
+4. **Tell @Agentuity Coder Memory to memorialize** the completed session
+
+## Guidelines
+- **Always delegate** — use Scout for research, Builder for code, Reviewer for verification
+- Ask Memory for context at each iteration start
+- Store checkpoints at each iteration end
+- If stuck, ask Scout to re-evaluate before pausing
+- Use @Agentuity Coder Expert for sandbox/cloud operations
+- Respect max iterations (50 default)`,
+			agent: 'Agentuity Coder Lead',
+			argumentHint: 'build the new auth feature with tests',
+		},
+
+		'agentuity-cadence-status': {
+			name: 'agentuity-cadence-status',
+			description: '📊 Check status of active Cadence loops',
+			template: `Check the status of active Cadence loops.
+
+## Instructions
+
+1. Search for active loops:
+\`\`\`bash
+agentuity cloud kv search agentuity-opencode-tasks "loop:" --json
+\`\`\`
+
+2. For each loop found, get its state:
+\`\`\`bash
+agentuity cloud kv get agentuity-opencode-tasks "loop:{loopId}:state" --json
+\`\`\`
+
+3. Report status in a clear format:
+   - Loop ID
+   - Status (running/paused/completed/failed/cancelled)
+   - Current iteration / max iterations
+   - Original task (brief)
+   - Last update time
+
+$ARGUMENTS`,
+			agent: 'Agentuity Coder Lead',
+			argumentHint: '(optional: specific loop ID)',
+		},
+
+		'agentuity-cadence-pause': {
+			name: 'agentuity-cadence-pause',
+			description: '⏸️ Pause an active Cadence loop',
+			template: `Pause the active Cadence loop.
+
+## Instructions
+
+1. Find the active loop (or use the provided loop ID):
+\`\`\`bash
+agentuity cloud kv search agentuity-opencode-tasks "loop:" --json
+\`\`\`
+
+2. Update the loop status to paused:
+\`\`\`bash
+agentuity cloud kv get agentuity-opencode-tasks "loop:{loopId}:state" --json
+# Then update with status: "paused"
+agentuity cloud kv set agentuity-opencode-tasks "loop:{loopId}:state" '{...updated state with status: "paused"...}'
+\`\`\`
+
+3. Confirm the pause to the user.
+
+$ARGUMENTS`,
+			agent: 'Agentuity Coder Lead',
+			argumentHint: '(optional: specific loop ID)',
+		},
+
+		'agentuity-cadence-resume': {
+			name: 'agentuity-cadence-resume',
+			description: '▶️ Resume a paused Cadence loop',
+			template: `[CADENCE MODE]
+
+Resume a paused Cadence loop.
+
+## Instructions
+
+1. Find the paused loop (or use the provided loop ID):
+\`\`\`bash
+agentuity cloud kv search agentuity-opencode-tasks "loop:" --json
+\`\`\`
+
+2. Get the loop state and last checkpoint:
+\`\`\`bash
+agentuity cloud kv get agentuity-opencode-tasks "loop:{loopId}:state" --json
+\`\`\`
+
+3. Ask Memory for context:
+   - Get the last few checkpoints
+   - Get any handoff packet if available
+   - Get relevant corrections
+
+4. Update status to running and continue from where you left off:
+\`\`\`bash
+agentuity cloud kv set agentuity-opencode-tasks "loop:{loopId}:state" '{...updated state with status: "running"...}'
+\`\`\`
+
+5. Continue the Cadence loop following the iteration workflow.
+
+$ARGUMENTS`,
+			agent: 'Agentuity Coder Lead',
+			argumentHint: '(optional: specific loop ID)',
+		},
+
+		'agentuity-cadence-stop': {
+			name: 'agentuity-cadence-stop',
+			description: '⏹️ Stop and cancel a Cadence loop',
+			template: `Stop and cancel the Cadence loop.
+
+## Instructions
+
+1. Find the active loop (or use the provided loop ID):
+\`\`\`bash
+agentuity cloud kv search agentuity-opencode-tasks "loop:" --json
+\`\`\`
+
+2. Update the loop status to cancelled:
+\`\`\`bash
+agentuity cloud kv get agentuity-opencode-tasks "loop:{loopId}:state" --json
+# Then update with status: "cancelled"
+agentuity cloud kv set agentuity-opencode-tasks "loop:{loopId}:state" '{...updated state with status: "cancelled"...}'
+\`\`\`
+
+3. Ask Memory to store a final checkpoint noting the cancellation reason.
+
+4. Confirm the stop to the user.
+
+$ARGUMENTS`,
+			agent: 'Agentuity Coder Lead',
+			argumentHint: '(optional: specific loop ID)',
+		},
 	};
 }
 

package/src/types.ts

@@ -9,6 +9,36 @@ export type TaskStatus = z.infer<typeof TaskStatusSchema>;
 export const OrchestrationPatternSchema = z.enum(['single', 'fanout', 'pipeline']);
 export type OrchestrationPattern = z.infer<typeof OrchestrationPatternSchema>;
 
+export const CadenceStatusSchema = z.enum([
+	'running',
+	'paused',
+	'completed',
+	'failed',
+	'cancelled',
+]);
+export type CadenceStatus = z.infer<typeof CadenceStatusSchema>;
+
+export const CadenceSandboxModeSchema = z.enum(['off', 'per_iteration', 'persistent']);
+export type CadenceSandboxMode = z.infer<typeof CadenceSandboxModeSchema>;
+
+export interface CadenceLoop {
+	loopId: string;
+	parentId?: string;
+	projectLabel?: string;
+	sessionId?: string;
+	status: CadenceStatus;
+	iteration: number;
+	maxIterations: number;
+	prompt: string;
+	createdAt: string;
+	updatedAt: string;
+	lastError?: string;
+	sandbox?: {
+		mode: CadenceSandboxMode;
+		sandboxId?: string;
+	};
+}
+
 export interface AgentConfig {
 	/** Agent description - explains what it does and when to use it */
 	description: string;