Sidecar process

[djfarrelly]

Optionally run a sidecar Inngest application, where the core agent can write new Inngest functions and have them scheduled by Inngest, so Utah can expand into more automations, async sub-agents and data ingestion workflows.

---

Summary by cubic

Adds an optional sidecar process that runs an inngest v4 worker, hot‑loads functions from {workspace.root}/functions, and injects a skills index into the system prompt. This enables scheduling, event-driven automations, and async workflows without touching the core agent.

• New Features

  • Sidecar runner (src/sidecar/sidecar.ts) connects via inngest/connect, respects AGENT_WORKSPACE, ensures {workspace.root}/functions exists, loads *.ts default exports (skips _*.ts and client.ts), watches with 2s debounce, hot‑reconnects, and logs JSON with extended traces; built‑in heartbeat every 30m.
  • Shared sidecar client (src/sidecar/client.ts, id utah-sidecar); example cron at workspace/functions/example-cron.ts using ../../src/sidecar/client.js (.js required).
  • Skills index in the system prompt from markdown frontmatter (src/lib/skills.ts, src/lib/context.ts); configurable SKILLS_DIR in src/config.ts; new skills guides at skills/inngest-functions.md and skills/sidecar-management.md.
  • Main worker client id set to utah-agent (src/client.ts); scripts sidecar and sidecar:dev added; .gitignore updated for *.plist; inngest bumped to 4.1.1.
  • Docs: docs/sidecar.md; macOS daemon guide updated with worker/sidecar LaunchAgents and commands; removed obsolete docs/SUB-AGENTS.md.

• Migration

  • Add Inngest env to .env, then run pnpm sidecar:dev (dev) or pnpm sidecar (prod).
  • Create functions in {workspace.root}/functions/ that default‑export inngest.createFunction() and import the client from ../../src/sidecar/client.js. Avoid top‑level side effects; prefix helper files with _.
  • Optional: run worker and sidecar as macOS launch agents; see docs/macos-daemon.md.

^{Written for commit 5702426. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 12 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/inngest-functions.md">

<violation number="1" location="skills/inngest-functions.md:41">
P3: The trigger examples use `;` inside object literals, which is invalid syntax. Use commas so the documentation shows valid code that can be copied into functions.</violation>
</file>

<file name="skills/sidecar-management.md">

<violation number="1" location="skills/sidecar-management.md:21">
P2: The doc tells users to import `client.js`, but this repo requires `.ts` extensions for ESM and the file is `client.ts`. This guidance will cause sidecar functions to fail to load with a module-not-found error.</violation>
</file>

<file name="src/lib/skills.ts">

<violation number="1" location="src/lib/skills.ts:16">
P2: Frontmatter parsing only supports LF newlines; CRLF markdown files will be skipped from the skills index.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Frontmatter parsing only supports LF newlines; CRLF markdown files will be skipped from the skills index.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/lib/skills.ts, line 16:

<comment>Frontmatter parsing only supports LF newlines; CRLF markdown files will be skipped from the skills index.</comment>

<file context>
@@ -0,0 +1,61 @@
+  filePath: string;
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+
+function parseFrontmatter(content: string): Record<string, string> {
</file context>

[cubic-dev-ai]

P3: The trigger examples use ; inside object literals, which is invalid syntax. Use commas so the documentation shows valid code that can be copied into functions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/inngest-functions.md, line 41:

<comment>The trigger examples use `;` inside object literals, which is invalid syntax. Use commas so the documentation shows valid code that can be copied into functions.</comment>

<file context>
@@ -0,0 +1,240 @@
+
+```typescript
+{
+  triggers: [{ cron: "0 */6 * * *" }];
+} // Every 6 hours
+{
</file context>